harnery 0.29.0 → 0.30.0

package/src/core/work/state.ts

@@ -39,6 +39,12 @@ const MAX_EVENTS_BYTES = 4 * 1024 * 1024;
 const MAX_EVENT_BYTES = 16 * 1024;
 const MAX_EVENTS = 1_000;
 const FOREIGN_LEASE_STALE_MS = 24 * 60 * 60 * 1_000;
+/** Default ceiling on consecutive uncharged attempts (ADR 0046). Kept low: each
+ * one is a real vendor round-trip, so a handful gives a transient outage room
+ * to recover before the item stops and names the outside service. There is no
+ * backoff between them beyond the cadence of the supervisor and the vendor's own
+ * responses, which is why the bound stays small. */
+const DEFAULT_MAX_UNCHARGED_ATTEMPTS = 3;
 
 export type WorkState =
   | "waiting"
@@ -71,6 +77,12 @@ export interface WorkIntent {
   dependencies: string[];
   workflow: { path: string; sha256: string };
   max_attempts: number;
+  /** Ceiling on CONSECUTIVE uncharged attempts (ADR 0046), separate from
+   * max_attempts. An upstream outage produces uncharged attempt after uncharged
+   * attempt; without a bound it would retry forever. At the bound the item stops
+   * and reports it is blocked on an outside service. Optional for back-compat:
+   * an intent written before ADR 0046 has none and falls back to the default. */
+  max_uncharged_attempts?: number;
   source?: { kind: "human" | "workflow" | "external"; ref?: string };
   created_at: string;
 }
@@ -128,6 +140,10 @@ export interface WorkAttempt {
   approval_id?: string;
   proof_path?: string;
   journal_error?: string;
+  /** Why this failed attempt was uninformative about the work (ADR 0046), read
+   * from the proof's run.class. Absent ⇒ the attempt is charged, exactly as
+   * before ADR 0046 (which is also how a proof without a class reads). */
+  uncharged?: "environment" | "upstream";
 }
 
 export interface WorkProjection {
@@ -138,7 +154,13 @@ export interface WorkProjection {
   next_action: WorkNextAction;
   unresolved_dependencies: string[];
   attempts: WorkAttempt[];
+  /** Every attempt started, charged or not. Drives the next attempt number and
+   * history ordering, so it counts uncharged attempts too. */
   attempts_used: number;
+  /** Attempts that were informative about the work (ADR 0046). This — not
+   * attempts_used — is what max_attempts budgets, so an uncharged environment or
+   * upstream attempt does not consume the retry budget. */
+  charged_attempts: number;
   attempts_remaining: number;
   latest_run_id?: string;
   approval_id?: string;
@@ -160,6 +182,7 @@ export interface CreateWorkItemInput {
   acceptance?: string[];
   dependencies?: string[];
   maxAttempts?: number;
+  maxUnchargedAttempts?: number;
   source?: WorkIntent["source"];
   id?: string;
   actor?: string;
@@ -188,6 +211,14 @@ export function createWorkItem(input: CreateWorkItemInput): WorkRecord {
   if (!Number.isSafeInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 100) {
     throw new Error("work maxAttempts must be an integer from 1 to 100");
   }
+  const maxUnchargedAttempts = input.maxUnchargedAttempts ?? DEFAULT_MAX_UNCHARGED_ATTEMPTS;
+  if (
+    !Number.isSafeInteger(maxUnchargedAttempts) ||
+    maxUnchargedAttempts < 1 ||
+    maxUnchargedAttempts > 100
+  ) {
+    throw new Error("work maxUnchargedAttempts must be an integer from 1 to 100");
+  }
   const acceptance = (input.acceptance ?? []).map((value, index) =>
     boundedString(value, `work acceptance[${index}]`, MAX_ACCEPTANCE_ITEM),
   );
@@ -204,6 +235,7 @@ export function createWorkItem(input: CreateWorkItemInput): WorkRecord {
     dependencies,
     workflow: { path: workflowPath, sha256: workflowScriptDigest(workflowPath) },
     max_attempts: maxAttempts,
+    max_uncharged_attempts: maxUnchargedAttempts,
     source,
     created_at: new Date().toISOString(),
   };
@@ -375,13 +407,18 @@ function deriveWorkProjection(
   const attempts = attemptEvents.map((event, index) =>
     inspectAttempt(coordRoot, event, intent, attemptEvents[index - 1]?.run_id),
   );
+  // Charged attempts — not the raw count — are what max_attempts budgets
+  // (ADR 0046). An uncharged environment/upstream attempt still increments
+  // attempts_used (ordering + next number) but not the budget.
+  const chargedAttempts = attempts.filter((attempt) => attempt.uncharged === undefined).length;
   const base = {
     id: intent.id,
     title: intent.title,
     unresolved_dependencies: [] as string[],
     attempts,
     attempts_used: attempts.length,
-    attempts_remaining: Math.max(0, intent.max_attempts - attempts.length),
+    charged_attempts: chargedAttempts,
+    attempts_remaining: Math.max(0, intent.max_attempts - chargedAttempts),
     latest_run_id: attempts.at(-1)?.run_id,
     approval_id: attempts.at(-1)?.approval_id,
     proof_path: attempts.at(-1)?.proof_path,
@@ -462,7 +499,7 @@ function deriveWorkProjection(
       next_action: "review",
     };
   }
-  const attemptsRemaining = intent.max_attempts - attempts.length;
+  const attemptsRemaining = intent.max_attempts - chargedAttempts;
   if (latest.status === "journal_unreadable") {
     return {
       ...base,
@@ -473,6 +510,49 @@ function deriveWorkProjection(
       next_action: attemptsRemaining > 0 ? "retry" : "none",
     };
   }
+  // Uncharged failures (ADR 0046) are handled before the ordinary work-failure
+  // path: they did not touch the work, so they neither spent the budget nor
+  // signal that retrying the work would help.
+  if (latest.status === "failed" && latest.uncharged === "environment") {
+    // A missing precondition. The operator chose to STOP the item immediately
+    // rather than retry an unchanged environment (ADR 0046); next_action "none"
+    // stops the supervisor. A human who fixes the environment can still force a
+    // retry — the attempt was uncharged, so the budget is intact.
+    return {
+      ...base,
+      state: "blocked",
+      reason: environmentBlockedReason(latest),
+      next_action: "none",
+    };
+  }
+  if (latest.status === "failed" && latest.uncharged === "upstream") {
+    // Count trailing consecutive uncharged attempts in the current window. The
+    // bound is the only brake on an outage that never ends, so at the limit the
+    // item stops and names the outside service — distinct from work-blocked.
+    const maxUncharged = intent.max_uncharged_attempts ?? DEFAULT_MAX_UNCHARGED_ATTEMPTS;
+    let trailingUncharged = 0;
+    for (let index = currentAttempts.length - 1; index >= 0; index--) {
+      if (currentAttempts[index]!.uncharged === undefined) break;
+      trailingUncharged++;
+    }
+    if (trailingUncharged >= maxUncharged || attemptsRemaining <= 0) {
+      return {
+        ...base,
+        state: "blocked",
+        reason:
+          trailingUncharged >= maxUncharged
+            ? `blocked waiting on an outside service after ${trailingUncharged} consecutive uncharged attempt(s): ${upstreamReason(latest)}`
+            : `workflow attempt ${latest.number} was uncharged (${upstreamReason(latest)}) but the work attempt budget is exhausted`,
+        next_action: "none",
+      };
+    }
+    return {
+      ...base,
+      state: "blocked",
+      reason: `workflow attempt ${latest.number} did not touch the work; an outside service refused: ${upstreamReason(latest)}`,
+      next_action: "retry",
+    };
+  }
   return {
     ...base,
     state: "blocked",
@@ -484,6 +564,33 @@ function deriveWorkProjection(
   };
 }
 
+/** The failure reason for an uncharged attempt, read from the proof when
+ * present. Bounded so a verbose vendor transcript cannot bloat the projection
+ * reason (which is persisted verbatim into the reconciliation event). */
+function unchargedProofError(attempt: WorkAttempt): string | undefined {
+  if (!attempt.proof_path) return undefined;
+  try {
+    const proof = parseObject(readFileSync(attempt.proof_path, "utf8"), "workflow proof");
+    const run = proof.run;
+    const error =
+      run && typeof run === "object" ? (run as Record<string, unknown>).error : undefined;
+    return typeof error === "string" && error.trim() ? boundedJournalError(error) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function environmentBlockedReason(attempt: WorkAttempt): string {
+  const detail = unchargedProofError(attempt);
+  return detail
+    ? `workflow attempt ${attempt.number} could not start; a required precondition is missing: ${detail}`
+    : `workflow attempt ${attempt.number} could not start; a required precondition is missing`;
+}
+
+function upstreamReason(attempt: WorkAttempt): string {
+  return unchargedProofError(attempt) ?? "the vendor was reached and refused";
+}
+
 function inspectAttempt(
   coordRoot: string,
   event: WorkEvent,
@@ -547,6 +654,15 @@ function inspectAttempt(
       proof.acceptance.summary.unknown === 0
         ? "succeeded"
         : "failed";
+    // A failed attempt the run classified as uninformative about the work is
+    // uncharged (ADR 0046). Absent class ⇒ charged, as before. Read only for a
+    // failed attempt: a succeeded run never carries a class.
+    if (
+      attempt.status === "failed" &&
+      (proof.run.class === "environment" || proof.run.class === "upstream")
+    ) {
+      attempt.uncharged = proof.run.class;
+    }
     return attempt;
   }
   const journalPath = workflowJournalPath(coordRoot, runId);
@@ -882,7 +998,13 @@ function validateWorkIntent(intent: WorkIntent, workId: string): void {
     !/^[a-f0-9]{64}$/.test(intent.workflow.sha256) ||
     !Number.isSafeInteger(intent.max_attempts) ||
     intent.max_attempts < 1 ||
-    intent.max_attempts > 100
+    intent.max_attempts > 100 ||
+    // Optional for back-compat: absent on pre-ADR-0046 intents. When present it
+    // must be a valid bound.
+    (intent.max_uncharged_attempts !== undefined &&
+      (!Number.isSafeInteger(intent.max_uncharged_attempts) ||
+        intent.max_uncharged_attempts < 1 ||
+        intent.max_uncharged_attempts > 100))
   ) {
     throw new Error(`work intent ${workId} has an unsupported or mismatched schema`);
   }

package/src/core/workflow/engine.ts

@@ -911,6 +911,11 @@ async function executeWorkflow(
 
         if (!last.ok) {
           journal("agent.attempt_failed", { id, attempt, error: last.error });
+          // ADR 0046: an environment failure (the binary was absent) cannot be
+          // helped by retrying an unchanged environment, so stop the in-agent
+          // retry too — not just the outer attempt/replan budget. An upstream
+          // refusal keeps retrying here: the vendor may recover mid-loop.
+          if (last.class === "environment") break;
           continue; // spawn-level failure: retry with the original prompt
         }
         if (!agentOpts.schema) {
@@ -982,6 +987,12 @@ async function executeWorkflow(
         agentCostUsd > 0 || last?.costUsd !== undefined ? agentCostUsd : undefined;
       agentProof.session_id = last?.sessionId;
       agentProof.error = reason;
+      // Carry the spawn class (environment/upstream) onto the proof only when the
+      // final outcome was a spawn failure. A schema failure after a spawn that
+      // reached the model is a work failure — left unclassed (charged). An
+      // earlier attempt that transiently failed and then succeeded returned
+      // above, so this only fires when the agent genuinely failed.
+      if (last && !last.ok && last.class) agentProof.class = last.class;
       journal("agent.failed", { id, error: reason });
       throw new Error(`agent ${proofLabel}: ${reason}`);
     } catch (error) {

package/src/core/workflow/index.ts

@@ -25,6 +25,7 @@ export { runWorkflow, WorkflowParkedError, WorkflowRunError } from "./engine.ts"
 export {
   buildWorkflowProof,
   createEvidenceRecord,
+  deriveRunFailureClass,
   digestResult,
   normalizeWorkflowMeta,
   readWorkflowProof,
@@ -43,6 +44,7 @@ export {
   workflowScriptDigest,
   writeWorkflowRunManifest,
 } from "./run-state.ts";
+export { isUpstreamFailureText, vendorFailureText } from "./spawn-failure.ts";
 export type {
   AcceptanceCriterion,
   AcceptanceResult,
@@ -59,6 +61,7 @@ export type {
   ResultDigest,
   RunReport,
   Spawner,
+  SpawnFailureClass,
   SpawnRequest,
   SpawnResult,
   StageSchema,

package/src/core/workflow/proof.ts

@@ -20,6 +20,7 @@ import type {
   HarnessEvidenceCapability,
   HarnessEvidenceCoverage,
   ResultDigest,
+  SpawnFailureClass,
   WorkflowAgentProof,
   WorkflowAttemptContext,
   WorkflowEvidenceInput,
@@ -218,6 +219,36 @@ export function digestResult(value: unknown, kind?: "text" | "json"): ResultDige
   };
 }
 
+/**
+ * The run-level failure class (ADR 0046), derived from the agents rather than a
+ * single terminal throw so it survives a script's `parallel()` swallowing the
+ * rejection — a swallowed agent's proof is still recorded with its class.
+ *
+ * Rules, in order, all in service of "default to charging":
+ * 1. A succeeded run is never classed (there is nothing uncharged about it).
+ * 2. If ANY agent produced a result (succeeded or replayed from cache) the
+ *    attempt was informative about the work — charge it. This also keeps a
+ *    resumed run whose earlier segment did real work from being written off by
+ *    a later environment failure.
+ * 3. Otherwise, among the failed agents, environment wins over upstream: a
+ *    missing binary means nothing ran at all, and it is the operator-chosen
+ *    hard stop.
+ * 4. Anything else is undefined ⇒ a charged work failure, exactly as today.
+ */
+export function deriveRunFailureClass(
+  status: "succeeded" | "failed",
+  agents: readonly Pick<WorkflowAgentProof, "status" | "class">[],
+): SpawnFailureClass | undefined {
+  if (status !== "failed") return undefined;
+  if (agents.some((agent) => agent.status === "succeeded" || agent.status === "cached")) {
+    return undefined;
+  }
+  const failed = agents.filter((agent) => agent.status === "failed");
+  if (failed.some((agent) => agent.class === "environment")) return "environment";
+  if (failed.some((agent) => agent.class === "upstream")) return "upstream";
+  return undefined;
+}
+
 export function buildWorkflowProof(input: BuildWorkflowProofInput): WorkflowProof {
   const acceptance = rollupAcceptance(input.meta.acceptance, input.evidence);
   const repository = buildRepoEvidence(input.before, input.after);
@@ -231,6 +262,7 @@ export function buildWorkflowProof(input: BuildWorkflowProofInput): WorkflowProo
   }));
   const harnesses = buildHarnessCoverage(agents, input.harnessEvidence, input.harnessAttestations);
   const unknowns = buildUnknowns(agents, harnesses, repository);
+  const runClass = deriveRunFailureClass(input.status, agents);
   const journal = readFileSync(input.journalPath);
   return {
     schema_version: WORKFLOW_PROOF_SCHEMA_VERSION,
@@ -247,6 +279,7 @@ export function buildWorkflowProof(input: BuildWorkflowProofInput): WorkflowProo
       objective: input.meta.objective,
       error: clippedOptional(input.error, MAX_SUMMARY_CHARS),
       result: input.result === undefined ? undefined : digestResult(input.result),
+      ...(runClass ? { class: runClass } : {}),
     },
     acceptance,
     agents,
@@ -326,6 +359,9 @@ export function readWorkflowProof(coordRoot: string, runId: string): WorkflowPro
   if (
     proof.schema_version !== WORKFLOW_PROOF_SCHEMA_VERSION ||
     proof.run?.id !== runId ||
+    (proof.run.class !== undefined &&
+      proof.run.class !== "environment" &&
+      proof.run.class !== "upstream") ||
     (proof.run.work_context !== undefined &&
       (!proof.run.work_item_id ||
         proof.run.work_context.id !== proof.run.work_item_id ||

package/src/core/workflow/spawn-claude.ts

@@ -24,7 +24,7 @@ import type { HarnessInvocation, HarnessRawResult } from "../harnesses/types.ts"
 import { buildChildEnv } from "./child-env.ts";
 import { notFoundError } from "./harnesses.ts";
 import { resolveSandboxProjection } from "./sandbox-projection.ts";
-import { vendorFailureText } from "./spawn-failure.ts";
+import { isUpstreamFailureText, vendorFailureText } from "./spawn-failure.ts";
 import type { Spawner, SpawnRequest, SpawnResult } from "./types.ts";
 
 interface ClaudeEnvelope {
@@ -70,7 +70,20 @@ export function normalizeClaudeResult(raw: HarnessRawResult): SpawnResult {
       error: `claude timed out after ${raw.durationMs}ms and was killed`,
     };
   }
+  // Structural environment signal: the binary was never there (spawned directly,
+  // so a missing binary surfaces as ENOENT). Uncharged and not retried.
+  if (raw.spawnErrno === "ENOENT") {
+    return {
+      ok: false,
+      text: "",
+      durationMs: raw.durationMs,
+      error: notFoundError("claude-code"),
+      class: "environment",
+    };
+  }
   if (raw.exitCode === 127) {
+    // A bare 127 with no errno is a shell/vendor 127, indistinguishable from a
+    // legitimate one — charged as work rather than classed environment.
     return {
       ok: false,
       text: "",
@@ -79,11 +92,13 @@ export function normalizeClaudeResult(raw: HarnessRawResult): SpawnResult {
     };
   }
   if (raw.exitCode !== 0) {
+    const failureText = vendorFailureText(raw);
     return {
       ok: false,
       text: "",
       durationMs: raw.durationMs,
-      error: `claude exited ${raw.exitCode}: ${vendorFailureText(raw)}`,
+      error: `claude exited ${raw.exitCode}: ${failureText}`,
+      ...(isUpstreamFailureText(failureText) ? { class: "upstream" as const } : {}),
     };
   }
 
@@ -100,6 +115,9 @@ export function normalizeClaudeResult(raw: HarnessRawResult): SpawnResult {
   }
 
   if (envelope.is_error) {
+    const envelopeError = `${envelope.subtype ?? ""} ${(envelope.errors ?? []).join("; ")} ${String(
+      envelope.result ?? "",
+    )}`;
     return {
       ok: false,
       text: String(envelope.result ?? ""),
@@ -107,6 +125,7 @@ export function normalizeClaudeResult(raw: HarnessRawResult): SpawnResult {
       costUsd: envelope.total_cost_usd,
       durationMs: raw.durationMs,
       error: `harness error (${envelope.subtype ?? "unknown"}): ${(envelope.errors ?? []).join("; ") || "see envelope"}`,
+      ...(isUpstreamFailureText(envelopeError) ? { class: "upstream" as const } : {}),
     };
   }
 

package/src/core/workflow/spawn-codex.ts

@@ -25,7 +25,7 @@ import type { HarnessInvocation, HarnessRawResult } from "../harnesses/types.ts"
 import { buildChildEnv } from "./child-env.ts";
 import { notFoundError } from "./harnesses.ts";
 import { resolveSandboxProjection } from "./sandbox-projection.ts";
-import { vendorFailureText } from "./spawn-failure.ts";
+import { isUpstreamFailureText, vendorFailureText } from "./spawn-failure.ts";
 import type { Spawner, SpawnRequest, SpawnResult } from "./types.ts";
 
 export function buildCodexInvocation(req: SpawnRequest, resultFile?: string): HarnessInvocation {
@@ -69,15 +69,30 @@ export function normalizeCodexResult(raw: HarnessRawResult): SpawnResult {
       error: `codex timed out after ${raw.durationMs}ms and was killed`,
     };
   }
+  // Structural environment signal: the binary was never there (spawned directly,
+  // so a missing binary surfaces as ENOENT). Uncharged and not retried.
+  if (raw.spawnErrno === "ENOENT") {
+    return {
+      ok: false,
+      text: "",
+      durationMs: raw.durationMs,
+      error: notFoundError("codex"),
+      class: "environment",
+    };
+  }
   if (raw.exitCode === 127) {
+    // A bare 127 with no errno is a shell/vendor 127, indistinguishable from a
+    // legitimate one — charged as work rather than classed environment.
     return { ok: false, text: "", durationMs: raw.durationMs, error: notFoundError("codex") };
   }
   if (raw.exitCode !== 0) {
+    const failureText = vendorFailureText(raw);
     return {
       ok: false,
       text: "",
       durationMs: raw.durationMs,
-      error: `codex exited ${raw.exitCode}: ${vendorFailureText(raw)}`,
+      error: `codex exited ${raw.exitCode}: ${failureText}`,
+      ...(isUpstreamFailureText(failureText) ? { class: "upstream" as const } : {}),
     };
   }
   return {

package/src/core/workflow/spawn-cursor.ts

@@ -25,7 +25,7 @@ import type { HarnessInvocation, HarnessRawResult } from "../harnesses/types.ts"
 import { buildChildEnv } from "./child-env.ts";
 import { notFoundError } from "./harnesses.ts";
 import { resolveSandboxProjection } from "./sandbox-projection.ts";
-import { vendorFailureText } from "./spawn-failure.ts";
+import { isUpstreamFailureText, vendorFailureText } from "./spawn-failure.ts";
 import type { Spawner, SpawnRequest, SpawnResult } from "./types.ts";
 
 interface CursorEnvelope {
@@ -82,15 +82,30 @@ export function normalizeCursorResult(raw: HarnessRawResult): SpawnResult {
       error: `cursor timed out after ${raw.durationMs}ms and was killed`,
     };
   }
+  // Structural environment signal: the binary was never there (spawned directly,
+  // so a missing binary surfaces as ENOENT). Uncharged and not retried.
+  if (raw.spawnErrno === "ENOENT") {
+    return {
+      ok: false,
+      text: "",
+      durationMs: raw.durationMs,
+      error: notFoundError("cursor"),
+      class: "environment",
+    };
+  }
   if (raw.exitCode === 127) {
+    // A bare 127 with no errno is a shell/vendor 127, indistinguishable from a
+    // legitimate one — charged as work rather than classed environment.
     return { ok: false, text: "", durationMs: raw.durationMs, error: notFoundError("cursor") };
   }
   if (raw.exitCode !== 0) {
+    const failureText = vendorFailureText(raw);
     return {
       ok: false,
       text: "",
       durationMs: raw.durationMs,
-      error: `cursor-agent exited ${raw.exitCode}: ${vendorFailureText(raw)}`,
+      error: `cursor-agent exited ${raw.exitCode}: ${failureText}`,
+      ...(isUpstreamFailureText(failureText) ? { class: "upstream" as const } : {}),
     };
   }
 
@@ -102,6 +117,7 @@ export function normalizeCursorResult(raw: HarnessRawResult): SpawnResult {
       sessionId: parsed.sessionId,
       durationMs: raw.durationMs,
       error: `cursor-agent reported is_error: ${parsed.text.slice(0, 300)}`,
+      ...(isUpstreamFailureText(parsed.text) ? { class: "upstream" as const } : {}),
     };
   }
   return {

package/src/core/workflow/spawn-failure.ts

@@ -26,3 +26,43 @@ export function vendorFailureText(
   const combined = parts.join("\n");
   return combined.length > maxChars ? `…${combined.slice(-maxChars)}` : combined;
 }
+
+// A 429 or 5xx status, but only where it sits in HTTP-status CONTEXT — not any
+// digits that merely happen to fall in that range. A bare-number match treats a
+// line number ("at line 500"), an item count ("got 429 items"), or a duration
+// ("after 502 seconds") as an upstream refusal, which wrongly withholds a charge
+// for a failure that was entirely our code. Three recognized shapes:
+//   1. after an "HTTP" label:  "HTTP 429", "HTTP/1.1 503 Service Unavailable"
+//   2. after a "status" label: "status 500", "status: 429", "status code 502"
+//   3. a bare status line:     "503 Service Unavailable" (code at line start,
+//      then a reason phrase) — the classic "<code> <Reason-Phrase>" shape.
+// The trailing `(?![0-9])` and the label/line-start anchors also keep a status
+// embedded in a longer number ("4295"/"5031") out. All 5xx are server-side; 429
+// is the only 4xx that means "reached and refused, retry later".
+const STATUS = "(?:429|5[0-9]{2})";
+const UPSTREAM_STATUS = new RegExp(
+  `(?:\\bHTTP\\b[/0-9. ]*|\\bstatus(?:\\s*code)?\\b[\\s:=]*)${STATUS}(?![0-9])` +
+    `|(?:^|\\n)\\s*${STATUS}\\s+[A-Za-z]`,
+  "i",
+);
+// Explicit vendor wording for the same conditions when a numeric status is
+// absent. Deliberately short — see isUpstreamFailureText.
+const UPSTREAM_PHRASES =
+  /circuit[ _-]?open|service unavailable|too many requests|rate[ _-]?limit|overloaded|bad gateway|gateway time-?out|internal server error/i;
+
+/**
+ * Whether failure text names an UPSTREAM refusal — the vendor was reached and
+ * refused (a 5xx/429 status or circuit-open wording), as opposed to a work
+ * failure (the model ran and produced a wrong or incomplete result).
+ *
+ * There is no structural upstream signal the way ENOENT structurally marks a
+ * missing binary, so this is the one text match in the classifier. It is kept
+ * SHORT and documented on purpose: a per-vendor regex zoo would rot, and a
+ * false positive here wrongly withholds a charge, so both the phrase list and
+ * the numeric match stay tight — the number must sit in HTTP-status context, not
+ * merely fall in the 429/5xx range. Anything it does not match falls through to
+ * a charged work failure.
+ */
+export function isUpstreamFailureText(text: string): boolean {
+  return UPSTREAM_STATUS.test(text) || UPSTREAM_PHRASES.test(text);
+}

package/src/core/workflow/types.ts

@@ -99,6 +99,11 @@ export interface WorkflowAgentProof {
   session_id?: string;
   result?: ResultDigest;
   error?: string;
+  /** Set on a failed agent whose spawn was classified uninformative about the
+   * work (ADR 0046): environment (binary absent) or upstream (vendor refused).
+   * Absent ⇒ a work failure. Recorded even when a script's parallel() swallows
+   * the rejection, so the run-level class can still be derived from proof. */
+  class?: SpawnFailureClass;
 }
 
 export interface WorkflowRepoSnapshot {
@@ -186,6 +191,12 @@ export interface WorkflowProof {
     objective?: string;
     error?: string;
     result?: ResultDigest;
+    /** Set on a failed run that was uninformative about the work (ADR 0046):
+     * environment or upstream. Derived from the agents' classes when no agent
+     * produced a result; absent ⇒ the attempt is charged as before. The durable
+     * work projection reads this to decide charging, stopping, and the
+     * uncharged-attempt bound. */
+    class?: SpawnFailureClass;
   };
   acceptance: {
     criteria: AcceptanceResult[];
@@ -298,6 +309,19 @@ export interface WorkflowSpecialistProfile {
   maxTurns?: number;
 }
 
+/**
+ * Why a failed run was uninformative about the work (ADR 0046). Absent means
+ * the attempt produced information about the work (or succeeded), which is the
+ * default and is charged against the attempt budget exactly as before.
+ *
+ * - `environment`: the run never started — a precondition was missing (the
+ *   vendor binary was absent). Uncharged AND not retried: retrying an unchanged
+ *   environment cannot help, so the work item stops and names the precondition.
+ * - `upstream`: the vendor was reached and refused (5xx, 429, circuit open).
+ *   Uncharged, but retry stays available (bounded by max_uncharged_attempts).
+ */
+export type SpawnFailureClass = "environment" | "upstream";
+
 /** What a spawn adapter returns for one subagent run. */
 export interface SpawnResult {
   ok: boolean;
@@ -309,6 +333,9 @@ export interface SpawnResult {
   durationMs: number;
   /** Populated when ok=false. */
   error?: string;
+  /** Set when ok=false and the failure was positively identified as
+   * uninformative about the work. Absent ⇒ a work failure (charged). */
+  class?: SpawnFailureClass;
 }
 
 export interface SpawnRequest {

package/src/lib/exec.ts

@@ -17,6 +17,13 @@ export interface ExecResult {
    * child that handles the signal cleanly still exits 0, so the exit code alone
    * cannot distinguish a kill from an ordinary finish. */
   timedOut?: boolean;
+  /** The `code` from a spawn-level failure (`proc` "error" event), e.g.
+   * "ENOENT" when the binary is absent. Absent for an ordinary process exit.
+   * We collapse such failures to exitCode 127 so callers' exit-code branches
+   * still fire, but a shell can legitimately exit 127 too; only this field
+   * distinguishes "the binary was never there" from "the process ran and exited
+   * 127". The process that knows reports it (as ADR 0044 did for `timedOut`). */
+  spawnErrno?: string;
 }
 
 export interface ExecOpts {
@@ -56,7 +63,7 @@ export function exec(cmd: string[], opts: ExecOpts = {}): Promise<ExecResult> {
       proc.kill();
     }, timeout);
 
-    const finish = (exitCode: number, errOverride?: string): void => {
+    const finish = (exitCode: number, errOverride?: string, spawnErrno?: string): void => {
       clearTimeout(timer);
       const stdout = Buffer.concat(out).toString("utf-8");
       const stderr = errOverride ?? Buffer.concat(err).toString("utf-8");
@@ -66,13 +73,16 @@ export function exec(cmd: string[], opts: ExecOpts = {}): Promise<ExecResult> {
         stderr: shouldTrim ? stderr.trim() : stderr.replace(/\n$/, ""),
         exitCode,
         ...(timedOut ? { timedOut: true } : {}),
+        ...(spawnErrno ? { spawnErrno } : {}),
       });
     };
 
     // ENOENT (binary not found) and similar spawn failures surface here rather
     // than throwing: resolve with 127 + the message so callers' exitCode
-    // branches handle it instead of crashing on an unhandled rejection.
-    proc.on("error", (e: Error) => finish(127, e.message));
+    // branches handle it instead of crashing on an unhandled rejection. The
+    // errno (e.g. "ENOENT") is carried through so a real missing binary is
+    // distinguishable from a shell that merely exited 127.
+    proc.on("error", (e: Error) => finish(127, e.message, (e as NodeJS.ErrnoException).code));
     proc.on("close", (code) => finish(code ?? 1));
   });
 }