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

package/src/execution/stream-turn.ts

@@ -22,14 +22,18 @@ import {
   detectTransportInLine,
   detectUnavailableInLine,
 } from "../interpretation/limits.js";
-import { composeEscalatedPrompt, detectQuestionBlock } from "../interpretation/question.js";
+import {
+  composeEscalatedPrompt,
+  detectQuestionBlock,
+  type QuestionMode,
+} from "../interpretation/question.js";
 import { ArgvRefusalError } from "../interpretation/refusal.js";
 import type { HarnessDescriptor } from "../knowledge/descriptor.js";
 import { matcherOverridesOf } from "../knowledge/overrides.js";
 import { AsyncChannel } from "./channel.js";
 import { decodeLine, freshDecodeState } from "./decode.js";
 import type { RunnerDeps, SpawnedProcess } from "./deps.js";
-import type { ExitCause, HarnessEvent } from "./events.js";
+import type { EscalationDetection, ExitCause, HarnessEvent } from "./events.js";
 import type { FailureSummary } from "./failure.js";
 import {
   failureFromAuth,
@@ -111,13 +115,9 @@ export interface TurnRunOptions extends LaunchOptions {
    * normalized argv. Wrong-harness flags here fail in the harness itself
    * and surface as native errors - hcn never validates them. */
   readonly passthrough?: readonly string[];
-  /** issue #41: question escalation (behavior instruction, NOT a turn
-   * option - no flag ever reaches the harness). True (the default when
-   * undefined) prepends the protocol preamble and arms question-block
-   * detection; false prepends the state-the-assumption instruction and
-   * disarms detection. Applies on launch AND resume: it shapes each
-   * turn's prompt and event stream, never a session setting. */
-  readonly escalateQuestions?: boolean;
+  /** question mode: which preamble to inject (ask/assume/none).
+   * Behavior instruction - never a harness flag. Defaults to "ask". */
+  readonly questions?: QuestionMode;
   /** 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. */
@@ -132,20 +132,17 @@ export async function* streamTurn(
   const turnId = deps.turnId ?? `turn-${++turnCounter}`;
   const log = deps.log ?? (() => {});
 
-  // issue #41: compose the escalation preamble onto the prompt (the
-  // transport IS the prompt - no harness has native question conveyance)
-  // and arm detection in the true mode. Composition is idempotent, so a
-  // caller that already composed (the CLI does, for spawn-line truth)
-  // never double-prepends.
-  const escalateQuestions = opts.escalateQuestions !== false;
+  // compose the preamble onto the prompt based on question mode.
+  const questionMode: QuestionMode = opts.questions ?? "ask";
   const effective: TurnRunOptions = {
     ...opts,
-    prompt: composeEscalatedPrompt(opts.prompt, escalateQuestions),
+    prompt: composeEscalatedPrompt(opts.prompt, questionMode),
   };
   // The turn's last assistant message - where the protocol says the
   // hcn-question block lives. Tracked only when detection is armed.
   let lastAssistantText: string | null = null;
   let asked = false;
+  let escalationDetection: EscalationDetection = "none";
 
   // Validate env before building argv so an invalid env is a refusal, not a spawn
   if (opts.env !== undefined) {
@@ -172,7 +169,13 @@ export async function* streamTurn(
           argv: redactArgv([], effective.prompt),
         });
         yield { kind: "failure", ...failure };
-        yield { kind: "done", exitCode: null, cause: "failed", failure };
+        yield {
+          kind: "done",
+          exitCode: null,
+          cause: "failed",
+          failure,
+          escalation: { mode: questionMode, detection: "none" },
+        };
         return;
       }
     }
@@ -188,12 +191,11 @@ export async function* streamTurn(
     if (effective.passthrough !== undefined && effective.passthrough.length > 0) {
       argv = [...argv, "--", ...effective.passthrough];
     }
-    // issue #38: claude renders the skills allowlist as settings JSON at
-    // the argv tail (the complement-off form).
-    const claudeSkillTokens = (opts as unknown as { __claudeSkillTokens?: string[] })
-      .__claudeSkillTokens;
-    if (claudeSkillTokens !== undefined && claudeSkillTokens.length > 0) {
-      argv = [...argv, ...claudeSkillTokens];
+    // issue #38: claude/codex render the skills allowlist as complement-off
+    // tokens at the argv tail (claude: settings JSON; codex: -c skills.config).
+    const skillTokens = (opts as unknown as { __skillTokens?: string[] }).__skillTokens;
+    if (skillTokens !== undefined && skillTokens.length > 0) {
+      argv = [...argv, ...skillTokens];
     }
     granularity = streamingGranularityOf(h, argv);
   } catch (e) {
@@ -223,7 +225,13 @@ export async function* streamTurn(
         argv: argvForLog,
       });
       yield { kind: "failure", ...failure };
-      yield { kind: "done", exitCode: null, cause: "failed", failure };
+      yield {
+        kind: "done",
+        exitCode: null,
+        cause: "failed",
+        failure,
+        escalation: { mode: questionMode, detection: "none" },
+      };
       return;
     }
     throw e;
@@ -271,7 +279,13 @@ export async function* streamTurn(
     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 };
+    yield {
+      kind: "done",
+      exitCode: 127,
+      cause: "failed",
+      failure,
+      escalation: { mode: questionMode, detection: "none" },
+    };
     return;
   }
 
@@ -439,7 +453,7 @@ export async function* streamTurn(
         if (event.terminal === true) await pushFailure(failureFromTerminalError(h, event.message));
         return;
       }
-      if (escalateQuestions && event.kind === "message" && event.role === "assistant") {
+      if (questionMode === "ask" && event.kind === "message" && event.role === "assistant") {
         lastAssistantText = event.text;
       }
       await queue.push(event);
@@ -469,18 +483,26 @@ export async function* streamTurn(
   /** issue #41: scan the last assistant message for the hcn-question
    * block. Structured-first - the block's fields become the event; no
    * prose parsing. Runs after the pumps settle (the last message is only
-   * last then) and only when detection is armed (escalateQuestions
-   * true). A malformed block surfaces as an error event, never a silent
+   * last then) and only when detection is armed (questions ask).
+   * A malformed block surfaces as an error event, never a silent
    * no-op. */
   const emitQuestionIfAsked = async (): Promise<void> => {
-    if (!escalateQuestions || lastAssistantText === null) return;
+    if (questionMode !== "ask" || lastAssistantText === null) {
+      escalationDetection = "none";
+      return;
+    }
     const detection = detectQuestionBlock(lastAssistantText);
-    if (detection === null) return;
+    if (detection === null) {
+      escalationDetection = "none";
+      return;
+    }
     if ("malformed" in detection) {
+      escalationDetection = "malformed";
       await queue.push({ kind: "error", message: detection.malformed });
       await pushFailure(failureFromTask(`malformed hcn-question block: ${detection.malformed}`));
       return;
     }
+    escalationDetection = "block";
     log({
       event: "question",
       turnId,
@@ -680,6 +702,7 @@ export async function* streamTurn(
       exitCode: nativeReduced ? null : exitCode,
       cause,
       ...(reduced ? { failure: reduced } : {}),
+      escalation: { mode: questionMode, detection: escalationDetection },
     };
   } finally {
     if (abortHandler !== null) opts.signal?.removeEventListener("abort", abortHandler);

package/src/interpretation/argv.ts

@@ -76,11 +76,11 @@ export interface TurnOptions {
   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.
-   * Undefined means the default: true. */
-  readonly escalateQuestions?: boolean;
+  /** question mode: which preamble hcn injects (ask/assume/none).
+   * 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. Undefined means the default: "ask". */
+  readonly questions?: import("./question.js").QuestionMode;
   /** Internal: set by CLI when prompt came from --prompt/--prompt-file to bypass leading '-' guard */
   readonly __explicitPrompt?: boolean;
   /** toolMap extensible vocabulary per harness (issue toolMap) */
@@ -192,6 +192,10 @@ export interface SessionOptions {
   /** Provider selector (pi). A harness with no provider selector refuses,
    * the same way a one-shot turn does. */
   readonly provider?: string;
+  /** True when this argv should resume an existing conversation, false for a
+   * fresh session. Controls which descriptor flag is rendered: resumeFlag
+   * vs idFlag. Only consumers that alias --resume/--session-id set this. */
+  readonly isResume?: boolean;
 }
 
 export const buildSessionArgv = (h: HarnessDescriptor, opts: SessionOptions): string[] => {
@@ -206,13 +210,8 @@ export const buildSessionArgv = (h: HarnessDescriptor, opts: SessionOptions): st
     });
   }
   refuseUnusableSessionId(h, opts.sessionId);
-  const argv = [
-    h.bin,
-    ...h.sessionMode.flags,
-    // idFlag null = the harness refuses unknown ids and mints its own
-    // (pi rpc); the caller-side sessionId stays a correlation handle.
-    ...(h.sessionMode.idFlag !== null ? [h.sessionMode.idFlag, opts.sessionId] : []),
-  ];
+  const flag = opts.isResume ? h.sessionMode.resumeFlag : h.sessionMode.idFlag;
+  const argv = [h.bin, ...h.sessionMode.flags, ...(flag !== null ? [flag, opts.sessionId] : [])];
   if (opts.model !== undefined) {
     const validated = validateModel(h, opts.model);
     if (!validated.ok) {

package/src/interpretation/capabilities.ts

@@ -11,8 +11,30 @@ import type {
   HarnessMode,
   StreamingGranularity,
 } from "../knowledge/descriptor.js";
+import { compareVersions } from "./versions.js";
 import { resolveModel } from "./vocabulary.js";
 
+export interface EscalationObservedOn {
+  readonly harness: string;
+  readonly model: string;
+  readonly version: string;
+  readonly date: string;
+}
+
+/**
+ * Escalation claim: whether this harness and model were observed to emit
+ * the structured hcn-question block when instructed, NOT "this harness can
+ * ask" - live probes show models ask unprompted, so capability-to-ask would
+ * be false.
+ */
+export interface EscalationClaim {
+  /** True when this harness and model were observed to emit the structured block when instructed. */
+  readonly supported: boolean;
+  readonly source: "runtime-verified" | "curated" | "unknown";
+  readonly confidence: "high" | "medium" | "none";
+  readonly observedOn?: EscalationObservedOn;
+}
+
 export interface CapabilityResult {
   readonly vision: boolean;
   readonly images: boolean;
@@ -20,8 +42,34 @@ export interface CapabilityResult {
   readonly session: boolean;
   readonly source: "runtime-verified" | "curated" | "unknown";
   readonly confidence: "high" | "medium" | "none";
+  readonly escalation: EscalationClaim;
 }
 
+const escalationOf = (h: HarnessDescriptor): EscalationClaim => {
+  const obs = h.escalation.observedOn;
+  if (obs !== undefined) {
+    const cmp = compareVersions(obs.version, h.verifiedAgainst);
+    if (cmp < 0) {
+      return {
+        supported: true,
+        source: "runtime-verified",
+        confidence: "medium",
+        observedOn: obs,
+      };
+    }
+    return {
+      supported: true,
+      source: "runtime-verified",
+      confidence: "high",
+      observedOn: obs,
+    };
+  }
+  if (h.escalation.supported) {
+    return { supported: true, source: "curated", confidence: "medium" };
+  }
+  return { supported: false, source: "unknown", confidence: "none" };
+};
+
 export const capabilitiesOf = (
   h: HarnessDescriptor,
   model: string,
@@ -41,6 +89,7 @@ export const capabilitiesOf = (
       session: false,
       source: "unknown",
       confidence: "none",
+      escalation: { supported: false, source: "unknown", confidence: "none" },
     };
   }
   return {
@@ -50,5 +99,6 @@ export const capabilitiesOf = (
     session: h.capabilities.session,
     source: "curated",
     confidence: "medium",
+    escalation: escalationOf(h),
   };
 };

package/src/interpretation/hints.ts

@@ -49,7 +49,7 @@ const HINTS: Readonly<Record<string, Readonly<Record<string, string>>>> = deepFr
     "discovery.extensions":
       "codex loads MCP servers and plugins from config; disable per-server with -c or codex mcp remove rather than a call-time toggle",
     "discovery.skills":
-      "codex discovers skills from its skills directory; no call-time toggle - remove or move the skill files instead",
+      'codex has no global skills-off switch (skills.enabled is not a key); disable per skill per call with -c skills.config=[{path=".../SKILL.md", enabled=false}] and bundled skills with -c skills.bundled.enabled=false',
   },
   pi: {
     sandbox:

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: {