tickmarkr 1.97.0 → 2.1.0

package/dist/drivers/herdr.js

@@ -69,19 +69,19 @@ export function workerSplitDirection(paneCols, safeFloor = TRAILER_SAFE_FLOOR_CO
 }
 // The watch board's geometry, deliberately NOT the trailer floor above. `workerSplitDirection`
 // halves the caller and refuses a right split under 108+2 — that bound protects WORKER panes, which
-// print a trailer; the supervising seat + board pair does not. Applied to that pair on 2026-08-18 it
-// sent a 189-column tab's board BELOW the seat and the operator corrected it (QUEUE-v194 criterion 1;
-// skills/tickmarkr-overseer/SKILL.md: "the side placement outranks the halving floor"). So the board
-// is allocated its measured width FIRST and the seat keeps the remainder.
-export const BOARD_TARGET_COLS = 110; // §14a measured clean-render bound for the board
-export const BOARD_SEAT_FLOOR_COLS = 40; // the seat beside it still has to be usable
-/** Board-first placement beside the supervising seat: right only while the caller can fund the board
- *  its target AND leave the seat its floor; otherwise down at full width, never a squeezed board.
- *  An unmeasurable caller falls back to down like every other placement here (fail closed). */
-export function boardSplitPlan(callerCols, boardCols = BOARD_TARGET_COLS, seatFloor = BOARD_SEAT_FLOOR_COLS) {
-    if (callerCols == null || callerCols < boardCols + seatFloor)
-        return { direction: "down", boardCols: null };
-    return { direction: "right", ratio: Math.round(((callerCols - boardCols) / callerCols) * 1e4) / 1e4, boardCols };
+// print a trailer; the supervising seat + board pair does not, and neither does the board's own
+// 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
+ *  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" };
 }
 /** 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.
@@ -147,6 +147,7 @@ export class HerdrDriver {
     // the caller launched tickmarkr elsewhere (process.cwd is not run identity). The repo itself is
     // also bound for judge/review/consult slots whose cwd is the root rather than a task worktree.
     journalRoots = new Map();
+    narrate;
     // VIS-10: the run's workspace id, captured once at construction (the daemon inherits it from the
     // operator's env before the driver is built). Required at slot() time, never in the constructor —
     // pickDriver and its unit test construct HerdrDriver without env, so slot() is the trust gate.
@@ -176,7 +177,14 @@ export class HerdrDriver {
         if (!repoRoot) {
             throw new Error(`cannot journal dispatch-retry: slot ${slot.name} has no daemon repo binding for ${slot.cwd}`);
         }
-        Journal.open(repoRoot, owned.runId).append("dispatch-retry", owned.taskId, data);
+        // Bound to the live narration sink (`narrateWith`): this Journal is the driver's own — the
+        // daemon never appends this event and never sees it — so an unbound handle here persists the
+        // recovery to the file and the pipe while the operator's rail stays silent about it.
+        Journal.open(repoRoot, owned.runId, this.narrate).append("dispatch-retry", owned.taskId, data);
+    }
+    /** v1.99 T2: bind this driver's own journal writes to the run's live narration sink. */
+    narrateWith(narrate) {
+        this.narrate = narrate;
     }
     serial(fn) {
         const p = this.groupSerial.then(fn, fn);
@@ -274,6 +282,20 @@ export class HerdrDriver {
             return null;
         }
     }
+    // Is this pane id still in the listing? FAIL CLOSED: a listing we cannot read cannot prove a pane
+    // gone, and the caller uses this to decide whether a pane it tried to close is really off screen.
+    async paneStillOpen(paneId) {
+        const r = await this.herdr(`pane list`);
+        if (r.code !== 0)
+            return true;
+        try {
+            const panes = JSON.parse(r.stdout).result?.panes;
+            return !Array.isArray(panes) || panes.some((p) => p.pane_id === paneId);
+        }
+        catch {
+            return true;
+        }
+    }
     // Before delivery, resolve fresh via the durable name because pane ids can compact. After delivery,
     // pin the verified target so early liveness cannot drift to a label rebound onto another pane.
     async paneId(slot) {
@@ -1059,19 +1081,18 @@ 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 — beside it when the
-    // tab can fund the board its width, below it at full width when it cannot. Its durable owned name
-    // is how a later daemon RECOGNIZES the board it must retire, so a run never stacks a second one.
+    // 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
+    // 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");
-        // Board width first (boardSplitPlan), measured off the caller through the driver's own layout
-        // read — never an unconditional right split, and never the worker halving rule.
-        const plan = boardSplitPlan(await this.paneWidth(this.callerPane));
-        const ratio = plan.ratio == null ? "" : ` --ratio ${plan.ratio}`;
-        const sp = await this.herdr(`pane split ${shq(this.callerPane)} --direction ${plan.direction}${ratio} --no-focus`);
+        // 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.
+        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)
             throw new Error(`herdr watch split failed: ${sp.stderr || sp.stdout}`);
         let pane;
@@ -1083,18 +1104,61 @@ 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)}`);
+        // Flag lives at `result.swap.changed` (verbatim 0.8.0); see herdr-swap-shape.test.ts.
+        let swapChanged;
+        try {
+            const result = JSON.parse(swapped.stdout).result;
+            swapChanged = result?.swap?.changed ?? 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}`}`);
+        }
         const renamed = await this.herdr(`pane rename ${shq(pane)} ${shq(name)}`);
         if (renamed.code !== 0 || await this.namedPaneId(name) !== pane) {
-            await this.herdr(`pane close ${shq(pane)}`);
-            throw new Error(`herdr watch rename failed: ${renamed.stderr || renamed.stdout}`);
+            await this.discardSplit(pane, `herdr watch rename failed: ${renamed.stderr || renamed.stdout}`);
         }
         const seed = await this.herdr(`pane run ${shq(pane)} ${shq(`cd ${shq(cwd)}; export HERDR_WORKSPACE_ID=${shq(this.ws)}; ${herdrSealShellPrefix()}`)}`, cwd);
         if (seed.code !== 0) {
-            await this.herdr(`pane close ${shq(pane)}`);
-            throw new Error(`herdr watch seed failed: ${seed.stderr || seed.stdout}`);
+            await this.discardSplit(pane, `herdr watch seed failed: ${seed.stderr || seed.stdout}`);
         }
         return { id: pane, name, cwd };
     }
+    // A board that could not be placed costs the OPERATOR a stray pane unless the split is really
+    // taken back, so every close is followed by a pane-list verification rather than issued and
+    // forgotten. A nonzero close and a success that frees nothing are both diagnosed from that same
+    // observation. The daemon swallows it either way and runs boardless — but never silently keeps a
+    // split the geometry it asked for does not include.
+    async discardSplit(pane, why) {
+        const closed = await this.herdr(`pane close ${shq(pane)}`);
+        const stillOpen = await this.paneStillOpen(pane);
+        const orphan = stillOpen
+            ? closed.code !== 0
+                ? closed.stderr || closed.stdout || `exit ${closed.code}`
+                : "close reported success but the pane could not be proven absent from pane list"
+            : null;
+        if (orphan !== null) {
+            // The daemon swallows narrator failures whole (visibility is never a gate), so the thrown
+            // error dies in its catch. This line is the operator's only notice that a pane they did not
+            // ask for is still on their screen and that no process will take it back.
+            console.error(`tickmarkr: the watch split ${pane} survived its close (${orphan}) — close it by hand; the run continues boardless`);
+        }
+        throw new Error(orphan === null ? why : `${why} — and the split pane ${pane} survived its close (${orphan})`);
+    }
     // T6 narrator: the run's single live status surface, RUNNING THE COMMAND THIS CALL SUPPLIED. Only
     // a board this driver instance itself opened is reused (this.watches); any other surviving board —
     // a prior run's, or one already carrying this run's canonical name after a resume — is retired and

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>;
+}