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

package/src/execution/stream-turn.ts

@@ -31,6 +31,7 @@ import {
   failureFromLimit,
   failureFromNative,
   failureFromRejected,
+  failureFromTask,
   failureFromTimeout,
   failureFromTransport,
   reduceFailures,
@@ -110,6 +111,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 +234,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 +261,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 +269,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,6 +294,21 @@ 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> => {
@@ -354,32 +387,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(failureFromTask(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
@@ -477,6 +551,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 +576,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 &&
@@ -500,7 +594,7 @@ export async function* streamTurn(
       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 +607,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 work-verdict failure (the model ran out of steps, or ended its
+    // turn in error) is not a harness crash even when the process exits
+    // nonzero: the cause is failed and the real exit code rides along.
+    if ((reduced?.class === "budget" || reduced?.class === "task") && cause === "crash") {
+      cause = "failed";
+    }
     const tail = stderrTail.snapshot();
     log({
       event: "exit",
@@ -542,7 +646,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 +665,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:
@@ -167,10 +194,9 @@ export const buildSessionArgv = (h: HarnessDescriptor, opts: SessionOptions): st
       supported: ["session is available where sessionMode is declared"],
     });
   }
-  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 [];
 };
@@ -127,7 +131,11 @@ const pi = (r: Record<string, unknown>): ContentEvent[] => {
       // exit). Without this the failure is invisible - a silent empty turn.
       if (message.stopReason === "error") {
         return [
-          { kind: "error", message: "pi turn ended with stopReason error (provider/auth failure)" },
+          {
+            kind: "error",
+            message: "pi turn ended with stopReason error (provider/auth failure)",
+            terminal: true,
+          },
         ];
       }
       const text = textOfBlocks(message.content);
@@ -171,7 +179,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)",
   },
 });
 

package/src/interpretation/resolve-options.ts

@@ -163,6 +163,23 @@ export const resolveEffectiveOptions = (
     // the emit-nothing rule, recorded in provenance. On a harness with
     // dormant built-ins (pi), it becomes the enabling include list.
     if (key === "tools" && value === "all-known") {
+      // --no-tools containment: a tier that switched discovery.tools off
+      // must not have the profile grant switch them back on (pi reads
+      // --tools as an enabling allowlist). The tier that turned tools off
+      // owns the skip.
+      const toolsOff = (o: Partial<TurnOptions> | undefined): boolean =>
+        o?.discovery?.tools === false;
+      const offTier: ProvenanceTier | undefined = toolsOff(effectiveArgs)
+        ? "arg"
+        : toolsOff(tiers.project)
+          ? "project-config"
+          : toolsOff(tiers.user)
+            ? "user-config"
+            : undefined;
+      if (offTier !== undefined) {
+        provenance.push({ key, value: "none (discovery.tools off)", tier: offTier });
+        continue;
+      }
       const enabled = h.tools.builtins.filter((t) => t.defaultEnabled).length;
       const all = h.tools.builtins.length;
       if (enabled === all) {

package/src/interpretation/tool-selection.ts

@@ -109,6 +109,15 @@ export const renderToolSelection = (
     const names = validateNames(h, selection.include!);
     const { mapped, unmapped } = resolveNames(h, names);
     if (!h.tools.includeIsStrictAllowlist) {
+      if (mapped.length === 0 && unmapped.length > 0) {
+        throw new ArgvRefusalError({
+          issue: "unknown-tool-name",
+          harness: h.name,
+          option: "tools",
+          supported: [`known tool names: ${h.tools.builtins.map((t) => t.name).join(", ")}`],
+          detail: `unknown tool name(s) ${unmapped.join(", ")}`,
+        });
+      }
       // claude: exact allowlist must reshape the visible set via the deny
       // complement (probe 2b). The include flag also carries the granted
       // names (curated + pass-throughs) so they skip approval prompts;

package/src/interpretation/turn-options.ts

@@ -227,17 +227,22 @@ export const renderTurnOptions = (
           supported: resumeSupported.length ? resumeSupported : ["(none)"],
         });
       }
-      // Reject config-kv for non-closed vocabulary
+      // Reject config-kv for open vocabularies. Exception (issue #48):
+      // prompt-text rides config-kv VERBATIM on codex - both a literal and
+      // a path are accepted (live-verified 0.146.1); no quoting, because
+      // codex's k=v split takes the rest of the token raw and both probed
+      // forms passed unquoted.
       if (
         (spec as unknown as SpecBase).render.kind === "config-kv" &&
         (spec as { kind: string }).kind !== "enum" &&
-        (spec as { kind: string }).kind !== "effort"
+        (spec as { kind: string }).kind !== "effort" &&
+        (spec as { kind: string }).kind !== "prompt-text"
       ) {
         throw new ArgvRefusalError({
           issue: "invalid-option-value",
           harness: h.name,
           option: key,
-          supported: ["config-kv only for enum and effort (closed vocabularies)"],
+          supported: ["config-kv only for enum, effort, and prompt-text (issue #48)"],
         });
       }
     }
@@ -320,6 +325,29 @@ export const renderTurnOptions = (
         sequences.push(seq);
         break;
       }
+      case "prompt-text": {
+        // issue #48: free-form prompt prose (systemPrompt / appendSystemPrompt).
+        // No closed vocabulary - validate non-empty string, render verbatim.
+        // Values may be multi-line and may contain shell-hostile characters;
+        // they cross as single argv tokens, never through a shell.
+        if (typeof raw !== "string" || raw.trim() === "") {
+          throw new ArgvRefusalError({
+            issue: "invalid-option-value",
+            harness: h.name,
+            option: key,
+            supported: ["non-empty prompt text"],
+            detail: typeof raw === "string" ? "(empty)" : String(raw),
+          });
+        }
+        const r = effectiveRender!;
+        let seq: string[];
+        if (r.kind === "flag-value") seq = [...(r.extraFlags ?? []), r.flag, raw];
+        else if (r.kind === "config-kv") seq = [r.flag, `${r.key}=${raw}`];
+        else if (r.kind === "flag-list") seq = [...r.flags];
+        else seq = [];
+        sequences.push(seq);
+        break;
+      }
       case "selector": {
         if (typeof raw !== "string") {
           throw new ArgvRefusalError({

package/src/knowledge/claude-code.ts

@@ -49,7 +49,10 @@ export const claudeCode: HarnessDescriptor = deepFreeze({
     // A-001: one process, many turns; `result` delimits turns; mid-turn sends
     // queue. --setting-sources project isolates the child from user-level
     // hooks (D-025). Token deltas require this exact output flag set.
+    // sessionMode.flags is the complete flag list after the binary, so -p
+    // lives here rather than being inherited from launch.baseFlags.
     flags: [
+      "-p",
       "--input-format",
       "stream-json",
       "--output-format",
@@ -139,6 +142,24 @@ export const claudeCode: HarnessDescriptor = deepFreeze({
   },
   turnOptions: {
     effort: { kind: "effort", render: { kind: "flag-value", flag: "--effort" } },
+    // issue #48, live-verified 2.1.235: --system-prompt replaces the built-in
+    // prompt; --exclude-dynamic-system-prompt-sections strips the dynamic
+    // sections (git state, directory listing) that ride even under a
+    // replacement. hcn pairs them - a payload-stripping replacement without
+    // the exclusion keeps injected sections. Verified live: the pair changes
+    // model behavior (NAKED-HAIKU probe vs BASELINE-OK).
+    systemPrompt: {
+      kind: "prompt-text",
+      render: {
+        kind: "flag-value",
+        flag: "--system-prompt",
+        extraFlags: ["--exclude-dynamic-system-prompt-sections"],
+      },
+    },
+    appendSystemPrompt: {
+      kind: "prompt-text",
+      render: { kind: "flag-value", flag: "--append-system-prompt" },
+    },
     discovery: {
       kind: "discovery",
       facets: {

package/src/knowledge/codex.ts

@@ -106,6 +106,15 @@ export const codexCli: HarnessDescriptor = deepFreeze({
       kind: "effort",
       render: { kind: "config-kv", flag: "-c", key: "model_reasoning_effort" },
     },
+    // issue #48, live-verified 0.146.1 under --strict-config: the config key
+    // `instructions` accepts BOTH a literal string (LITERAL-OK probe) and a
+    // file path (FILE-OK probe); hcn passes the value verbatim and codex
+    // validates. `model_instructions` / `experimental_instructions_file`
+    // are refused by codex (probed) - wrong spellings, not alternates.
+    systemPrompt: {
+      kind: "prompt-text",
+      render: { kind: "config-kv", flag: "-c", key: "instructions" },
+    },
     sandbox: {
       kind: "enum",
       values: ["read-only", "workspace-write", "danger-full-access"],

package/src/knowledge/descriptor.ts

@@ -84,6 +84,12 @@ export const TURN_OPTION_KEYS = deepFreeze([
   "write",
   "shell",
   "maxSteps",
+  // issue #48 (ratified 2026-08-20): the payload-stripping dimensions.
+  // systemPrompt replaces the built-in prompt; appendSystemPrompt adds to
+  // it. Both are opt-in-only (arg/config, no profile entry) - a default
+  // that strips the payload changes every bare run's semantics.
+  "systemPrompt",
+  "appendSystemPrompt",
 ] as const);
 export type TurnOptionKey = (typeof TURN_OPTION_KEYS)[number];
 
@@ -101,8 +107,14 @@ export const DISCOVERY_FACETS = deepFreeze([
 export type DiscoveryFacet = (typeof DISCOVERY_FACETS)[number];
 
 export type OptionRender =
-  /** `--flag <value>` */
-  | { readonly kind: "flag-value"; readonly flag: string }
+  /** `--flag <value>`; `extraFlags` are fixed companion tokens emitted
+   *  before the value pair (claude's --system-prompt pairs with
+   *  --exclude-dynamic-system-prompt-sections - issue #48). */
+  | {
+      readonly kind: "flag-value";
+      readonly flag: string;
+      readonly extraFlags?: readonly string[];
+    }
   /** `-c key=value` - codex's config-override grammar. Permitted only for
    *  closed-vocabulary specs, so no value can need escaping. */
   | { readonly kind: "config-kv"; readonly flag: string; readonly key: string }
@@ -128,6 +140,10 @@ export type TurnOptionSpec =
   | (SpecBase & { readonly kind: "effort" })
   /** Open selector, CLEAN_SELECTOR-validated. */
   | (SpecBase & { readonly kind: "selector" })
+  /** Free-form prompt text (issue #48): systemPrompt / appendSystemPrompt.
+   * Values are prose, never a closed vocabulary - no validation beyond
+   * non-emptiness, rendering is verbatim. */
+  | (SpecBase & { readonly kind: "prompt-text" })
   /** `polarity: "disables"` emits the render when the caller asks for FALSE. */
   | (SpecBase & { readonly kind: "toggle"; readonly polarity: "enables" | "disables" })
   | (SpecBase & { readonly kind: "integer"; readonly min: number; readonly max: number })
@@ -239,14 +255,16 @@ export interface HarnessDescriptor {
      * harness. */
     readonly onMissing: "error" | "create";
   };
-  /** Persistent headless session support: the exact flag set that opens one
-   * lucid-owned process serving many turns, or null when the harness has no
-   * such mode. `idFlag` pins the caller-assigned session identity.
-   * `turnEnd` is the stdout record that delimits one turn (claude: the
-   * `result` record; pi rpc: `agent_settled`). `identityProbe`, when
-   * present, names a command the runner writes at spawn whose response
-   * carries the session id - pi rpc is identity-silent at startup (spike
-   * evidence: test/fixtures/pi-rpc-spike), so identity needs a round trip. */
+  /** Persistent headless session support: the complete flag list that follows
+   * the binary to open one lucid-owned process serving many turns, or null
+   * when the harness has no such mode. This is the entire argv prefix after
+   * the binary - no launch flags are prepended. `idFlag` pins the
+   * caller-assigned session identity. `turnEnd` is the stdout record that
+   * delimits one turn (claude: the `result` record; pi rpc:
+   * `agent_settled`). `identityProbe`, when present, names a command the
+   * runner writes at spawn whose response carries the session id - pi rpc
+   * is identity-silent at startup (spike evidence:
+   * test/fixtures/pi-rpc-spike), so identity needs a round trip. */
   readonly sessionMode: {
     readonly flags: readonly string[];
     /** Pin an EXISTING session id; null when the harness only accepts

package/src/knowledge/matchers.ts

@@ -20,7 +20,14 @@ export const SHARED_LIMIT_MATCHERS: ReadonlyArray<LimitMatcher> = [
     code: "quota",
   },
   // Rate-limit patterns are last so a line with both a usage wall and a 429 keeps usage-limit (first-match-wins, documented cost)
-  { pattern: "429", flags: "i", code: "rate-limit" },
+  // 429 only next to an HTTP status word: a bare digit run inside an id, a
+  // byte count, or a timing must never read as a wall. "429 Too Many
+  // Requests" is covered by the next matcher.
+  {
+    pattern: "\\b(?:HTTP|status(?:[_ ]?code)?|code)\\b\\W*[:=]?\\W*429\\b",
+    flags: "i",
+    code: "rate-limit",
+  },
   { pattern: "Too Many Requests", flags: "i", code: "rate-limit" },
   { pattern: "rate limit(?:ed|ing)?", flags: "i", code: "rate-limit" },
   { pattern: "Retry-After", flags: "i", code: "rate-limit" },