@dungle-scrubs/harness-cli-normalizer 0.6.2 → 0.6.4

package/src/execution/supervisor.ts

@@ -27,6 +27,30 @@ import {
  * signal. */
 export const KILL_GRACE_MS = 5_000;
 
+/** Shared process termination policy for turn runners and control probes. */
+export function superviseTermination(
+  clock: Clock,
+  signal: (sig: SignalName) => void,
+): { readonly escalate: () => void; readonly settle: () => void } {
+  let settled = false;
+  let timer: TimerHandle | null = null;
+  return {
+    escalate(): void {
+      if (settled || timer !== null) return;
+      signal("SIGTERM");
+      timer = clock.setTimeout(() => {
+        timer = null;
+        if (!settled) signal("SIGKILL");
+      }, KILL_GRACE_MS);
+    },
+    settle(): void {
+      settled = true;
+      if (timer !== null) clock.clearTimeout(timer);
+      timer = null;
+    },
+  };
+}
+
 /** Bounded tail of unmatched stderr - the crash context a nonzero exit is
  * explained by (v1 kept the turn's output slice for exactly this). */
 export class StderrTail {
@@ -106,30 +130,18 @@ export const superviseTurn = (
   questionMode: QuestionMode,
   io: SupervisorIo,
 ): TurnSupervisor => {
-  let settled = false;
-  let killTimer: TimerHandle | null = null;
+  const termination = superviseTermination(io.clock, io.signal);
   let stallTimer: TimerHandle | null = null;
   let turnOpen = false;
   let lastAssistantText: string | null = null;
 
-  const signal = (sig: SignalName): void => {
-    if (!settled) io.signal(sig);
-  };
-
   const disarm = (): void => {
     if (stallTimer !== null) io.clock.clearTimeout(stallTimer);
     stallTimer = null;
     turnOpen = false;
   };
 
-  const escalate = (): void => {
-    if (settled || killTimer !== null) return;
-    signal("SIGTERM");
-    killTimer = io.clock.setTimeout(() => {
-      killTimer = null;
-      signal("SIGKILL");
-    }, KILL_GRACE_MS);
-  };
+  const escalate = termination.escalate;
 
   const armStall = (): void => {
     if (io.stallMs === undefined || !turnOpen) return;
@@ -156,9 +168,7 @@ export const superviseTurn = (
     disarm,
     escalate,
     settle(): void {
-      settled = true;
-      if (killTimer !== null) io.clock.clearTimeout(killTimer);
-      killTimer = null;
+      termination.settle();
       disarm();
     },
     async stderrLine(line: string): Promise<void> {

package/src/interpretation/argv.ts

@@ -12,6 +12,7 @@ import type {
 import { defaultDescriptors } from "../knowledge/overrides.js";
 import { assertIsolationCombination } from "./isolation.js";
 import { ArgvRefusalError } from "./refusal.js";
+import { assertAccessExclusivity } from "./resolve-options.js";
 import { assertUsableSessionId, SESSION_ID_MAX, SessionIdRefusalError } from "./session-id.js";
 import { renderSkillsSelection, type SkillsSelection } from "./skills-selection.js";
 import { supportedBy } from "./support.js";
@@ -105,12 +106,28 @@ export interface ResumeOptions extends TurnOptions {
 
 export type LaunchOptions = TurnOptions;
 
+/** Returns the exact text to pipe, or null when it travels in argv. */
+export function stdinPromptOf(h: HarnessDescriptor, opts: TurnOptions): string | null {
+  const transport = h.launch.stdinPrompt;
+  if (!transport) return null;
+  const text = promptTextOf(opts);
+  if (text.length <= transport.aboveBytes / 3) return null;
+  return text.length > transport.aboveBytes ||
+    new TextEncoder().encode(text).byteLength > transport.aboveBytes
+    ? text
+    : null;
+}
+
 /** The shared tail of every headless-turn argv: prompt, stream flags, then
  * validated selections, with the variadic tools flag LAST and fed exactly
  * one joined token so nothing after it can be swallowed as a tool name. */
 const turnTail = (h: HarnessDescriptor, opts: TurnOptions): string[] => {
-  assertCleanPrompt(h, opts.prompt);
-  const tail = [promptTextOf(opts), ...h.launch.streamFlags];
+  const stdinPrompt = stdinPromptOf(h, opts);
+  if (stdinPrompt === null) assertCleanPrompt(h, opts.prompt);
+  const tail = [
+    stdinPrompt === null ? promptTextOf(opts) : (h.launch.stdinPrompt?.argument ?? ""),
+    ...h.launch.streamFlags,
+  ];
   if (opts.model !== undefined) {
     const validated = validateModel(h, opts.model);
     if (!validated.ok) {
@@ -154,8 +171,9 @@ const turnTail = (h: HarnessDescriptor, opts: TurnOptions): string[] => {
 export const buildLaunchArgv = (h: HarnessDescriptor, opts: LaunchOptions): string[] => [
   h.bin,
   ...h.launch.baseFlags,
-  ...renderTurnOptions(h, opts, "launch"),
+  ...renderTurnOptions(h, opts, "launch", "before-prompt"),
   ...turnTail(h, opts),
+  ...renderTurnOptions(h, opts, "launch", "after-prompt"),
 ];
 
 /** A session id that fails the shape rule is a spawn-boundary refusal like
@@ -180,6 +198,7 @@ const refuseUnusableSessionId = (h: HarnessDescriptor, sessionId: string): void
 
 export const buildResumeArgv = (h: HarnessDescriptor, opts: ResumeOptions): string[] => {
   refuseUnusableSessionId(h, opts.sessionId);
+  assertAccessExclusivity(h, opts);
   // 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:
@@ -191,8 +210,9 @@ export const buildResumeArgv = (h: HarnessDescriptor, opts: ResumeOptions): stri
     h.resume.flag,
     opts.sessionId,
     ...h.resume.extraFlags,
-    ...renderTurnOptions(h, opts, "resume"),
+    ...renderTurnOptions(h, opts, "resume", "before-prompt"),
     ...turnTail(h, opts),
+    ...renderTurnOptions(h, opts, "resume", "after-prompt"),
   ];
 };
 

package/src/interpretation/context-inspection.ts

@@ -0,0 +1,169 @@
+import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import type { SpawnArgvOptions } from "./argv.js";
+import { buildSpawnArgv } from "./argv.js";
+import { ArgvRefusalError } from "./refusal.js";
+import { asRecord } from "./shape.js";
+
+/** Preserve the real turn's launch settings, replacing only its prompt
+ * transport. The pending task is staged later over the control channel. */
+export function buildContextInspectionArgv(
+  harness: HarnessDescriptor,
+  options: SpawnArgvOptions,
+): string[] {
+  assertContextInspectionOptions(harness, options);
+  if (harness.contextInspection?.kind !== "claude-control-v1") {
+    throw new ArgvRefusalError({
+      harness: harness.name,
+      issue: "invalid-option-value",
+      option: "context",
+      supported: ["verified native context adapter without native passthrough"],
+    });
+  }
+  return [
+    ...buildSpawnArgv(harness, { ...options, prompt: { text: "", explicit: true } }),
+    ...harness.contextInspection.flags,
+    ...(options.resume === undefined ? [] : [harness.contextInspection.forkFlag]),
+  ];
+}
+
+export function assertContextInspectionOptions(
+  harness: HarnessDescriptor,
+  options: SpawnArgvOptions,
+): void {
+  if (!options.passthrough?.length) return;
+  throw new ArgvRefusalError({
+    harness: harness.name,
+    issue: "invalid-option-value",
+    option: "context",
+    supported: ["context inspection without native passthrough"],
+  });
+}
+
+/** A native estimate of the complete staged request, including recalled
+ * history. No inferred token ratio or model table is used here. The caller
+ * owns its additional reserve and dispatch policy. */
+export type ContextInspection =
+  | {
+      readonly contextWindowTokens: number;
+      readonly inputLimitTokens: number;
+      readonly method: "native-context-estimate";
+      readonly model: string;
+      readonly status: "available";
+      readonly totalTokens: number;
+    }
+  | {
+      readonly reason:
+        | "cancelled"
+        | "transport-limit"
+        | "transport"
+        | "protocol"
+        | "timeout"
+        | "cleanup";
+      readonly status: "unavailable";
+    }
+  | {
+      readonly reason:
+        | "unverified-adapter"
+        | "unsupported-adapter"
+        | "auth"
+        | "limit"
+        | "native-exit";
+      readonly status: "unavailable";
+    };
+
+const positive = (value: unknown): value is number =>
+  typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+
+/** Normalize only a complete native response. A window alone says nothing
+ * about remaining capacity, and invalid compaction data must not increase it. */
+export function contextInspectionOf(input: unknown): ContextInspection {
+  const value = asRecord(input);
+  if (
+    value === null ||
+    Array.isArray(input) ||
+    typeof value.model !== "string" ||
+    value.model.length === 0 ||
+    !positive(value.maxTokens) ||
+    typeof value.totalTokens !== "number" ||
+    !Number.isSafeInteger(value.totalTokens) ||
+    value.totalTokens < 0 ||
+    typeof value.isAutoCompactEnabled !== "boolean" ||
+    (value.isAutoCompactEnabled && !positive(value.autoCompactThreshold))
+  ) {
+    return { status: "unavailable", reason: "protocol" };
+  }
+  return {
+    contextWindowTokens: value.maxTokens,
+    inputLimitTokens:
+      value.isAutoCompactEnabled && positive(value.autoCompactThreshold)
+        ? Math.min(value.maxTokens, value.autoCompactThreshold)
+        : value.maxTokens,
+    method: "native-context-estimate",
+    model: value.model,
+    status: "available",
+    totalTokens: value.totalTokens,
+  };
+}
+
+export interface ContextProbe {
+  readonly initial: string;
+  readonly staged: string;
+  accept(
+    line: string,
+  ):
+    | { readonly kind: "send"; readonly line: string }
+    | { readonly kind: "complete"; readonly accounting: ContextInspection }
+    | null;
+}
+
+/** Pure protocol state: only an acknowledgement of this staged UUID allows
+ * the usage query. The execution owner handles transport and cancellation. */
+export function createContextProbe(inputId: string, prompt: string): ContextProbe {
+  let phase: "initialize" | "ack" | "usage" | "finished" = "initialize";
+  const initializeId = `${inputId}:initialize`;
+  const usageId = `${inputId}:usage`;
+  const control = (id: string, request: unknown): string =>
+    JSON.stringify({ type: "control_request", request_id: id, request });
+  const staged = JSON.stringify({
+    message: { role: "user", content: prompt },
+    parent_tool_use_id: null,
+    shouldQuery: false,
+    type: "user",
+    uuid: inputId,
+  });
+  return {
+    initial: control(initializeId, { subtype: "initialize", hooks: null }),
+    staged,
+    accept(line) {
+      if (phase === "finished") return null;
+      let decoded: unknown;
+      try {
+        decoded = JSON.parse(line);
+      } catch {
+        phase = "finished";
+        return { kind: "complete", accounting: { status: "unavailable", reason: "protocol" } };
+      }
+      const frame = asRecord(decoded);
+      if (frame === null || Array.isArray(decoded)) return null;
+      if (phase === "ack" && frame.type === "user" && frame.uuid === inputId) {
+        phase = "usage";
+        return { kind: "send", line: control(usageId, { subtype: "get_context_usage" }) };
+      }
+      const response = asRecord(frame.response);
+      if (frame.type !== "control_response" || response === null || Array.isArray(frame.response))
+        return null;
+      const expected = phase === "initialize" ? initializeId : phase === "usage" ? usageId : null;
+      if (expected === null || response.request_id !== expected) return null;
+      if (response.subtype !== "success") {
+        phase = "finished";
+        return { kind: "complete", accounting: { status: "unavailable", reason: "protocol" } };
+      }
+      if (phase === "initialize") {
+        phase = "ack";
+        return { kind: "send", line: staged };
+      }
+      phase = "finished";
+      return { kind: "complete", accounting: contextInspectionOf(response.response) };
+    },
+  };
+}

package/src/interpretation/refusal.ts

@@ -31,6 +31,7 @@ export type RefusalIssue = (typeof REFUSAL_ISSUES)[number];
  * branch on it without a default arm. */
 export type RefusalOption =
   | TurnOptionKey
+  | "context"
   | "tools"
   | "excludeTools"
   | "skills"

package/src/interpretation/resolve-options.ts

@@ -51,6 +51,30 @@ export interface ResolvedOptions {
   readonly unrenderable: readonly string[];
 }
 
+export function assertAccessExclusivity(
+  harness: HarnessDescriptor,
+  options: Partial<TurnOptions>,
+  explicit: (key: keyof TurnOptions) => boolean = (key) => options[key] !== undefined,
+): void {
+  if (options.access === undefined) return;
+  const spec = harness.turnOptions.access;
+  const claimed = spec?.kind === "access" ? spec.claims : undefined;
+  const claimedConflict = claimed !== undefined && explicit(claimed as keyof TurnOptions);
+  const conflict = explicit("tools") || explicit("excludeTools") || claimedConflict;
+  if (conflict)
+    throw new ArgvRefusalError({
+      issue: "mutually-exclusive-options",
+      harness: harness.name,
+      option: "access",
+      supported: [
+        claimedConflict
+          ? `--access or --${claimed}, not both on ${harness.name}`
+          : "--access is a preset allowlist, not a filter over --tools/--exclude-tools",
+      ],
+      detail: "mutual exclusion",
+    });
+}
+
 /** Expressibility per profile dimension. Dimensions whose "on" state is
  * the harness's own default (discovery all-on) or whose "off" state emits
  * nothing (autonomy false) are expressible EVERYWHERE - the profile value
@@ -211,36 +235,11 @@ export const resolveEffectiveOptions = (
   // from the descriptor, so no harness name appears here.
   const accessSpec = h.turnOptions.access;
   const claimed = accessSpec?.kind === "access" ? accessSpec.claims : undefined;
-  if (claimed !== undefined && resolved.access !== undefined) {
-    const hasExplicit =
-      effectiveArgs[claimed as keyof TurnOptions] !== undefined ||
-      sourceTier(claimed) !== undefined;
-    if (hasExplicit) {
-      throw new ArgvRefusalError({
-        issue: "mutually-exclusive-options",
-        harness: h.name,
-        option: "access",
-        supported: [`--access or --${claimed}, not both on ${h.name}`],
-        detail: "mutual exclusion",
-      });
-    }
-  }
-  // Access vs tools exclusivity: only explicit tools/excludeTools from args or config, never profile-derived.
-  if (resolved.access !== undefined) {
-    const explicitTools = effectiveArgs.tools !== undefined || sourceTier("tools") !== undefined;
-    const explicitExclude =
-      (effectiveArgs as unknown as Record<string, unknown>).excludeTools !== undefined ||
-      sourceTier("excludeTools") !== undefined;
-    if (explicitTools || explicitExclude) {
-      throw new ArgvRefusalError({
-        issue: "mutually-exclusive-options",
-        harness: h.name,
-        option: "access",
-        supported: ["--access is a preset allowlist, not a filter over --tools/--exclude-tools"],
-        detail: "mutual exclusion",
-      });
-    }
-  }
+  assertAccessExclusivity(
+    h,
+    resolved,
+    (key) => effectiveArgs[key] !== undefined || sourceTier(key) !== undefined,
+  );
 
   // toolMap merge per harness per canonical (project > user). The merged
   // shape is the one shape past this point (RFC-02 change 8).

package/src/interpretation/turn-options.ts

@@ -41,6 +41,7 @@ export const renderTurnOptions = (
   h: HarnessDescriptor,
   opts: TurnOptions,
   phase: "launch" | "resume",
+  placement: "all" | "before-prompt" | "after-prompt" = "all",
 ): string[] => {
   assertIsolationCombination(h, opts);
   const sequences: string[][] = [];
@@ -52,6 +53,13 @@ export const renderTurnOptions = (
   for (const key of TURN_OPTION_KEYS) {
     const spec = h.turnOptions[key];
     const raw = (opts as unknown as Record<string, unknown>)[key];
+    const afterPrompt =
+      key === "access" &&
+      spec?.kind === "access" &&
+      opts.access !== undefined &&
+      spec.renders[opts.access] === "tool-preset";
+    if (placement === "before-prompt" && afterPrompt) continue;
+    if (placement === "after-prompt" && !afterPrompt) continue;
 
     // Discovery is a table of facets, handled separately.
     if (key === "discovery") {

package/src/knowledge/claude-code.ts

@@ -1,6 +1,6 @@
 /**
  * The claude-code descriptor: facts about the `claude` CLI as data, verified
- * against claude 2.1.233 and the 00-chat-substrate spike evidence (A-001,
+ * against claude 2.1.263 and the 00-chat-substrate spike evidence (A-001,
  * A-002, A-005). No process logic lives here.
  *
  * Discovery: claude 2.1.233 has no isolated instruction-file toggle.
@@ -20,15 +20,20 @@
 import { deepFreeze, type HarnessDescriptor, UUID_SHAPE } from "./descriptor.js";
 import { SHARED_AUTH_MATCHERS, SHARED_LIMIT_MATCHERS } from "./matchers.js";
 
+const STREAM_INPUT_FLAGS = ["--input-format", "stream-json"] as const;
+
 export const claudeCode: HarnessDescriptor = deepFreeze({
   name: "claude",
   bin: "claude",
-  verifiedAgainst: "2.1.233",
+  verifiedAgainst: "2.1.263",
   versionSource: { kind: "npm", package: "@anthropic-ai/claude-code" },
   launch: {
     baseFlags: ["-p"],
     subcommands: [],
     promptStyle: "positional",
+    // Print mode accepts piped text. Keep ordinary argv introspection
+    // stable while staying below per-argument limits for large requests.
+    stdinPrompt: { argument: "", aboveBytes: 65_536 },
     // A headless turn launches with the full stream-json output set so the
     // runner can decode identity/limits and stream token deltas; bare -p
     // (granularity none) is a degraded invocation this builder never emits.
@@ -67,8 +72,7 @@ export const claudeCode: HarnessDescriptor = deepFreeze({
     // recalls codeword "pomegranate".
     flags: [
       "-p",
-      "--input-format",
-      "stream-json",
+      ...STREAM_INPUT_FLAGS,
       "--output-format",
       "stream-json",
       "--include-partial-messages",
@@ -117,9 +121,16 @@ export const claudeCode: HarnessDescriptor = deepFreeze({
   autonomy: { flag: "--dangerously-skip-permissions" },
   vocabulary: {
     modelFlag: "--model",
-    models: ["claude-fable-5", "claude-opus-5", "claude-sonnet-5", "claude-haiku-4-5-20251001"],
+    // https://platform.claude.com/docs/en/models/fable-5-1/overview
+    models: [
+      "claude-fable-5-1",
+      "claude-fable-5",
+      "claude-opus-5",
+      "claude-sonnet-5",
+      "claude-haiku-4-5-20251001",
+    ],
     aliases: {
-      fable: "claude-fable-5",
+      fable: "claude-fable-5-1",
       opus: "claude-opus-5",
       sonnet: "claude-sonnet-5",
       haiku: "claude-haiku-4-5-20251001",
@@ -140,6 +151,11 @@ export const claudeCode: HarnessDescriptor = deepFreeze({
     object: "context_window",
     usedPctField: "used_percentage",
   },
+  contextInspection: {
+    kind: "claude-control-v1",
+    flags: [...STREAM_INPUT_FLAGS, "--no-session-persistence", "--replay-user-messages"],
+    forkFlag: "--fork-session",
+  },
   resumeLast: null,
   stdin: "inherit",
   presence: {
@@ -160,7 +176,7 @@ export const claudeCode: HarnessDescriptor = deepFreeze({
   // 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" },
+    observedOn: { harness: "claude", model: "sonnet", version: "2.1.263", date: "2026-09-07" },
   },
   turnOptions: {
     // Native CLI reference: bare removes discovery; the empty built-in list and

package/src/knowledge/codex.ts

@@ -83,6 +83,7 @@ export const codexCli: HarnessDescriptor = deepFreeze({
     cwdSlug: "verbatim",
   },
   contextHook: null,
+  contextInspection: null,
   // Valid only in the `exec resume` context: `codex exec resume --last`.
   resumeLast: { flag: "--last" },
   // codex exec appends piped stdin as a <stdin> block and can block on an

package/src/knowledge/descriptor.ts

@@ -323,6 +323,8 @@ export interface HarnessDescriptor {
      * `workspace-write` into subcommands. */
     readonly subcommands: readonly string[];
     readonly promptStyle: "positional";
+    /** A verified alternate transport for prompts too large for argv. */
+    readonly stdinPrompt?: { readonly argument: string; readonly aboveBytes: number };
     readonly streamFlags: readonly string[];
     /** The flag that pins a caller-assigned id at LAUNCH (spawn-time
      * assignment; the execution layer consumes it), or null when the
@@ -454,6 +456,13 @@ export interface HarnessDescriptor {
     readonly object: string;
     readonly usedPctField: string;
   } | null;
+  /** Disposable native context accounting, verified at verifiedAgainst.
+   * Null is unknown support, never a model-window estimate. */
+  readonly contextInspection: {
+    readonly flags: readonly string[];
+    readonly forkFlag: string;
+    readonly kind: "claude-control-v1";
+  } | null;
   /** Resume-most-recent support (codex --last), or null. The race it opens
    * is owned by the corroboration ranking in interpretation. */
   readonly resumeLast: { readonly flag: string } | null;

package/src/knowledge/muse.ts

@@ -77,6 +77,7 @@ export const museCode: HarnessDescriptor = deepFreeze({
     cwdSlug: "verbatim",
   },
   contextHook: null,
+  contextInspection: null,
   // `muse resume --last` exists (muse resume --help).
   resumeLast: { flag: "--last" },
   stdin: "inherit",

package/src/knowledge/pi.ts

@@ -115,6 +115,7 @@ export const piCli: HarnessDescriptor = deepFreeze({
     cwdSlug: "pi-dash-wrapped",
   },
   contextHook: null,
+  contextInspection: null,
   resumeLast: null,
   stdin: "close-required",
   presence: {