@cat-factory/executor-harness 1.43.0 → 1.43.4

package/dist/git.js

@@ -91,6 +91,81 @@ export function isGitTimeoutKill(err, aborted) {
 function gitSubcommand(args) {
     return args.find((a) => a !== '' && !a.startsWith('-')) ?? 'command';
 }
+/**
+ * Classify the common shapes of git's own stderr into an actionable remedy, else undefined
+ * (an unrecognized failure keeps just its raw stderr). This is the FIRST-WRAP-POINT for
+ * unavoidable third-party text (per the error-message initiative's I6): git's stderr is the
+ * only signal we get for a clone/push auth or access fault, so we match it ONCE here and
+ * APPEND a cause + fix, never rewrite the raw line. Host-neutral — the same remedy serves a
+ * GitHub-App installation token and a GitLab/GitHub PAT (local mode). Pure, so it is
+ * unit-tested over a fixed set of stderr strings.
+ */
+export function describeGitFailure(stderr) {
+    const s = stderr.toLowerCase();
+    // Rate-limit / abuse-detection first: the host returns these as a 403, which would
+    // otherwise fall into the write-access shape below and be mislabeled as a permission
+    // problem — but the fix is to wait, not to grant access.
+    if (/rate limit|secondary rate|abuse detection/i.test(stderr)) {
+        return ('The git host rate-limited this run (a primary/secondary rate limit or abuse-detection ' +
+            'trip). This is usually transient — wait a few minutes and retry. If it persists, reduce ' +
+            'the number of concurrent runs against this host.');
+    }
+    // Order matters: a 404 "repository not found" is sometimes GitHub's stand-in for "your
+    // token can't see this private repo", so it is checked before the generic auth shape.
+    if (/repository not found|remote:\s*not found|returned error:\s*404|fatal:\s*could not read from remote repository/i.test(stderr) &&
+        !/authentication failed|invalid username or password/i.test(s)) {
+        return ('The repository could not be found or is not visible to the credential used for this run. ' +
+            'It may have been deleted, renamed, or made private, or the GitHub App installation / access ' +
+            'token no longer has access to it. Confirm the repository still exists and that the connected ' +
+            'GitHub App (or, in local mode, the GITHUB_PAT) can see it, then retry.');
+    }
+    if (/authentication failed|invalid username or password|could not read username|could not read password|terminal prompts disabled|support for password authentication was removed|returned error:\s*401|http basic:\s*access denied/i.test(stderr)) {
+        return ('Git authentication was rejected — the credential this run used was refused. The GitHub App ' +
+            'installation token (or, in local mode, the GITHUB_PAT) is most likely expired, rotated, ' +
+            'revoked, or no longer installed on this repository. Reconnect the GitHub App for the ' +
+            'workspace (or regenerate the PAT with repo scope in local mode), then retry.');
+    }
+    if (/permission to .* denied|remote:\s*permission|protected branch|pre-receive hook declined|returned error:\s*403|http 403/i.test(stderr)) {
+        return ('Git authenticated but the credential lacks WRITE access to push to this repository. Grant ' +
+            'the connected GitHub App (or the local-mode PAT) write permission on the repo — and, if the ' +
+            'target branch is protected, the permission its branch-protection rule requires — then retry.');
+    }
+    return undefined;
+}
+/**
+ * Classify a PR/MR-open REST failure by its HTTP status into an actionable remedy, else
+ * undefined (an unmapped status keeps just the raw `Failed to open … (HTTP n)` line). Like
+ * {@link describeGitFailure} this only APPENDS a cause + fix — the raw status line is
+ * load-bearing detail and stays. `provider` tailors the scope/permission wording (GitHub App
+ * Pull-requests permission / `repo` PAT scope vs GitLab `api` scope) and the noun (pull
+ * request vs merge request). Pure, so it is unit-tested per status.
+ */
+export function describePrOpenFailure(status, provider) {
+    const noun = provider === 'gitlab' ? 'merge request' : 'pull request';
+    if (status === 401) {
+        return (`The credential was rejected while opening the ${noun}. The GitHub App installation token ` +
+            '(or, in local mode, the GITHUB_PAT) is most likely expired, rotated, or revoked — reconnect ' +
+            'the GitHub App for the workspace (or regenerate the PAT), then retry.');
+    }
+    if (status === 403) {
+        const scope = provider === 'gitlab'
+            ? 'the GitLab token needs the `api` scope and Developer+ access to the project'
+            : 'the GitHub App needs the "Pull requests: write" permission (or the PAT the `repo` scope) and write access to the repository';
+        return `The credential lacks permission to open a ${noun}: ${scope}. Grant it, then retry.`;
+    }
+    if (status === 404) {
+        return (`The repository could not be found while opening the ${noun} — it may have been deleted, ` +
+            'renamed, or made private, or the credential can no longer see it. Confirm the repo and the ' +
+            "credential's access to it, then retry.");
+    }
+    if (status === 422 || status === 400) {
+        return (`GitHub/GitLab rejected the ${noun} as invalid. Usually the head or base branch does not ` +
+            'exist, the two branches are identical (nothing to compare), or the base branch is protected ' +
+            'against direct PRs. Check the branch names and that the head has commits ahead of the base, ' +
+            'then retry.');
+    }
+    return undefined;
+}
 /**
  * Wrap a git failure into a credential-scrubbed {@link HarnessFailure}('git') with an ACCURATE
  * message. Three cases the old bare "Command failed: git …" collapsed together:
@@ -114,7 +189,12 @@ function gitFailure(err, args, aborted) {
     const stderr = typeof e?.stderr === 'string' ? e.stderr : (e?.stderr?.toString() ?? '');
     const base = e instanceof Error ? e.message : String(err);
     const combined = stderr.trim() ? `${base}\n${stderr.trim()}` : base;
-    const failure = new HarnessFailure('git', redactSecrets(combined));
+    // Append a cause + fix for the recognized auth/access shapes, keeping the raw (scrubbed)
+    // stderr above it as the detail. The remedy is static text with no secrets, so it is added
+    // after redaction.
+    const remedy = describeGitFailure(combined);
+    const message = remedy ? `${redactSecrets(combined)}\n${remedy}` : redactSecrets(combined);
+    const failure = new HarnessFailure('git', message);
     if (e?.stack)
         failure.stack = redactSecrets(e.stack);
     return failure;
@@ -834,7 +914,9 @@ export async function openPullRequest(opts) {
         // the run with GitHub's opaque 422.
         if (res.status === 422 && /no commits between/i.test(detail))
             return null;
-        throw new HarnessFailure('api', redactSecrets(`Failed to open PR (HTTP ${res.status}): ${detail.slice(0, 300)}`));
+        const remedy = describePrOpenFailure(res.status, 'github');
+        const base = redactSecrets(`Failed to open PR (HTTP ${res.status}): ${detail.slice(0, 300)}`);
+        throw new HarnessFailure('api', remedy ? `${base}\n${remedy}` : base);
     }
     const body = (await res.json());
     if (!body.html_url)
@@ -881,7 +963,9 @@ async function openGitLabMergeRequest(opts) {
             if (existing)
                 return existing;
         }
-        throw new HarnessFailure('api', redactSecrets(`Failed to open merge request (HTTP ${res.status}): ${detail.slice(0, 300)}`));
+        const remedy = describePrOpenFailure(res.status, 'gitlab');
+        const base = redactSecrets(`Failed to open merge request (HTTP ${res.status}): ${detail.slice(0, 300)}`);
+        throw new HarnessFailure('api', remedy ? `${base}\n${remedy}` : base);
     }
     const body = (await res.json());
     if (!body.web_url)

package/dist/pi.js

@@ -5,6 +5,7 @@ import { dirname, join } from 'node:path';
 import { killChildProcess, spawnDetached } from './process.js';
 import { pathExists } from './fs-utils.js';
 import { redactSecrets } from './redact.js';
+import { HarnessFailure } from './failure.js';
 import { log } from './logger.js';
 // Drives the Pi coding-agent CLI. Pi is pointed at the Worker's OpenAI-compatible
 // proxy via a custom provider in ~/.pi/agent/models.json, authenticated with the
@@ -756,18 +757,37 @@ export function runPi(opts) {
                 const runError = terminalRunError(stdout);
                 if (runError) {
                     const scrubbed = redactSecrets(runError).slice(0, 1000);
-                    reject(new Error(tail ? `${scrubbed} Agent stderr: ${tail}` : scrubbed));
+                    const detail = tail ? `${scrubbed} Agent stderr: ${tail}` : scrubbed;
+                    reject(piRunFailure(detail, runError));
                 }
                 else {
                     resolve({ ...summarizePiRun(stdout), ...(tail ? { stderrTail: tail } : {}) });
                 }
             }
             else {
-                reject(new Error(`pi exited with code ${code}: ${(stderr || stdout).slice(-500)}`));
+                // A non-zero exit is the OTHER way a proxy refusal can surface (Pi crashing rather
+                // than exiting 0 after exhausting retries), so classify it here too — otherwise a
+                // 401/402/429 that happens to crash Pi would read as a generic agent failure. Redact
+                // the transcript slice before it becomes the detail: unlike the exit-0 path above, the
+                // raw `stderr`/`stdout` here was previously interpolated unscrubbed.
+                const raw = (stderr || stdout).slice(-500);
+                reject(piRunFailure(`pi exited with code ${code}: ${redactSecrets(raw)}`, raw));
             }
         });
     });
 }
+/**
+ * Build the rejection for a failed Pi run: if its terminal text points at the LLM proxy
+ * refusing every model call (auth/quota/rate-limit), stamp the structured `llm-upstream`
+ * cause with the remedy APPENDED after the detail (keeping the raw line first, matching the
+ * git/PR-open classifiers); otherwise a plain Error (→ the generic `agent` cause). Shared by
+ * both the exit-0 terminal-error path and the non-zero exit path so a proxy refusal is
+ * classified the same whether Pi survives it or crashes on it.
+ */
+function piRunFailure(detail, sourceText) {
+    const remedy = classifyLlmUpstreamError(sourceText);
+    return remedy ? new HarnessFailure('llm-upstream', `${detail}\n${remedy}`) : new Error(detail);
+}
 /** Parse Pi's LF-framed JSONL stdout into its event records, skipping noise. */
 function parsePiEvents(stdout) {
     const events = [];
@@ -813,6 +833,37 @@ export function terminalRunError(stdout) {
     }
     return undefined;
 }
+/**
+ * Classify a terminal run error whose text points at the LLM PROXY rejecting every model call
+ * (auth / quota / rate-limit) into an actionable remedy, else undefined. All model traffic goes
+ * through the Worker's OpenAI-compatible proxy, so a 401/402/429 surfaced in Pi's `finalError`
+ * means the leased provider key was refused, is out of credit, or was rate-limited — none of
+ * which is an agent bug. This is the first-wrap-point for Pi's own error text (per the
+ * error-message initiative's I6): we match it ONCE here and let the caller stamp the structured
+ * `llm-upstream` cause + this remedy. Pure, so it is unit-tested over fixed error strings.
+ */
+export function classifyLlmUpstreamError(finalError) {
+    const s = finalError.toLowerCase();
+    // 402 / quota / credit — check before the generic auth shape (a 402 body can also say
+    // "unauthorized"-ish things, but a payment/quota signal is the more actionable cause).
+    if (/\b402\b|payment required|insufficient (?:funds|quota|credit|balance)|out of (?:quota|credit)|quota exceeded|billing/i.test(finalError)) {
+        return ('The model provider rejected the run: the account is out of quota or credit (HTTP 402). ' +
+            'Top up or raise the limit with the provider, or switch to a provider key that has quota in ' +
+            'the workspace AI key pool (Configure AI), then retry.');
+    }
+    if (/\b429\b|too many requests|rate.?limit/i.test(finalError) &&
+        !/\b401\b|\b402\b|\b403\b/.test(finalError)) {
+        return ('The model provider rate-limited the run (HTTP 429) and the agent exhausted its automatic ' +
+            'retries. This is usually transient — wait a moment and retry. If it persists, reduce ' +
+            'concurrent runs or use a provider key / plan with a higher rate limit in the AI key pool.');
+    }
+    if (/\b401\b|\b403\b|unauthorized|forbidden|invalid api key|authentication|invalid.*token/i.test(s)) {
+        return ('The model provider rejected the run: the API credential was refused (HTTP 401/403). The ' +
+            'provider key in the workspace AI key pool is most likely invalid, revoked, or expired — ' +
+            're-enter it under the AI provider keys (Configure AI), then retry.');
+    }
+    return undefined;
+}
 /**
  * Pi's assistant summary plus {@link PiRunStats}, derived from one pass over its
  * output — the canonical close-of-run signal the harness uses both to report the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.43.0",
+  "version": "1.43.4",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -22,12 +22,12 @@
   },
   "devDependencies": {
     "@hono/node-server": "^2.0.8",
-    "@types/node": "^26.0.0",
-    "hono": "^4.12.27",
+    "@types/node": "^26.1.1",
+    "hono": "^4.12.29",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.9",
-    "@cat-factory/server": "0.108.0",
-    "@cat-factory/spend": "0.12.10"
+    "vitest": "^4.1.10",
+    "@cat-factory/server": "0.113.5",
+    "@cat-factory/spend": "0.12.26"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/failure.ts

@@ -22,6 +22,8 @@
  *  - `agent`              — the agent ran but produced an unusable/failed result, or threw.
  *  - `git`                — a git operation failed (clone/push/merge/PR).
  *  - `api`                — an upstream API call failed (e.g. the GitHub/GitLab PR/MR REST call).
+ *  - `llm-upstream`       — the model provider rejected every call (auth/quota/rate-limit) and Pi
+ *                           exhausted its retries, so the run never produced a result.
  *  - `no-usable-output`   — the agent finished but returned no usable report / structured output.
  *  - `no-changes`         — a coding agent finished without producing any change to push.
  */
@@ -31,6 +33,7 @@ export type FailureCause =
   | 'agent'
   | 'git'
   | 'api'
+  | 'llm-upstream'
   | 'no-usable-output'
   | 'no-changes'
 

package/src/git.ts

@@ -112,6 +112,113 @@ function gitSubcommand(args: string[]): string {
   return args.find((a) => a !== '' && !a.startsWith('-')) ?? 'command'
 }
 
+/**
+ * Classify the common shapes of git's own stderr into an actionable remedy, else undefined
+ * (an unrecognized failure keeps just its raw stderr). This is the FIRST-WRAP-POINT for
+ * unavoidable third-party text (per the error-message initiative's I6): git's stderr is the
+ * only signal we get for a clone/push auth or access fault, so we match it ONCE here and
+ * APPEND a cause + fix, never rewrite the raw line. Host-neutral — the same remedy serves a
+ * GitHub-App installation token and a GitLab/GitHub PAT (local mode). Pure, so it is
+ * unit-tested over a fixed set of stderr strings.
+ */
+export function describeGitFailure(stderr: string): string | undefined {
+  const s = stderr.toLowerCase()
+  // Rate-limit / abuse-detection first: the host returns these as a 403, which would
+  // otherwise fall into the write-access shape below and be mislabeled as a permission
+  // problem — but the fix is to wait, not to grant access.
+  if (/rate limit|secondary rate|abuse detection/i.test(stderr)) {
+    return (
+      'The git host rate-limited this run (a primary/secondary rate limit or abuse-detection ' +
+      'trip). This is usually transient — wait a few minutes and retry. If it persists, reduce ' +
+      'the number of concurrent runs against this host.'
+    )
+  }
+  // Order matters: a 404 "repository not found" is sometimes GitHub's stand-in for "your
+  // token can't see this private repo", so it is checked before the generic auth shape.
+  if (
+    /repository not found|remote:\s*not found|returned error:\s*404|fatal:\s*could not read from remote repository/i.test(
+      stderr,
+    ) &&
+    !/authentication failed|invalid username or password/i.test(s)
+  ) {
+    return (
+      'The repository could not be found or is not visible to the credential used for this run. ' +
+      'It may have been deleted, renamed, or made private, or the GitHub App installation / access ' +
+      'token no longer has access to it. Confirm the repository still exists and that the connected ' +
+      'GitHub App (or, in local mode, the GITHUB_PAT) can see it, then retry.'
+    )
+  }
+  if (
+    /authentication failed|invalid username or password|could not read username|could not read password|terminal prompts disabled|support for password authentication was removed|returned error:\s*401|http basic:\s*access denied/i.test(
+      stderr,
+    )
+  ) {
+    return (
+      'Git authentication was rejected — the credential this run used was refused. The GitHub App ' +
+      'installation token (or, in local mode, the GITHUB_PAT) is most likely expired, rotated, ' +
+      'revoked, or no longer installed on this repository. Reconnect the GitHub App for the ' +
+      'workspace (or regenerate the PAT with repo scope in local mode), then retry.'
+    )
+  }
+  if (
+    /permission to .* denied|remote:\s*permission|protected branch|pre-receive hook declined|returned error:\s*403|http 403/i.test(
+      stderr,
+    )
+  ) {
+    return (
+      'Git authenticated but the credential lacks WRITE access to push to this repository. Grant ' +
+      'the connected GitHub App (or the local-mode PAT) write permission on the repo — and, if the ' +
+      'target branch is protected, the permission its branch-protection rule requires — then retry.'
+    )
+  }
+  return undefined
+}
+
+/**
+ * Classify a PR/MR-open REST failure by its HTTP status into an actionable remedy, else
+ * undefined (an unmapped status keeps just the raw `Failed to open … (HTTP n)` line). Like
+ * {@link describeGitFailure} this only APPENDS a cause + fix — the raw status line is
+ * load-bearing detail and stays. `provider` tailors the scope/permission wording (GitHub App
+ * Pull-requests permission / `repo` PAT scope vs GitLab `api` scope) and the noun (pull
+ * request vs merge request). Pure, so it is unit-tested per status.
+ */
+export function describePrOpenFailure(
+  status: number,
+  provider: 'github' | 'gitlab',
+): string | undefined {
+  const noun = provider === 'gitlab' ? 'merge request' : 'pull request'
+  if (status === 401) {
+    return (
+      `The credential was rejected while opening the ${noun}. The GitHub App installation token ` +
+      '(or, in local mode, the GITHUB_PAT) is most likely expired, rotated, or revoked — reconnect ' +
+      'the GitHub App for the workspace (or regenerate the PAT), then retry.'
+    )
+  }
+  if (status === 403) {
+    const scope =
+      provider === 'gitlab'
+        ? 'the GitLab token needs the `api` scope and Developer+ access to the project'
+        : 'the GitHub App needs the "Pull requests: write" permission (or the PAT the `repo` scope) and write access to the repository'
+    return `The credential lacks permission to open a ${noun}: ${scope}. Grant it, then retry.`
+  }
+  if (status === 404) {
+    return (
+      `The repository could not be found while opening the ${noun} — it may have been deleted, ` +
+      'renamed, or made private, or the credential can no longer see it. Confirm the repo and the ' +
+      "credential's access to it, then retry."
+    )
+  }
+  if (status === 422 || status === 400) {
+    return (
+      `GitHub/GitLab rejected the ${noun} as invalid. Usually the head or base branch does not ` +
+      'exist, the two branches are identical (nothing to compare), or the base branch is protected ' +
+      'against direct PRs. Check the branch names and that the head has commits ahead of the base, ' +
+      'then retry.'
+    )
+  }
+  return undefined
+}
+
 /**
  * Wrap a git failure into a credential-scrubbed {@link HarnessFailure}('git') with an ACCURATE
  * message. Three cases the old bare "Command failed: git …" collapsed together:
@@ -139,7 +246,12 @@ function gitFailure(err: unknown, args: string[], aborted: boolean): HarnessFail
   const stderr = typeof e?.stderr === 'string' ? e.stderr : (e?.stderr?.toString() ?? '')
   const base = e instanceof Error ? e.message : String(err)
   const combined = stderr.trim() ? `${base}\n${stderr.trim()}` : base
-  const failure = new HarnessFailure('git', redactSecrets(combined))
+  // Append a cause + fix for the recognized auth/access shapes, keeping the raw (scrubbed)
+  // stderr above it as the detail. The remedy is static text with no secrets, so it is added
+  // after redaction.
+  const remedy = describeGitFailure(combined)
+  const message = remedy ? `${redactSecrets(combined)}\n${remedy}` : redactSecrets(combined)
+  const failure = new HarnessFailure('git', message)
   if (e?.stack) failure.stack = redactSecrets(e.stack)
   return failure
 }
@@ -1017,10 +1129,9 @@ export async function openPullRequest(opts: OpenPullRequestOptions): Promise<str
     // from base). Signal it with null so the caller records a clean no-op instead of failing
     // the run with GitHub's opaque 422.
     if (res.status === 422 && /no commits between/i.test(detail)) return null
-    throw new HarnessFailure(
-      'api',
-      redactSecrets(`Failed to open PR (HTTP ${res.status}): ${detail.slice(0, 300)}`),
-    )
+    const remedy = describePrOpenFailure(res.status, 'github')
+    const base = redactSecrets(`Failed to open PR (HTTP ${res.status}): ${detail.slice(0, 300)}`)
+    throw new HarnessFailure('api', remedy ? `${base}\n${remedy}` : base)
   }
   const body = (await res.json()) as { html_url?: string }
   if (!body.html_url) throw new HarnessFailure('api', 'GitHub did not return a PR url')
@@ -1075,10 +1186,11 @@ async function openGitLabMergeRequest(
       const existing = await findOpenMergeRequestUrl(apiBase, project, opts)
       if (existing) return existing
     }
-    throw new HarnessFailure(
-      'api',
-      redactSecrets(`Failed to open merge request (HTTP ${res.status}): ${detail.slice(0, 300)}`),
+    const remedy = describePrOpenFailure(res.status, 'gitlab')
+    const base = redactSecrets(
+      `Failed to open merge request (HTTP ${res.status}): ${detail.slice(0, 300)}`,
     )
+    throw new HarnessFailure('api', remedy ? `${base}\n${remedy}` : base)
   }
   const body = (await res.json()) as { web_url?: string }
   if (!body.web_url) throw new HarnessFailure('api', 'GitLab did not return a merge request url')

package/src/pi.ts

@@ -5,6 +5,7 @@ import { dirname, join } from 'node:path'
 import { killChildProcess, spawnDetached } from './process.js'
 import { pathExists } from './fs-utils.js'
 import { redactSecrets } from './redact.js'
+import { HarnessFailure } from './failure.js'
 import { log } from './logger.js'
 
 // Drives the Pi coding-agent CLI. Pi is pointed at the Worker's OpenAI-compatible
@@ -1061,17 +1062,37 @@ export function runPi(opts: {
         const runError = terminalRunError(stdout)
         if (runError) {
           const scrubbed = redactSecrets(runError).slice(0, 1000)
-          reject(new Error(tail ? `${scrubbed} Agent stderr: ${tail}` : scrubbed))
+          const detail = tail ? `${scrubbed} Agent stderr: ${tail}` : scrubbed
+          reject(piRunFailure(detail, runError))
         } else {
           resolve({ ...summarizePiRun(stdout), ...(tail ? { stderrTail: tail } : {}) })
         }
       } else {
-        reject(new Error(`pi exited with code ${code}: ${(stderr || stdout).slice(-500)}`))
+        // A non-zero exit is the OTHER way a proxy refusal can surface (Pi crashing rather
+        // than exiting 0 after exhausting retries), so classify it here too — otherwise a
+        // 401/402/429 that happens to crash Pi would read as a generic agent failure. Redact
+        // the transcript slice before it becomes the detail: unlike the exit-0 path above, the
+        // raw `stderr`/`stdout` here was previously interpolated unscrubbed.
+        const raw = (stderr || stdout).slice(-500)
+        reject(piRunFailure(`pi exited with code ${code}: ${redactSecrets(raw)}`, raw))
       }
     })
   })
 }
 
+/**
+ * Build the rejection for a failed Pi run: if its terminal text points at the LLM proxy
+ * refusing every model call (auth/quota/rate-limit), stamp the structured `llm-upstream`
+ * cause with the remedy APPENDED after the detail (keeping the raw line first, matching the
+ * git/PR-open classifiers); otherwise a plain Error (→ the generic `agent` cause). Shared by
+ * both the exit-0 terminal-error path and the non-zero exit path so a proxy refusal is
+ * classified the same whether Pi survives it or crashes on it.
+ */
+function piRunFailure(detail: string, sourceText: string): Error {
+  const remedy = classifyLlmUpstreamError(sourceText)
+  return remedy ? new HarnessFailure('llm-upstream', `${detail}\n${remedy}`) : new Error(detail)
+}
+
 /** Parse Pi's LF-framed JSONL stdout into its event records, skipping noise. */
 function parsePiEvents(stdout: string): Record<string, unknown>[] {
   const events: Record<string, unknown>[] = []
@@ -1117,6 +1138,52 @@ export function terminalRunError(stdout: string): string | undefined {
   return undefined
 }
 
+/**
+ * Classify a terminal run error whose text points at the LLM PROXY rejecting every model call
+ * (auth / quota / rate-limit) into an actionable remedy, else undefined. All model traffic goes
+ * through the Worker's OpenAI-compatible proxy, so a 401/402/429 surfaced in Pi's `finalError`
+ * means the leased provider key was refused, is out of credit, or was rate-limited — none of
+ * which is an agent bug. This is the first-wrap-point for Pi's own error text (per the
+ * error-message initiative's I6): we match it ONCE here and let the caller stamp the structured
+ * `llm-upstream` cause + this remedy. Pure, so it is unit-tested over fixed error strings.
+ */
+export function classifyLlmUpstreamError(finalError: string): string | undefined {
+  const s = finalError.toLowerCase()
+  // 402 / quota / credit — check before the generic auth shape (a 402 body can also say
+  // "unauthorized"-ish things, but a payment/quota signal is the more actionable cause).
+  if (
+    /\b402\b|payment required|insufficient (?:funds|quota|credit|balance)|out of (?:quota|credit)|quota exceeded|billing/i.test(
+      finalError,
+    )
+  ) {
+    return (
+      'The model provider rejected the run: the account is out of quota or credit (HTTP 402). ' +
+      'Top up or raise the limit with the provider, or switch to a provider key that has quota in ' +
+      'the workspace AI key pool (Configure AI), then retry.'
+    )
+  }
+  if (
+    /\b429\b|too many requests|rate.?limit/i.test(finalError) &&
+    !/\b401\b|\b402\b|\b403\b/.test(finalError)
+  ) {
+    return (
+      'The model provider rate-limited the run (HTTP 429) and the agent exhausted its automatic ' +
+      'retries. This is usually transient — wait a moment and retry. If it persists, reduce ' +
+      'concurrent runs or use a provider key / plan with a higher rate limit in the AI key pool.'
+    )
+  }
+  if (
+    /\b401\b|\b403\b|unauthorized|forbidden|invalid api key|authentication|invalid.*token/i.test(s)
+  ) {
+    return (
+      'The model provider rejected the run: the API credential was refused (HTTP 401/403). The ' +
+      'provider key in the workspace AI key pool is most likely invalid, revoked, or expired — ' +
+      're-enter it under the AI provider keys (Configure AI), then retry.'
+    )
+  }
+  return undefined
+}
+
 /**
  * Pi's assistant summary plus {@link PiRunStats}, derived from one pass over its
  * output — the canonical close-of-run signal the harness uses both to report the