@dungle-scrubs/harness-cli-normalizer 0.1.1

package/src/interpretation/argv.ts

@@ -0,0 +1,188 @@
+/**
+ * Argv construction: pure functions turning a descriptor + launch options
+ * into the exact argv a spawner would exec. Ordering rules (positional
+ * prompt before tool grants) and the spawn-boundary refusals live here so
+ * no caller re-derives them.
+ */
+import type { HarnessDescriptor, StreamingGranularity } from "../knowledge/descriptor.js";
+import { assertUsableSessionId } from "./session-id.js";
+import { validateModel } from "./vocabulary.js";
+
+/** Raised when launch options would corrupt or subvert the spawned argv. */
+export class ArgvRefusalError extends Error {
+  constructor(
+    readonly issue: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "ArgvRefusalError";
+  }
+}
+
+/** One guard for every builder that places a positional prompt. Selector
+ * hygiene (session ids) lives in session-id.ts; model selectors go through
+ * validateModel - both refuse, never sanitize. */
+const assertCleanPrompt = (h: HarnessDescriptor, prompt: string): void => {
+  if (prompt.startsWith("-")) {
+    throw new ArgvRefusalError(
+      "prompt-flag-injection",
+      `positional prompt may not start with '-'; it would be parsed as a flag by ${h.bin}`,
+    );
+  }
+};
+
+export interface TurnOptions {
+  readonly prompt: string;
+  readonly tools?: readonly string[];
+  readonly model?: string;
+  readonly autonomy?: boolean;
+}
+
+export interface ResumeOptions extends TurnOptions {
+  readonly sessionId: string;
+}
+
+export type LaunchOptions = TurnOptions;
+
+/** 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 = [opts.prompt, ...h.launch.streamFlags];
+  if (opts.model !== undefined) {
+    const validated = validateModel(h, opts.model);
+    if (!validated.ok) throw new ArgvRefusalError("unknown-model", validated.reason);
+    tail.push(h.vocabulary.modelFlag, validated.id);
+  }
+  if (opts.autonomy === true) {
+    if (h.autonomy === null) {
+      throw new ArgvRefusalError("no-autonomy-mode", `${h.bin} has no unattended-run flag`);
+    }
+    tail.push(h.autonomy.flag);
+  }
+  if (opts.tools !== undefined && h.launch.toolsFlag !== null) {
+    if (opts.tools.length === 0 || opts.tools.some((t) => t.trim() === "" || t.includes(","))) {
+      throw new ArgvRefusalError(
+        "invalid-tool-grant",
+        `tool grant for ${h.bin} contains an empty entry or a comma; a blank ${h.launch.toolsFlag} value grants nothing detectable, and a comma inside one name silently splits the grant`,
+      );
+    }
+    tail.push(h.launch.toolsFlag, opts.tools.join(","));
+  }
+  return tail;
+};
+
+export const buildLaunchArgv = (h: HarnessDescriptor, opts: LaunchOptions): string[] => [
+  h.bin,
+  ...h.launch.baseFlags,
+  ...turnTail(h, opts),
+];
+
+export const buildResumeArgv = (h: HarnessDescriptor, opts: ResumeOptions): string[] => {
+  assertUsableSessionId(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:
+  // `claude --resume <id> -p <prompt>`, `codex exec resume <id> --json
+  // <prompt>`, `muse exec --session-id <id> <prompt>`.
+  return [
+    h.bin,
+    ...h.launch.subcommands,
+    h.resume.flag,
+    opts.sessionId,
+    ...h.resume.extraFlags,
+    ...turnTail(h, opts),
+  ];
+};
+
+export interface SessionOptions {
+  readonly sessionId: string;
+  readonly model?: string;
+}
+
+export const buildSessionArgv = (h: HarnessDescriptor, opts: SessionOptions): string[] => {
+  if (!h.sessionMode) {
+    throw new ArgvRefusalError(
+      "no-session-mode",
+      `${h.bin} declares no persistent headless session mode`,
+    );
+  }
+  assertUsableSessionId(opts.sessionId);
+  const argv = [
+    h.bin,
+    ...h.launch.baseFlags,
+    ...h.sessionMode.flags,
+    h.sessionMode.idFlag,
+    opts.sessionId,
+  ];
+  if (opts.model !== undefined) {
+    const validated = validateModel(h, opts.model);
+    if (!validated.ok) throw new ArgvRefusalError("unknown-model", validated.reason);
+    argv.push(h.vocabulary.modelFlag, validated.id);
+  }
+  return argv;
+};
+
+/** Canonicalize an argv into a last-wins flag map: `--flag=value` splits,
+ * `--flag value` consumes the following non-flag token as its value, a flag
+ * followed by another flag is boolean. Positional tokens are skipped, so a
+ * value can never satisfy a boolean pin member. Aliases map onto canonical
+ * spellings. Known limitation: a crafted argv giving a pin member as the
+ * value of an unknown variadic flag can still false-positive - full CLI
+ * grammar is unknowable from outside. */
+const flagMapOf = (h: HarnessDescriptor, argv: readonly string[]): Map<string, string | true> => {
+  const map = new Map<string, string | true>();
+  for (let i = 1; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === undefined || !token.startsWith("-")) continue;
+    const eq = token.indexOf("=");
+    if (eq !== -1) {
+      const name = token.slice(0, eq);
+      map.set(h.output.flagAliases[name] ?? name, token.slice(eq + 1));
+      continue;
+    }
+    const name = h.output.flagAliases[token] ?? token;
+    const next = argv[i + 1];
+    if (next !== undefined && !next.startsWith("-")) {
+      map.set(name, next);
+      i++;
+    } else {
+      map.set(name, true);
+    }
+  }
+  return map;
+};
+
+const pinSatisfied = (
+  pin: readonly string[],
+  flags: ReadonlyMap<string, string | true>,
+): boolean => {
+  for (let i = 0; i < pin.length; i++) {
+    const member = pin[i];
+    if (member === undefined || !member.startsWith("-")) continue;
+    const expected = pin[i + 1];
+    const actual = flags.get(member);
+    if (actual === undefined) return false;
+    if (expected !== undefined && !expected.startsWith("-") && actual !== expected) {
+      return false;
+    }
+  }
+  return true;
+};
+
+/** The granularity an invocation will actually emit: pins are checked in
+ * order, first fully-satisfied pin wins (every member present with its
+ * pinned value, last occurrence winning like the CLIs themselves); an argv
+ * satisfying no pin gets the floor. */
+export const streamingGranularityOf = (
+  h: HarnessDescriptor,
+  argv: readonly string[],
+): StreamingGranularity => {
+  if (h.output.pins.length === 0) return h.output.floor;
+  const flags = flagMapOf(h, argv);
+  for (const pin of h.output.pins) {
+    if (pinSatisfied(pin.flags, flags)) return pin.granularity;
+  }
+  return h.output.floor;
+};

package/src/interpretation/capabilities.ts

@@ -0,0 +1,51 @@
+/**
+ * Capability resolution: capabilitiesOf(h, model, mode) answers what this
+ * harness/model/mode combination can actually do, always with a source.
+ * This layer serves the CURATED baseline (or degrades to unknown for a
+ * model outside the vocabulary); runtime verification against a live
+ * harness/registry happens at attach time in the consumer, which upgrades
+ * source to runtime-verified. An LLM self-asserting capability is neither.
+ */
+import type {
+  HarnessDescriptor,
+  HarnessMode,
+  StreamingGranularity,
+} from "../knowledge/descriptor.js";
+import { resolveModel } from "./vocabulary.js";
+
+export interface CapabilityResult {
+  readonly vision: boolean;
+  readonly images: boolean;
+  readonly streaming: StreamingGranularity;
+  readonly session: boolean;
+  readonly source: "runtime-verified" | "curated" | "unknown";
+  readonly confidence: "high" | "medium" | "none";
+}
+
+export const capabilitiesOf = (
+  h: HarnessDescriptor,
+  model: string,
+  mode: HarnessMode,
+): CapabilityResult => {
+  if (!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.
+    return {
+      vision: false,
+      images: false,
+      streaming: "none",
+      session: false,
+      source: "unknown",
+      confidence: "none",
+    };
+  }
+  return {
+    vision: h.capabilities.vision,
+    images: h.capabilities.images,
+    streaming: h.capabilities.streamingByMode[mode],
+    session: h.capabilities.session,
+    source: "curated",
+    confidence: "medium",
+  };
+};

package/src/interpretation/content.ts

@@ -0,0 +1,191 @@
+/**
+ * Content decoding: extract assistant text, token deltas, tool calls, and
+ * progress from ONE parsed harness record. Each harness has an entirely
+ * different event vocabulary, so this dispatches by harness name to a pure
+ * per-harness reader. Identity and wall detection stay descriptor-driven
+ * elsewhere; this owns the message/token/tool/progress classes only.
+ *
+ * (Kept as functions rather than descriptor data because the shapes are
+ * structurally too varied - array-of-blocks text, nested delta events,
+ * payload-discriminated records - for the flat match/field spec that
+ * identity decoding uses.)
+ */
+import type { HarnessName } from "../knowledge/descriptor.js";
+import { asRecord } from "./shape.js";
+
+export type ContentEvent =
+  | { readonly kind: "token"; readonly text: string }
+  | { 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 };
+
+/** Text of an array of `{type:"text", text}` content blocks. */
+const textOfBlocks = (content: unknown): string =>
+  Array.isArray(content)
+    ? content
+        .map((b) => asRecord(b))
+        .filter((b): b is Record<string, unknown> => b !== null && b.type === "text")
+        .map((b) => (typeof b.text === "string" ? b.text : ""))
+        .join("")
+    : "";
+
+const at = (record: Record<string, unknown>, path: string): unknown => {
+  let cursor: unknown = record;
+  for (const seg of path.split(".")) {
+    const inner = asRecord(cursor);
+    if (inner === null) return undefined;
+    cursor = inner[seg];
+  }
+  return cursor;
+};
+
+const claude = (r: Record<string, unknown>): ContentEvent[] => {
+  const events: ContentEvent[] = [];
+  if (r.type === "assistant") {
+    const content = at(r, "message.content");
+    if (Array.isArray(content)) {
+      for (const raw of content) {
+        const block = asRecord(raw);
+        if (block?.type === "tool_use" && typeof block.name === "string") {
+          events.push({ kind: "tool", name: block.name, input: block.input });
+        }
+      }
+    }
+    const text = textOfBlocks(content);
+    if (text !== "") events.push({ kind: "message", role: "assistant", text });
+  } else if (r.type === "stream_event") {
+    const delta = at(r, "event.delta");
+    const d = asRecord(delta);
+    if (d?.type === "text_delta" && typeof d.text === "string") {
+      events.push({ kind: "token", text: d.text });
+    }
+  } else if (r.type === "system" && r.subtype !== "init" && typeof r.subtype === "string") {
+    // Non-init system lines (hook_started etc.) surface as droppable
+    // progress, as the pre-refactor decoder did. The init line is the
+    // identity announcement, handled upstream.
+    events.push({ kind: "progress", label: r.subtype });
+  } else if (r.type === "result" && r.is_error === true) {
+    // A result line marked is_error is a failed turn (max-turns, execution
+    // 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}` });
+  }
+  return events;
+};
+
+// codex item types that are NOT tool activity - everything else on
+// item.started is a tool of some kind (command_execution, file_change,
+// mcp_tool_call, web_search, ...), surfaced generically by item.type.
+const CODEX_NON_TOOL = new Set(["agent_message", "error", "reasoning", "todo_list"]);
+
+const codex = (r: Record<string, unknown>): ContentEvent[] => {
+  const item = asRecord(r.item);
+  if (item === null) return [];
+  // Tool activity is emitted once on start so it is not double-counted
+  // against the completion record. Any non-message/reasoning item is a tool;
+  // name it by its item.type, carry the most useful field as input.
+  if (
+    r.type === "item.started" &&
+    typeof item.type === "string" &&
+    !CODEX_NON_TOOL.has(item.type)
+  ) {
+    const name = item.type === "command_execution" ? "shell" : item.type;
+    const input = item.command ?? item.changes ?? item.query ?? item.invocation ?? undefined;
+    return [{ kind: "tool", name, input }];
+  }
+  if (r.type !== "item.completed") return [];
+  if (item.type === "agent_message" && typeof item.text === "string") {
+    return [{ kind: "message", role: "assistant", text: item.text }];
+  }
+  if (item.type === "error" && typeof item.message === "string") {
+    return [{ kind: "error", message: item.message }];
+  }
+  return [];
+};
+
+const pi = (r: Record<string, unknown>): ContentEvent[] => {
+  // One clean tool event per invocation (the toolcall_start/delta/end and
+  // tool_execution_update stream is noise; tool_execution_start fires once).
+  if (r.type === "tool_execution_start" && typeof r.toolName === "string") {
+    return [{ kind: "tool", name: r.toolName, input: r.args }];
+  }
+  if (r.type === "message_update") {
+    const ev = asRecord(r.assistantMessageEvent);
+    if (ev?.type === "text_delta" && typeof ev.delta === "string") {
+      return [{ kind: "token", text: ev.delta }];
+    }
+    return [];
+  }
+  if (r.type === "message_end") {
+    const message = asRecord(r.message);
+    if (message?.role === "assistant") {
+      // A turn that ends with stopReason "error" is a provider/auth/token
+      // failure pi does NOT print to stderr and exits 0 for (verified with
+      // an expired minimax token: empty content, stopReason error, clean
+      // 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)" },
+        ];
+      }
+      const text = textOfBlocks(message.content);
+      if (text !== "") return [{ kind: "message", role: "assistant", text }];
+    }
+  }
+  return [];
+};
+
+const muse = (r: Record<string, unknown>): ContentEvent[] => {
+  const payload = asRecord(r.payload);
+  if (payload === null) return [];
+  // Tool activity: muse emits a tool_result naming the tool in
+  // correlation_facts.tool_name, with the command inside the result text.
+  if (payload.kind === "tool_result") {
+    const facts = asRecord(payload.correlation_facts);
+    const name = typeof facts?.tool_name === "string" ? facts.tool_name : "tool";
+    // Shell tools carry a JSON result with a `command`; file tools carry
+    // plain prose. Surface the command when present, else leave input off
+    // (the tool name is the signal that matters).
+    let command: unknown;
+    if (typeof payload.text === "string") {
+      try {
+        command = (JSON.parse(payload.text) as Record<string, unknown>).command;
+      } catch {
+        command = undefined;
+      }
+    }
+    return [{ kind: "tool", name, input: command }];
+  }
+  if (payload.kind === "run_output_delta" && typeof payload.text === "string") {
+    return [{ kind: "token", text: payload.text }];
+  }
+  if (payload.kind === "run_terminal") {
+    if (
+      payload.terminal === "completed" &&
+      typeof payload.text === "string" &&
+      payload.text !== ""
+    ) {
+      return [{ kind: "message", role: "assistant", text: payload.text }];
+    }
+    if (payload.terminal === "failed") {
+      const reason = typeof payload.reason === "string" ? payload.reason : "run failed";
+      return [{ kind: "error", message: `muse run failed: ${reason}` }];
+    }
+  }
+  return [];
+};
+
+const READERS: Record<HarnessName, (r: Record<string, unknown>) => ContentEvent[]> = {
+  claude,
+  codex,
+  pi,
+  muse,
+};
+
+export const contentEventsOf = (harness: HarnessName, raw: unknown): ContentEvent[] => {
+  const record = asRecord(raw);
+  if (record === null) return [];
+  return READERS[harness](record);
+};

package/src/interpretation/context.ts

@@ -0,0 +1,28 @@
+/**
+ * Context-hook decoding: recognizes the harness's context-window usage
+ * payload and surfaces it as a `context` HarnessEvent, the droppable
+ * gauge-class event the chat layer may coalesce under pressure. For claude
+ * the payload arrives on the STATUSLINE channel, never on stream-json
+ * stdout - route this at the channel level, do not call it per stdout line.
+ * Values are sanitized (v1 sanitizeContext): non-finite is rejected,
+ * out-of-range is clamped, so callers report nothing rather than a broken
+ * gauge.
+ */
+import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import { asRecord } from "./shape.js";
+
+export interface ContextEvent {
+  readonly kind: "context";
+  readonly usedPct: number;
+}
+
+export const contextEventFrom = (h: HarnessDescriptor, raw: unknown): ContextEvent | null => {
+  if (h.contextHook === null) return null;
+  const record = asRecord(raw);
+  if (record === null) return null;
+  const outer = asRecord(record[h.contextHook.object]);
+  if (outer === null) return null;
+  const usedPct = outer[h.contextHook.usedPctField];
+  if (typeof usedPct !== "number" || !Number.isFinite(usedPct)) return null;
+  return { kind: "context", usedPct: Math.min(100, Math.max(0, usedPct)) };
+};

package/src/interpretation/dimensions.ts

@@ -0,0 +1,20 @@
+/**
+ * Small dimension accessors: one interpretation function per PLAN 3.1
+ * dimension whose value is a direct descriptor lookup. They exist so every
+ * dimension has a single named owner in the interpretation layer - callers
+ * never reach into descriptor internals.
+ */
+import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+
+export const stdinPolicyOf = (h: HarnessDescriptor): "inherit" | "close-required" => h.stdin;
+
+export const providerFlagOf = (h: HarnessDescriptor): string | null =>
+  h.provider === null ? null : h.provider.flag;
+
+export const toolsFlagOf = (h: HarnessDescriptor): string | null => h.launch.toolsFlag;
+
+export const discoveryDisableFlagsOf = (h: HarnessDescriptor): readonly string[] =>
+  h.discoveryDisableFlags;
+
+export const autonomyFlagOf = (h: HarnessDescriptor): string | null =>
+  h.autonomy === null ? null : h.autonomy.flag;

package/src/interpretation/identity.ts

@@ -0,0 +1,81 @@
+/**
+ * Identity decoding: pure recognition of a harness's identity announcement
+ * inside its output stream. D-022: claude re-emits `system/init` with the
+ * same session_id at every turn start, so announcements are deduped against
+ * the last seen id - an identity is only "news" on first sight or change.
+ * Under caller-assigned authority an announcement that differs from the
+ * REQUESTED id is a rotation anomaly (v1 HSI005): binding it would silently
+ * attach the conversation to a context that never saw it, so the outcome is
+ * surfaced for the runner to refuse, never papered over.
+ */
+import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import { isUsableSessionId } from "./session-id.js";
+import { asRecord } from "./shape.js";
+
+export type IdentityOutcome =
+  /** Not an identity announcement at all. */
+  | "none"
+  /** First sight (or a changed id under harness-minted authority). */
+  | "announced"
+  /** Same id as last seen - turn-start metadata, not news. */
+  | "duplicate"
+  /** Caller-assigned authority, but the harness announced a DIFFERENT id
+   * than the one requested - refuse to bind, do not paper over. */
+  | "rotated"
+  /** Announcement present but the id fails the shape rule - not believed. */
+  | "malformed";
+
+export interface DecodedIdentity {
+  /** The id this raw event announces, whether or not it is news. */
+  readonly sessionId: string | null;
+  /** The id to surface as an identity HarnessEvent, or null when not news. */
+  readonly identity: string | null;
+  readonly outcome: IdentityOutcome;
+}
+
+const NOT_ANNOUNCED: DecodedIdentity = { sessionId: null, identity: null, outcome: "none" };
+
+export const decodeIdentity = (
+  h: HarnessDescriptor,
+  raw: unknown,
+  lastSeenId: string | null,
+  requestedId: string | null = null,
+): DecodedIdentity => {
+  const record = asRecord(raw);
+  if (record === null) return NOT_ANNOUNCED;
+  const spec = h.identity.announce;
+  for (const [key, expected] of Object.entries(spec.match)) {
+    if (record[key] !== expected) return NOT_ANNOUNCED;
+  }
+  // idField is a dot-path: muse nests its id at stream.id.
+  let cursor: unknown = record;
+  for (const segment of spec.idField.split(".")) {
+    const inner = asRecord(cursor);
+    if (inner === null) return NOT_ANNOUNCED;
+    cursor = inner[segment];
+  }
+  const announced = cursor;
+  if (typeof announced !== "string" || !isUsableSessionId(announced)) {
+    // A record that matched a real discriminator (claude system/init) but
+    // carries a null/missing/garbage id is a MALFORMED announcement the
+    // runner must see - treating it as unrelated output leaves the runner
+    // waiting for an identity that already failed to arrive. Descriptors
+    // with an empty match (muse: any record) have no discriminator, so a
+    // record without the id path is ordinary output, not malformed.
+    const discriminated = Object.keys(spec.match).length > 0;
+    return discriminated
+      ? { sessionId: null, identity: null, outcome: "malformed" }
+      : NOT_ANNOUNCED;
+  }
+  if (
+    h.identity.authority === "caller-assigned" &&
+    requestedId !== null &&
+    announced !== requestedId
+  ) {
+    return { sessionId: announced, identity: null, outcome: "rotated" };
+  }
+  if (announced === lastSeenId) {
+    return { sessionId: announced, identity: null, outcome: "duplicate" };
+  }
+  return { sessionId: announced, identity: announced, outcome: "announced" };
+};

package/src/interpretation/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Interpretation layer: owns pure functions that operate over descriptors.
+ *
+ * This includes argv building, identity decoding, limit detection, and
+ * capability queries. Every function here is total and side-effect free: it
+ * performs no I/O and imports no side-effecting Node builtins - purity is
+ * test-enforced. It is NOT responsible for spawning processes or handling
+ * streams; that is the execution layer's job.
+ */
+export * from "./argv.js";
+export * from "./capabilities.js";
+export * from "./context.js";
+export * from "./dimensions.js";
+export * from "./identity.js";
+export * from "./limits.js";
+export * from "./parse-resume.js";
+export * from "./presence.js";
+export * from "./resume-last.js";
+export * from "./session-id.js";
+export * from "./session-input.js";
+export * from "./store.js";
+export * from "./vocabulary.js";

package/src/interpretation/limits.ts

@@ -0,0 +1,63 @@
+/**
+ * Wall detection: pure classification of harness output against the
+ * descriptor's limit and auth matchers. Returns the CODE, never the matched
+ * line - the consumers of a detection are a retained record and a viewer
+ * warning, and anything the harness printed on that line (a prompt, a
+ * filename, a customer's name) must not ride along (v1 D-005: records carry
+ * identifiers and outcomes, never content).
+ *
+ * Feed these wall-eligible output only - stderr and the non-JSON tail of a
+ * dying turn - never assistant message content, where the model merely
+ * TALKING about limits would match.
+ */
+import type { AuthFailureKind, HarnessDescriptor, LimitCode } from "../knowledge/descriptor.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
+ * scan over an accumulating session buffer is O(turns x output). */
+const BATCH_SCAN_MAX_LINES = 200;
+
+const scanLine = <Code>(
+  line: string,
+  matchers: ReadonlyArray<readonly [RegExp, Code]>,
+): Code | null => {
+  for (let i = 0; i < matchers.length; i++) {
+    const matcher = matchers[i];
+    if (matcher?.[0].test(line)) return matcher[1];
+  }
+  return null;
+};
+
+const scanTail = <Code>(
+  output: string,
+  matchers: ReadonlyArray<readonly [RegExp, Code]>,
+): Code | null => {
+  let end = output.length;
+  let scanned = 0;
+  while (end > 0 && scanned < BATCH_SCAN_MAX_LINES) {
+    const start = output.lastIndexOf("\n", end - 1);
+    const line = output.slice(start + 1, end).trim();
+    end = start;
+    if (line === "") continue;
+    scanned++;
+    const code = scanLine(line, matchers);
+    if (code !== null) return code;
+  }
+  return null;
+};
+
+/** Per-line entry point for streaming readers: O(1) per line, no rescans. */
+export const detectLimitInLine = (h: HarnessDescriptor, line: string): LimitCode | null =>
+  scanLine(line.trim(), h.limitMatchers);
+
+/** Batch convenience over a turn's tail, bounded and bottom-up. */
+export const detectLimit = (h: HarnessDescriptor, output: string): LimitCode | null =>
+  scanTail(output, h.limitMatchers);
+
+export const detectAuthFailureInLine = (
+  h: HarnessDescriptor,
+  line: string,
+): AuthFailureKind | null => scanLine(line.trim(), h.authMatchers);
+
+export const detectAuthFailure = (h: HarnessDescriptor, output: string): AuthFailureKind | null =>
+  scanTail(output, h.authMatchers);