tickmarkr 2.0.0 → 2.1.1

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/commands/status.js

@@ -527,10 +527,34 @@ const foldTaskEffort = (tasks, events) => {
     return [...effort.values()].sort((left, right) => right.total - left.total
         || order.get(left.taskId) - order.get(right.taskId));
 };
-// Attention (review) and failure (park) wear the ONE amethyst, so the bar segments and their legend
-// markers carry the distinction in SHAPE: a full block for dispatch, light shade for a review round,
-// dark shade for a human park. Same display width, so the fitted bar keeps its measured columns.
-const EFFORT_GLYPH = { dispatch: "\u2588", review: "\u2592", park: "\u2593" };
+// ONE glyph for every segment, distinction by COLOUR. This was shade-based — full block for dispatch,
+// light shade for a review round, dark shade for a human park — because attention and failure share the
+// ONE amethyst and shape was their only discriminator. OPERATOR 2026-08-25, with a screenshot: the rows
+// rendered at DIFFERENT HEIGHTS. A row carrying the shade glyphs pulls a fallback font whose cell box is
+// taller, so the whole line grows and its full blocks stretch with it — T1 (dispatch+review+park) stood
+// visibly taller than T3 (dispatch only). Same display WIDTH was verified and preserved; nobody checked
+// height, and the fitted-column arithmetic cannot see it.
+//
+// So review moves off amethyst onto `information` (cornflower) — an EXISTING token. Deliberately not a
+// new amber: brand.ts calls the five live colours operator-approved and says "no token introduces a
+// sixth colour", and a bar chart is not the place to spend that.
+//
+// The shape scheme existed so a reader WITHOUT colour could still separate a review round from a human
+// park. That reader does not exist on this panel. `renderFrame` computes `const unicode = visual()`
+// (`visual()` = `isTTY === true && NO_COLOR === undefined`) and, when it is false, EARLY-RETURNS the
+// ASCII machine/CI surface at the `if (!unicode)` branch — which sits ABOVE the `effortPanel(...)` call
+// below, so the panel is never built on that path. Measured before it was explained: a frame rendered
+// with isTTY=true and NO_COLOR=1 contains no "WHERE THE EFFORT WENT" and no block glyph at all.
+// (The `--watch` loop has its own `visual()` gate; that one is NOT what suppresses this panel, and the
+// non-watch path reaches renderFrame unconditionally.) So the shades were paying an accessibility cost
+// on a surface that cannot render colourless, and a conditional to restore them under NO_COLOR would
+// have been an unreachable branch (the v1.80 injected-clock lesson: the fix for that is deletion).
+//
+// One glyph, three colours. Review moves off amethyst onto `information` (cornflower) — an EXISTING
+// token, deliberately not a new amber: brand.ts calls the five live colours operator-approved and says
+// "no token introduces a sixth colour". Every row now draws the same block, which is what makes the
+// rows equal height.
+const EFFORT_GLYPH = { dispatch: "\u2588", review: "\u2588", park: "\u2588" };
 /**
  * Prototype panel, fitted by the cockpit's display-cell authority before board-wide wrapping.
  *
@@ -557,7 +581,7 @@ const effortPanel = (tasks, events, columns) => {
         const reviewEnd = Math.round(((task.dispatches + task.reviews) / maxTotal) * barColumns);
         const parkEnd = Math.round((task.total / maxTotal) * barColumns);
         const stack = ok(EFFORT_GLYPH.dispatch.repeat(dispatchEnd))
-            + warn(EFFORT_GLYPH.review.repeat(Math.max(0, reviewEnd - dispatchEnd)))
+            + information(EFFORT_GLYPH.review.repeat(Math.max(0, reviewEnd - dispatchEnd)))
             + fail(EFFORT_GLYPH.park.repeat(Math.max(0, parkEnd - reviewEnd)));
         return `${prefix}${fitCells(stack, barColumns)}  ${counts}`;
     });
@@ -567,7 +591,7 @@ const effortPanel = (tasks, events, columns) => {
         "",
         ...rows,
         "",
-        `   ${ok(EFFORT_GLYPH.dispatch)} ${dim("dispatch")}  ${warn(EFFORT_GLYPH.review)} ${dim("review round")}  ${fail(EFFORT_GLYPH.park)} ${dim("human park")}`,
+        `   ${ok(EFFORT_GLYPH.dispatch)} ${dim("dispatch")}  ${information(EFFORT_GLYPH.review)} ${dim("review round")}  ${fail(EFFORT_GLYPH.park)} ${dim("human park")}`,
     ];
 };
 // VIS-11 (v1.13): a liveness header for renderFrame — last journal event age + whether the recorded

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.d.ts

@@ -23,17 +23,17 @@ export declare class DeliveryCorruptedError extends Error {
 export type DriverJournal = (event: string, slotName: string, data: Record<string, unknown>) => void;
 /** First-generation join direction from measured trailer-safe floor (43-MEASUREMENT.md). */
 export declare function workerSplitDirection(paneCols: number | null, safeFloor?: number, margin?: number): "right" | "down";
-export declare const BOARD_HEIGHT_SHARE = 0.72;
+export declare const BOARD_WIDTH_SHARE = 0.5;
 export interface BoardPlacement {
-    /** Always down: the split is vertical, so the board can own the caller's FULL width. */
-    direction: "down";
-    /** herdr's split ratio is the FIRST child's share, and a down split's first child is the TOP
-     *  region — the region the board occupies once it is swapped above the caller. */
+    /** Always right: the board sits BESIDE the caller, so the narration keeps a column of its own. */
+    direction: "right";
+    /** herdr's split ratio is the FIRST child's share, and a right split's first child is the LEFT
+     *  region — the caller's, i.e. the narration. The board takes the remainder, on the right.
+     *  Measured against a live herdr 2026-08-25: a 256-col caller split right at 0.5 leaves the caller
+     *  at x=36 w=128 and puts the NEW pane at x=164 w=128. */
     ratio: number;
-    /** The new pane is swapped ABOVE the caller; the split alone would leave the board underneath. */
-    swap: "above";
 }
-/** The single approved vertical-stack record. The caller's columns are accepted and deliberately
+/** The single approved side-by-side record. The caller's columns are accepted and deliberately
  *  ignored: this signature is where width used to decide the arrangement, and the parameter stays
  *  so that "the plan does not depend on it" is a property a caller (and a test) can exercise. */
 export declare function boardSplitPlan(_callerCols?: number | null): BoardPlacement;

package/dist/drivers/herdr.js

@@ -73,15 +73,27 @@ export function workerSplitDirection(paneCols, safeFloor = TRAILER_SAFE_FLOOR_CO
 // placement any more. Every width-derived variant of this placement has been wrong in the operator's
 // tab: the halving floor sent a 189-column board below the seat (2026-08-18), and the width-first
 // side split that replaced it puts the board and the narration shoulder to shoulder when the board is
-// the surface the operator reads and the narration is the rail beneath it. The placement is now ONE
-// record — the board stacked ABOVE the caller at full width, taking 72% of the height — and it is
-// invariant: no terminal width, measured or unmeasurable, can select a different arrangement.
-export const BOARD_HEIGHT_SHARE = 0.72; // board 72 / narration 28, the operator's stack
-/** The single approved vertical-stack record. The caller's columns are accepted and deliberately
+// the surface the operator reads and the narration is the rail beneath it. The placement is ONE
+// record and it is invariant: no terminal width, measured or unmeasurable, can select a different
+// arrangement. THAT invariance is the hard-won part and it is unchanged here.
+//
+// What the record SAYS changed on operator instruction (2026-08-25): the board sits to the RIGHT of
+// the caller, not stacked above it. The vertical stack gave the board 72% of the HEIGHT at full
+// width, and in the operator's own tab that was mostly empty board over a squeezed narration rail —
+// a task table is a handful of rows, so height was the axis it did not need and the narration did.
+// Side by side spends the axis the board actually uses.
+//
+// ⚠ This is NOT a return to the width-derived placement that was wrong twice. Those variants let the
+// MEASURED width choose the arrangement, so the same run rendered differently in different terminals
+// and neither operator nor test could name one expected geometry. This record is constant: every
+// caller width gets `right`, and `boardSplitPlan` still ignores the columns it is handed. The
+// invariance test's width-sensitive control still fails, which is the property that mattered.
+export const BOARD_WIDTH_SHARE = 0.5; // narration 50 / board 50, side by side
+/** The single approved side-by-side record. The caller's columns are accepted and deliberately
  *  ignored: this signature is where width used to decide the arrangement, and the parameter stays
  *  so that "the plan does not depend on it" is a property a caller (and a test) can exercise. */
 export function boardSplitPlan(_callerCols) {
-    return { direction: "down", ratio: BOARD_HEIGHT_SHARE, swap: "above" };
+    return { direction: "right", ratio: BOARD_WIDTH_SHARE };
 }
 /** The tab a slot belongs to: its TASK — worker, judge, review and consult panes for one task share it.
  *  Returns undefined for everything else, which keeps those on the dedicated-tab path.
@@ -1081,16 +1093,17 @@ export class HerdrDriver {
             return p.workspace_id === this.ws && typeof p.pane_id === "string" && owned?.role === "watch" && owned.taskId === "run";
         }).map((p) => p.pane_id);
     }
-    // T2: the watch is a sibling of the daemon's own pane, never a separate tab — stacked ABOVE it at
-    // the caller's full width, always, whatever the terminal measures. Its durable owned name is how a
+    // T2: the watch is a sibling of the daemon's own pane, never a separate tab — placed to the RIGHT
+    // of it, always, whatever the terminal measures. Its durable owned name is how a
     // later daemon RECOGNIZES the board it must retire, so a run never stacks a second one.
     async watchSlot(cwd, name) {
         if (!this.ws)
             throw new Error("herdr watch placement requires HERDR_WORKSPACE_ID — refusing unseeded pane");
         if (!this.callerPane)
             throw new Error("herdr watch placement requires HERDR_PANE_ID — refusing untargeted split");
-        // One invariant placement (boardSplitPlan): split the caller down, then swap the new pane above
-        // it. No layout read decides this — width chose the arrangement twice and was wrong twice.
+        // One invariant placement (boardSplitPlan): split the caller RIGHT. No layout read decides this —
+        // width chose the arrangement twice and was wrong twice. No swap: a right split already lands the
+        // new pane — the board — beside the caller, so there is no second operation to verify.
         const plan = boardSplitPlan();
         const sp = await this.herdr(`pane split ${shq(this.callerPane)} --direction ${plan.direction} --ratio ${plan.ratio} --no-focus`);
         if (sp.code !== 0)
@@ -1104,28 +1117,12 @@ export class HerdrDriver {
         }
         if (typeof pane !== "string" || !pane)
             throw new Error(`herdr watch split returned no pane id: ${sp.stdout}`);
-        // The split leaves the board UNDER the caller; the swap is what makes the stack the requested
-        // one. Verified, not assumed: a swap that failed would leave a board below the narration while
-        // the daemon reported the geometry it asked for. Instead the split pane is closed and the failure
-        // propagates — the daemon swallows it and runs boardless, which is honest about what is on screen.
-        // `pane swap` answers a no-op with a ZERO exit and `changed:false` (herdr socket API: a swap it
-        // declined is a non-error response), so an exit code alone proves nothing about the geometry —
-        // that is exactly the path that would leave the board below the narration while the daemon
-        // 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)}`);
-        let swapChanged;
-        try {
-            swapChanged = JSON.parse(swapped.stdout).result?.changed;
-        }
-        catch {
-            /* fail closed below */
-        }
-        if (swapped.code !== 0 || swapChanged !== true) {
-            await this.discardSplit(pane, `herdr watch swap ${plan.swap} failed: ${swapped.code !== 0
-                ? swapped.stderr || swapped.stdout
-                : `herdr reported no swap took place: ${swapped.stdout || swapped.stderr}`}`);
-        }
+        // No swap step to verify any more. The stack needed one — the split landed the board UNDER the
+        // caller and only the swap made the geometry the requested one, so a `pane swap` that no-opped
+        // with a ZERO exit could leave a board below the narration while the daemon reported the stack;
+        // the `changed` flag existed to catch exactly that. A right split places the board where it
+        // belongs in ONE operation that either returns a pane id or throws above, so there is no
+        // second-operation gap left to fail closed on.
         const renamed = await this.herdr(`pane rename ${shq(pane)} ${shq(name)}`);
         if (renamed.code !== 0 || await this.namedPaneId(name) !== pane) {
             await this.discardSplit(pane, `herdr watch rename failed: ${renamed.stderr || renamed.stdout}`);

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();
 }