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

package/src/execution/open-session.ts

@@ -15,7 +15,11 @@
  */
 import { buildSessionArgv } from "../interpretation/argv.js";
 import { capabilitiesOf } from "../interpretation/capabilities.js";
-import { detectAuthFailureInLine, detectLimitInLine } from "../interpretation/limits.js";
+import {
+  detectAuthFailureInLine,
+  detectLimitInLine,
+  detectTransportInLine,
+} from "../interpretation/limits.js";
 import { composeEscalatedPrompt, detectQuestionBlock } from "../interpretation/question.js";
 import {
   encodeSessionInput,
@@ -27,6 +31,15 @@ import { AsyncChannel } from "./channel.js";
 import { decodeParsed, freshDecodeState } from "./decode.js";
 import type { RunnerDeps, SpawnedProcess } from "./deps.js";
 import type { ExitCause, HarnessEvent } from "./events.js";
+import type { FailureSummary } from "./failure.js";
+import {
+  failureFromAuth,
+  failureFromLimit,
+  failureFromTask,
+  failureFromTerminalError,
+  failureFromTransport,
+  reduceFailures,
+} from "./failure.js";
 import { LineBuffer } from "./lines.js";
 import { KILL_GRACE_MS, PIPE_GRACE_MS, redactArgv, StderrTail } from "./stream-turn.js";
 
@@ -145,6 +158,7 @@ export const openSession = (
   let exitCode: number | null = null;
   let resultError = false;
   let turnLimitSeen = false;
+  let turnFailures: FailureSummary[] = [];
   let pumpError: unknown = null;
   // issue #44: the active turn's last assistant message (where the
   // hcn-question block lives) and whether the turn ended by asking.
@@ -175,14 +189,24 @@ export const openSession = (
     }
   };
 
+  /** A decoded failure event minus its kind: what done.failure carries. */
+  const summaryOf = (event: HarnessEvent & { kind: "failure" }): FailureSummary => {
+    const { kind: _kind, ...summary } = event;
+    return summary;
+  };
+
   const startTurn = (): void => {
     turnLimitSeen = false;
+    turnFailures = [];
     turnAsked = false;
     lastAssistantText = null;
     activeTurn = new AsyncChannel<HarnessEvent>();
     activeTurnId = `${opts.sessionId}:turn-${++turnCounter}`;
     log({ event: "turn_start", sessionId: opts.sessionId, turnId: activeTurnId });
-    for (const held of preTurnEvents.splice(0)) activeTurn.push(held);
+    for (const held of preTurnEvents.splice(0)) {
+      if (held.kind === "failure") turnFailures.push(summaryOf(held));
+      activeTurn.push(held);
+    }
     turnsChannel.push(activeTurn);
   };
 
@@ -197,6 +221,9 @@ export const openSession = (
     if (detection === null) return;
     if ("malformed" in detection) {
       activeTurn?.push({ kind: "error", message: detection.malformed });
+      const failure = failureFromTask(`malformed hcn-question block: ${detection.malformed}`);
+      turnFailures.push(failure);
+      void activeTurn?.push({ kind: "failure", ...failure });
       return;
     }
     turnAsked = true;
@@ -224,6 +251,13 @@ export const openSession = (
     // in sessions) and the caller answers with the next send().
     emitQuestionIfAsked();
     if (turnAsked && done.cause === "clean") done = { ...done, cause: "awaiting-input" };
+    // Every failure was already emitted as an event through pushFailure;
+    // the turn's done carries the reduced summary, as streamTurn's does.
+    const reduced = reduceFailures(turnFailures);
+    if (reduced !== undefined) {
+      if (done.cause === "clean") done = { ...done, cause: "failed", failure: reduced };
+      else done = { ...done, failure: reduced };
+    }
     activeTurn.push(done);
     activeTurn.close();
     log({
@@ -265,6 +299,20 @@ export const openSession = (
     return Promise.resolve();
   };
 
+  const pushFailure = (f: FailureSummary): Promise<void> => {
+    turnFailures.push(f);
+    return routeEvent({ kind: "failure", ...f });
+  };
+
+  /** A decoded event other than a failure: a terminal error also records
+   * the failure it stands for, the way streamTurn does. */
+  const routeDecoded = async (event: HarnessEvent): Promise<void> => {
+    await routeEvent(event);
+    if (event.kind === "error" && event.terminal === true) {
+      await pushFailure(failureFromTerminalError(h, event.message));
+    }
+  };
+
   const pumpStdout = async (): Promise<void> => {
     const lines = new LineBuffer();
     const matches = (
@@ -297,6 +345,7 @@ export const openSession = (
         const code = detectLimitInLine(h, line);
         if (code !== null) {
           await routeEvent({ kind: "limit", code, message: `limit wall detected (${code})` });
+          await pushFailure(failureFromLimit(code));
         }
         return;
       }
@@ -328,7 +377,7 @@ export const openSession = (
               await routeEvent({
                 kind: "identity",
                 sessionId: announced,
-                authority: h.identity.authority,
+                authority: "harness-minted",
                 capabilities: capabilitiesOf(h, opts.model ?? "", "headless-session"),
               });
             }
@@ -338,7 +387,7 @@ export const openSession = (
               await routeEvent({
                 kind: "identity",
                 sessionId: announced,
-                authority: h.identity.authority,
+                authority: "caller-assigned",
                 capabilities: capabilitiesOf(h, opts.model ?? "", "headless-session"),
               });
             }
@@ -367,7 +416,10 @@ export const openSession = (
         // decodeParsed already surfaces the is_error case as an error event
         // (content.ts claude reader); routing the events is enough - we only
         // still track resultError here to classify the done cause.
-        for (const event of events) await routeEvent(event);
+        for (const event of events) {
+          if (event.kind === "failure") await pushFailure(summaryOf(event));
+          else await routeDecoded(event);
+        }
         if (parsed.is_error === true) resultError = true;
         endTurn({
           kind: "done",
@@ -376,7 +428,10 @@ export const openSession = (
         });
         return;
       }
-      for (const event of events) await routeEvent(event);
+      for (const event of events) {
+        if (event.kind === "failure") await pushFailure(summaryOf(event));
+        else await routeDecoded(event);
+      }
     };
     for await (const chunk of proc.stdout) {
       for (const line of lines.push(chunk)) await handleLine(line);
@@ -396,10 +451,12 @@ export const openSession = (
             code: limit,
             message: `limit wall detected (${limit})`,
           });
+          await pushFailure(failureFromLimit(limit));
           continue;
         }
         const auth = detectAuthFailureInLine(h, line);
         if (auth !== null) {
+          await pushFailure(failureFromAuth(auth));
           await routeEvent({ kind: "error", message: `auth wall: ${auth}` });
           continue;
         }

package/src/execution/stream-turn.ts

@@ -16,7 +16,11 @@ import {
   streamingGranularityOf,
 } from "../interpretation/argv.js";
 import { stdinPolicyOf } from "../interpretation/dimensions.js";
-import { detectAuthFailureInLine, detectLimitInLine } from "../interpretation/limits.js";
+import {
+  detectAuthFailureInLine,
+  detectLimitInLine,
+  detectTransportInLine,
+} from "../interpretation/limits.js";
 import { composeEscalatedPrompt, detectQuestionBlock } from "../interpretation/question.js";
 import { ArgvRefusalError } from "../interpretation/refusal.js";
 import type { HarnessDescriptor } from "../knowledge/descriptor.js";
@@ -31,6 +35,8 @@ import {
   failureFromLimit,
   failureFromNative,
   failureFromRejected,
+  failureFromTask,
+  failureFromTerminalError,
   failureFromTimeout,
   failureFromTransport,
   reduceFailures,
@@ -110,6 +116,10 @@ export interface TurnRunOptions extends LaunchOptions {
    * disarms detection. Applies on launch AND resume: it shapes each
    * turn's prompt and event stream, never a session setting. */
   readonly escalateQuestions?: boolean;
+  /** F-05: caller-requested stop. When aborted, the runner escalates
+   * SIGTERM then SIGKILL and classifies the exit as killed with no
+   * transport failure for the kill itself. */
+  readonly signal?: AbortSignal;
 }
 
 export async function* streamTurn(
@@ -229,6 +239,14 @@ export async function* streamTurn(
     ...(envKeys?.length ? { envKeys } : {}),
   });
 
+  // F-23: create-on-missing resume warns before spawn - the harness will
+  // accept any id and silently start a blank session, so the consumer
+  // must verify the id exists.
+  const resumeOnMissingCreate = effective.resume !== undefined && h.resume.onMissing === "create";
+  const resumeCreateWarning = resumeOnMissingCreate
+    ? `${h.name} creates a new session when ${effective.resume} is unknown; verify the id exists`
+    : null;
+
   let proc: SpawnedProcess;
   try {
     proc = deps.spawn(argv, {
@@ -248,6 +266,7 @@ export async function* streamTurn(
       cause: "crash",
       spawnError: message,
     });
+    if (resumeCreateWarning !== null) yield { kind: "error", message: resumeCreateWarning };
     yield { kind: "error", message: `spawn failed: ${message}` };
     yield { kind: "failure", ...failure };
     yield { kind: "done", exitCode: 127, cause: "failed", failure };
@@ -255,9 +274,13 @@ export async function* streamTurn(
   }
 
   const queue = new AsyncChannel<HarnessEvent>();
+  // F-23 warning is an early stream event, before any harness output
+  if (resumeCreateWarning !== null)
+    void queue.push({ kind: "error", message: resumeCreateWarning });
   const state = freshDecodeState(effective.resume ?? null);
   const stderrTail = new StderrTail();
   let killedByWatchdog = false;
+  let killedByAbort = false;
   let exited = false;
   let exitCode: number | null = null;
   let pipesOpenAtExit = false;
@@ -276,9 +299,27 @@ export async function* streamTurn(
       safeSignal("SIGKILL");
     }, KILL_GRACE_MS);
   };
+  let abortHandler: (() => void) | null = null;
+  if (opts.signal) {
+    const onAbort = (): void => {
+      if (killedByAbort) return;
+      killedByAbort = true;
+      escalate();
+    };
+    if (opts.signal.aborted) {
+      killedByAbort = true;
+      escalate();
+    } else {
+      opts.signal.addEventListener("abort", onAbort, { once: true });
+      abortHandler = onAbort;
+    }
+  }
 
   const failures: FailureSummary[] = [];
   const pushFailure = async (f: FailureSummary): Promise<void> => {
+    // Suppress a failure identical in class and message to the previous one
+    const prev = failures[failures.length - 1];
+    if (prev !== undefined && prev.class === f.class && prev.message === f.message) return;
     failures.push(f);
     await queue.push({ kind: "failure", ...f });
   };
@@ -354,32 +395,73 @@ export async function* streamTurn(
 
   const pumpStdout = async (): Promise<void> => {
     const lines = new LineBuffer();
+    let identitySeen = false;
+    const droppableBuffer: HarnessEvent[] = [];
+    const BUFFER_CAP = 256;
+    const isDroppable = (kind: string): boolean =>
+      kind === "progress" || kind === "token" || kind === "context";
+    const flushDroppable = async (): Promise<void> => {
+      for (const e of droppableBuffer) await queue.push(e);
+      droppableBuffer.length = 0;
+    };
+    const handleEvent = async (event: HarnessEvent): Promise<void> => {
+      if (!identitySeen) {
+        if (event.kind === "identity") {
+          identitySeen = true;
+          await queue.push(event);
+          await flushDroppable();
+          return;
+        }
+        if (isDroppable(event.kind)) {
+          if (droppableBuffer.length >= BUFFER_CAP) droppableBuffer.shift();
+          droppableBuffer.push(event);
+          return;
+        }
+        // Lossless events other than identity flush the buffer before themselves
+        await flushDroppable();
+      }
+      if (event.kind === "failure") {
+        const { kind: _kind, ...summary } = event;
+        await pushFailure(summary);
+        return;
+      }
+      if (event.kind === "limit") {
+        // A wall decoded from stdout counts like one read on stderr: the
+        // turn's done must carry it, not only the limit event.
+        await queue.push(event);
+        await pushFailure(failureFromLimit(event.code));
+        return;
+      }
+      if (event.kind === "error") {
+        await queue.push(event);
+        if (event.terminal === true) await pushFailure(failureFromTerminalError(h, event.message));
+        return;
+      }
+      if (escalateQuestions && event.kind === "message" && event.role === "assistant") {
+        lastAssistantText = event.text;
+      }
+      await queue.push(event);
+    };
     for await (const chunk of proc.stdout) {
       if (cancelled) break;
       // Any output chunk rearms the inactivity budget, but not the wall-clock deadline
       if (deps.stallMs !== undefined) rearm();
       for (const line of lines.push(chunk)) {
-        for (const event of decodeLine(h, line, state, opts.model ?? "")) {
-          if ((event as unknown as { kind: string }).kind === "failure") {
-            // Directly from decode's rate_limit_event handling - track for reduction
-            failures.push(event as unknown as FailureSummary);
-          }
-          if (escalateQuestions && event.kind === "message" && event.role === "assistant") {
-            lastAssistantText = event.text;
-          }
-          await queue.push(event);
+        for (const event of decodeLine(h, line, state, opts.model ?? "", granularity)) {
+          await handleEvent(event);
         }
       }
     }
     const rest = lines.flush();
     if (rest !== null && !cancelled) {
-      for (const event of decodeLine(h, rest, state, opts.model ?? "")) {
-        if ((event as unknown as { kind: string }).kind === "failure") {
-          failures.push(event as unknown as FailureSummary);
-        }
-        await queue.push(event);
+      for (const event of decodeLine(h, rest, state, opts.model ?? "", granularity)) {
+        await handleEvent(event);
       }
     }
+    // Flush at exit if no identity ever arrived
+    if (!identitySeen && droppableBuffer.length > 0) {
+      await flushDroppable();
+    }
   };
 
   /** issue #41: scan the last assistant message for the hcn-question
@@ -394,6 +476,7 @@ export async function* streamTurn(
     if (detection === null) return;
     if ("malformed" in detection) {
       await queue.push({ kind: "error", message: detection.malformed });
+      await pushFailure(failureFromTask(`malformed hcn-question block: ${detection.malformed}`));
       return;
     }
     log({
@@ -477,6 +560,24 @@ export async function* streamTurn(
   try {
     for await (const event of queue) yield event;
 
+    // F-04: a harness binary that is not installed surfaces as an
+    // async ENOENT. The adapter records it in startupError and resolves
+    // exited with 127 while appending `spawn failed:` to stderr. Treat
+    // it like the synchronous-throw branch: transport failure, retryable,
+    // done cause failed with the real exit code.
+    const startupMessage = proc.startupError?.() ?? null;
+    let startupFailed = false;
+    if (startupMessage !== null && failures.length === 0) {
+      const f = failureFromTransport(`spawn failed: ${startupMessage}`);
+      failures.push(f);
+      startupFailed = true;
+      // The stderr pump appends the spawn line to the tail but does not
+      // emit an error event for it; emit the error here to match the sync
+      // branch, and suppress the later tail-error path for this case.
+      yield { kind: "error", message: `spawn failed: ${startupMessage}` };
+      yield { kind: "failure", ...f };
+    }
+
     // Post-queue failure sources. Nonzero exit with no other failure and a
     // non-empty stderr tail is a NATIVE failure (D6): the harness rejected
     // its own arguments or crashed on them - verbatim stderr, native exit
@@ -484,6 +585,8 @@ export async function* streamTurn(
     // (a silent nonzero exit reads as an environment problem, not a
     // harness judgment).
     if (
+      !startupFailed &&
+      !killedByAbort &&
       failures.length === 0 &&
       exitCode !== 0 &&
       exitCode !== null &&
@@ -491,16 +594,19 @@ export async function* streamTurn(
       !state.limitSeen
     ) {
       const tailForNative = stderrTail.snapshot();
+      const transportLine = tailForNative.find((line) => detectTransportInLine(line));
       const f =
-        tailForNative.length > 0
-          ? failureFromNative(exitCode, tailForNative)
-          : failureFromTransport(`nonzero exit ${exitCode}`);
+        transportLine !== undefined
+          ? failureFromTransport(transportLine)
+          : tailForNative.length > 0
+            ? failureFromNative(exitCode, tailForNative)
+            : failureFromTransport(`nonzero exit ${exitCode}`);
       failures.push(f);
       // Need to emit this failure before done, even though queue is closed
       yield { kind: "failure", ...f };
     }
     // Stall watchdog also implies a transport failure if not already present
-    if (killedByWatchdog && failures.length === 0) {
+    if (killedByWatchdog && !killedByAbort && failures.length === 0) {
       // D11: a wall-clock deadline kill is a timeout, not a stall - the
       // run was not necessarily silent, it simply outlived its budget.
       const f =
@@ -513,19 +619,29 @@ export async function* streamTurn(
 
     let cause: ExitCause = state.limitSeen
       ? "limit"
-      : killedByWatchdog && exitCode !== 0
-        ? watchdogReason === "turn-deadline"
-          ? "killed" // D11: the run was killed on budget, not stalled
-          : "stall"
-        : exitCode === 0
-          ? asked
-            ? "awaiting-input" // issue #41: asking SUCCEEDED the turn
-            : "clean"
-          : exitCode === null
-            ? "killed"
-            : "crash";
+      : killedByAbort
+        ? "killed"
+        : killedByWatchdog && exitCode !== 0
+          ? watchdogReason === "turn-deadline"
+            ? "killed" // D11: the run was killed on budget, not stalled
+            : "stall"
+          : exitCode === 0
+            ? asked
+              ? "awaiting-input" // issue #41: asking SUCCEEDED the turn
+              : "clean"
+            : exitCode === null
+              ? "killed"
+              : startupFailed
+                ? "failed"
+                : "crash";
     const reduced = reduceFailures(failures);
     if (reduced && cause === "clean") cause = "failed";
+    // A classified failure other than native on a nonzero exit is a failed
+    // turn, not a crash: the failure taxonomy already captured the reason.
+    // Crash stays for unclassified exits and native failures.
+    if (reduced && reduced.class !== "native" && cause === "crash") {
+      cause = "failed";
+    }
     const tail = stderrTail.snapshot();
     log({
       event: "exit",
@@ -542,7 +658,9 @@ export async function* streamTurn(
     // A failure with captured stderr surfaces as a stream-level error, not
     // only in the exit log - so a crash from the real adapter's async spawn
     // failure carries the same error-event signal as the sync-throw path.
-    if ((cause === "crash" || cause === "killed") && tail.length > 0) {
+    // F-04: the startupError path already emitted the spawn error; do not
+    // duplicate it via the tail.
+    if (!startupFailed && (cause === "crash" || cause === "killed") && tail.length > 0) {
       yield { kind: "error", message: tail.join("\n").slice(0, 4096) };
     }
     terminalEventReached = true;
@@ -559,6 +677,7 @@ export async function* streamTurn(
       ...(reduced ? { failure: reduced } : {}),
     };
   } finally {
+    if (abortHandler !== null) opts.signal?.removeEventListener("abort", abortHandler);
     const abandoned = !terminalEventReached;
     cancelled = true;
     queue.close();

package/src/interpretation/argv.ts

@@ -7,7 +7,7 @@
 import type { HarnessDescriptor, StreamingGranularity } from "../knowledge/descriptor.js";
 import { defaultDescriptors } from "../knowledge/overrides.js";
 import { ArgvRefusalError } from "./refusal.js";
-import { assertUsableSessionId } from "./session-id.js";
+import { assertUsableSessionId, SESSION_ID_MAX, SessionIdRefusalError } from "./session-id.js";
 import { renderSkillsSelection } from "./skills-selection.js";
 import { supportedBy } from "./support.js";
 import { renderToolSelection } from "./tool-selection.js";
@@ -69,6 +69,13 @@ export interface TurnOptions {
   readonly write?: boolean;
   readonly shell?: boolean;
   readonly maxSteps?: number;
+  /** issue #48: replaces the harness's built-in system prompt (opt-in-only,
+   * no profile entry). claude/pi: flag-value (claude pairs the dynamic-section
+   * exclusion); codex: config-kv `instructions` (literal or path); muse:
+   * refuses with hint. */
+  readonly systemPrompt?: string;
+  /** issue #48: appends to the built-in prompt (claude/pi only). */
+  readonly appendSystemPrompt?: string;
   /** issue #41: question escalation - a BEHAVIOR INSTRUCTION, not a turn
    * option. It never renders into any harness argv; the CLI layer turns
    * it into the prompt preamble and arms question-block detection.
@@ -136,8 +143,28 @@ export const buildLaunchArgv = (h: HarnessDescriptor, opts: LaunchOptions): stri
   ...turnTail(h, opts),
 ];
 
+/** A session id that fails the shape rule is a spawn-boundary refusal like
+ * any other: typed, so streamTurn turns it into failure + done and the CLI
+ * exits 2, instead of a bare SessionIdRefusalError escaping the runner. */
+const refuseUnusableSessionId = (h: HarnessDescriptor, sessionId: string): void => {
+  try {
+    assertUsableSessionId(sessionId);
+  } catch (e) {
+    if (!(e instanceof SessionIdRefusalError)) throw e;
+    throw new ArgvRefusalError({
+      issue: "invalid-option-value",
+      harness: h.name,
+      message: `${h.name} cannot resume ${e.message}`,
+      supported: [
+        `a session id of letters, digits, '.', '_', ':', '@', '-' only, starting with a letter or digit, at most ${SESSION_ID_MAX} chars`,
+      ],
+      detail: e.message,
+    });
+  }
+};
+
 export const buildResumeArgv = (h: HarnessDescriptor, opts: ResumeOptions): string[] => {
-  assertUsableSessionId(opts.sessionId);
+  refuseUnusableSessionId(h, opts.sessionId);
   // Subcommands lead, then the resume token and id, then the flags the
   // RESUME grammar accepts (never inherited launch flags - codex exec
   // resume rejects --sandbox). One shape serves both styles:
@@ -161,16 +188,18 @@ export interface SessionOptions {
 
 export const buildSessionArgv = (h: HarnessDescriptor, opts: SessionOptions): string[] => {
   if (!h.sessionMode) {
+    const supported = Object.values(defaultDescriptors())
+      .filter((d): d is HarnessDescriptor => d !== undefined && d.sessionMode !== null)
+      .map((d) => d.name);
     throw new ArgvRefusalError({
       issue: "no-session-mode",
       harness: h.name,
-      supported: ["session is available where sessionMode is declared"],
+      supported,
     });
   }
-  assertUsableSessionId(opts.sessionId);
+  refuseUnusableSessionId(h, opts.sessionId);
   const argv = [
     h.bin,
-    ...h.launch.baseFlags,
     ...h.sessionMode.flags,
     // idFlag null = the harness refuses unknown ids and mints its own
     // (pi rpc); the caller-side sessionId stays a correlation handle.

package/src/interpretation/capabilities.ts

@@ -27,7 +27,10 @@ export const capabilitiesOf = (
   model: string,
   mode: HarnessMode,
 ): CapabilityResult => {
-  if (!resolveModel(h, model).curated) {
+  // F-09: an absent model means the harness default model (curated), not
+  // an unknown model. Only degrade when a model was explicitly given and is
+  // not curated.
+  if (model !== "" && !resolveModel(h, model).curated) {
     // Curated claims cover curated models only - an extensible registry's
     // unknown model still degrades here until runtime verification.
     // Degrade: no raw-image claims, no streaming claims - transcribe/hold.

package/src/interpretation/content.ts

@@ -18,7 +18,11 @@ export type ContentEvent =
   | { readonly kind: "message"; readonly role: string; readonly text: string }
   | { readonly kind: "tool"; readonly name: string; readonly input?: unknown }
   | { readonly kind: "progress"; readonly label: string }
-  | { readonly kind: "error"; readonly message: string };
+  /** `terminal: true` marks an error that ended the turn (a failed result
+   * record); the runner turns it into a task failure. Other errors are
+   * informational and the turn goes on. */
+  | { readonly kind: "error"; readonly message: string; readonly terminal?: boolean }
+  | { readonly kind: "budget"; readonly detail: string };
 
 /** Text of an array of `{type:"text", text}` content blocks. */
 const textOfBlocks = (content: unknown): string =>
@@ -70,7 +74,7 @@ const claude = (r: Record<string, unknown>): ContentEvent[] => {
     // error) - surface it so a streamTurn consumer sees the failure, not a
     // clean turn. (openSession handles result boundaries itself.)
     const sub = typeof r.subtype === "string" ? r.subtype : "result error";
-    events.push({ kind: "error", message: `turn failed: ${sub}` });
+    events.push({ kind: "error", message: `turn failed: ${sub}`, terminal: true });
   }
   return events;
 };
@@ -100,7 +104,7 @@ const codex = (r: Record<string, unknown>): ContentEvent[] => {
     return [{ kind: "message", role: "assistant", text: item.text }];
   }
   if (item.type === "error" && typeof item.message === "string") {
-    return [{ kind: "error", message: item.message }];
+    return [{ kind: "error", message: item.message, terminal: true }];
   }
   return [];
 };
@@ -126,8 +130,16 @@ const pi = (r: Record<string, unknown>): ContentEvent[] => {
       // an expired minimax token: empty content, stopReason error, clean
       // exit). Without this the failure is invisible - a silent empty turn.
       if (message.stopReason === "error") {
+        const msg =
+          typeof message.errorMessage === "string"
+            ? `pi turn ended with stopReason error: ${message.errorMessage}`
+            : "pi turn ended with stopReason error (provider/auth failure)";
         return [
-          { kind: "error", message: "pi turn ended with stopReason error (provider/auth failure)" },
+          {
+            kind: "error",
+            message: msg,
+            terminal: true,
+          },
         ];
       }
       const text = textOfBlocks(message.content);
@@ -171,7 +183,12 @@ const muse = (r: Record<string, unknown>): ContentEvent[] => {
     }
     if (payload.terminal === "failed") {
       const reason = typeof payload.reason === "string" ? payload.reason : "run failed";
-      return [{ kind: "error", message: `muse run failed: ${reason}` }];
+      // The muse reader is the muse-specific seam; no descriptor field
+      // carries budget phrasings yet, so the pattern lives here.
+      if (/did not reach a terminal state within \d+ step/i.test(reason)) {
+        return [{ kind: "budget", detail: reason }];
+      }
+      return [{ kind: "error", message: `muse run failed: ${reason}`, terminal: true }];
     }
   }
   return [];

package/src/interpretation/hints.ts

@@ -29,6 +29,9 @@ const HINTS: Readonly<Record<string, Readonly<Record<string, string>>>> = deepFr
   codex: {
     write:
       "codex has no write toggle; use --sandbox read-only (config: sandbox_mode) so shell commands cannot write either",
+    // issue #48: the append half has no codex spelling.
+    appendSystemPrompt:
+      "codex has no append-to-prompt flag; -c instructions=<literal or path> REPLACES the whole prompt (both accepted, live-verified) - there is no additive form",
     shell:
       "codex has no shell toggle; disable the shell tool via config (-c features.shell_tool=false) or use --sandbox read-only",
     maxSteps:
@@ -65,6 +68,11 @@ const HINTS: Readonly<Record<string, Readonly<Record<string, string>>>> = deepFr
       "muse loads rules per workspace trust; --no-foreign-personal-context excludes foreign personal rules, and withholding --trust-workspace keeps workspace rules unloaded",
     "discovery.skills":
       "muse scopes skills by trust like rules; --no-foreign-personal-context drops foreign skills and untrusted workspaces stay unloaded - there is no unconditional skills-off switch",
+    // issue #48 (ratified 2026-08-20): muse cannot strip the payload at all.
+    systemPrompt:
+      "muse has no system-prompt surface; its built-in prompt always applies - there is no replacement or append spelling (structural: nothing to approximate with)",
+    appendSystemPrompt:
+      "muse has no system-prompt surface; its built-in prompt always applies - there is no replacement or append spelling (structural: nothing to approximate with)",
   },
 });