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

package/src/interpretation/limits.ts

@@ -23,7 +23,9 @@ import type {
   HarnessDescriptor,
   LimitCode,
   LimitMatcher,
+  TransportMatcher,
 } from "../knowledge/descriptor.js";
+import { SHARED_TRANSPORT_MATCHERS } from "../knowledge/matchers.js";
 
 /** Bottom-up batch scans stop after this many non-empty lines: the wall is
  * virtually always the last thing a dying turn printed, and an unbounded
@@ -152,3 +154,30 @@ export const detectAuthFailureInLine = (
 
 export const detectAuthFailure = (h: HarnessDescriptor, output: string): AuthFailureKind | null =>
   scanTail(output, compileAuthMatchers(h.authMatchers));
+
+const transportCache = new WeakMap<
+  ReadonlyArray<TransportMatcher>,
+  ReadonlyArray<readonly [RegExp, boolean]>
+>();
+
+const compileTransportMatchers = (
+  matchers: ReadonlyArray<TransportMatcher>,
+): ReadonlyArray<readonly [RegExp, boolean]> => {
+  const cached = transportCache.get(matchers);
+  if (cached !== undefined) return cached;
+  if (matchers.length > MAX_MATCHERS_PER_KIND) {
+    throw new Error(`more than ${MAX_MATCHERS_PER_KIND} matchers per harness per kind`);
+  }
+  const compiled = matchers.map((m) => [validateAndCompile(m.pattern, m.flags), true] as const);
+  transportCache.set(matchers, compiled);
+  return compiled;
+};
+
+export const detectTransportInLine = (line: string): boolean => {
+  const compiled = compileTransportMatchers(SHARED_TRANSPORT_MATCHERS);
+  const windowed = line.slice(0, WINDOW).trim();
+  for (const [re] of compiled) {
+    if (re.test(windowed)) return true;
+  }
+  return false;
+};

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

@@ -107,8 +107,33 @@ export const renderToolSelection = (
 
   if (hasInclude) {
     const names = validateNames(h, selection.include!);
+    if (names.length === 0) {
+      // Empty include list = deny everything. On pi --tools "" has no
+      // defined meaning, so refuse; on claude emit the deny complement
+      // without an empty include token.
+      if (h.tools.includeIsStrictAllowlist || h.tools.excludeFlag === null) {
+        throw new ArgvRefusalError({
+          issue: "invalid-tool-grant",
+          harness: h.name,
+          option: "tools",
+          supported: ["non-empty tool list (empty include would deny everything)"],
+          detail: "empty include list",
+        });
+      }
+      const known = h.tools.builtins.map((t) => t.name);
+      return { tokens: [h.tools.excludeFlag, known.join(",")], unmapped: [] };
+    }
     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/interpretation/versions.ts

@@ -7,7 +7,7 @@
  * precedence.
  */
 
-export type VersionStatus = "ok" | "behind" | "ahead" | "unknown";
+export type VersionStatus = "ok" | "behind" | "ahead" | "unknown" | "drift";
 
 const parse = (v: string): number[] =>
   v

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

@@ -71,6 +71,11 @@ export interface AuthMatcher {
   readonly kind: AuthFailureKind;
 }
 
+export interface TransportMatcher {
+  readonly pattern: string;
+  readonly flags?: string;
+}
+
 /** The turn-option vocabulary is closed for the same reason `LimitCode` is:
  * a descriptor must not invent an option a consumer has no field for. Every
  * key here maps to a field on `TurnOptions`; adding a key without a consumer
@@ -84,6 +89,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 +112,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 +145,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 +260,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/index.ts

@@ -12,7 +12,11 @@
 export { claudeCode } from "./claude-code.js";
 export { codexCli } from "./codex.js";
 export * from "./descriptor.js";
-export { SHARED_AUTH_MATCHERS, SHARED_LIMIT_MATCHERS } from "./matchers.js";
+export {
+  SHARED_AUTH_MATCHERS,
+  SHARED_LIMIT_MATCHERS,
+  SHARED_TRANSPORT_MATCHERS,
+} from "./matchers.js";
 export { museCode } from "./muse.js";
 export {
   type DescriptorSet,

package/src/knowledge/matchers.ts

@@ -4,7 +4,7 @@
  * or a provider 401 must classify no matter which CLI printed it. Each
  * descriptor spreads these after its harness-specific phrasings.
  */
-import type { AuthMatcher, LimitMatcher } from "./descriptor.js";
+import type { AuthMatcher, LimitMatcher, TransportMatcher } from "./descriptor.js";
 
 export const SHARED_LIMIT_MATCHERS: ReadonlyArray<LimitMatcher> = [
   { pattern: "you'?ve hit your usage limit", flags: "i", code: "usage-limit" },
@@ -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" },
@@ -30,3 +37,19 @@ export const SHARED_AUTH_MATCHERS: ReadonlyArray<AuthMatcher> = [
   { pattern: "401 unauthorized", flags: "i", kind: "expired" },
   { pattern: "invalid api key", flags: "i", kind: "invalid-key" },
 ];
+
+export const SHARED_TRANSPORT_MATCHERS: ReadonlyArray<TransportMatcher> = [
+  { pattern: "connection error", flags: "i" },
+  { pattern: "ECONNREFUSED", flags: "i" },
+  { pattern: "ECONNRESET", flags: "i" },
+  { pattern: "ENOTFOUND", flags: "i" },
+  { pattern: "EAI_AGAIN", flags: "i" },
+  { pattern: "ETIMEDOUT", flags: "i" },
+  { pattern: "fetch failed", flags: "i" },
+  { pattern: "socket hang up", flags: "i" },
+  { pattern: "network error", flags: "i" },
+  { pattern: "service unavailable", flags: "i" },
+  { pattern: "bad gateway", flags: "i" },
+  { pattern: "gateway time-?out", flags: "i" },
+  { pattern: "\\b(?:HTTP|status(?:[_ ]?code)?|code)\\b\\W*[:=]?\\W*50[234]\\b", flags: "i" },
+];

package/src/knowledge/pi.ts

@@ -30,6 +30,15 @@ export const piCli: HarnessDescriptor = deepFreeze({
     // Caller-assigned: the same --session-id re-enters the session. Resume
     // carries the same structured-output flags launch does, or a resumed
     // turn would stream plain text the runner cannot decode.
+    // Verified 2026-08-21 on pi 0.84.2: a session id minted by `pi --mode rpc`
+    // via the get_state probe (01a022e3-9afb-7ce5-88f5-07ad0e9ac8fa) resumed
+    // after close through the one-shot grammar `pi --session-id <id> -p
+    // --mode json` (flag --session-id, extraFlags -p --mode json), exit 0,
+    // 207 lines, and the reply recalled the codeword "otter" (evidence at
+    // test/fixtures/pi-rpc-spike/06-resume-after-close/: rpc-turn.ndjson,
+    // resume.argv.json, resume.ndjson, README.md). If the resume had not
+    // recalled the codeword, this comment would say so and the descriptor
+    // would not be changed here.
     style: "flag",
     flag: "--session-id",
     aliases: [],
@@ -69,7 +78,10 @@ export const piCli: HarnessDescriptor = deepFreeze({
     announce: { match: { type: "session" }, idField: "id" },
   },
   limitMatchers: [...SHARED_LIMIT_MATCHERS],
-  authMatchers: [...SHARED_AUTH_MATCHERS],
+  authMatchers: [
+    { pattern: "No API key found for", flags: "i", kind: "not-logged-in" },
+    ...SHARED_AUTH_MATCHERS,
+  ],
   autonomy: null,
   vocabulary: {
     modelFlag: "--model",
@@ -110,6 +122,17 @@ export const piCli: HarnessDescriptor = deepFreeze({
   turnOptions: {
     effort: { kind: "effort", render: { kind: "flag-value", flag: "--thinking" } },
     provider: { kind: "selector", render: { kind: "flag-value", flag: "--provider" } },
+    // issue #48, live-verified 0.84.2: pi's --system-prompt replaces the
+    // default coding-assistant prompt (PI-NAKED probe). No dynamic-section
+    // exclusion exists - pi injects no such sections into a replaced prompt.
+    systemPrompt: {
+      kind: "prompt-text",
+      render: { kind: "flag-value", flag: "--system-prompt" },
+    },
+    appendSystemPrompt: {
+      kind: "prompt-text",
+      render: { kind: "flag-value", flag: "--append-system-prompt" },
+    },
     discovery: {
       kind: "discovery",
       facets: {