@dungle-scrubs/harness-cli-normalizer 0.4.4 → 0.4.6

package/src/cli/run.ts

@@ -1,16 +1,72 @@
+import { existsSync } from "node:fs";
 import type { HarnessEvent } from "../execution/events.js";
+import { failureFromRejected } from "../execution/failure.js";
 import { nodeRunnerDeps } from "../execution/node-deps.js";
 import { KILL_GRACE_MS, redactArgv, streamTurn } from "../execution/stream-turn.js";
 import { buildLaunchArgv, buildResumeArgv } from "../interpretation/argv.js";
 import { composeEscalatedPrompt } from "../interpretation/question.js";
+import type { RefusalIssue } from "../interpretation/refusal.js";
 import { ArgvRefusalError } from "../interpretation/refusal.js";
 import { FloorExceededError, resolveEffectiveOptions } from "../interpretation/resolve-options.js";
+import { storePath } from "../interpretation/store.js";
 import { recognizeNativeSpelling, supportedBy } from "../interpretation/support.js";
 import { defaultDescriptors } from "../knowledge/overrides.js";
 import { parseRunExtra, parseTurnOptions, resolvePromptAsync } from "./args.js";
 import { createRenderState, renderEvent, writeEventNdjson } from "./render.js";
 import { resolveHarness } from "./resolve-harness.js";
 
+/** One shape for every hcn-side refusal. Stderr keeps the prose (message,
+ * hint, support lists, usage pointer); under --json the same fields also
+ * ride stdout as a `failure` event plus a `done`, so a stream reader never
+ * meets an empty stream on exit 2. */
+interface Refusal {
+  readonly message: string;
+  readonly issue: RefusalIssue;
+  readonly option?: ArgvRefusalError["option"];
+  readonly facet?: ArgvRefusalError["facet"];
+  readonly supported?: readonly string[];
+  readonly supportedBy?: ArgvRefusalError["supportedBy"];
+  readonly hint?: string;
+  /** Plain stderr lines written after the structured ones. */
+  readonly trailer?: readonly string[];
+}
+
+const refusalOf = (err: ArgvRefusalError): Refusal => ({
+  message: err.message,
+  issue: err.issue,
+  option: err.option,
+  facet: err.facet,
+  supported: err.supported,
+  supportedBy: err.supportedBy,
+  hint: err.hint,
+});
+
+const refuse = (r: Refusal, json: boolean): void => {
+  process.stderr.write(`${r.message}\n`);
+  if (r.hint) process.stderr.write(`hint: ${r.hint}\n`);
+  if (r.supportedBy?.length) {
+    process.stderr.write(
+      `supported on: ${r.supportedBy.map((e) => `${e.harness} (${e.spelling})`).join(", ")}\n`,
+    );
+  }
+  if (r.supported?.length) process.stderr.write(`supported: ${r.supported.join(", ")}\n`);
+  for (const line of r.trailer ?? []) process.stderr.write(`${line}\n`);
+  if (json) {
+    const summary = failureFromRejected({
+      issue: r.issue,
+      option: r.option,
+      facet: r.facet,
+      supported: r.supported,
+      supportedBy: r.supportedBy,
+      hint: r.hint,
+      detail: r.message,
+    });
+    writeEventNdjson({ kind: "failure", ...summary });
+    writeEventNdjson({ kind: "done", exitCode: null, cause: "failed", failure: summary });
+  }
+  process.exitCode = 2;
+};
+
 export const run = async (harnessName: string, rawArgs: string[]): Promise<void> => {
   const h = resolveHarness(harnessName);
 
@@ -23,7 +79,10 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
   const { parseCommonFlags, detectPositionalPromptInjection, splitPassthrough } = await import(
     "./args.js"
   );
-  const { passthrough } = splitPassthrough(rawArgs);
+  const { normalized, passthrough } = splitPassthrough(rawArgs);
+  // Decided before any refusal can fire: a refused --json run still owes
+  // the stream a failure and a done.
+  const wantJson = normalized.includes("--json");
   const injection = detectPositionalPromptInjection(rawArgs);
   if (injection) {
     const err = new ArgvRefusalError({
@@ -32,9 +91,7 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
       supported: ["prompt must not start with '-'"],
       detail: `it would be parsed as a flag by ${h.bin}`,
     });
-    process.stderr.write(`${err.message}\n`);
-    process.stderr.write(`supported: prompt must not start with '-'\n`);
-    process.exitCode = 2;
+    refuse(refusalOf(err), wantJson);
     return;
   }
   let parsed: ReturnType<typeof parseCommonFlags>;
@@ -77,19 +134,25 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
           : native.option.startsWith("discovery.")
             ? `--no-${native.option.split(".")[1] === "instructionFiles" ? "instruction-files" : native.option.split(".")[1]}`
             : `--${native.option}`;
-      process.stderr.write(
-        `unknown flag: ${rawFlag} is a native spelling (used by ${native.entries.map((e) => e.harness).join(", ")}) - use the normalized ${normalizedSpelling} flag instead\n`,
+      refuse(
+        {
+          message: `unknown flag: ${rawFlag} is a native spelling (used by ${native.entries.map((e) => e.harness).join(", ")}) - use the normalized ${normalizedSpelling} flag instead`,
+          issue: "invalid-option-value",
+          supportedBy: by,
+          trailer: ["Run 'hcn run --help' for usage."],
+        },
+        wantJson,
       );
-      if (by.length > 0) {
-        process.stderr.write(
-          `supported on: ${by.map((e) => `${e.harness} (${e.spelling})`).join(", ")}\n`,
-        );
-      }
-    } else {
-      process.stderr.write(`unknown flag: ${message}\n`);
+      return;
     }
-    process.stderr.write(`Run 'hcn run --help' for usage.\n`);
-    process.exitCode = 2;
+    refuse(
+      {
+        message: `unknown flag: ${message}`,
+        issue: "invalid-option-value",
+        trailer: ["Run 'hcn run --help' for usage."],
+      },
+      wantJson,
+    );
     return;
   }
 
@@ -98,18 +161,26 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
   // positionals may contain prompt if not using flag; harness already consumed so first positional is prompt
   const positionalPrompt = positionals.length > 0 ? positionals[0] : undefined;
   if (positionals.length > 1) {
-    process.stderr.write(`too many positionals for run; expected one prompt\n`);
-    process.exitCode = 2;
+    refuse(
+      {
+        message: "too many positionals for run; expected one prompt",
+        issue: "invalid-option-value",
+      },
+      wantJson,
+    );
     return;
   }
   if (passthrough.length === 0 && rawArgs.includes("--")) {
-    process.stderr.write(`-- separator given but no passthrough tokens followed it\n`);
-    process.exitCode = 2;
+    refuse(
+      {
+        message: "-- separator given but no passthrough tokens followed it",
+        issue: "invalid-option-value",
+      },
+      wantJson,
+    );
     return;
   }
 
-  const wantJson = values.json === true;
-
   // Resolve prompt (async for --prompt-file -)
   let prompt: string;
   let promptSource: string;
@@ -123,20 +194,14 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     promptSource = resolved.source;
   } catch (err) {
     if (err instanceof ArgvRefusalError) {
-      process.stderr.write(`${err.message}\n`);
-      if (err.hint) process.stderr.write(`hint: ${err.hint}\n`);
-      if (err.supportedBy?.length) {
-        process.stderr.write(
-          `supported on: ${err.supportedBy.map((e) => `${e.harness} (${e.spelling})`).join(", ")}\n`,
-        );
-      }
-      if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
-      process.exitCode = 2;
+      refuse(refusalOf(err), wantJson);
       return;
     }
     if (err instanceof Error && (err as NodeJS.ErrnoException).code === "ENOENT") {
-      process.stderr.write(`prompt file not found: ${(err as Error).message}\n`);
-      process.exitCode = 2;
+      refuse(
+        { message: `prompt file not found: ${err.message}`, issue: "invalid-option-value" },
+        wantJson,
+      );
       return;
     }
     throw err;
@@ -148,15 +213,7 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     turnOpts = parseTurnOptions(values);
   } catch (err) {
     if (err instanceof ArgvRefusalError) {
-      process.stderr.write(`${err.message}\n`);
-      if (err.hint) process.stderr.write(`hint: ${err.hint}\n`);
-      if (err.supportedBy?.length) {
-        process.stderr.write(
-          `supported on: ${err.supportedBy.map((e) => `${e.harness} (${e.spelling})`).join(", ")}\n`,
-        );
-      }
-      if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
-      process.exitCode = 2;
+      refuse(refusalOf(err), wantJson);
       return;
     }
     throw err;
@@ -167,15 +224,7 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     extra = parseRunExtra(values);
   } catch (err) {
     if (err instanceof ArgvRefusalError) {
-      process.stderr.write(`${err.message}\n`);
-      if (err.hint) process.stderr.write(`hint: ${err.hint}\n`);
-      if (err.supportedBy?.length) {
-        process.stderr.write(
-          `supported on: ${err.supportedBy.map((e) => `${e.harness} (${e.spelling})`).join(", ")}\n`,
-        );
-      }
-      if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
-      process.exitCode = 2;
+      refuse(refusalOf(err), wantJson);
       return;
     }
     throw err;
@@ -189,7 +238,7 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
   if (rawSkills !== undefined && rawSkills.length > 0) {
     try {
       const { resolveSkillNames, listKnownSkills } = await import("./skills-root.js");
-      const resolvedSkills = resolveSkillNames(rawSkills);
+      const resolvedSkills = resolveSkillNames(rawSkills, h.name);
       const claudeTokens: string[] = [];
       if (h.name === "claude") {
         const { claudeSkillOverridesArg } = await import("../interpretation/skills-selection.js");
@@ -199,9 +248,7 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
       (turnOpts as unknown as Record<string, unknown>).__claudeSkillTokens = claudeTokens;
     } catch (err) {
       if (err instanceof ArgvRefusalError) {
-        process.stderr.write(`${err.message}\n`);
-        if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
-        process.exitCode = 2;
+        refuse(refusalOf(err), wantJson);
         return;
       }
       throw err;
@@ -230,8 +277,10 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
       if (proj !== null) tiers.project = proj.config;
     } catch (configErr) {
       if (configErr instanceof ConfigError) {
-        process.stderr.write(`config error: ${(configErr as Error).message}\n`);
-        process.exitCode = 2;
+        refuse(
+          { message: `config error: ${configErr.message}`, issue: "invalid-option-value" },
+          wantJson,
+        );
         return;
       }
       throw configErr;
@@ -243,8 +292,7 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
       resolved = resolveEffectiveOptions(h, { ...turnOpts, prompt } as never, tiers);
     } catch (resErr) {
       if (resErr instanceof FloorExceededError) {
-        process.stderr.write(`${(resErr as Error).message}\n`);
-        process.exitCode = 2;
+        refuse({ message: resErr.message, issue: "invalid-tool-grant" }, wantJson);
         return;
       }
       throw resErr;
@@ -254,18 +302,8 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     effectiveTurnOpts = rest as ReturnType<typeof parseTurnOptions>;
     // Provenance is diagnostic data like the spawn line - stderr in BOTH
     // render modes, never stdout (stdout carries the NDJSON contract).
-    if (provenance.length > 0 || unrenderable.length > 0) {
-      for (const entry of provenance) {
-        process.stderr.write(
-          `provenance: ${entry.key} = ${JSON.stringify(entry.value)} (${entry.tier})\n`,
-        );
-      }
-      for (const key of unrenderable) {
-        process.stderr.write(
-          `divergence: profile ${JSON.stringify(key)} not expressible on ${h.name}; harness default applies\n`,
-        );
-      }
-    }
+    const { writeProvenance } = await import("./provenance.js");
+    writeProvenance(h.name, provenance, unrenderable);
   }
 
   // issue #41: question-escalation precedence arg > project > user >
@@ -342,15 +380,7 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     _validated = true;
   } catch (err) {
     if (err instanceof ArgvRefusalError) {
-      process.stderr.write(`${err.message}\n`);
-      if (err.hint) process.stderr.write(`hint: ${err.hint}\n`);
-      if (err.supportedBy?.length) {
-        process.stderr.write(
-          `supported on: ${err.supportedBy.map((e) => `${e.harness} (${e.spelling})`).join(", ")}\n`,
-        );
-      }
-      if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
-      process.exitCode = 2;
+      refuse(refusalOf(err), wantJson);
       return;
     }
     throw err;
@@ -372,6 +402,51 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     process.stderr.write(
       `provenance: escalateQuestions = ${escalateQuestions} (${escalateTier})\n`,
     );
+    // On a harness whose include flag is not a strict allowlist (claude),
+    // a name outside the curated set passes through ungated; say which
+    // ones so a wrong-case name is visible. A grant with no known name at
+    // all refuses inside buildLaunchArgv below, so a throw here is left
+    // to that path.
+    const grant = (fullOpts.resume ? turnOpts : effectiveTurnOpts).tools;
+    if (grant !== undefined && grant.length > 0 && !h.tools.includeIsStrictAllowlist) {
+      try {
+        const { renderToolSelection } = await import("../interpretation/tool-selection.js");
+        const { unmapped } = renderToolSelection(h, { include: [...grant] });
+        if (unmapped.length > 0) {
+          process.stderr.write(`provenance: unmapped tools = ${JSON.stringify(unmapped)}\n`);
+        }
+      } catch {
+        // refused below with the structured message
+      }
+    }
+  }
+
+  // A harness that creates a session when the id is unknown (pi, muse)
+  // would turn a stale --resume into a silent blank session. Refuse when
+  // the session store path does not exist; where the path cannot be
+  // computed, the runner's pre-spawn warning is the only guard.
+  if (fullOpts.resume !== undefined && h.resume.onMissing === "create") {
+    let path: string | null = null;
+    try {
+      path = storePath(h, {
+        home: process.env.HOME ?? process.env.USERPROFILE ?? "",
+        cwd: extra.cwd ?? process.cwd(),
+        sessionId: fullOpts.resume,
+      });
+    } catch {
+      path = null;
+    }
+    if (path !== null && !existsSync(path)) {
+      refuse(
+        {
+          message: `no ${h.name} session ${fullOpts.resume} found at ${path}`,
+          issue: "invalid-option-value",
+          supported: [`a session id that exists in ${h.name}'s store`],
+        },
+        wantJson,
+      );
+      return;
+    }
   }
 
   // Delete HERDR_ENV before spawn
@@ -393,7 +468,7 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
   const _currentProc: { signal: (sig: "SIGTERM" | "SIGKILL") => void } | null = null;
   // We'll need to track the spawned process via deps.signal; but streamTurn owns process handle.
   // Instead we intercept deps.signal via a wrapper that captures proc.
-  // Simpler: use deps directly and handle SIGINT by calling process.kill? But spec says via injected signal.
+  // Simpler: use deps directly and handle SIGINT via injected signal.
   // We'll create a wrapper deps where signal captures last proc.
   let lastProc: import("../execution/deps.js").SpawnedProcess | null = null;
   const originalSignal = deps.signal;
@@ -410,23 +485,25 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     },
   };
 
+  const abortController = new AbortController();
   let interrupted = false;
+  let escalationTimer: ReturnType<typeof setTimeout> | null = null;
   const onSig = async () => {
     if (interrupted) return;
     interrupted = true;
+    abortController.abort();
     if (lastProc) {
       try {
         wrappedDeps.signal(lastProc, "SIGTERM");
-        await new Promise<void>((resolve) => {
-          setTimeout(() => {
-            if (lastProc) {
-              try {
-                wrappedDeps.signal(lastProc, "SIGKILL");
-              } catch {}
-            }
-            resolve();
-          }, KILL_GRACE_MS);
-        });
+        escalationTimer = setTimeout(() => {
+          if (lastProc) {
+            try {
+              wrappedDeps.signal(lastProc, "SIGKILL");
+            } catch {}
+          }
+          escalationTimer = null;
+        }, KILL_GRACE_MS);
+        escalationTimer.unref?.();
       } catch {}
     }
   };
@@ -439,7 +516,7 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
 
   try {
     // streamTurn handles both launch and resume via TurnRunOptions
-    const events = streamTurn(h, fullOpts, wrappedDeps);
+    const events = streamTurn(h, { ...fullOpts, signal: abortController.signal }, wrappedDeps);
     for await (const event of events) {
       lastEvent = event;
       if (wantJson) {
@@ -492,6 +569,10 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     process.off("SIGTERM", onSig);
     return;
   } finally {
+    if (escalationTimer !== null) {
+      clearTimeout(escalationTimer);
+      escalationTimer = null;
+    }
     process.off("SIGINT", onSig);
     process.off("SIGTERM", onSig);
   }

package/src/cli/session.ts

@@ -3,6 +3,8 @@ import { createInterface } from "node:readline/promises";
 import { nodeRunnerDeps } from "../execution/node-deps.js";
 import { CLOSE_GRACE_MS, openSession } from "../execution/open-session.js";
 import { ArgvRefusalError } from "../interpretation/refusal.js";
+import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import { defaultDescriptors } from "../knowledge/overrides.js";
 import { createRenderState, renderEvent } from "./render.js";
 import { resolveHarness } from "./resolve-harness.js";
 
@@ -12,9 +14,8 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
   // session mode is available the moment its descriptor declares one.
   const h = resolveHarness(harnessName);
   if (h.sessionMode === null) {
-    const supported = ["claude", "codex", "pi", "muse"]
-      .map((name) => resolveHarness(name))
-      .filter((d) => d.sessionMode !== null)
+    const supported = Object.values(defaultDescriptors())
+      .filter((d): d is HarnessDescriptor => d !== undefined && d.sessionMode !== null)
       .map((d) => d.name);
     const err = new ArgvRefusalError({
       issue: "no-session-mode",

package/src/cli/skills-root.ts

@@ -12,6 +12,7 @@ import { existsSync, readdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { ArgvRefusalError } from "../interpretation/refusal.js";
+import type { HarnessName } from "../knowledge/descriptor.js";
 
 export const skillsRoot = (): string =>
   process.env.HCN_SKILLS_ROOT ?? join(homedir(), ".agents", "skills");
@@ -30,16 +31,22 @@ export const listKnownSkills = (): string[] => {
   });
 };
 
-export const resolveSkillNames = (names: readonly string[]): string[] => {
+export const resolveSkillNames = (
+  names: readonly string[],
+  harness: HarnessName = "claude",
+): string[] => {
   const root = skillsRoot();
   const known = new Set(listKnownSkills());
   const unknown = names.filter((n) => !known.has(n));
   if (unknown.length > 0) {
     throw new ArgvRefusalError({
-      issue: "unknown-tool-name",
-      harness: "claude",
+      issue: "invalid-option-value",
+      harness,
       option: "skills",
-      supported: known.size > 0 ? [[...known].join(", ")] : ["(registry is empty)"],
+      supported:
+        known.size > 0
+          ? [`registry at ${root}`, [...known].join(", ")]
+          : [`registry at ${root} (empty)`],
       detail: `unknown skill name(s): ${unknown.join(", ")}`,
     });
   }

package/src/execution/decode.ts

@@ -4,12 +4,13 @@
  * caller threads (identity dedupe per D-022). Unparseable lines on a
  * structured stream are tolerated - scanned for walls, never fatal.
  */
-import { capabilitiesOf } from "../interpretation/capabilities.js";
+import { type CapabilityResult, capabilitiesOf } from "../interpretation/capabilities.js";
 import { contentEventsOf } from "../interpretation/content.js";
 import { decodeIdentity } from "../interpretation/identity.js";
 import { detectLimitInLine } from "../interpretation/limits.js";
-import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import type { HarnessDescriptor, StreamingGranularity } from "../knowledge/descriptor.js";
 import type { HarnessEvent } from "./events.js";
+import { failureFromBudget } from "./failure.js";
 
 export interface DecodeState {
   lastSeenId: string | null;
@@ -30,6 +31,7 @@ export const decodeLine = (
   line: string,
   state: DecodeState,
   model: string,
+  streaming?: StreamingGranularity,
 ): HarnessEvent[] => {
   let raw: unknown;
   try {
@@ -43,7 +45,7 @@ export const decodeLine = (
     }
     return [];
   }
-  return decodeParsed(h, raw, state, model);
+  return decodeParsed(h, raw, state, model, streaming);
 };
 
 /** The parsed-record half of decodeLine, for pumps that already parsed the
@@ -54,27 +56,59 @@ export const decodeParsed = (
   raw: unknown,
   state: DecodeState,
   model: string,
+  streaming?: StreamingGranularity,
 ): HarnessEvent[] => {
   const events: HarnessEvent[] = [];
+  // Streaming is a property of the spawned argv, not of the model, so the
+  // runner passes what streamingGranularityOf computed for it; the curated
+  // baseline supplies the rest. An unknown model stays unknown throughout.
+  const capabilities = (): CapabilityResult => {
+    const base = capabilitiesOf(h, model, "headless-turn");
+    return streaming !== undefined && base.source !== "unknown" ? { ...base, streaming } : base;
+  };
   const decoded = decodeIdentity(h, raw, state.lastSeenId, state.requestedId);
   if (decoded.sessionId !== null) state.lastSeenId = decoded.sessionId;
   if (decoded.identity !== null) {
+    const authority = state.requestedId !== null ? "caller-assigned" : "harness-minted";
     events.push({
       kind: "identity",
       sessionId: decoded.identity,
-      authority: h.identity.authority,
-      capabilities: capabilitiesOf(h, model, "headless-turn"),
+      authority,
+      capabilities: capabilities(),
     });
   } else if (decoded.outcome === "malformed" || decoded.outcome === "rotated") {
-    // The interpretation layer classified an identity anomaly; swallowing
-    // it would leave the runner waiting for an identity that already
-    // failed to arrive (or bind a rotated one).
-    events.push({ kind: "error", message: `identity ${decoded.outcome}` });
+    if (decoded.outcome === "rotated") {
+      const requested = state.requestedId ?? "unknown";
+      const announced = decoded.sessionId ?? "unknown";
+      events.push({
+        kind: "error",
+        message: `identity rotated: requested ${requested} but announced ${announced}`,
+      });
+      // The harness answered under a different id: hand the consumer the
+      // id it can actually resume, marked as minted by the harness.
+      if (decoded.sessionId !== null) {
+        events.push({
+          kind: "identity",
+          sessionId: decoded.sessionId,
+          authority: "harness-minted",
+          capabilities: capabilities(),
+        });
+      }
+    } else {
+      events.push({ kind: "error", message: `identity ${decoded.outcome}` });
+    }
   }
 
-  // Content (message/token/tool/error) is per-harness; identity above is
-  // descriptor-driven. contentEventsOf dispatches by harness name.
-  for (const content of contentEventsOf(h.name, raw)) events.push(content);
+  // Content (message/token/tool/error/budget) is per-harness; identity
+  // above is descriptor-driven. contentEventsOf dispatches by harness
+  // name. budget is not a HarnessEvent kind and must not leak out.
+  for (const content of contentEventsOf(h.name, raw)) {
+    if (content.kind === "budget") {
+      events.push({ kind: "failure", ...failureFromBudget(content.detail) });
+    } else {
+      events.push(content);
+    }
+  }
 
   // claude's rate_limit_event: only non-"allowed" statuses are failures.
   // overageStatus is deliberately not classified - it is a separate

package/src/execution/deps.ts

@@ -1,6 +1,6 @@
 /**
  * Injected runtime primitives (D-005): the execution layer never imports
- * child_process, never calls process.kill, and never reads a wall clock -
+ * child_process, never signals the process directly, and never reads a wall clock -
  * spawn, clock, and signalling arrive as data so Node/Bun is a real
  * portability boundary and tests run against fakes deterministically.
  */
@@ -16,6 +16,9 @@ export interface SpawnedProcess {
   /** Resolves with the exit code, or null when the process died to a
    * signal without one. */
   readonly exited: Promise<number | null>;
+  /** After `exited` settles, the spawn-time error message when the child
+   * never started (async ENOENT and the like), else null. */
+  readonly startupError?: () => string | null;
   /** Present when the spawner opened a writable stdin (session mode needs
    * it; one-shot turns close or inherit stdin instead). */
   readonly stdin?: {

package/src/execution/events.ts

@@ -15,6 +15,7 @@
  * concatenate both.
  */
 import type { CapabilityResult } from "../interpretation/capabilities.js";
+import type { LimitCode } from "../knowledge/descriptor.js";
 import type { FailureSummary } from "./failure.js";
 
 export type ExitCause =
@@ -49,8 +50,10 @@ export type HarnessEvent =
       readonly options: readonly string[];
       readonly recommended?: string;
     }
-  | { readonly kind: "limit"; readonly code: string; readonly message: string }
-  | { readonly kind: "error"; readonly message: string }
+  | { readonly kind: "limit"; readonly code: LimitCode; readonly message: string }
+  /** `terminal: true` marks an error that ended the turn; the matching
+   * `failure` (class task) follows it. */
+  | { readonly kind: "error"; readonly message: string; readonly terminal?: boolean }
   | ({ readonly kind: "failure" } & FailureSummary)
   | {
       readonly kind: "done";

package/src/execution/failure.ts

@@ -13,8 +13,14 @@
  * options or a different harness, not a different model.
  */
 
+import { detectAuthFailureInLine, detectTransportInLine } from "../interpretation/limits.js";
 import type { RefusalIssue } from "../interpretation/refusal.js";
-import type { AuthFailureKind, DiscoveryFacet, LimitCode } from "../knowledge/descriptor.js";
+import type {
+  AuthFailureKind,
+  DiscoveryFacet,
+  HarnessDescriptor,
+  LimitCode,
+} from "../knowledge/descriptor.js";
 
 export const FAILURE_CLASSES = Object.freeze([
   "rate-limit",
@@ -131,6 +137,16 @@ export const failureFromAuth = (kind: AuthFailureKind): FailureSummary => ({
   authKind: kind,
 });
 
+/** A terminal error the harness reported on its stream: classify by what
+ * it says. An auth wall or a transport fault reached no verdict on the
+ * work (retryable); anything else is the model's own failure (task). */
+export const failureFromTerminalError = (h: HarnessDescriptor, message: string): FailureSummary => {
+  const auth = detectAuthFailureInLine(h, message);
+  if (auth !== null) return failureFromAuth(auth);
+  if (detectTransportInLine(message)) return failureFromTransport(message);
+  return failureFromTask(message);
+};
+
 export const failureFromTask = (detail?: string): FailureSummary => ({
   class: "task",
   retryable: false,

package/src/execution/index.ts

@@ -4,8 +4,8 @@
  * It exposes openSession() and streamTurn(), which drive a CLI process via
  * injected {spawn, clock, signal} primitives and emit HarnessEvent values.
  * This module knows nothing about any chat protocol. Because it must run
- * identically on Node and Bun, it never imports child_process and never calls
- * process.kill directly outside the node-deps adapter - all process I/O and
+ * identically on Node and Bun, it never imports child_process and never
+ * signals the process directly outside the node-deps adapter - all process I/O and
  * signalling flows through the injected primitives.
  */
 export { AsyncChannel } from "./channel.js";

package/src/execution/node-deps.ts

@@ -157,6 +157,7 @@ const realSpawn = (argv: readonly string[], opts: SpawnOptions): SpawnedProcess
     stdout: stdoutOutput === null ? emptyStream() : stdoutOutput.stream,
     stderr: stderrWithError(),
     exited,
+    startupError: () => spawnError?.message ?? null,
     disposeOutput: (): void => {
       if (outputDisposed) return;
       outputDisposed = true;