tickmarkr 2.2.1 → 2.3.0

package/dist/drivers/orca.js

@@ -2,8 +2,9 @@ import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { shq } from "../adapters/types.js";
 import { createWorktree, sh } from "../run/git.js";
+import { Journal } from "../run/journal.js";
 import { MAX_BUF } from "./subprocess.js";
-import { formatOwnedName, panesToClose } from "./types.js";
+import { formatOwnedName, panesToClose, parseOwnedName } from "./types.js";
 // Orca (onorca.dev) as a third execution surface beside herdr and subprocess. tickmarkr keeps
 // worktrees, routing, gates, journal and merges; orca supplies visible terminals only. Everything
 // here is bound by the 1.4.186 conformance spike
@@ -31,7 +32,10 @@ import { formatOwnedName, panesToClose } from "./types.js";
 //  - `terminal list`'s `--worktree` is OPTIONAL (same help): the reconcile sweep omits it, because
 //    an older run's leftover sits in a checkout this run never knew (T2).
 /** The response families the ONE shared envelope parser serves. There is no second JSON seam. */
-export const ORCA_RESPONSE_FAMILIES = ["status", "create", "list", "read", "send", "wait", "show", "close"];
+export const ORCA_RESPONSE_FAMILIES = [
+    "status", "create", "list", "read", "send", "wait", "show", "close",
+    "worktree-current", "hooks-status",
+];
 export const ORCA_FIXTURE_VERSION = "1.4.195";
 export const ORCA_CLI_COMMAND_ENV = "ORCA_CLI_COMMAND";
 export const STALE_HANDLE_CODE = "terminal_handle_stale";
@@ -50,6 +54,9 @@ const PAGE_LINES = 500; // per-page ask; orca caps server-side and reports `limi
 const LIST_LIMIT = 10000; // well past orca's own row default; `truncated` still decides (listAll)
 const MAX_PAGES = 400; // runaway guard: a cursor that stops advancing ends the sweep, never loops
 const POLL_MS = 200;
+export const WORKTREE_ADOPTION_TIMEOUT_MS = 60_000;
+const WORKTREE_ADOPTION_POLL_MS = 1_000;
+const WORKTREE_ADOPTION_JOURNAL_MS = 2_000;
 const SYSTEM_TIME = {
     now: () => Date.now(),
     sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
@@ -252,6 +259,9 @@ export class OrcaDriver {
     pageLines;
     pollMs;
     probeStalenessMs;
+    journalRoots = new Map();
+    narrate;
+    hookCoverage;
     constructor(opts = {}) {
         this.bin = opts.bin ?? resolveOrcaCliBinary(process.cwd(), { env: opts.env, platform: opts.platform }) ?? "orca";
         // Config values flow into a shell here: every argv element is quoted, always.
@@ -347,7 +357,7 @@ export class OrcaDriver {
         // Canonical: git and Orca can spell one checkout two ways, and every later comparison — create
         // receipt, relist, reconcile — is against THIS value.
         const worktree = canonicalWorktreePath(cwd);
-        this.slots.set(id, { title, cwd: worktree, buf: "", recoveries: 0, recovering: false });
+        this.slots.set(id, { title, cwd: worktree, agent: opts?.agent, buf: "", recoveries: 0, recovering: false });
         return { id, name: title, cwd: worktree, group: opts?.group };
     }
     /** Where to invoke the CLI for this slot's calls (see OrcaSlotState.dir). */
@@ -396,6 +406,7 @@ export class OrcaDriver {
     }
     async create(st, cmd) {
         await this.probeRuntime(this.cliCwd(st));
+        await this.awaitWorktreeAdoption(st);
         // The selector names THIS slot's checkout outright, and the CLI child is bound to it too, so
         // neither the UI's active worktree (`active`/`current`) nor the daemon's cwd can place it.
         const env = await this.call("create", [
@@ -429,6 +440,64 @@ export class OrcaDriver {
             await this.notify(`tickmarkr orca terminal created on ${surface} surface`, { tier: "attention" });
         }
     }
+    /**
+     * A freshly-created git checkout does not become a valid Orca selector atomically. Ask
+     * `worktree current` FROM that checkout until Orca itself resolves the exact filesystem identity;
+     * an enclosing checkout is still not adoption. Only selector_not_found is a retryable refusal —
+     * malformed envelopes and every other refusal remain explicit driver failures.
+     */
+    async awaitWorktreeAdoption(st) {
+        const started = this.time.now();
+        const deadline = started + WORKTREE_ADOPTION_TIMEOUT_MS;
+        let lastReported;
+        for (;;) {
+            const left = deadline - this.time.now();
+            if (left < 0)
+                break;
+            try {
+                const env = await this.call("worktree-current", ["worktree", "current"], st.cwd, Math.max(1, left));
+                const worktree = env.result.worktree;
+                if (typeof worktree !== "object" || worktree === null || Array.isArray(worktree)) {
+                    throw new OrcaError("worktree-current", "response carries no worktree record", env.raw, { runtimeId: env.runtimeId });
+                }
+                const reported = terminalWorktree(worktree);
+                if (!reported) {
+                    throw new OrcaError("worktree-current", "worktree record carries no path", env.raw, { runtimeId: env.runtimeId });
+                }
+                lastReported = canonicalWorktreePath(reported);
+                if (lastReported === st.cwd) {
+                    const waitedMs = this.time.now() - started;
+                    if (waitedMs > WORKTREE_ADOPTION_JOURNAL_MS)
+                        this.appendAdoptionWait(st, waitedMs);
+                    return;
+                }
+            }
+            catch (error) {
+                if (!(error instanceof OrcaError) || error.code !== "selector_not_found")
+                    throw error;
+                lastReported = undefined;
+            }
+            const remaining = deadline - this.time.now();
+            if (remaining <= 0)
+                break;
+            await this.time.sleep(Math.min(WORKTREE_ADOPTION_POLL_MS, remaining));
+        }
+        const waitedMs = this.time.now() - started;
+        throw new OrcaUnavailableError("worktree-current", `Orca did not adopt ${st.cwd} within ${WORKTREE_ADOPTION_TIMEOUT_MS}ms${lastReported ? ` (last answered ${lastReported})` : ""}`, `waitedMs=${waitedMs}`);
+    }
+    /** Same repo/run/narration path Herdr uses for its driver-owned dispatch-retry row. */
+    appendAdoptionWait(st, waitedMs) {
+        const owned = parseOwnedName(st.title);
+        if (!owned)
+            throw new Error(`cannot journal worktree-adoption-wait: slot ${st.title} carries no run identity`);
+        const repoRoot = this.journalRoots.get(st.cwd);
+        if (!repoRoot) {
+            throw new Error(`cannot journal worktree-adoption-wait: slot ${st.title} has no daemon repo binding for ${st.cwd}`);
+        }
+        Journal.open(repoRoot, owned.runId, this.narrate).append("worktree-adoption-wait", owned.taskId, {
+            milliseconds: waitedMs,
+        });
+    }
     // ---- handle identity and restart recovery ----------------------------------------------------
     /**
      * Every terminal-addressed call — read AND write — goes through here, and the runtime identity is
@@ -628,6 +697,18 @@ export class OrcaDriver {
         ], this.cliCwd(st)), { onRecovered: () => { recovered = true; } });
         return { term: this.validated(family, st, env), raw: env.raw, recovered };
     }
+    /** A rendered-frame liveness read. `--screen` and `--cursor` are mutually exclusive in Orca. */
+    async readScreen(st) {
+        const env = await this.terminalOp("status", st, (h) => this.call("read", [
+            "terminal", "read", "--terminal", h, "--screen",
+        ], this.cliCwd(st)));
+        const term = this.validated("status", st, env);
+        const source = str(term.source);
+        if (source !== "screen" && source !== "screen-unavailable") {
+            throw new OrcaError("read", `screen read reports source ${source ?? "absent"}, not screen or screen-unavailable`, env.raw);
+        }
+        return { term, source };
+    }
     /** A single UNPAGED tail read — exactly what the caller asked for and nothing more. Markers split
      *  across cursor pages are not reassembled here; that is waitOutput's job. */
     async read(slot, lines) {
@@ -704,10 +785,14 @@ export class OrcaDriver {
             // reporting even when the show record alone would still look connected (show carries no
             // status field of its own, so a terminal can report "unknown"/"exited" on read while its
             // show row still says connected — the read leg is the only place that catches that).
-            await this.readPage("status", st, undefined, 1);
+            const screen = await this.readScreen(st);
             if (`${st.runtimeId}:${st.handle}:${st.recoveries}` !== gen) {
                 continue;
             }
+            // No rendered frame means no trustworthy TUI state. In particular, the stream fragments this
+            // call replaced cannot license an idle verdict or a wait probe.
+            if (screen.source === "screen-unavailable")
+                return "unknown";
             const env = await this.terminalOp("show", st, (h) => this.call("show", ["terminal", "show", "--terminal", h], this.cliCwd(st)));
             if (`${st.runtimeId}:${st.handle}:${st.recoveries}` !== gen) {
                 continue;
@@ -715,6 +800,11 @@ export class OrcaDriver {
             const term = this.liveShowTerm("status", st, env);
             if (term.agentWait === true)
                 return "blocked";
+            // Orca can only report tui-idle/agentWait for agents whose managed hook is installed. A
+            // definitively unhooked adapter is unknown; an agent absent from Orca's table keeps the
+            // legacy probe because absence is not proof that the CLI has no compatible status surface.
+            if (await this.agentHookAvailable(st) === false)
+                return "unknown";
             // `idle` is proven only by orca's own tui-idle condition: a 1ms wait is a point-in-time probe —
             // satisfied now → idle; elapsed (the recorded `timeout` refusal) → not idle.
             const isIdle = await this.waitCondition(st, "tui-idle", 1);
@@ -724,6 +814,50 @@ export class OrcaDriver {
             return mapAgentState(term, isIdle);
         }
     }
+    hookAgent(adapter) {
+        if (adapter === "claude-code")
+            return "claude";
+        if (adapter === "cursor-agent")
+            return "cursor";
+        return adapter;
+    }
+    /** true = hooked, false = definitively unhooked, undefined = agent absent from Orca's table. */
+    async agentHookAvailable(st) {
+        if (!st.agent)
+            return undefined;
+        this.hookCoverage ??= this.loadHookCoverage(st.cwd);
+        const coverage = await this.hookCoverage;
+        const state = coverage.states.get(this.hookAgent(st.agent));
+        // The table's omission is deliberately inconclusive even when managed hooks are disabled:
+        // Orca may not know this agent, so preserve the legacy probe exactly as an unlisted row does.
+        if (state === undefined)
+            return undefined;
+        return coverage.enabled && state === "installed";
+    }
+    async loadHookCoverage(cwd) {
+        const env = await this.call("hooks-status", ["agent", "hooks", "status"], cwd);
+        if (typeof env.result.enabled !== "boolean") {
+            throw new OrcaError("hooks-status", "response carries no boolean enabled", env.raw, { runtimeId: env.runtimeId });
+        }
+        const statuses = env.result.statuses;
+        if (!Array.isArray(statuses)) {
+            throw new OrcaError("hooks-status", "response carries no statuses array", env.raw, { runtimeId: env.runtimeId });
+        }
+        const states = new Map();
+        const allowed = new Set(["installed", "not_installed", "partial", "error"]);
+        for (const row of statuses) {
+            if (typeof row !== "object" || row === null || Array.isArray(row)) {
+                throw new OrcaError("hooks-status", "statuses carries a non-object row", env.raw, { runtimeId: env.runtimeId });
+            }
+            const agent = str(row.agent);
+            const state = str(row.state);
+            if (!agent || !state || !allowed.has(state)) {
+                throw new OrcaError("hooks-status", "status row carries no valid agent/state pair", env.raw, { runtimeId: env.runtimeId });
+            }
+            states.set(agent, state);
+        }
+        return { enabled: env.result.enabled, states };
+    }
     /** One `terminal wait` through the full identity machinery. The recorded 1.4.186 elapsed answer
      *  is rc 1 + ok:true + {handle, condition, satisfied:false, status:"running"}; it is "not yet"
      *  only after this method validates all four fields. Any malformed/refused wait remains explicit. */
@@ -791,6 +925,9 @@ export class OrcaDriver {
             return;
         console.log(`[tickmarkr] ${msg}`); // console fallback only — notification injection is out of scope
     }
+    narrateWith(narrate) {
+        this.narrate = narrate;
+    }
     async close(slot) {
         const st = this.slots.get(slot.id);
         if (!st)
@@ -909,7 +1046,11 @@ export class OrcaDriver {
         catch { /* cosmetic — visibility hygiene never fails the run */ }
     }
     // tickmarkr's own createWorktree stays the sole checkout authority — orca never makes worktrees.
-    worktree(repo, branch, baseRef) {
-        return createWorktree(repo, branch, baseRef);
+    async worktree(repo, branch, baseRef) {
+        const worktree = await createWorktree(repo, branch, baseRef);
+        const repoRoot = canonicalWorktreePath(repo);
+        this.journalRoots.set(repoRoot, repoRoot);
+        this.journalRoots.set(canonicalWorktreePath(worktree), repoRoot);
+        return worktree;
     }
 }

package/dist/drivers/subprocess.d.ts

@@ -1,14 +1,14 @@
 import type { ExecutorDriver, NotifyOpts, Slot } from "./types.js";
 export declare const MAX_BUF: number;
-export declare const HERDR_CONTROL_VARS: readonly ["HERDR_ENV", "HERDR_SOCKET_PATH"];
+export declare const HERDR_CONTROL_VARS: readonly ["HERDR_ENV", "HERDR_SOCKET_PATH", "ORCA_TERMINAL_HANDLE", "ORCA_PANE_KEY", "ORCA_TAB_ID"];
 /**
- * Copy of worker env with the fork cap applied and herdr control-plane vars stripped.
+ * Copy of worker env with the fork cap applied and host control-plane vars stripped.
  * The cap is the one the enclosing run resolved (resolvedForkCap) — a worker's suites divide the
  * same machine the gate shells do, so both seams have to read the same run-owned number rather
  * than a flat constant. The operator's own export still wins.
  */
 export declare function sealHerdrEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
-/** Pane/login-shell form of the same worker env seal (herdr seed + daemon setup). */
+/** Pane/login-shell form of the same host-neutral worker env seal (herdr seed + daemon setup). */
 export declare function herdrSealShellPrefix(env?: NodeJS.ProcessEnv): string;
 export declare class SubprocessDriver implements ExecutorDriver {
     id: string;

package/dist/drivers/subprocess.js

@@ -8,13 +8,20 @@ import { createWorktree, FORK_CAP_ENV, resolvedForkCap } from "../run/git.js";
 // waitOutput poll (~10MB/s sustained, far beyond agent-CLI rates). Tail-truncate, never head:
 // consumers only ever tail-read.
 export const MAX_BUF = 2 * 1024 * 1024;
-// OBS-17 / v1.22 T3: control-plane vars that let a process talk to the operator's herdr.
-// Workers, judges, reviewers, and consults must never inherit them — only the daemon process
-// (and its own herdr driver CLI calls) keep the live session. Socket path is the wire; HERDR_ENV
-// is the "I am inside herdr" gate every agent skill checks before mutating panes.
-export const HERDR_CONTROL_VARS = ["HERDR_ENV", "HERDR_SOCKET_PATH"];
+// OBS-17 / v1.22 T3 and OBS-843: host control-plane vars that let a process address the operator's
+// herdr or Orca UI. Workers, judges, reviewers, and consults must never inherit them — only the
+// daemon process and its driver calls keep the live session. TERM_PROGRAM is host description, not
+// an addressing capability, and ORCA_AGENT_HOOK_* belongs to agent status transport, so both stay.
+// Keep the exported name for compatibility even though the list is now host-neutral.
+export const HERDR_CONTROL_VARS = [
+    "HERDR_ENV",
+    "HERDR_SOCKET_PATH",
+    "ORCA_TERMINAL_HANDLE",
+    "ORCA_PANE_KEY",
+    "ORCA_TAB_ID",
+];
 /**
- * Copy of worker env with the fork cap applied and herdr control-plane vars stripped.
+ * Copy of worker env with the fork cap applied and host control-plane vars stripped.
  * The cap is the one the enclosing run resolved (resolvedForkCap) — a worker's suites divide the
  * same machine the gate shells do, so both seams have to read the same run-owned number rather
  * than a flat constant. The operator's own export still wins.
@@ -27,7 +34,7 @@ export function sealHerdrEnv(env = process.env) {
         delete out[k];
     return out;
 }
-/** Pane/login-shell form of the same worker env seal (herdr seed + daemon setup). */
+/** Pane/login-shell form of the same host-neutral worker env seal (herdr seed + daemon setup). */
 export function herdrSealShellPrefix(env = process.env) {
     const forkCap = sealHerdrEnv(env)[FORK_CAP_ENV] ?? resolvedForkCap();
     return `export ${FORK_CAP_ENV}=${shq(forkCap)}; ` +
@@ -56,8 +63,8 @@ export class SubprocessDriver {
         // HARD-05: interactive=false — no operator, so an open stdin pipe is a promise tickmarkr can never
         // keep; codex exec appends a piped stdin as a <stdin> block (`codex exec --help`) and blocks on a
         // read that never EOFs. One spawn site covers every adapter (D-06).
-        // v1.22 T3: seal herdr control vars so worker/judge/review/consult children cannot reach the
-        // operator's herdr (OBS-17 watch-tab leak class). process.env of the daemon is untouched.
+        // v1.22 T3 / OBS-843: seal host control vars so worker/judge/review/consult children cannot
+        // address the operator's herdr or Orca UI. process.env of the daemon is untouched.
         const p = spawn("bash", ["-lc", cmd], {
             cwd: slot.cwd,
             stdio: ["ignore", "pipe", "pipe"],

package/dist/drivers/types.d.ts

@@ -36,6 +36,8 @@ export interface SlotOpts {
     group?: string;
     label?: string;
     owned?: OwnedName;
+    /** Adapter id for execution surfaces whose liveness support is agent-specific. */
+    agent?: string;
 }
 export declare const OWNED_ROLES: readonly ["worker", "judge", "review", "consult", "watch", "other"];
 export type OwnedRole = (typeof OWNED_ROLES)[number];

package/dist/gates/baseline.d.ts

@@ -23,6 +23,8 @@ export interface BaselineCommand {
     exitCode?: number;
     fingerprints: string[];
     missingCommand?: boolean;
+    /** Why a capture returned no verdict. */
+    invalidCause?: "ceiling-kill" | "resource-exhaustion";
     /** What this command actually took at capture, on a pristine tree. Absent in pre-v1.90 baselines. */
     durationMs?: number;
     /** Sum of the per-file durations named by the runner; null when its output names none. */

package/dist/gates/baseline.js

@@ -427,8 +427,9 @@ export function ceilingKillResult(gate, r, ceilingMs) {
  * shell asks it to finish faster than the thing it is measuring.
  */
 export const CAPTURE_CEILING_MS = 1_800_000;
-const invalidCaptureEntry = (durationMs, invalidatingLines = []) => ({
+const invalidCaptureEntry = (durationMs, invalidCause, invalidatingLines = []) => ({
     infra: true,
+    invalidCause,
     fingerprints: [],
     durationMs,
     fileDurationSumMs: null,
@@ -463,7 +464,7 @@ export async function captureBaseline(cwd, commands) {
             console.error(`tickmarkr: baseline capture for "${name}" was killed at its ${CAPTURE_CEILING_MS}ms ceiling — `
                 + `it recorded NO fingerprints, so nothing is forgiven and every gate will treat a pre-existing `
                 + `failure as a fresh one. Raise the ceiling or shorten the command.`);
-            base.commands[name] = invalidCaptureEntry(durationMs);
+            base.commands[name] = invalidCaptureEntry(durationMs, "ceiling-kill");
             continue;
         }
         const combinedOutput = r.stdout + "\n" + r.stderr;
@@ -479,7 +480,7 @@ export async function captureBaseline(cwd, commands) {
                 + `it recorded NO exit-code verdict and NO fingerprints, so nothing is forgiven for this command; `
                 + `the measurement cannot distinguish a pre-existing failure from one caused by exhaustion. `
                 + `First invalidating line: ${invalidatingLines[0]}`);
-            base.commands[name] = invalidCaptureEntry(durationMs, invalidatingLines);
+            base.commands[name] = invalidCaptureEntry(durationMs, "resource-exhaustion", invalidatingLines);
             continue;
         }
         base.commands[name] = {
@@ -591,6 +592,19 @@ export async function compareToBaseline(cwd, commands, baseline, enabled) {
             record(killed);
             continue;
         }
+        const runner = shellToken(cmd) ?? name;
+        if (entry?.missingCommand === true || r.code === 127) {
+            const cause = entry?.missingCommand === true && r.code !== 127
+                ? "the baseline capture recorded this runner as missing"
+                : `the head command exited 127${/\bENOENT\b/i.test(`${r.stdout}\n${r.stderr}`) ? " (spawn ENOENT)" : ""}`;
+            record({
+                gate: name,
+                pass: false,
+                details: `unreadable — ${cause}; runner ${JSON.stringify(runner)} did not produce a trustworthy verdict`,
+                meta: { unreadable: true, runner },
+            });
+            continue;
+        }
         if (r.code === 0) {
             record({ gate: name, pass: true, details: "exit 0" });
             continue;
@@ -629,8 +643,11 @@ export async function compareToBaseline(cwd, commands, baseline, enabled) {
         // entries with no exitCode keep the `?? 1` red default both readers share (merge.ts:131).
         const baselineRed = entry?.infra !== true && (entry?.exitCode ?? 1) !== 0;
         if (!failing.length && !baselineRed) {
+            const recordedCause = entry?.invalidCause === "resource-exhaustion" || entry?.invalidatingLines?.length
+                ? `was invalidated by its recorded process/resource-exhaustion cause${entry.invalidatingLines?.[0] ? ` (${entry.invalidatingLines[0]})` : ""}`
+                : "was killed at its ceiling";
             const closed = entry?.infra === true
-                ? `the baseline capture for this command was killed at its ceiling and recorded no verdict, so nothing here is forgivable — it now exits ${r.code} with no recognizable failure lines — failing closed`
+                ? `the baseline capture for this command ${recordedCause} and recorded no verdict, so nothing here is forgivable — it now exits ${r.code} with no recognizable failure lines — failing closed`
                 : `command was green at baseline but now exits ${r.code} with no recognizable failure lines — failing closed`;
             const evidence = unrecognizedEvidence(raw);
             record({

package/dist/gates/llm.d.ts

@@ -57,9 +57,15 @@ export declare function captureLlmOutput<T>(run: () => Promise<T>): Promise<{
     value: T;
     outputs: string[];
 }>;
+export interface LlmRunResult {
+    output: string;
+    exitCode?: number;
+    timedOut: boolean;
+}
 export declare function runHeadless(adapter: WorkerAdapter, model: string, prompt: string, cwd: string, timeoutMs?: number): Promise<string>;
 export declare function runViaDriver(adapter: WorkerAdapter, model: string, prompt: string, cwd: string, via: LlmVia, timeoutMs?: number): Promise<string>;
 export declare function dewrapPaneVerdict(out: string, nonce: string): string;
+export declare function runLlmDetailed(adapter: WorkerAdapter, model: string, prompt: string, cwd: string, via?: LlmVia, timeoutMs?: number): Promise<LlmRunResult>;
 export declare function runLlm(adapter: WorkerAdapter, model: string, prompt: string, cwd: string, via?: LlmVia, timeoutMs?: number): Promise<string>;
 export declare function extractJson<T>(raw: string): T | null;
 /** Fable F3: verdict JSON must echo the call nonce — skip unbound or mismatched objects. */

package/dist/gates/llm.js

@@ -129,21 +129,24 @@ export async function captureLlmOutput(run) {
     const value = await llmOutputCapture.run(outputs, run);
     return { value, outputs };
 }
-export async function runHeadless(adapter, model, prompt, cwd, timeoutMs = 300000) {
+async function runHeadlessDetailed(adapter, model, prompt, cwd, timeoutMs = 300000) {
     const dir = mkdtempSync(join(tmpdir(), "tickmarkr-llm-"));
     try {
         const pf = join(dir, "prompt.md");
         writeFileSync(pf, prompt);
         const r = await sh(adapter.headlessCommand(pf, model), cwd, timeoutMs);
-        return r.stdout + "\n" + r.stderr;
+        return { output: r.stdout + "\n" + r.stderr, exitCode: r.code, timedOut: r.timedOut === true };
     }
     finally {
         rmSync(dir, { recursive: true, force: true });
     }
 }
+export async function runHeadless(adapter, model, prompt, cwd, timeoutMs = 300000) {
+    return (await runHeadlessDetailed(adapter, model, prompt, cwd, timeoutMs)).output;
+}
 // v1.1 default path: the same headless CLI call, but dispatched through the driver
 // as a visible named agent (herdr pane), with the quote-split completion wrapper.
-export async function runViaDriver(adapter, model, prompt, cwd, via, timeoutMs = 300000) {
+async function runViaDriverDetailed(adapter, model, prompt, cwd, via, timeoutMs = 300000) {
     const dir = mkdtempSync(join(tmpdir(), "tickmarkr-llm-"));
     let slot;
     let accountant;
@@ -176,6 +179,7 @@ export async function runViaDriver(adapter, model, prompt, cwd, via, timeoutMs =
         // false-complete — same guard the worker path uses (daemon.ts:330-331).
         const exitPattern = `TICKMARKR_EXIT_${nonce}:\\d`;
         let out;
+        let timedOut = false;
         const gatePrompt = prompt.startsWith("TICKMARKR-JUDGE") || prompt.startsWith("TICKMARKR-REVIEW");
         if (!gatePrompt) {
             await via.driver.waitOutput(slot, exitPattern, timeoutMs, { regex: true });
@@ -241,8 +245,14 @@ export async function runViaDriver(adapter, model, prompt, cwd, via, timeoutMs =
                     break;
                 }
             }
+            timedOut = Date.now() - startedAt >= timeoutMs && !new RegExp(exitPattern).test(out);
         }
-        return dewrapPaneVerdict(out, nonce);
+        const exitCode = Number(new RegExp(`TICKMARKR_EXIT_${nonce}:(\\d+)`).exec(out)?.[1]);
+        return {
+            output: dewrapPaneVerdict(out, nonce),
+            ...(Number.isFinite(exitCode) ? { exitCode } : {}),
+            timedOut,
+        };
     }
     finally {
         try {
@@ -256,6 +266,9 @@ export async function runViaDriver(adapter, model, prompt, cwd, via, timeoutMs =
         }
     }
 }
+export async function runViaDriver(adapter, model, prompt, cwd, via, timeoutMs = 300000) {
+    return (await runViaDriverDetailed(adapter, model, prompt, cwd, via, timeoutMs)).output;
+}
 // OBS-155: a TUI renders the verdict as a bullet and HARD-wraps it at pane width with a 2-space
 // continuation indent, splitting words mid-token — so literal newlines land inside JSON string
 // literals and ZERO lines begin with `{`. `--source recent-unwrapped` cannot undo it: the wrap is
@@ -315,12 +328,15 @@ export function dewrapPaneVerdict(out, nonce) {
     }
     return out;
 }
+export async function runLlmDetailed(adapter, model, prompt, cwd, via, timeoutMs = 300000) {
+    const result = await (via
+        ? runViaDriverDetailed(adapter, model, prompt, cwd, via, timeoutMs)
+        : runHeadlessDetailed(adapter, model, prompt, cwd, timeoutMs));
+    llmOutputCapture.getStore()?.push(result.output);
+    return result;
+}
 export async function runLlm(adapter, model, prompt, cwd, via, timeoutMs = 300000) {
-    const out = await (via
-        ? runViaDriver(adapter, model, prompt, cwd, via, timeoutMs)
-        : runHeadless(adapter, model, prompt, cwd, timeoutMs));
-    llmOutputCapture.getStore()?.push(out);
-    return out;
+    return (await runLlmDetailed(adapter, model, prompt, cwd, via, timeoutMs)).output;
 }
 export function extractJson(raw) {
     const fenced = [...raw.matchAll(/```json\s*\n([\s\S]*?)```/g)].at(-1);

package/dist/gates/review.d.ts

@@ -41,13 +41,15 @@ export type TaskDiffMeasurement = {
     readonly fullMeasurement: ArtifactDiffMeasurement;
     readonly capMeasurement: ArtifactDiffMeasurement;
 };
-export declare function fetchTaskDiff(worktree: string, baseRef: string): Promise<TaskDiffMeasurement>;
+export declare function fetchTaskDiff(worktree: string, baseRef: string, files?: readonly string[]): Promise<TaskDiffMeasurement>;
 export declare function checkDiffCap(gate: string, measured: number, cap: number, prefix?: string): GateResult | null;
 /** Apply the strict reviewable-logic cap and the finite, larger capture cap independently. */
 export declare function checkTaskDiffCaps(gate: string, measured: Pick<TaskDiffMeasurement, "logicBytes" | "captureBytes">, logicCap: number, prefix?: string): GateResult | null;
 export declare function isDiffCapPark(result: GateResult): boolean;
 export declare function diffCapParkReason(results: GateResult[]): string | null;
 export declare function modelId(model: string): string;
+/** Provider identity comes from the served model, not a gateway adapter's stamped vendor. */
+export declare function modelProvider(model: string, fallback?: string): string;
 export declare function pickReviewer(author: Assignment, channels: BillingChannel[], exclude?: string[], // v1.1 failover: reviewer channels that already produced garbage for this task
 prefer?: string[], // v1.53 T2: review.prefer — reorders eligible channels, never changes eligibility
 floor?: Tier): BillingChannel | null;