tickmarkr 2.0.0 → 2.1.0

package/README.md

@@ -13,7 +13,8 @@ tickmarkr is a spec-driven orchestration harness for AI coding agent CLIs. You w
 acceptance criteria; the engine routes tasks to the best installed agent CLI (claude-code, codex,
 cursor-agent, opencode, grok, pi, kimi) by cost and capability, dispatches work in git worktrees for
 change isolation — as interactive TUIs when running under [herdr](https://herdr.dev), headless
-subprocesses otherwise — and independently verifies each committed result by checking for no new
+subprocesses otherwise, or in [Orca](https://onorca.dev) terminals when you name that driver
+yourself — and independently verifies each committed result by checking for no new
 baseline failures per task, then strictly verifying the integration tip. Green tasks consolidate onto a
 `tickmarkr/<runId>` branch; merging to your mainline is always your call, never automated. Engage
 with full visibility into routing decisions, worker progress, and gate verdicts — or run headless
@@ -250,6 +251,23 @@ and first-attempt success rate. Cost reporting follows strict honesty rules and
 When running under [herdr](https://herdr.dev), tickmarkr creates a labeled pane-and-tab workspace
 for real-time visibility (optional — omit `--driver herdr` or run headless if preferred).
 
+### Orca: an explicit-selection execution surface
+
+[Orca](https://onorca.dev) is the third execution surface, and the only one you must ask for by
+name: `--driver orca` or `driver: orca` in config. `--driver auto` never selects it — auto picks
+herdr when a herdr session is live and subprocess otherwise — so Orca is never inherited from an
+ambient environment variable, and an Orca that is installed but unreachable is not silently
+downgraded to a hidden subprocess worker either. Naming it is the whole gate; its runtime failures
+stay Orca's, reported as failures.
+
+What Orca supplies is terminals. What tickmarkr keeps is everything that decides whether work
+ships: **it creates and owns the git worktree** for every task (Orca is told which checkout to bind
+its terminal to, and never makes one), **it runs the full gate battery** — build, test, lint,
+evidence, scope, acceptance, review — against the commits that land there, and **it holds merge
+authority**, consolidating only green tasks onto the run's `tickmarkr/<runId>` integration branch.
+Orca is given no say over any of the three. Merging that branch to your mainline remains your call,
+exactly as with every other driver.
+
 tickmarkr borrows audit-firm vocabulary for its roles: **you** are the *Partner* (final sign-off),
 workers are the *field team*, the acceptance judge is the *EQR* (engagement quality reviewer), and
 the frontier-model consult is the *National Office*. The terms below use that vocabulary:

package/dist/cli/commands/doctor.d.ts

@@ -2,6 +2,7 @@ import { type ClaudeAlias } from "../../adapters/claude-code.js";
 import type { WorkerAdapter } from "../../adapters/types.js";
 import { type KimiDoctorTurnResult } from "../../adapters/kimi.js";
 import { type CatalogReadResult } from "../../adapters/catalog-remote.js";
+import { type ShResult } from "../../run/git.js";
 /** Where a newer `table_<date>.csv` is discovered — the deployed site builds filenames by
  *  concatenation and publishes no index, so the release listing is the only enumerable surface. */
 export declare const LIVEBENCH_RELEASES_URL = "https://api.github.com/repos/LiveBench/livebench.github.io/contents/public";
@@ -15,7 +16,24 @@ export type DoctorOpts = {
     /** init's between-acts surface: status rows only — the model matrix and inline drift stay
      *  behind `tickmarkr doctor` (files are still written; only the RETURNED string shrinks). */
     compact?: boolean;
+    /** Test seam for the same `orca status --json` transport production invokes. */
+    orcaStatusProbe?: (cwd: string, binary: string) => Promise<ShResult>;
+    /** Test seam for shell-path discovery; absence remains a normal doctor row, never an exception. */
+    resolveOrcaBinary?: (cwd: string) => string | undefined;
 };
+type OrcaCapability = {
+    verdict: "pass" | "fail";
+    detail: string;
+};
+/**
+ * Orca's status body is deliberately interpreted by T1's one shared envelope parser. Doctor owns
+ * only capability presentation: it may classify an absent executable, but it never invents a second
+ * permissive JSON reader for a malformed or refused status response.
+ *
+ * Capability-row `detail` stays hermetic — never `OrcaError.message`, which embeds volatile CLI
+ * stderr (Electron timestamps), so the row is byte-stable across runs.
+ */
+export declare function probeOrcaCapability(cwd: string, opts?: Pick<DoctorOpts, "orcaStatusProbe" | "resolveOrcaBinary">): Promise<OrcaCapability>;
 export declare function runnerIgnoreFinding(cwd: string): {
     verdict: "pass" | "warn";
     detail: string;
@@ -71,3 +89,4 @@ export declare function selfShadowFinding(ownVersion: string, cwd?: string, reso
  */
 export declare function liveBenchStalenessFinding(now: Date): string | undefined;
 export declare function doctor(_argv: string[], cwd?: string, adapters?: WorkerAdapter[], opts?: DoctorOpts): Promise<string>;
+export {};

package/dist/cli/commands/doctor.js

@@ -6,14 +6,17 @@ import { detectPackageManager, turboContinueFindings } from "../../gates/baselin
 import { version } from "./version.js";
 import { allAdapters, binaryShadowWarnings, detectCandidateClis, flagDriftWarnings, modelAliasExclusions, modelAliasLine, probeAll, probeModels, resolveShellBinary, servableExclusions, servabilityLine, writeDoctor } from "../../adapters/registry.js";
 import { CLAUDE_ALIAS_IDENTITY_STAMPS, claudeCode, resolveClaudeAliasIdentity } from "../../adapters/claude-code.js";
+import { shq } from "../../adapters/types.js";
 import { BANNER, compactTokens, dim, fail, kvRow, legend, ok, rule, statusRow, title } from "../../brand.js";
 import { tickmarkrDir, stateDirName } from "../../graph/graph.js";
 import { catalogModelAdvisory, catalogTierRanking, declaredModelWindow, hasWindowsConfig, modelLints, suggestOverlay, ttyVisual } from "../../adapters/model-lints.js";
 import { loadConfig, overlayPreferShapes } from "../../config/config.js";
 import { HerdrDriver } from "../../drivers/herdr.js";
+import { parseEnvelope } from "../../drivers/orca.js";
 import { kimi, probeKimiDoctorTurn } from "../../adapters/kimi.js";
 import { denyPreferCollisionLine, denyPreferCollisions, disallowedBy, excludedChannels, exclusionLine, preferRanks } from "../../route/preference.js";
 import { LIVEBENCH_TABLE_DATE, readCachedCatalog, refreshCatalogCommand } from "../../adapters/catalog-remote.js";
+import { sh } from "../../run/git.js";
 /** Where a newer `table_<date>.csv` is discovered — the deployed site builds filenames by
  *  concatenation and publishes no index, so the release listing is the only enumerable surface. */
 export const LIVEBENCH_RELEASES_URL = "https://api.github.com/repos/LiveBench/livebench.github.io/contents/public";
@@ -21,6 +24,57 @@ export const LIVEBENCH_TABLE_MAX_AGE_DAYS = 90;
 const visual = () => process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
 const alignedStatusRow = (verdict, key, value) => `  ${statusRow(verdict, kvRow(key, value).slice(2))}`;
 const attentionRow = (text) => `  ${statusRow("warn", text)}`;
+/**
+ * Orca's status body is deliberately interpreted by T1's one shared envelope parser. Doctor owns
+ * only capability presentation: it may classify an absent executable, but it never invents a second
+ * permissive JSON reader for a malformed or refused status response.
+ *
+ * Capability-row `detail` stays hermetic — never `OrcaError.message`, which embeds volatile CLI
+ * stderr (Electron timestamps), so the row is byte-stable across runs.
+ */
+export async function probeOrcaCapability(cwd, opts = {}) {
+    const binary = opts.resolveOrcaBinary ? opts.resolveOrcaBinary(cwd) : resolveShellBinary("orca", cwd).resolved;
+    if (!binary)
+        return { verdict: "fail", detail: "CLI not installed" };
+    let response;
+    try {
+        response = await (opts.orcaStatusProbe ?? ((probeCwd, executable) => sh(`${shq(executable)} status --json`, probeCwd, 10_000)))(cwd, binary);
+    }
+    catch {
+        // The seam (or the shell) never reaching a verdict is a failed probe, never an exception out of
+        // doctor: an absent or sick runtime must still render its row.
+        return { verdict: "fail", detail: "CLI installed but runtime probe failed" };
+    }
+    try {
+        // Do this before accepting the process result: Orca's documented refused transport is rc=1
+        // with an ok:false envelope on stdout, and parseEnvelope preserves that refusal fail-closed.
+        const envelope = parseEnvelope("status", response.stdout);
+        if (response.code !== 0 || response.timedOut) {
+            return {
+                verdict: "fail",
+                detail: `CLI installed but runtime probe failed — orca status exited ${response.code}${response.timedOut ? " after timeout" : ""}`,
+            };
+        }
+        const runtime = envelope.result.runtime;
+        const reachable = typeof runtime === "object" && runtime !== null && !Array.isArray(runtime)
+            ? runtime.reachable
+            : undefined;
+        if (reachable === true)
+            return { verdict: "pass", detail: `runtime reachable (${envelope.runtimeId})` };
+        if (reachable === false)
+            return { verdict: "fail", detail: "CLI installed but runtime unreachable" };
+        return { verdict: "fail", detail: "CLI installed but runtime probe failed — status carries no reachability proof" };
+    }
+    catch {
+        // Only the shared parser reads this body. Every shape it rejects — unparseable, non-object,
+        // ok:false refusal, no result, or absent/`none` `_meta.runtimeId` — is a FAILED probe, never
+        // an unreachable-runtime claim: a doctor that re-read those bytes with its own permissive
+        // reader would call malformed metadata "installed but unreachable". Unreachable is proven only
+        // by a well-formed envelope that says `reachable:false` (the shape a live orca CLI emits with
+        // its runtime down — tests/helpers/fake-orca.ts).
+        return { verdict: "fail", detail: "CLI installed but runtime probe failed" };
+    }
+}
 function detectRunner(cwd) {
     const readIf = (p) => (existsSync(join(cwd, p)) ? readFileSync(join(cwd, p), "utf8") : "");
     let pkg = {};
@@ -373,6 +427,11 @@ export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(
     }
     if (trustNa.length)
         rows.push(`  ${dim("=")} ${dim(`n/a (${trustNa.length}): ${trustNa.join(", ")}`)}`);
+    // Orca is an explicit choice, so its health is capability information rather than an auto-routing
+    // input. A failed probe never changes pickDriver's auto ordering or substitutes subprocess.
+    const orca = await probeOrcaCapability(cwd, opts);
+    rows.push(legend("execution runtime:"));
+    rows.push(alignedStatusRow(orca.verdict, "orca", orca.detail));
     for (const [role, sel] of [["judge", cfg.judge], ["consult", cfg.consult]]) {
         if (!health[sel.adapter]?.installed) {
             rows.push(attentionRow(`${role} runs on ${sel.adapter}:${sel.model} — NOT installed; that gate will fail closed until you install it or remap cfg.${role}`));

package/dist/cli/commands/init.js

@@ -12,11 +12,14 @@ import { Journal } from "../../run/journal.js";
 import { doctor } from "./doctor.js";
 import { assembleFleetEditor } from "./fleet.js";
 const SCAFFOLD_SPEC = "tickmarkr.spec.md";
-// Operator-approved (2026-07-17) environments footer — three rows; no npm install for herdr
-// (npm package "herdr" is a reserved 0.0.0 placeholder as of that date).
+// Operator-approved (2026-07-17) environments footer — no npm install for herdr (npm package
+// "herdr" is a reserved 0.0.0 placeholder as of that date). The orca row joins it with the v2.1
+// driver: it is a THIRD execution surface an operator selects outright — `auto` still resolves
+// herdr-else-subprocess and never picks it, so the footer names it beside the other two choices.
 const ENVIRONMENTS_FOOTER = [
     "environments:",
     "  herdr — the full cockpit — every worker, judge, and consult is a visible pane you can watch and unblock · https://herdr.dev",
+    "  orca — visible terminals in the Orca app — an explicit driver choice: set driver: orca (auto never picks it) · https://onorca.dev",
     "  claude code — tickmarkr init --agent installs the /tkr skills + AGENTS.md so Claude Code (or any agent CLI) drives the loop natively",
     "  anywhere — no herdr? same fail-closed gates, headless subprocess driver",
 ].join("\n");

package/dist/cli/commands/resume.js

@@ -1,5 +1,6 @@
+import { parseArgs } from "node:util";
 import { loadConfig } from "../../config/config.js";
-import { pickDriver } from "../../drivers/index.js";
+import { parseDriverOverride, pickDriver } from "../../drivers/index.js";
 import { loadGraph } from "../../graph/graph.js";
 import { formatSummary, runDaemon } from "../../run/daemon.js";
 import { denyPreferCollisionLine, denyPreferCollisions } from "../../route/preference.js";
@@ -7,14 +8,24 @@ import { narrationSink, bindNarration } from "./run.js";
 const summaryGreen = (s) => s.failed.length === 0 && s.human.length === 0 && s.blocked.length === 0 && s.pending.length === 0
     && s.tipVerify !== "failed";
 export async function resume(argv, cwd = process.cwd()) {
-    const runId = argv[0];
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: {
+            "graph-changed": { type: "boolean" },
+            "retry-failed": { type: "boolean" },
+            driver: { type: "string" },
+        },
+        allowPositionals: true,
+    });
+    const runId = positionals[0];
     if (!runId)
-        throw new Error("usage: tickmarkr resume <run-id> [--graph-changed] [--retry-failed]");
+        throw new Error("usage: tickmarkr resume <run-id> [--graph-changed] [--retry-failed] [--driver <auto|herdr|subprocess|orca>]");
+    const driverOverride = parseDriverOverride(values.driver);
     // T3: --graph-changed is the operator's audited release of the engagement-identity guard (Sol #2 /
     // Fable F2) — the daemon refuses a mismatched/unbound journal unless this is set, then journals a
     // graph-rehash event naming both hashes. Strip the flag before runId resolution so a bare id still wins.
-    const graphChanged = argv.includes("--graph-changed");
-    const retryFailed = argv.includes("--retry-failed");
+    const graphChanged = values["graph-changed"] ?? false;
+    const retryFailed = values["retry-failed"] ?? false;
     const cfg = loadConfig(cwd);
     // v1.87 T3 (OBS-162, twice-carried workaround): the preflight runs AFTER the graph is read and
     // sees only the shapes the resumed graph carries. A deny∩prefer collision on a shape no resumed
@@ -32,7 +43,7 @@ export async function resume(argv, cwd = process.cwd()) {
         graphChanged,
         retryFailed,
         // bound to the same sink the daemon gets, so a driver-journaled recovery reaches this rail too
-        driver: bindNarration(pickDriver(cfg), narrate),
+        driver: bindNarration(pickDriver(cfg, driverOverride), narrate),
         // v1.99 T2: the ONE narration sink — the quiet rail on a TTY, the raw journal formatter on a
         // pipe. A resumed run meets the same surface a fresh one does; printing the raw formatter here
         // would leave `resume` as the last place the old unfiltered dump survives. Bound to the run id

package/dist/cli/commands/run.js

@@ -1,7 +1,7 @@
 import { parseArgs } from "node:util";
 import { allAdapters, discoverChannels, probeAll, readDoctor } from "../../adapters/registry.js";
 import { ROUTING_MODES } from "../../config/config.js";
-import { pickDriver } from "../../drivers/index.js";
+import { parseDriverOverride, pickDriver } from "../../drivers/index.js";
 import { loadGraph } from "../../graph/graph.js";
 import { formatSummary, resolveRunMode, runDaemon } from "../../run/daemon.js";
 import { isRunLockLive } from "../../run/lock.js";
@@ -393,6 +393,9 @@ export async function run(argv, cwd = process.cwd()) {
         if (!Number.isInteger(n) || n <= 0)
             throw new Error(`--concurrency must be a positive integer (got ${values.concurrency})`);
     }
+    // Keep invalid input at the argv boundary. In particular, do not cast a string into the closed
+    // driver union and accidentally turn an unknown explicit choice into auto-selection.
+    const driverOverride = parseDriverOverride(values.driver);
     if (values.quality && values.mode !== undefined) {
         throw new Error("--quality is a compatibility alias for --mode partner-led and cannot be combined with an explicit --mode — pass one or the other");
     }
@@ -443,7 +446,7 @@ export async function run(argv, cwd = process.cwd()) {
         const s = await runDaemon(cwd, {
             runId,
             concurrency: values.concurrency ? Number(values.concurrency) : undefined,
-            driver: bindNarration(pickDriver(cfg, values.driver), narrate),
+            driver: bindNarration(pickDriver(cfg, driverOverride), narrate),
             mode: flagMode,
             supersedes: values.supersedes,
             narrate,

package/dist/cli/index.d.ts

@@ -5,7 +5,7 @@ export type CommandResult = string | {
 };
 export type CommandMap = Record<string, (argv: string[]) => Promise<CommandResult>>;
 export declare const COMMANDS: CommandMap;
-export declare const USAGE = "tickmarkr \u2014 spec-driven orchestration harness for AI coding agents\nusage: tickmarkr <command>\n  init          guided setup + doctor; init --agent [--force] [--docs] adds agent skills/docs\n  doctor        re-probe adapters, herdr, auth; print capability matrix (--fix writes the test-runner ignore when a safe edit exists)\n  fleet         interactive fleet editor (fleet --print for CI drift checks)\n  compile <src> spec \u2192 .tickmarkr/graph.json (fails without acceptance criteria)\n  scope <intent> draft a compiled native spec beside an answered intent (--force to overwrite)\n  plan          dry-run routing table + cost estimate + floor lints\n  eval          run checked-in fixtures against every channel in isolated temp repos\n  run           execute the graph (--concurrency N --driver herdr|subprocess --route-strict)\n  status        live run state\n  verify        run the gate battery standalone against merge-base(--base, HEAD)..HEAD \u2014 no daemon, one verdict (--base main --criteria <file> | --task <id> [--files <glob>] [--author adapter:model] [--no-review] [--json])\n  resume <id>   continue a run from its journal\n  report <id>   cost/quality report (--md for committable execution record)\n  profile       show learned routing profile (profile reset = forget history via cursor, keeps telemetry)\n  ui            open the Fleet Studio TUI (full-screen tabbed cockpit)\n  unlock        remove a stale/garbage run lock (refuses if the holder is alive)\n  beat <tier>   record one supervision beat for orchestrator|overseer|watch (--stand-down to hand off); a supervising seat's own watcher loop calls it, and status reads the tier STALE once the beats stop\n  approve <id> <task>  release a park (--uphold sides with the reviewer and funds a fixed attempt; --by <name> --reason <text>); takes effect on resume";
+export declare const USAGE = "tickmarkr \u2014 spec-driven orchestration harness for AI coding agents\nusage: tickmarkr <command>\n  init          guided setup + doctor; init --agent [--force] [--docs] adds agent skills/docs\n  doctor        re-probe adapters, herdr, auth; print capability matrix (--fix writes the test-runner ignore when a safe edit exists)\n  fleet         interactive fleet editor (fleet --print for CI drift checks)\n  compile <src> spec \u2192 .tickmarkr/graph.json (fails without acceptance criteria)\n  scope <intent> draft a compiled native spec beside an answered intent (--force to overwrite)\n  plan          dry-run routing table + cost estimate + floor lints\n  eval          run checked-in fixtures against every channel in isolated temp repos\n  run           execute the graph (--concurrency N --driver auto|herdr|subprocess|orca --route-strict; orca runs only when named)\n  status        live run state\n  verify        run the gate battery standalone against merge-base(--base, HEAD)..HEAD \u2014 no daemon, one verdict (--base main --criteria <file> | --task <id> [--files <glob>] [--author adapter:model] [--no-review] [--json])\n  resume <id>   continue a run from its journal\n  report <id>   cost/quality report (--md for committable execution record)\n  profile       show learned routing profile (profile reset = forget history via cursor, keeps telemetry)\n  ui            open the Fleet Studio TUI (full-screen tabbed cockpit)\n  unlock        remove a stale/garbage run lock (refuses if the holder is alive)\n  beat <tier>   record one supervision beat for orchestrator|overseer|watch (--stand-down to hand off); a supervising seat's own watcher loop calls it, and status reads the tier STALE once the beats stop\n  approve <id> <task>  release a park (--uphold sides with the reviewer and funds a fixed attempt; --by <name> --reason <text>); takes effect on resume";
 export declare function dispatch(cmd: string | undefined, argv: string[], commands?: CommandMap): Promise<{
     out: string;
     code: number;

package/dist/cli/index.js

@@ -35,7 +35,7 @@ usage: tickmarkr <command>
   scope <intent> draft a compiled native spec beside an answered intent (--force to overwrite)
   plan          dry-run routing table + cost estimate + floor lints
   eval          run checked-in fixtures against every channel in isolated temp repos
-  run           execute the graph (--concurrency N --driver herdr|subprocess --route-strict)
+  run           execute the graph (--concurrency N --driver auto|herdr|subprocess|orca --route-strict; orca runs only when named)
   status        live run state
   verify        run the gate battery standalone against merge-base(--base, HEAD)..HEAD — no daemon, one verdict (--base main --criteria <file> | --task <id> [--files <glob>] [--author adapter:model] [--no-review] [--json])
   resume <id>   continue a run from its journal

package/dist/config/config.d.ts

@@ -138,6 +138,7 @@ export declare const TickmarkrConfigSchema: z.ZodObject<{
         auto: "auto";
         herdr: "herdr";
         subprocess: "subprocess";
+        orca: "orca";
     }>;
     integrationBranchPrefix: z.ZodString;
     taskTimeoutMinutes: z.ZodNumber;

package/dist/config/config.js

@@ -266,7 +266,7 @@ const ShapeGateParticipationSchema = z
 });
 export const TickmarkrConfigSchema = z.object({
     concurrency: z.number().int().positive(),
-    driver: z.enum(["auto", "herdr", "subprocess"]),
+    driver: z.enum(["auto", "herdr", "subprocess", "orca"]),
     integrationBranchPrefix: z
         .string()
         .regex(/^[A-Za-z0-9][A-Za-z0-9._/-]*$/, "must be branch-safe (letters/digits/._/-, no spaces or shell metacharacters)")
@@ -713,7 +713,7 @@ export function overlayBytesLoadError(repoRoot, bytes, opts = {}) {
 export function configTemplate(overlay) {
     const base = `# tickmarkr config overlay — merges over built-in defaults (repo beats global beats defaults)
 # concurrency: 3
-# driver: auto            # auto | herdr | subprocess
+# driver: auto            # auto | herdr | subprocess | orca
 # taskTimeoutMinutes: 30
 # contextWarnTokens: 170000   # v1.23: journal+notify once per attempt when live worker context crosses this (status shows the sample)
 # setup: npm ci --prefer-offline   # run in each fresh task worktree before dispatch

package/dist/drivers/herdr.js

@@ -1114,9 +1114,11 @@ export class HerdrDriver {
         // reported the stack. The documented `changed` flag is the verification; anything else — a
         // nonzero exit, `changed:false`, an unparseable result — fails closed.
         const swapped = await this.herdr(`pane swap --source-pane ${shq(pane)} --target-pane ${shq(this.callerPane)}`);
+        // Flag lives at `result.swap.changed` (verbatim 0.8.0); see herdr-swap-shape.test.ts.
         let swapChanged;
         try {
-            swapChanged = JSON.parse(swapped.stdout).result?.changed;
+            const result = JSON.parse(swapped.stdout).result;
+            swapChanged = result?.swap?.changed ?? result?.changed;
         }
         catch {
             /* fail closed below */

package/dist/drivers/index.d.ts

@@ -1,3 +1,7 @@
 import type { TickmarkrConfig } from "../config/config.js";
 import type { ExecutorDriver } from "./types.js";
-export declare function pickDriver(cfg: TickmarkrConfig, override?: "auto" | "herdr" | "subprocess"): ExecutorDriver;
+export declare const DRIVER_CHOICES: readonly ["auto", "herdr", "subprocess", "orca"];
+export type DriverChoice = (typeof DRIVER_CHOICES)[number];
+/** Validate argv at the CLI boundary rather than casting an arbitrary string into a driver choice. */
+export declare function parseDriverOverride(override?: string): DriverChoice | undefined;
+export declare function pickDriver(cfg: TickmarkrConfig, override?: string): ExecutorDriver;

package/dist/drivers/index.js

@@ -1,7 +1,18 @@
 import { HerdrDriver } from "./herdr.js";
+import { OrcaDriver } from "./orca.js";
 import { SubprocessDriver } from "./subprocess.js";
+export const DRIVER_CHOICES = ["auto", "herdr", "subprocess", "orca"];
+/** Validate argv at the CLI boundary rather than casting an arbitrary string into a driver choice. */
+export function parseDriverOverride(override) {
+    if (override === undefined)
+        return undefined;
+    for (const choice of DRIVER_CHOICES)
+        if (override === choice)
+            return choice;
+    throw new Error(`usage: --driver must be one of ${DRIVER_CHOICES.join(" | ")} (got ${override})`);
+}
 export function pickDriver(cfg, override) {
-    const want = override ?? cfg.driver;
+    const want = parseDriverOverride(override) ?? cfg.driver;
     // VIS-09 item 2: plumb the per-tab cap into the HerdrDriver — the driver takes it as a constructor
     // param and never imports config (cfg is the only seam). Guaranteed present: DEFAULT_CONFIG seeds
     // workersPerTab:3 and deepMerge overlays on top, so a missing overlay key still resolves.
@@ -9,5 +20,9 @@ export function pickDriver(cfg, override) {
         return new HerdrDriver("herdr", cfg.visibility.workersPerTab);
     if (want === "subprocess")
         return new SubprocessDriver();
+    // Orca is an operator-selected execution surface. Its runtime failure stays on Orca; selection
+    // must never substitute a hidden subprocess worker after this explicit choice.
+    if (want === "orca")
+        return new OrcaDriver();
     return HerdrDriver.available() ? new HerdrDriver("herdr", cfg.visibility.workersPerTab) : new SubprocessDriver();
 }

package/dist/drivers/orca.d.ts

@@ -0,0 +1,189 @@
+import { type ShResult } from "../run/git.js";
+import { type ExecutorDriver, type NotifyOpts, type Slot, type SlotOpts } from "./types.js";
+/** The response families the ONE shared envelope parser serves. There is no second JSON seam. */
+export declare const ORCA_RESPONSE_FAMILIES: readonly ["status", "create", "list", "read", "send", "wait", "show", "close"];
+export type OrcaFamily = (typeof ORCA_RESPONSE_FAMILIES)[number];
+export declare const STALE_HANDLE_CODE = "terminal_handle_stale";
+export declare const NOT_WRITABLE_CODE = "terminal_not_writable";
+/** The ONLY terminal status that licenses reading a terminal's bytes or its agent state. */
+export declare const RUNNING_STATUS = "running";
+export declare const STATUS_GOVERNED_METHODS: readonly ["read", "waitOutput", "status", "waitAgentStatus"];
+export interface OrcaExec {
+    (args: string[], cwd: string, timeoutMs?: number): Promise<ShResult>;
+}
+export interface OrcaTimeSource {
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+}
+/** Every failure this driver produces is explicit and carries the raw bytes that produced it. */
+export declare class OrcaError extends Error {
+    readonly family: string;
+    readonly reason: string;
+    readonly raw: string;
+    readonly code?: string;
+    readonly runtimeId?: string;
+    constructor(family: string, reason: string, raw: string, opts?: {
+        code?: string;
+        runtimeId?: string;
+    });
+}
+/** The slot cannot be addressed: dead/unknown terminal record, or a handle that cannot be recovered
+ *  to exactly one owned terminal in the slot's own worktree. Never a silent false or empty string. */
+export declare class OrcaUnavailableError extends OrcaError {
+    readonly terminalStatus?: string | undefined;
+    constructor(family: string, reason: string, raw: string, terminalStatus?: string | undefined);
+}
+export interface OrcaEnvelope {
+    result: Record<string, unknown>;
+    runtimeId: string;
+    raw: string;
+}
+/**
+ * The one JSON seam. Fails CLOSED on every degenerate response — empty, unparseable (a truncated
+ * body lands here), non-object, no boolean `ok`, `ok:false`, `ok:true` with no result object, or a
+ * successful response without a usable `_meta.runtimeId` —
+ * and preserves the raw bytes on the thrown error for diagnostics. Callers never see a partial
+ * envelope, so no caller can reinterpret a parse failure as empty output, an unknown-but-successful
+ * status, or a successful close.
+ */
+export declare function parseEnvelope(family: OrcaFamily, stdout: string, raw?: string): OrcaEnvelope;
+/** The worktree a terminal record binds to. The spike pinned the record's shape but not this key's
+ *  spelling, so the known aliases are accepted and nothing else — a record with none is unbound,
+ *  which fails every identity comparison below rather than passing one by default. */
+export declare function terminalWorktree(term: Record<string, unknown>): string | undefined;
+/**
+ * The same checkout under two spellings. git hands tickmarkr one (`/tmp/...` on darwin, or anything
+ * below a symlinked parent) while Orca answers the canonicalized one (`/private/tmp/...`), and
+ * `resolve()` collapses `..` but never a symlink — so string equality on resolved paths reports two
+ * different checkouts and leaves a perfectly valid slot unreacquirable after a runtime restart.
+ * Identity is FILESYSTEM identity. A path that does not exist has no filesystem identity to read, so
+ * it keeps its resolved spelling: deterministic, and still comparable to another spelling of itself.
+ */
+export declare function canonicalWorktreePath(path: string): string;
+/** Conservative agent-state mapping over orca's ACTUAL surfaces: `blocked` only when the show
+ *  record reports agentWait:true, `idle` only when the `terminal wait --for tui-idle` condition is
+ *  satisfied. The recorded 1.4.186 show response carries NO agent field at all — an absent signal
+ *  is "unknown", never a fabricated definite status. */
+export declare function mapAgentState(term: Record<string, unknown>, tuiIdle: boolean): string;
+/**
+ * The renderer hard-wraps long lines, paints margin chrome, and a cursor page boundary splits a
+ * marker exactly like a wrap does. `parseWorkerResult` (src/adapters/prompt.ts) already de-wraps
+ * trailers this way, so marker matching gets the same joined view beside the raw one.
+ * ponytail: joining every line can in principle glue two unrelated lines into a marker — the same
+ * tolerance parseWorkerResult has carried since v1.2; raw is matched first, so an unwrapped hit
+ * never depends on this.
+ */
+export declare function joinWrapped(raw: string): string;
+export interface OrcaDriverOpts {
+    bin?: string;
+    exec?: OrcaExec;
+    time?: OrcaTimeSource;
+    pageLines?: number;
+    pollMs?: number;
+    /** Bounded, seam-adjustable staleness window for runtime probes before mutations. */
+    probeStalenessMs?: number;
+}
+export declare class OrcaDriver implements ExecutorDriver {
+    id: string;
+    interactive: boolean;
+    private slots;
+    private n;
+    private bin;
+    private exec;
+    private time;
+    private pageLines;
+    private pollMs;
+    private probeStalenessMs;
+    constructor(opts?: OrcaDriverOpts);
+    private call;
+    /** The live runtime's identity, or an explicit failure. A missing or unreachable runtime is a
+     *  driver-level failure carrying the raw refusal — never a reachable-looking default. */
+    private runtimeEnv;
+    /** Explicit runtime probe. Also T3's doctor probe. */
+    probeRuntime(cwd?: string): Promise<string>;
+    slot(cwd: string, name: string, opts?: SlotOpts): Promise<Slot>;
+    /** Where to invoke the CLI for this slot's calls (see OrcaSlotState.dir). */
+    private cliCwd;
+    private state;
+    private latched;
+    private assertAvailable;
+    run(slot: Slot, cmd: string): Promise<void>;
+    private create;
+    /**
+     * Every terminal-addressed call — read AND write — goes through here, and the runtime identity is
+     * established BEFORE the runtime-scoped handle goes on the wire. Discarding a lookalike's answer
+     * after reading it is still having addressed it, so the probe comes first; the post-call check
+     * only closes the narrow race of a restart landing between probe and call. Same for an explicit
+     * `terminal_handle_stale`. Either way the driver relists the slot's exact worktree and replaces
+     * the handle exactly once, then re-issues the operation against the replacement.
+     */
+    private terminalOp;
+    private recover;
+    /** Validated READ terminal record, or an explicit unavailable failure. Called BEFORE any caller
+     *  looks at tail bytes — on every page, on every read-governed method. Read records are the one
+     *  place orca reports a literal `status` (recorded: "running" live, "exited" on the dead record). */
+    private validated;
+    /** Validated SHOW terminal record, or an explicit unavailable failure. The recorded 1.4.186 show
+     *  response reports liveness through connected/orphaned and carries NO status and NO agent field,
+     * so this is the status discipline's show leg: a terminal that cannot prove connected-and-not-
+     * orphaned is unavailable for state questions, exactly as a non-running read record is for bytes. */
+    private liveShowTerm;
+    private tailText;
+    private readPage;
+    /** 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. */
+    read(slot: Slot, lines: number): Promise<string>;
+    /**
+     * Bounded cursor-paged sweep into the slot's accumulated buffer. The first read of a slot carries
+     * no cursor: it is the ANCHOR, whose `oldestCursor` says where the retained buffer starts (its own
+     * tail is the newest lines, not the oldest, so it is not appended). Every page after it appends,
+     * and every one of them — anchor included — is status-validated before a single byte is matched.
+     */
+    private sweep;
+    waitOutput(slot: Slot, pattern: string, timeoutMs: number, opts?: {
+        regex?: boolean;
+    }): Promise<boolean>;
+    status(slot: Slot): Promise<string>;
+    /** 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. */
+    private waitCondition;
+    waitAgentStatus(slot: Slot, status: string, timeoutMs: number): Promise<boolean>;
+    notify(msg: string, opts?: NotifyOpts): Promise<void>;
+    close(slot: Slot): Promise<void>;
+    /**
+     * The one destructive call in this driver, for a slot's own terminal AND for a reconcile candidate
+     * alike. It goes through terminalOp deliberately: the live runtime identity is proven immediately
+     * BEFORE the handle goes on the wire, and a runtime that changed does not merely fail the close —
+     * the handle is DISCARDED and re-derived from the owned tab title in that exact checkout, where a
+     * handle value the new runtime happened to reissue to somebody else's terminal is refused by
+     * construction (recover()). Checking identity on the receipt afterwards could not undo a close.
+     */
+    private closeTerminal;
+    /**
+     * The WHOLE terminal table. `terminal list` caps rows at its own default and says so through
+     * `truncated`/`totalCount`; a capped listing is not an ownership snapshot, because the row it
+     * dropped is precisely the older run's leftover no later sweep would ever see again.
+     * ponytail: two asks, not a paging loop — `--limit` takes the whole table in one go, and a runtime
+     * that still reports truncated at totalCount rows is a listing this sweep declines to judge on.
+     */
+    private listAll;
+    /**
+     * Sweep tickmarkr-owned terminals down to `desired`. Ownership is decided ONLY by parseOwnedName
+     * over the owned TAB title, through the same panesToClose fold herdr uses (drivers/types.ts): an
+     * owned-and-undesired terminal closes whichever run — and whichever daemon — created it, and a
+     * title that does not parse is never a candidate however much it resembles one.
+     *
+     * The listing is UNSCOPED and layout-bearing. Unscoped because an older run's leftover sits in a
+     * checkout this run never knew, so a `--worktree`-filtered sweep is exactly how such a leftover
+     * survives forever. Layout-bearing because the owned title survives at TAB identity only — a list
+     * row's `title` is the shell-controlled pane title, and closing on that is how a foreign pane that
+     * happens to be running an owned-looking command gets killed.
+     *
+     * Cosmetic by contract: every failure is swallowed, per candidate and overall.
+     */
+    reconcile(desired: Set<string>, runId: string, opts?: {
+        spareLiveLlm?: boolean;
+    }): Promise<void>;
+    worktree(repo: string, branch: string, baseRef: string): Promise<string>;
+}