fix: return 429 instead of 403 when max turns exceeded

.github/workflows/contribution-check.md

@@ -11,7 +11,7 @@ permissions:
   contents: read
   pull-requests: read
   issues: read
-max-turns: 3
+max-turns: 4
 concurrency:
   group: "contribution-check-${{ github.event.pull_request.number || github.ref }}"
   cancel-in-progress: true

containers/api-proxy/guards/common-guard-checks.js

@@ -80,8 +80,10 @@ function buildCommonGuardChecks(deps, model) {
     {
       block: getMaxRunsBlockState(),
       isBlocked: block => block && block.maxExceeded,
-      // Terminal hard cap — non-retryable (see effective-tokens guard above).
-      statusCode: 403,
+      // Terminal hard cap: 429 signals the agent has exhausted its allowed
+      // turns.  Unlike transient rate-limits, the Retry-After is absent so
+      // well-behaved clients won't retry indefinitely.
+      statusCode: 429,
       eventName: 'max_runs_exceeded',
       buildError: buildMaxRunsExceededError,
       buildLogFields: block => ({

containers/api-proxy/server.token-guards.test.js

@@ -231,7 +231,7 @@ describe('proxyRequest max-runs guard', () => {
     jest.restoreAllMocks();
   });
 
-  it('returns 403 with structured payload when max runs limit is exceeded', async () => {
+  it('returns 429 with structured payload when max runs limit is exceeded', async () => {
     const cycle = createMockUpstreamCycle(https);
 
     // First request completes successfully — consumes the single allowed run
@@ -251,11 +251,12 @@ describe('proxyRequest max-runs guard', () => {
     await flushPromises();
 
     expect(cycle.spy).toHaveBeenCalledTimes(1);
-    expect(res2.writeHead).toHaveBeenCalledWith(403, expect.objectContaining({
+    expect(res2.writeHead).toHaveBeenCalledWith(429, expect.objectContaining({
       'Content-Type': 'application/json',
     }));
     const payload = JSON.parse(res2.end.mock.calls[0][0]);
     expect(payload.error.type).toBe('max_runs_exceeded');
+    expect(payload.error.message).toMatch(/Maximum LLM invocations exceeded/);
     expect(payload.error.max_runs).toBe(1);
     expect(payload.error.invocation_count).toBe(1);
   });

containers/api-proxy/server.websocket.test.js

@@ -323,14 +323,14 @@ describe('proxyWebSocket security guards', () => {
     jest.restoreAllMocks();
   });
 
-  it('blocks with 403 when max-runs limit is exceeded', () => {
+  it('blocks with 429 when max-runs limit is exceeded', () => {
     process.env.AWF_MAX_RUNS = '1';
     applyMaxRunsInvocation(); // consume the single allowed run
 
     const socket = makeMockSocket();
     wsProxy(makeUpgradeReq(), socket, Buffer.alloc(0), 'api.openai.com', {}, 'openai');
 
-    expect(socket.write).toHaveBeenCalledWith(expect.stringContaining('HTTP/1.1 403 Forbidden'));
+    expect(socket.write).toHaveBeenCalledWith(expect.stringContaining('HTTP/1.1 429 Too Many Requests'));
     expect(socket.write).toHaveBeenCalledWith(expect.stringContaining('"max_runs_exceeded"'));
     expect(socket.destroy).toHaveBeenCalled();
   });

docs/awf-config.schema.json

@@ -162,7 +162,7 @@
         "maxTurns": {
           "type": "integer",
           "minimum": 1,
-          "description": "Maximum number of LLM invocations allowed for a run. When reached, the API proxy rejects subsequent requests with HTTP 403 and error type 'max_runs_exceeded'. See spec §11."
+          "description": "Maximum number of LLM invocations allowed for a run. When reached, the API proxy rejects subsequent requests with HTTP 429 and error type 'max_runs_exceeded'. See spec §11."
         },
         "maxRuns": {
           "type": "integer",

scripts/ci/contribution-check-workflow.test.ts

@@ -34,7 +34,7 @@ describe('contribution-check workflow', () => {
   it('has conservative turn limit and appropriate model', () => {
     const source = fs.readFileSync(sourcePath, 'utf-8');
 
-    expect(source).toContain('max-turns: 3');
+    expect(source).toContain('max-turns: 4');
     expect(source).toContain('model: gpt-5.4-mini');
   });
 });

src/awf-config-schema.json

@@ -162,7 +162,7 @@
         "maxTurns": {
           "type": "integer",
           "minimum": 1,
-          "description": "Maximum number of LLM invocations allowed for a run. When reached, the API proxy rejects subsequent requests with HTTP 403 and error type 'max_runs_exceeded'. See spec §11."
+          "description": "Maximum number of LLM invocations allowed for a run. When reached, the API proxy rejects subsequent requests with HTTP 429 and error type 'max_runs_exceeded'. See spec §11."
         },
         "maxRuns": {
           "type": "integer",