harnery 0.28.0 → 0.30.0

package/src/core/supervisor/state.ts

@@ -38,6 +38,13 @@ const MAX_INTENT_BYTES = 256 * 1024;
 const MAX_TEMPLATES = 20;
 const TEMPLATE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 const FOREIGN_LEASE_STALE_MS = 24 * 60 * 60 * 1_000;
+/** Ceiling on CONSECUTIVE uncharged (upstream) replans (ADR 0046). Because an
+ * uncharged replan does not spend `max_replans`, an unending vendor outage would
+ * otherwise replan forever; this bound stops it and names the outside service.
+ * Kept low — each replan is a real planner round-trip — and a module constant
+ * rather than a policy field to keep the frozen replanning schema unchanged; an
+ * environment failure self-bounds at one because it stops immediately. */
+const MAX_UNCHARGED_REPLANS = 3;
 
 export interface SupervisorLimits {
   max_cycles: number;
@@ -322,6 +329,18 @@ function deriveProjection(
 ): SupervisorProjection {
   const root = work.find((record) => record.intent.id === plans.active_root_work_id);
   const attemptsUsed = governed.reduce((sum, record) => sum + record.projection.attempts_used, 0);
+  // The goal budget, like the per-item budget, counts only charged attempts
+  // (ADR 0046): an uncharged environment/upstream attempt on any child does not
+  // spend the goal's total. attempts_used stays the raw count for display.
+  const chargedUsed = governed.reduce((sum, record) => sum + record.projection.charged_attempts, 0);
+  // Replans, like per-item attempts (ADR 0046), are budgeted by the CHARGED
+  // count: an uncharged planner failure (environment/upstream) does not spend
+  // max_replans. replans_used stays the raw count for display.
+  const unchargedReplans = plans.plans.filter(
+    (plan) =>
+      plan.status === "failed" && (plan.class === "environment" || plan.class === "upstream"),
+  ).length;
+  const chargedReplans = plans.plans.length - unchargedReplans;
   const readyWork = work
     .filter((record) => record.projection.state === "ready")
     .map((record) => record.intent.id);
@@ -382,11 +401,11 @@ function deriveProjection(
     retryable_work: retryableWork,
     attention_work: attentionWork,
     attempts_used: attemptsUsed,
-    attempts_remaining: Math.max(0, intent.limits.max_total_attempts - attemptsUsed),
+    attempts_remaining: Math.max(0, intent.limits.max_total_attempts - chargedUsed),
     specialists: Object.keys(intent.specialists),
     plan_generation: plans.generation,
     replans_used: plans.plans.length,
-    replans_remaining: Math.max(0, (intent.replanning?.max_replans ?? 0) - plans.plans.length),
+    replans_remaining: Math.max(0, (intent.replanning?.max_replans ?? 0) - chargedReplans),
     milestones_completed: milestonesCompleted,
     milestones_remaining: Math.max(0, (intent.mission?.max_milestones ?? 0) - milestonesCompleted),
     pending_plan_id: plans.latest?.status === "proposed" ? plans.latest.request.id : undefined,
@@ -433,6 +452,46 @@ function deriveProjection(
       next_action: "replan",
     };
   }
+  // ADR 0046: a planner failure that never touched the plan is handled before
+  // the replan path. Otherwise a "failed" plan falls through to canReplan and
+  // the runner replans an unchanged environment on every tick — the failure mode
+  // that burned the measured 19 "codex not found" replans.
+  if (plans.latest?.status === "failed" && plans.latest.class === "environment") {
+    // A missing precondition (the planner binary was absent). Retrying an
+    // unchanged environment cannot help, so the goal STOPS and names it. A human
+    // who installs the binary can re-run; the failure was uncharged, so the
+    // replan budget is intact.
+    return {
+      ...base,
+      state: "blocked",
+      reason: `planning could not start; a required precondition is missing: ${plans.latest.reason ?? "the planner binary was absent"}`,
+      next_action: "none",
+    };
+  }
+  if (plans.latest?.status === "failed" && plans.latest.class === "upstream") {
+    // The vendor refused. Uncharged replans do not spend max_replans, so the
+    // only brake on an unending outage is this consecutive bound; at the limit
+    // the goal stops and names the outside service, distinct from work-blocked.
+    let trailingUncharged = 0;
+    for (let index = plans.plans.length - 1; index >= 0; index--) {
+      const plan = plans.plans[index]!;
+      if (plan.status !== "failed" || (plan.class !== "environment" && plan.class !== "upstream")) {
+        break;
+      }
+      trailingUncharged++;
+    }
+    if (trailingUncharged >= MAX_UNCHARGED_REPLANS) {
+      return {
+        ...base,
+        state: "blocked",
+        reason: `planning is blocked waiting on an outside service after ${trailingUncharged} consecutive uncharged attempt(s): ${plans.latest.reason ?? "the vendor refused"}`,
+        next_action: "none",
+      };
+    }
+    // Under the bound: fall through so the goal replans when nothing else is
+    // dispatchable — the vendor may have recovered. canReplan reads
+    // chargedReplans, so these uncharged attempts do not exhaust max_replans.
+  }
   const triggerFingerprint = supervisorGraphFingerprint({
     rootWorkId: plans.active_root_work_id,
     generation: plans.generation,
@@ -449,13 +508,11 @@ function deriveProjection(
       reason: plans.latest.reason ?? `plan ${plans.latest.request.id} requires attention`,
       attention_plan_id: plans.latest.request.id,
       next_action:
-        intent.replanning && plans.plans.length < intent.replanning.max_replans
-          ? "retry_plan"
-          : "none",
+        intent.replanning && chargedReplans < intent.replanning.max_replans ? "retry_plan" : "none",
     };
   }
   if (!root && intent.mission) {
-    if (!intent.replanning || plans.plans.length >= intent.replanning.max_replans) {
+    if (!intent.replanning || chargedReplans >= intent.replanning.max_replans) {
       return {
         ...base,
         state: "budget_exhausted",
@@ -472,7 +529,7 @@ function deriveProjection(
   }
   if (!root) throw new Error(`supervisor ${intent.id} root work is missing`);
   if (root.projection.state === "succeeded" && intent.mission) {
-    if (!intent.replanning || plans.plans.length >= intent.replanning.max_replans) {
+    if (!intent.replanning || chargedReplans >= intent.replanning.max_replans) {
       return {
         ...base,
         state: "budget_exhausted",
@@ -517,7 +574,7 @@ function deriveProjection(
       next_action: "run",
     };
   }
-  if (attemptsUsed >= intent.limits.max_total_attempts && attemptDispatchable.length > 0) {
+  if (chargedUsed >= intent.limits.max_total_attempts && attemptDispatchable.length > 0) {
     return {
       ...base,
       state: "budget_exhausted",
@@ -565,7 +622,7 @@ function deriveProjection(
       next_action: "retry",
     };
   }
-  if (attemptsUsed >= intent.limits.max_total_attempts && cancelled.length === 0) {
+  if (chargedUsed >= intent.limits.max_total_attempts && cancelled.length === 0) {
     return {
       ...base,
       state: "budget_exhausted",
@@ -575,7 +632,7 @@ function deriveProjection(
   }
   const canReplan =
     intent.replanning !== undefined &&
-    plans.plans.length < intent.replanning.max_replans &&
+    chargedReplans < intent.replanning.max_replans &&
     cancelled.length === 0 &&
     !latestHandledSameGraph;
   if (canReplan) {
@@ -590,7 +647,7 @@ function deriveProjection(
   }
   if (
     intent.replanning &&
-    plans.plans.length >= intent.replanning.max_replans &&
+    chargedReplans >= intent.replanning.max_replans &&
     cancelled.length === 0
   ) {
     return {

package/src/core/work/runner.ts

@@ -68,7 +68,11 @@ export async function runWorkItem(input: RunWorkItemInput): Promise<RunReport> {
     if (!(record.projection.state === "ready" || record.projection.state === "blocked")) {
       throw new Error(`work item ${input.workId} cannot run from state ${record.projection.state}`);
     }
-    if (record.projection.attempts_used >= record.intent.max_attempts) {
+    // Budget is spent by CHARGED attempts (ADR 0046); uncharged environment or
+    // upstream attempts don't count against it. The attempt NUMBER still comes
+    // from attempts_used so the history stays a gapless 1..N and the validator
+    // is satisfied.
+    if (record.projection.charged_attempts >= record.intent.max_attempts) {
       throw new Error(
         `work item ${input.workId} exhausted its ${record.intent.max_attempts} attempts`,
       );
@@ -132,7 +136,12 @@ function priorContext(
   coordRoot: string,
   prior: WorkAttempt,
 ): NonNullable<WorkflowAttemptContext["prior"]> {
-  if (!prior.proof_path) {
+  // An uncharged attempt (ADR 0046) produced no information about the work, so
+  // it is presented to the retry the same way a lost attempt is — carrying no
+  // proof-derived cause. Reporting its 5xx/circuit-open text as a
+  // "workflow_error" would tell the model "your code errored" for something that
+  // never ran the work.
+  if (prior.uncharged || !prior.proof_path) {
     return {
       run_id: prior.run_id,
       causes: ["lost"],

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 {