@dungle-scrubs/harness-cli-normalizer 0.5.5 → 0.5.6

package/src/interpretation/question.ts

@@ -47,7 +47,15 @@ If and only if a genuine decision you cannot make defensibly blocks correct prog
 
 Say nothing after the block and stop generating. The caller's user will answer, and the answer arrives as the next user message in this session - continue from it. For every choice you can make defensibly yourself, do not ask - decide, act, and state the decision you made.`;
 
-/** Compose the transport preamble onto a prompt. `mode` selects the
+export type QuestionMode = "ask" | "assume" | "none";
+
+export const QUESTION_MODES: readonly QuestionMode[] = ["ask", "assume", "none"] as const;
+
+export const isQuestionMode = (value: string): value is QuestionMode =>
+  (QUESTION_MODES as readonly string[]).includes(value);
+
+/** Compose the transport preamble onto a prompt. `mode` selects which
+ * preamble to inject (ask/assume/none), and `channel` selects the
  * contract wording: "turn" (exit-and-resume transport, hcn run) or
  * "session" (live channel, hcn session). Idempotent: a prompt that
  * already carries any preamble passes through unchanged - a turn-mode
@@ -55,12 +63,14 @@ Say nothing after the block and stop generating. The caller's user will answer,
  * both; the already-composed contract stands). */
 export const composeEscalatedPrompt = (
   prompt: string,
-  escalate: boolean,
-  mode: "turn" | "session" = "turn",
-): string =>
-  prompt.startsWith(QUESTION_PREAMBLE_MARKER)
-    ? prompt
-    : `${mode === "session" && escalate ? SESSION_ESCALATION_PREAMBLE : escalate ? ESCALATION_PREAMBLE : NO_ESCALATION_PREAMBLE}\n\n${prompt}`;
+  mode: QuestionMode,
+  channel: "turn" | "session" = "turn",
+): string => {
+  if (prompt.startsWith(QUESTION_PREAMBLE_MARKER)) return prompt;
+  if (mode === "none") return prompt;
+  if (mode === "assume") return `${NO_ESCALATION_PREAMBLE}\n\n${prompt}`;
+  return `${channel === "session" ? SESSION_ESCALATION_PREAMBLE : ESCALATION_PREAMBLE}\n\n${prompt}`;
+};
 
 /** The structured question a worker asks (the block's fields). */
 export interface QuestionBlock {

package/src/interpretation/refusal.ts

@@ -35,6 +35,7 @@ export type RefusalOption =
   | "excludeTools"
   | "skills"
   | "autonomy"
+  | "questions"
   | `discovery.${string}`;
 
 /** One helper builds the message from the structured fields so message and
@@ -89,7 +90,7 @@ export const buildRefusalMessage = (
     case "no-autonomy-mode":
       return `${harness} has no unattended-run flag; ${supportedStr} - drop autonomy or route to a supporting harness (claude --dangerously-skip-permissions, codex/muse --yolo)`;
     case "no-session-mode":
-      return `${harness} declares no persistent headless session mode; ${supportedStr} - use streamTurn instead of openSession`;
+      return `${harness} declares no persistent headless session mode; ${supportedStr} - use hcn run --resume <id>`;
     default: {
       const exhaustive: never = issue;
       return `${exhaustive as string} for ${harness}${optionPart}${detailSuffix}; ${supportedStr}`;

package/src/interpretation/skills-selection.ts

@@ -10,7 +10,15 @@
  *   OFF - `--settings '{"skillOverrides":{"<name>":"off",...}}'` for every
  *   known skill except the picks. Known set comes from the caller's root
  *   listing (same source that resolved the names).
- * - codex/muse: refuse (structural) with the standard hint shape.
+ * - codex: per-skill disable via config-kv array `-c
+ *   skills.config=[{path="...", enabled=false}]` for every known skill
+ *   except the picks (complement-off, same inversion as claude). Uses
+ *   `path` selector rather than `name` because a skill's frontmatter
+ *   `name` need not equal its directory basename, and `path` is exact.
+ *   The path for skill <n> under root <root> is <root>/<n>/SKILL.md.
+ *   No global `skills.enabled` switch exists. Requires the known set
+ *   and the resolved picks (root derived from picks via dirname).
+ * - muse: refuse (structural) with the standard hint shape.
  */
 import type { HarnessDescriptor } from "../knowledge/descriptor.js";
 import { ArgvRefusalError } from "./refusal.js";
@@ -20,6 +28,11 @@ export const basenameOf = (p: string): string => {
   return i === -1 ? p : p.slice(i + 1);
 };
 
+const dirnameOf = (p: string): string => {
+  const i = p.lastIndexOf("/");
+  return i === -1 ? "" : p.slice(0, i);
+};
+
 export const renderSkillsSelection = (
   h: HarnessDescriptor,
   skills: readonly string[],
@@ -35,11 +48,9 @@ export const renderSkillsSelection = (
       supportedBy: [
         { harness: "pi", spelling: "--skill" },
         { harness: "claude", spelling: "skillOverrides" },
+        { harness: "codex", spelling: "-c skills.config" },
       ],
-      hint:
-        h.name === "codex"
-          ? "codex discovers skills from its own directory with no call-time surface - stage the skills into $CODEX_HOME/skills or pass their content in the prompt"
-          : "muse scopes skills by workspace trust with no per-skill surface - include the skill content in the prompt or use --trust-workspace for the whole registry",
+      hint: "muse scopes skills by workspace trust with no per-skill surface - include the skill content in the prompt or use --trust-workspace for the whole registry",
     });
   }
 
@@ -50,9 +61,9 @@ export const renderSkillsSelection = (
     return tokens;
   }
 
-  // claude: complement-off via settings JSON. Names are the skill dir
-  // basenames; unknown names in knownSkills would be turned off
-  // pointlessly, so the caller passes exactly the known set.
+  // claude and codex: complement-off via CLI layer (settings JSON / config
+  // array). The descriptor-level render returns [] and tokens append in
+  // stream-turn / CLI.
   return [];
 };
 
@@ -71,3 +82,30 @@ export const claudeSkillOverridesArg = (
   const json = JSON.stringify({ skillOverrides: offs });
   return ["--settings", json];
 };
+
+/** Codex complement form: every known skill except the picks gets
+ * `{path="<root>/<name>/SKILL.md>", enabled=false}` via `-c
+ * skills.config=[...]`. Uses `path` (exact) over `name` because
+ * frontmatter name may diverge from directory basename. Root is derived
+ * from the picks' dirname (all picks share the same root); if picks is
+ * empty the complement cannot be rooted and we return [] (caller picks
+ * nothing - no integration point needs this, and the CLI layer never
+ * calls with empty picks). Empty complement returns [] (no flag). */
+export const codexSkillConfigArg = (
+  knownSkills: readonly string[],
+  pickedPaths: readonly string[],
+): string[] => {
+  const picks = new Set(pickedPaths.map(basenameOf));
+  // Derive root from first pick's dirname; all picks are under same root
+  // (skills-root guarantees this). Fall back to "" if no picks.
+  const root = pickedPaths.length > 0 ? dirnameOf(pickedPaths[0] as string) : "";
+  const entries: string[] = [];
+  for (const name of knownSkills) {
+    if (!picks.has(name)) {
+      const absPath = root ? `${root}/${name}/SKILL.md` : `${name}/SKILL.md`;
+      entries.push(`{path=${JSON.stringify(absPath)}, enabled=false}`);
+    }
+  }
+  if (entries.length === 0) return [];
+  return ["-c", `skills.config=[${entries.join(", ")}]`];
+};

package/src/knowledge/claude-code.ts

@@ -51,6 +51,19 @@ export const claudeCode: HarnessDescriptor = deepFreeze({
     // 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.
+    // claude has two session-id flags with opposite unknown-id behaviour:
+    // `--session-id` NAMES a fresh session (creates if missing, silent) while
+    // `--resume` RESTORES an existing one (refuses unknown id, exit 1
+    // "No conversation found" - verified phase11,
+    // test/fixtures/phase11-claude-session-resume/resume-unknown-id.stderr.txt).
+    // `idFlag` is the naming flag (`--session-id`); `resumeFlag` is the
+    // restoring flag (`--resume`) - distinct as data so the renderer cannot
+    // pick the wrong one. Unknown-id behaviour reuses `resume.onMissing:
+    // "error"` as the single source; sessionMode does not restate it.
+    // Verified phase11 (test/fixtures/phase11-claude-session-resume):
+    // `session-id-establish.ndjson` creates with `--session-id`, and
+    // `resume-restores.ndjson` restores the same id with `--resume` and
+    // recalls codeword "pomegranate".
     flags: [
       "-p",
       "--input-format",
@@ -63,6 +76,7 @@ export const claudeCode: HarnessDescriptor = deepFreeze({
       "project",
     ],
     idFlag: "--session-id",
+    resumeFlag: "--resume",
     input: { kind: "claude-sdk-user-message" },
     turnEnd: { type: "result" },
     identityProbe: null,
@@ -140,6 +154,13 @@ export const claudeCode: HarnessDescriptor = deepFreeze({
     },
     session: true,
   },
+  // Escalation provenance transcribed from test/fixtures/phase7-questions/,
+  // committed 2026-08-19. `model` is empty because no fixture on that stream
+  // records a model id - absence of evidence, not an unset field.
+  escalation: {
+    supported: true,
+    observedOn: { harness: "claude", model: "", version: "2.1.235", date: "2026-08-19" },
+  },
   turnOptions: {
     effort: { kind: "effort", render: { kind: "flag-value", flag: "--effort" } },
     // issue #48, live-verified 2.1.235: --system-prompt replaces the built-in

package/src/knowledge/codex.ts

@@ -101,6 +101,13 @@ export const codexCli: HarnessDescriptor = deepFreeze({
     },
     session: false,
   },
+  // Escalation provenance transcribed from test/fixtures/phase7-questions/,
+  // committed 2026-08-19. `model` is empty because no fixture on that stream
+  // records a model id - absence of evidence, not an unset field.
+  escalation: {
+    supported: true,
+    observedOn: { harness: "codex", model: "", version: "0.146.1", date: "2026-08-19" },
+  },
   turnOptions: {
     effort: {
       kind: "effort",
@@ -129,12 +136,15 @@ export const codexCli: HarnessDescriptor = deepFreeze({
       render: { kind: "flag-value", flag: "--sandbox" },
     },
   },
-  // Phase 0 fixtures: codex-tool-surface.md. No name lists anywhere -
-  // not on the CLI, not in config.toml. Control is feature booleans
-  // (reachable per-call via -c key=value / --enable/--disable FEATURE),
-  // sandbox, and approval policy. MCP servers do have per-tool keys
-  // (mcp_servers.<id>.tools.<tool>) but built-ins do not.
-  skills: null,
+  // Tools: no built-in name lists; control is feature booleans
+  // (reachable per-call via -c key=value), sandbox, and approval policy.
+  // MCP servers do have per-tool keys (mcp_servers.<id>.tools.<tool>)
+  // but built-ins do not.
+  // Skills (verified 2026-08-22, codex 0.147.0, --strict-config probes):
+  // per-skill disable via config-kv array -c skills.config=[{path=...,
+  // enabled=false}] (selector path or name, validated per entry); also
+  // -c skills.bundled.enabled=false. No global skills.enabled switch.
+  skills: { loadFlag: null, overridesVia: "config-skills-array" },
   tools: {
     includeFlag: null,
     excludeFlag: null,

package/src/knowledge/descriptor.ts

@@ -52,6 +52,9 @@ export interface SessionInputContract {
   readonly kind: SessionInputKind;
 }
 
+export const SESSION_RESUME_FLAGS = ["--resume", "--session-id"] as const;
+export type SessionResumeFlag = (typeof SESSION_RESUME_FLAGS)[number];
+
 /** Consumers branch on these (session-limit: wait for reset; weekly-limit:
  * route elsewhere), so the vocabulary is closed - a descriptor cannot invent
  * a code a consumer has no arm for. */
@@ -302,19 +305,26 @@ export interface HarnessDescriptor {
    * 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:
+   * caller-assigned session identity for a FRESH session (naming). `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
-     * caller ids that already exist (pi rpc: `--session` refuses unknown
-     * ids - spike evidence), so fresh sessions omit the flag and the
-     * harness mints the id, readable via `identityProbe`. */
-    readonly idFlag: string | null;
+    /** The flag that names a fresh session (caller-assigned identity at
+     * spawn). Null only when the harness mints the id itself. */
+    readonly idFlag: SessionResumeFlag | null;
+    /** The flag that carries an EXISTING session id to resume it in
+     * session mode, distinct from `idFlag` which names a fresh session.
+     * Closed vocabulary: pi reuses `--session-id` for both (verified
+     * phase10, test/fixtures/phase10-pi-rpc-resume); claude uses
+     * `--resume` to restore vs `--session-id` to name (verified phase11,
+     * test/fixtures/phase11-claude-session-resume). Unknown-id behavior
+     * is not duplicated here; it reuses `resume.onMissing` as the single
+     * source. */
+    readonly resumeFlag: SessionResumeFlag;
     readonly input: SessionInputContract;
     readonly turnEnd: Readonly<Record<string, string>>;
     readonly identityProbe: { readonly command: string } | null;
@@ -407,6 +417,23 @@ export interface HarnessDescriptor {
     readonly streamingByMode: Readonly<Record<HarnessMode, StreamingGranularity>>;
     readonly session: boolean;
   };
+  /** Escalation provenance: whether this harness and model were observed to
+   * emit the structured hcn-question block when instructed, and when that
+   * observation was made. `supported` is documented as "this harness and
+   * model were observed to emit the structured block when instructed", NOT
+   * as "this harness can ask" - live probes show models ask unprompted, so
+   * a capability-to-ask name would be false. `observedOn` is optional;
+   * absence means no probe exists for this harness/model. Staleness is
+   * derived from version comparison at read time, not stored. */
+  readonly escalation: {
+    readonly supported: boolean;
+    readonly observedOn?: {
+      readonly harness: string;
+      readonly model: string;
+      readonly version: string;
+      readonly date: string;
+    };
+  };
   /** Per-call turn options this harness can express, keyed by the closed
    * `TurnOptionKey` vocabulary. Absent keys are unexpressible on this
    * harness; a call passing them must refuse. Discovery is a table of
@@ -430,10 +457,11 @@ export interface HarnessDescriptor {
    * pi model registry, D-008). */
   /** Caller-directed skills allowlist surface (issue #38). pi: repeatable
    * load flag. claude: per-name "off" overrides via settings JSON.
-   * codex/muse: null (structural gap - trust/config scoped only). */
+   * codex: per-skill "off" via config-kv array (-c skills.config).
+   * muse: null (structural gap - trust/config scoped only). */
   readonly skills: {
     readonly loadFlag: string | null;
-    readonly overridesVia: "settings-skilloverrides" | null;
+    readonly overridesVia: "settings-skilloverrides" | "config-skills-array" | null;
   } | null;
   readonly tools: {
     readonly includeFlag: string | null;

package/src/knowledge/muse.ts

@@ -91,6 +91,13 @@ export const museCode: HarnessDescriptor = deepFreeze({
     },
     session: false,
   },
+  // Escalation provenance transcribed from test/fixtures/phase7-questions/,
+  // committed 2026-08-19. `model` is empty because no fixture on that stream
+  // records a model id - absence of evidence, not an unset field.
+  escalation: {
+    supported: true,
+    observedOn: { harness: "muse", model: "", version: "0.2.1", date: "2026-08-19" },
+  },
   turnOptions: {
     effort: { kind: "effort", render: { kind: "flag-value", flag: "--reasoning-effort" } },
     write: {

package/src/knowledge/pi.ts

@@ -55,10 +55,22 @@ export const piCli: HarnessDescriptor = deepFreeze({
   // slice remains the proven vertical (D-003); this entry is the second.
   sessionMode: {
     flags: ["--mode", "rpc"],
-    // `--session <id>` requires an EXISTING id ("No session found" on a
-    // fresh uuid - live-verified); fresh sessions omit it and pi mints
-    // the id, readable only through the get_state probe.
-    idFlag: null,
+    // pi has TWO flags with similar names and opposite unknown-id behaviour:
+    // `--session <path|id>` requires an EXISTING id (live-verified
+    // "No session found" on a fresh uuid) while `--session-id <id>` creates
+    // it if missing. Session mode uses `--session-id`, the flag the one-shot
+    // resume grammar also uses (resume.flag). That is why `idFlag` is
+    // `--session-id` here and not null - the earlier `idFlag: null` comment
+    // described `--session`, a different flag. Verified phase10
+    // (test/fixtures/phase10-pi-rpc-resume): a second `pi --mode rpc
+    // --session-id <id>` against the same id restored the codeword
+    // "pomegranate" (rpc-resume.ndjson), while the first established it
+    // and warned on stderr "creating a new session with that id"
+    // (rpc-establish.stderr.txt). An unknown id is therefore created with
+    // a stderr warning, which is what `resume.onMissing: "create"` already
+    // records for the one-shot grammar - no duplication in sessionMode.
+    idFlag: "--session-id",
+    resumeFlag: "--session-id",
     input: { kind: "pi-rpc-prompt" },
     turnEnd: { type: "agent_settled" },
     identityProbe: { command: "get_state" },
@@ -119,6 +131,13 @@ export const piCli: HarnessDescriptor = deepFreeze({
     },
     session: true,
   },
+  // Escalation provenance transcribed from test/fixtures/phase7-questions/,
+  // committed 2026-08-19. `model` is empty because no fixture on that stream
+  // records a model id - absence of evidence, not an unset field.
+  escalation: {
+    supported: true,
+    observedOn: { harness: "pi", model: "", version: "0.84.2", date: "2026-08-19" },
+  },
   turnOptions: {
     effort: { kind: "effort", render: { kind: "flag-value", flag: "--thinking" } },
     provider: { kind: "selector", render: { kind: "flag-value", flag: "--provider" } },