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

package/src/cli/session.ts

@@ -9,6 +9,9 @@ import { createRenderState, renderEvent } from "./render.js";
 import { resolveHarness } from "./resolve-harness.js";
 
 export const session = async (harnessName: string, rawArgs: string[]): Promise<void> => {
+  // Decided before any refusal can fire: a refused --json session still owes
+  // the stream a failure and a terminal `closed` (RFC-01 rule 3).
+  const jsonMode = rawArgs.includes("--json");
   // issue #44: the gate is the descriptor's sessionMode (claude stream-json,
   // pi --mode rpc), not a hardcoded name list - a harness that grows a
   // session mode is available the moment its descriptor declares one.
@@ -23,9 +26,8 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
       supported,
       detail: `session mode is available on ${supported.join(", ")}; ${harnessName} declares no persistent headless session`,
     });
-    process.stderr.write(`${err.message}\n`);
-    process.stderr.write(`supported: ${supported.join(", ")}\n`);
-    process.exitCode = 2;
+    const { refusalOf, refuse } = await import("./refuse.js");
+    refuse(refusalOf(err), jsonMode, "closed");
     return;
   }
 
@@ -42,6 +44,14 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     process.stderr.write(`unknown flag: ${message}\n`);
+    if (jsonMode) {
+      const { writeFailurePair } = await import("./refuse.js");
+      const { failureFromRejected } = await import("../execution/failure.js");
+      writeFailurePair(
+        failureFromRejected({ issue: "invalid-option-value", detail: `unknown flag: ${message}` }),
+        "closed",
+      );
+    }
     process.exitCode = 2;
     return;
   }
@@ -53,6 +63,7 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
     randomUUID();
   const model = values.model as string | undefined;
   const cwd = values.cwd as string | undefined;
+  const provider = values.provider as string | undefined;
 
   // issue #44: same precedence as hcn run - arg > project > user >
   // default-true. A behavior instruction, so it rides every send's
@@ -87,6 +98,17 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
             : "default";
   } catch (configErr) {
     process.stderr.write(`config error: ${(configErr as Error).message}\n`);
+    if (jsonMode) {
+      const { writeFailurePair } = await import("./refuse.js");
+      const { failureFromRejected } = await import("../execution/failure.js");
+      writeFailurePair(
+        failureFromRejected({
+          issue: "invalid-option-value",
+          detail: `config error: ${(configErr as Error).message}`,
+        }),
+        "closed",
+      );
+    }
     process.exitCode = 2;
     return;
   }
@@ -95,25 +117,92 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
   // Validate sessionId shape? let openSession handle via assertUsableSessionId
   delete (process.env as Record<string, string | undefined>).HERDR_ENV;
 
-  const deps = nodeRunnerDeps();
+  const wantJson = values.json === true;
+  // Opt-in per-turn inactivity budget. 0 disables; no default. A session turn
+  // can hang with the process alive, which no exit code reports.
+  const rawStall = values.stall as string | undefined;
+  let stallMs: number | undefined;
+  if (rawStall !== undefined) {
+    const seconds = Number(rawStall);
+    if (!Number.isFinite(seconds) || seconds < 0) {
+      process.stderr.write(`invalid --stall ${JSON.stringify(rawStall)}; expected seconds >= 0\n`);
+      if (jsonMode) {
+        const { writeFailurePair } = await import("./refuse.js");
+        const { failureFromRejected } = await import("../execution/failure.js");
+        writeFailurePair(
+          failureFromRejected({
+            issue: "invalid-option-value",
+            detail: `invalid --stall ${JSON.stringify(rawStall)}`,
+          }),
+          "closed",
+        );
+      }
+      process.exitCode = 2;
+      return;
+    }
+    if (seconds > 0) stallMs = seconds * 1000;
+  }
+  const baseDeps = stallMs === undefined ? nodeRunnerDeps() : nodeRunnerDeps({ stallMs });
+  // Capture the runner's final exitCode/cause for the --json `closed` event.
+  const closeInfo = { exitCode: null as number | null, cause: "clean" };
+  const droppedIds: string[] = [];
+  const deps = wantJson
+    ? {
+        ...baseDeps,
+        log: (e: Record<string, unknown>) => {
+          if (e.event === "session_close") {
+            closeInfo.exitCode = (e.exitCode as number | null) ?? null;
+            closeInfo.cause = (e.cause as string) ?? "clean";
+          }
+          if (e.event === "sends_dropped" && Array.isArray(e.ids)) {
+            for (const id of e.ids as unknown[]) if (typeof id === "string") droppedIds.push(id);
+          }
+          baseDeps.log?.(e);
+        },
+      }
+    : baseDeps;
 
   let handle: ReturnType<typeof openSession>;
   try {
-    handle = openSession(h, { sessionId, model, cwd, escalateQuestions }, deps);
+    handle = openSession(h, { sessionId, model, cwd, escalateQuestions, provider }, deps);
   } catch (err) {
     if (err instanceof ArgvRefusalError) {
-      process.stderr.write(`${err.message}\n`);
-      if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
-      process.exitCode = 2;
+      const { refusalOf, refuse } = await import("./refuse.js");
+      refuse(refusalOf(err), jsonMode, "closed");
       return;
     }
+    // S002: the harness binary is missing or would not start. A transport
+    // failure, not a refusal - exit 1, and the stream is still owed its pair.
     process.stderr.write(
       `could not open session: ${err instanceof Error ? err.message : String(err)}\n`,
     );
+    if (jsonMode) {
+      const { writeFailurePair } = await import("./refuse.js");
+      const { failureFromTransport } = await import("../execution/failure.js");
+      writeFailurePair(
+        failureFromTransport(err instanceof Error ? err.message : String(err)),
+        "closed",
+      );
+    }
     process.exitCode = 1;
     return;
   }
 
+  if (wantJson) {
+    const { runJsonSession } = await import("./session-json.js");
+    const { getVersion } = await import("./version.js");
+    process.exitCode = await runJsonSession({
+      handle,
+      sessionId,
+      harness: h.name,
+      hcnVersion: getVersion(),
+      escalateQuestions,
+      getCloseInfo: () => closeInfo,
+      getDroppedIds: () => droppedIds,
+    });
+    return;
+  }
+
   process.stdout.write(
     `interactive ${h.name} session ${sessionId}\n(empty line or "exit" to quit)\n`,
   );
@@ -136,6 +225,7 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
 
   // Handle SIGINT to close session cleanly
   let closing = false;
+  let sendCount = 0;
   const doClose = async () => {
     if (closing) return;
     closing = true;
@@ -168,7 +258,7 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
       const trimmed = line.trim();
       if (trimmed === "" || trimmed === "exit") break;
 
-      const result = handle.send(line);
+      const result = handle.send({ id: `you-${++sendCount}`, text: line });
       if (result.disposition === "queued") {
         process.stderr.write(`disposition: queued (turn in progress)\n`);
       }
@@ -209,9 +299,10 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
             answer = a;
           }
         }
-        handle.send(
-          `The user answered the question: "${q.question}" with: ${answer}. Continue accordingly.`,
-        );
+        handle.send({
+          id: `you-${++sendCount}`,
+          text: `The user answered the question: "${q.question}" with: ${answer}. Continue accordingly.`,
+        });
         // Drain the answer turn BEFORE prompting again - the pump's
         // backpressure stalls the harness until the turn iterable is
         // consumed (verified live: menu answered, you-prompt rendered, no

package/src/execution/failure.ts

@@ -13,7 +13,11 @@
  * options or a different harness, not a different model.
  */
 
-import { detectAuthFailureInLine, detectTransportInLine } from "../interpretation/limits.js";
+import {
+  detectAuthFailureInLine,
+  detectTransportInLine,
+  detectUnavailableInLine,
+} from "../interpretation/limits.js";
 import type { RefusalIssue } from "../interpretation/refusal.js";
 import type {
   AuthFailureKind,
@@ -30,6 +34,7 @@ export const FAILURE_CLASSES = Object.freeze([
   "budget",
   "task",
   "transport",
+  "unavailable",
   "rejected",
   "native",
   "timeout",
@@ -76,6 +81,8 @@ const messageFor = (cls: FailureClass, detail?: string): string => {
       return `Task failed${detail ? ` (${detail})` : ""} - surface to caller, do not auto-route`;
     case "transport":
       return `Transport failure${detail ? ` (${detail})` : ""} - retry or route to another provider`;
+    case "unavailable":
+      return `Provider cannot serve this route${detail ? ` (${detail})` : ""} - route to another model or provider`;
     case "rejected":
       return `Request rejected${detail ? ` (${detail})` : ""} - change options or harness`;
     case "timeout":
@@ -144,6 +151,7 @@ export const failureFromTerminalError = (h: HarnessDescriptor, message: string):
   const auth = detectAuthFailureInLine(h, message);
   if (auth !== null) return failureFromAuth(auth);
   if (detectTransportInLine(message)) return failureFromTransport(message);
+  if (detectUnavailableInLine(message)) return failureFromUnavailable(message);
   return failureFromTask(message);
 };
 
@@ -165,6 +173,12 @@ export const failureFromTransport = (detail?: string): FailureSummary => ({
   message: messageFor("transport", detail),
 });
 
+export const failureFromUnavailable = (detail?: string): FailureSummary => ({
+  class: "unavailable",
+  retryable: true,
+  message: messageFor("unavailable", detail),
+});
+
 export const failureFromRejected = (opts: {
   issue: RefusalIssue;
   option?: import("../interpretation/refusal.js").RefusalOption;
@@ -194,6 +208,7 @@ const PRECEDENCE: Record<FailureClass, number> = {
   "rate-limit": 2,
   "usage-limit": 2,
   quota: 2,
+  unavailable: 2,
   budget: 3,
   task: 3,
   transport: 4,

package/src/execution/open-session.ts

@@ -29,7 +29,7 @@ import {
 import type { HarnessDescriptor, SessionInputContract } from "../knowledge/descriptor.js";
 import { AsyncChannel } from "./channel.js";
 import { decodeParsed, freshDecodeState } from "./decode.js";
-import type { RunnerDeps, SpawnedProcess } from "./deps.js";
+import type { RunnerDeps, SpawnedProcess, TimerHandle } from "./deps.js";
 import type { ExitCause, HarnessEvent } from "./events.js";
 import type { FailureSummary } from "./failure.js";
 import {
@@ -50,15 +50,36 @@ export const CLOSE_GRACE_MS = 5_000;
 const PRETURN_MAX = 256;
 
 export interface SessionSendResult {
-  readonly disposition: "started" | "queued";
+  readonly disposition: "started" | "queued" | "rejected";
+  /** Present when rejected. `write-failed` is a broken stdin pipe, which is
+   * a different remedy from a session the caller already closed - the two
+   * must stay distinguishable. */
+  readonly reason?: "write-failed";
+}
+
+/** One turn's event stream, tagged with the id of the send that opened it.
+ * `inputId` is present for every turn a consumer send opened, which today is
+ * every turn; a turn opened by anything else (none exists yet) omits it. */
+export interface SessionTurn extends AsyncIterable<HarnessEvent> {
+  readonly inputId?: string;
+  /** `${sessionId}:turn-${n}`, matching the runner's turn_start log. */
+  readonly turnId?: string;
+}
+
+/** A send's payload: the consumer's correlation id travels with the text
+ * from the moment it arrives to the turn it opens and, on death, to the
+ * loss report. */
+export interface SessionInput {
+  readonly id: string;
+  readonly text: string;
 }
 
 export interface SessionHandle {
   /** One inner iterable per turn, each ending in a turn-scoped `done`.
    * Breaking out of THIS iterable closes the session; breaking out of a
    * single turn's iterable only stops reading that turn. */
-  readonly turns: AsyncIterable<AsyncIterable<HarnessEvent>>;
-  send(text: string): SessionSendResult;
+  readonly turns: AsyncIterable<SessionTurn>;
+  send(input: SessionInput): SessionSendResult;
   close(): Promise<void>;
 }
 
@@ -72,6 +93,8 @@ export interface OpenSessionOptions {
    * every send and arms block detection at turn end; false composes the
    * no-ask instruction and disarms detection. */
   readonly escalateQuestions?: boolean;
+  /** Provider selector (pi); refused on a harness without one. */
+  readonly provider?: string;
 }
 
 export class SessionClosedError extends Error {
@@ -99,6 +122,7 @@ export const openSession = (
   const argv = buildSessionArgv(h, {
     sessionId: opts.sessionId,
     ...(opts.model !== undefined ? { model: opts.model } : {}),
+    ...(opts.provider !== undefined ? { provider: opts.provider } : {}),
   });
   let sessionInput: SessionInputContract;
   try {
@@ -142,7 +166,7 @@ export const openSession = (
     argv: redactArgv(argv),
   });
 
-  const turnsChannel = new AsyncChannel<AsyncIterable<HarnessEvent>>();
+  const turnsChannel = new AsyncChannel<SessionTurn>();
   const state = freshDecodeState(opts.sessionId);
   const escalateQuestions = opts.escalateQuestions !== false;
   const sessionInputMode = h.sessionMode;
@@ -150,7 +174,7 @@ export const openSession = (
   let turnCounter = 0;
   let activeTurn: AsyncChannel<HarnessEvent> | null = null;
   let activeTurnId = "";
-  const pendingSends: string[] = [];
+  const pendingSends: SessionInput[] = [];
   const preTurnEvents: HarnessEvent[] = [];
   let dead = false;
   let closing = false;
@@ -174,6 +198,42 @@ export const openSession = (
     deps.clock.setTimeout(() => safeSignal("SIGKILL"), KILL_GRACE_MS);
   };
 
+  // Per-turn inactivity budget. A session turn can hang with the process
+  // alive and the pipes open, which no exit code reports; without this the
+  // consumer waits forever. Armed at turn start, rearmed on any output
+  // chunk, disarmed at turn end and at exit - the same discipline
+  // streamTurn uses, scoped to the turn rather than the process.
+  let stallTimer: TimerHandle | null = null;
+  let stalled = false;
+  const disarmStall = (): void => {
+    if (stallTimer !== null) deps.clock.clearTimeout(stallTimer);
+    stallTimer = null;
+  };
+  const rearmStall = (): void => {
+    if (deps.stallMs === undefined || activeTurn === null) return;
+    disarmStall();
+    stallTimer = deps.clock.setTimeout(() => {
+      // The turn may have ended between the timer firing and this callback
+      // running. Without this guard a clean turn that finished near the
+      // budget would be reported as a stall and the child signalled.
+      if (activeTurn === null) return;
+      stalled = true;
+      log({
+        event: "stall",
+        sessionId: opts.sessionId,
+        turnId: activeTurnId,
+        harness: h.name,
+        reason: "inactivity",
+        budgetMs: deps.stallMs,
+      });
+      // The turn is owed its own terminal event before the process dies;
+      // the exit path then closes the session with the same cause.
+      void pushFailure(failureFromTransport("stalled: inactivity"));
+      endTurn({ kind: "done", exitCode: null, cause: "stall" });
+      escalate();
+    }, deps.stallMs);
+  };
+
   const writeUser = (text: string): boolean => {
     try {
       stdin.write(
@@ -184,7 +244,13 @@ export const openSession = (
       );
       return true;
     } catch {
-      activeTurn?.push({ kind: "error", message: "send failed: session stdin is gone" });
+      // A broken stdin pipe ends the session: there is no way to drive the
+      // child any more. Surface it as its own event, stop accepting sends,
+      // and END the child - marking it dead here instead would suppress the
+      // very signal that stops it. The exit path then finalizes as usual.
+      void routeEvent({ kind: "error", message: "send failed: session stdin is gone" });
+      closing = true;
+      escalate();
       return false;
     }
   };
@@ -195,19 +261,25 @@ export const openSession = (
     return summary;
   };
 
-  const startTurn = (): void => {
+  const startTurn = (inputId?: string): void => {
     turnLimitSeen = false;
     turnFailures = [];
     turnAsked = false;
     lastAssistantText = null;
     activeTurn = new AsyncChannel<HarnessEvent>();
     activeTurnId = `${opts.sessionId}:turn-${++turnCounter}`;
+    // Tag the turn with the id of the send that opened it, so the consumer
+    // correlates a queued input to its turn by reading the tag, not by
+    // shadowing the runner's delivery order.
+    (activeTurn as { inputId?: string; turnId?: string }).inputId = inputId;
+    (activeTurn as { inputId?: string; turnId?: string }).turnId = activeTurnId;
     log({ event: "turn_start", sessionId: opts.sessionId, turnId: activeTurnId });
     for (const held of preTurnEvents.splice(0)) {
       if (held.kind === "failure") turnFailures.push(summaryOf(held));
       activeTurn.push(held);
     }
-    turnsChannel.push(activeTurn);
+    turnsChannel.push(activeTurn as SessionTurn);
+    rearmStall();
   };
 
   /** issue #44: at a turn boundary, scan the last assistant message for
@@ -246,6 +318,7 @@ export const openSession = (
 
   const endTurn = (done: HarnessEvent & { kind: "done" }): void => {
     if (activeTurn === null) return;
+    disarmStall();
     // Asking is a successful turn: the session semantic is "blocked on
     // answer, session alive" - the done stays TURN-scoped (exitCode null
     // in sessions) and the caller answers with the next send().
@@ -271,7 +344,21 @@ export const openSession = (
     // The boundary is the only legal delivery point for queued input.
     if (dead || closing) return;
     const next = pendingSends.shift();
-    if (next !== undefined && writeUser(next)) startTurn();
+    if (next === undefined) return;
+    if (writeUser(next.text)) {
+      startTurn(next.id);
+      return;
+    }
+    // The queue was shifted but the write failed: report the id that was
+    // accepted as queued and never delivered, instead of dropping it.
+    log({
+      event: "sends_dropped",
+      sessionId: opts.sessionId,
+      count: 1,
+      ids: [next.id],
+      reason: "write-failed",
+      lengths: [next.text.length],
+    });
   };
 
   const routeEvent = (event: HarnessEvent): Promise<void> => {
@@ -434,6 +521,7 @@ export const openSession = (
       }
     };
     for await (const chunk of proc.stdout) {
+      rearmStall();
       for (const line of lines.push(chunk)) await handleLine(line);
     }
     const rest = lines.flush();
@@ -443,6 +531,7 @@ export const openSession = (
   const pumpStderr = async (): Promise<void> => {
     const lines = new LineBuffer();
     for await (const chunk of proc.stderr) {
+      rearmStall();
       for (const line of lines.push(chunk)) {
         const limit = detectLimitInLine(h, line);
         if (limit !== null) {
@@ -478,28 +567,34 @@ export const openSession = (
   const finalize = (): void => {
     if (finalized) return;
     finalized = true;
-    const cause: ExitCause = state.limitSeen
-      ? "limit"
-      : exitCode === 0
-        ? "clean"
-        : exitCode === null
-          ? "killed"
-          : "crash";
+    // A stall killed the process on purpose, so the signal death it caused
+    // reports as "stall", not "killed".
+    const cause: ExitCause = stalled
+      ? "stall"
+      : state.limitSeen
+        ? "limit"
+        : exitCode === 0
+          ? "clean"
+          : exitCode === null
+            ? "killed"
+            : "crash";
     if (pumpError !== null) {
       void routeEvent({ kind: "error", message: `session pump failed: ${String(pumpError)}` });
     }
     if (pendingSends.length > 0) {
       // "queued" was an accepted disposition - the loss must be visible to
       // both the log and the consumer, never silent.
+      const droppedIds = pendingSends.map((s) => s.id);
       void routeEvent({
         kind: "error",
-        message: `${pendingSends.length} queued send(s) died with the session`,
+        message: `${pendingSends.length} queued send(s) died with the session: ${droppedIds.join(", ")}`,
       });
       log({
         event: "sends_dropped",
         sessionId: opts.sessionId,
         count: pendingSends.length,
-        lengths: pendingSends.map((s) => s.length),
+        ids: droppedIds,
+        lengths: pendingSends.map((s) => s.text.length),
       });
       pendingSends.length = 0;
     }
@@ -526,6 +621,8 @@ export const openSession = (
   void proc.exited.then((code) => {
     dead = true;
     exitCode = code;
+    // The process is gone: a later fire would flip a finished turn to stall.
+    disarmStall();
     // Pipes held open past exit (a grandchild) must not hang the session.
     const pipeGrace = deps.clock.setTimeout(() => {
       pipesOpenAtExit = true;
@@ -564,24 +661,36 @@ export const openSession = (
         if (!closing && !dead) void close();
       }
     })(),
-    send(text: string): SessionSendResult {
+    send(input: SessionInput): SessionSendResult {
       if (dead || closing) throw new SessionClosedError();
       if (activeTurn !== null) {
-        pendingSends.push(text);
+        pendingSends.push(input);
         log({
           event: "send",
           sessionId: opts.sessionId,
           turnId: activeTurnId,
+          inputId: input.id,
           disposition: "queued",
         });
         return { disposition: "queued" };
       }
-      if (!writeUser(text)) throw new SessionClosedError();
-      startTurn();
+      if (!writeUser(input.text)) {
+        log({
+          event: "send",
+          sessionId: opts.sessionId,
+          turnId: activeTurnId,
+          inputId: input.id,
+          disposition: "rejected",
+          reason: "write-failed",
+        });
+        return { disposition: "rejected", reason: "write-failed" };
+      }
+      startTurn(input.id);
       log({
         event: "send",
         sessionId: opts.sessionId,
         turnId: activeTurnId,
+        inputId: input.id,
         disposition: "started",
       });
       return { disposition: "started" };

package/src/execution/stream-turn.ts

@@ -20,6 +20,7 @@ import {
   detectAuthFailureInLine,
   detectLimitInLine,
   detectTransportInLine,
+  detectUnavailableInLine,
 } from "../interpretation/limits.js";
 import { composeEscalatedPrompt, detectQuestionBlock } from "../interpretation/question.js";
 import { ArgvRefusalError } from "../interpretation/refusal.js";
@@ -39,6 +40,7 @@ import {
   failureFromTerminalError,
   failureFromTimeout,
   failureFromTransport,
+  failureFromUnavailable,
   reduceFailures,
 } from "./failure.js";
 import { LineBuffer } from "./lines.js";
@@ -595,12 +597,15 @@ export async function* streamTurn(
     ) {
       const tailForNative = stderrTail.snapshot();
       const transportLine = tailForNative.find((line) => detectTransportInLine(line));
+      const unavailableLine = tailForNative.find((line) => detectUnavailableInLine(line));
       const f =
         transportLine !== undefined
           ? failureFromTransport(transportLine)
-          : tailForNative.length > 0
-            ? failureFromNative(exitCode, tailForNative)
-            : failureFromTransport(`nonzero exit ${exitCode}`);
+          : unavailableLine !== undefined
+            ? failureFromUnavailable(unavailableLine)
+            : tailForNative.length > 0
+              ? failureFromNative(exitCode, tailForNative)
+              : failureFromTransport(`nonzero exit ${exitCode}`);
       failures.push(f);
       // Need to emit this failure before done, even though queue is closed
       yield { kind: "failure", ...f };

package/src/interpretation/argv.ts

@@ -189,6 +189,9 @@ export const buildResumeArgv = (h: HarnessDescriptor, opts: ResumeOptions): stri
 export interface SessionOptions {
   readonly sessionId: string;
   readonly model?: string;
+  /** Provider selector (pi). A harness with no provider selector refuses,
+   * the same way a one-shot turn does. */
+  readonly provider?: string;
 }
 
 export const buildSessionArgv = (h: HarnessDescriptor, opts: SessionOptions): string[] => {
@@ -223,6 +226,11 @@ export const buildSessionArgv = (h: HarnessDescriptor, opts: SessionOptions): st
     }
     argv.push(h.vocabulary.modelFlag, validated.id);
   }
+  if (opts.provider !== undefined) {
+    // One dimension, rendered by the same code path a launch argv uses, so
+    // the flag spelling and the refusal (with supportedBy) stay identical.
+    argv.push(...renderTurnOptions(h, { provider: opts.provider } as TurnOptions, "launch"));
+  }
   return argv;
 };
 

package/src/interpretation/limits.ts

@@ -23,9 +23,9 @@ import type {
   HarnessDescriptor,
   LimitCode,
   LimitMatcher,
-  TransportMatcher,
+  PhraseMatcher,
 } from "../knowledge/descriptor.js";
-import { SHARED_TRANSPORT_MATCHERS } from "../knowledge/matchers.js";
+import { SHARED_TRANSPORT_MATCHERS, SHARED_UNAVAILABLE_MATCHERS } from "../knowledge/matchers.js";
 
 /** Bottom-up batch scans stop after this many non-empty lines: the wall is
  * virtually always the last thing a dying turn printed, and an unbounded
@@ -155,29 +155,28 @@ export const detectAuthFailureInLine = (
 export const detectAuthFailure = (h: HarnessDescriptor, output: string): AuthFailureKind | null =>
   scanTail(output, compileAuthMatchers(h.authMatchers));
 
-const transportCache = new WeakMap<
-  ReadonlyArray<TransportMatcher>,
-  ReadonlyArray<readonly [RegExp, boolean]>
->();
+const phraseCache = new WeakMap<ReadonlyArray<PhraseMatcher>, ReadonlyArray<RegExp>>();
 
-const compileTransportMatchers = (
-  matchers: ReadonlyArray<TransportMatcher>,
-): ReadonlyArray<readonly [RegExp, boolean]> => {
-  const cached = transportCache.get(matchers);
+const compilePhraseMatchers = (matchers: ReadonlyArray<PhraseMatcher>): ReadonlyArray<RegExp> => {
+  const cached = phraseCache.get(matchers);
   if (cached !== undefined) return cached;
   if (matchers.length > MAX_MATCHERS_PER_KIND) {
     throw new Error(`more than ${MAX_MATCHERS_PER_KIND} matchers per harness per kind`);
   }
-  const compiled = matchers.map((m) => [validateAndCompile(m.pattern, m.flags), true] as const);
-  transportCache.set(matchers, compiled);
+  const compiled = matchers.map((m) => validateAndCompile(m.pattern, m.flags));
+  phraseCache.set(matchers, compiled);
   return compiled;
 };
 
-export const detectTransportInLine = (line: string): boolean => {
-  const compiled = compileTransportMatchers(SHARED_TRANSPORT_MATCHERS);
+const detectPhraseInLine = (matchers: ReadonlyArray<PhraseMatcher>, line: string): boolean => {
   const windowed = line.slice(0, WINDOW).trim();
-  for (const [re] of compiled) {
-    if (re.test(windowed)) return true;
-  }
-  return false;
+  return compilePhraseMatchers(matchers).some((re) => re.test(windowed));
 };
+
+/** A network or gateway fault between the harness and its provider. */
+export const detectTransportInLine = (line: string): boolean =>
+  detectPhraseInLine(SHARED_TRANSPORT_MATCHERS, line);
+
+/** A provider that answered but cannot serve the requested model. */
+export const detectUnavailableInLine = (line: string): boolean =>
+  detectPhraseInLine(SHARED_UNAVAILABLE_MATCHERS, line);