tickmarkr 2.5.3 → 2.5.5

package/dist/drivers/herdr.js

@@ -6,7 +6,7 @@ import { declaredInputBoxForWorkerName, matchesEmptyInputBox, matchesInputBox, m
 import { consumePaneLaunchIntent, PANE_IDENTITY_ENV, paneIdentityLine } from "../brand.js";
 import { createWorktree, sh } from "../run/git.js";
 import { Journal } from "../run/journal.js";
-import { readSupervision, readWatchBoard, reserveWatchBoard, stopWatchBoard, WATCH_OWNER_ENV } from "../run/supervision.js";
+import { readSupervision, readWatchBoard, requestWatchBoardStop, reserveWatchBoard, stopWatchBoard, WATCH_OWNER_ENV } from "../run/supervision.js";
 import { herdrSealShellPrefix } from "./subprocess.js";
 import { canonicalizeLegacyName, formatOwnedName, panesToClose, parseOwnedName } from "./types.js";
 // VIS-09 P43-03: adopted safety floor from 43-MEASUREMENT.md (narrowest safe 53 → floor 108).
@@ -1169,8 +1169,16 @@ export class HerdrDriver {
             throw new Error("herdr pane list returned no panes");
         return panes.filter(p => p.workspace_id === this.ws && p.label === name);
     }
+    /** WB-1 (OBS-988): the daemon proved this run's own board lost. Forget the cached slot FIRST — even a
+     *  retire that fails must never let the narrator answer with the ghost again — then take the pane
+     *  back on ownership alone: the dead UI can never acknowledge, so the stop request is left for a
+     *  merely stuck one to find. Serialized with the narrator so no split races the close. */
+    async retireLostWatch(slot) {
+        this.watches.delete(slot.name);
+        await this.serial(() => this.retireWatch(slot, true));
+    }
     /** Name collisions never confer repository ownership. Unknown boards stay protected. */
-    async retireWatch(slot) {
+    async retireWatch(slot, lost = false) {
         const runId = parseOwnedName(slot.name)?.runId;
         const owner = runId ? readWatchBoard(slot.cwd, runId) : undefined;
         const matches = await this.watchPanes(slot.name);
@@ -1181,7 +1189,10 @@ export class HerdrDriver {
             owner.pane !== slot.id || matches.length !== 1 || matches[0]?.pane_id !== owner.pane) {
             throw new Error(`watch ownership unknown or foreign for ${slot.name}; existing board protected`);
         }
-        await stopWatchBoard(owner, this.time);
+        if (lost)
+            requestWatchBoardStop(owner); // a lost owner never answers; only a live one still gets the ack window
+        else
+            await stopWatchBoard(owner, this.time);
         const verified = await this.watchPanes(slot.name);
         if (verified.length !== 1 || verified[0]?.pane_id !== owner.pane)
             throw new Error("watch target changed after acknowledgement; pane protected");

package/dist/drivers/index.d.ts

@@ -2,6 +2,20 @@ import type { TickmarkrConfig } from "../config/config.js";
 import type { ExecutorDriver } from "./types.js";
 export declare const DRIVER_CHOICES: readonly ["auto", "herdr", "subprocess", "orca"];
 export type DriverChoice = (typeof DRIVER_CHOICES)[number];
+export type ClassifiedHost = "herdr" | "orca" | "none";
+/**
+ * One host classifier beside the driver chooser reads the launching environment:
+ * herdr only when HERDR_ENV is exactly 1, orca only when both Orca markers are present,
+ * none otherwise. run and resume call it once at the refs-preflight point and thread the
+ * result into pickDriver; nothing downstream reads the markers again.
+ */
+export declare function classifyHost(env?: NodeJS.ProcessEnv): ClassifiedHost;
+/**
+ * A config driver of herdr or orca whose host is not the classified one is refused naming the
+ * detected host, the config line and the --driver remedy. Any explicit --driver value bypasses
+ * this; auto and subprocess are never refused.
+ */
+export declare function preflightHostDriver(cfg: TickmarkrConfig, driverOverride: string | undefined, host: ClassifiedHost): void;
 /**
  * Orca authors both markers on every terminal it creates. Requiring the pair avoids treating an
  * unrelated TERM_PROGRAM value or a copied terminal handle as host identity. This is deliberately
@@ -11,4 +25,4 @@ export declare function orcaHostDetected(env?: NodeJS.ProcessEnv): boolean;
 /** 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 driverEvidence(cfg: TickmarkrConfig, driver: ExecutorDriver, override?: string): string;
-export declare function pickDriver(cfg: TickmarkrConfig, override?: string): ExecutorDriver;
+export declare function pickDriver(cfg: TickmarkrConfig, override?: string, host?: ClassifiedHost): ExecutorDriver;

package/dist/drivers/index.js

@@ -3,13 +3,42 @@ import { OrcaDriver } from "./orca.js";
 import { SubprocessDriver } from "./subprocess.js";
 export const DRIVER_CHOICES = ["auto", "herdr", "subprocess", "orca"];
 const overrideByDriver = new WeakMap();
+// The host snapshot the driver was selected under: driverEvidence reads this, never process.env,
+// so preflight, selection and the journal row all describe the same instant.
+const hostByDriver = new WeakMap();
+/**
+ * One host classifier beside the driver chooser reads the launching environment:
+ * herdr only when HERDR_ENV is exactly 1, orca only when both Orca markers are present,
+ * none otherwise. run and resume call it once at the refs-preflight point and thread the
+ * result into pickDriver; nothing downstream reads the markers again.
+ */
+export function classifyHost(env = process.env) {
+    if (env.HERDR_ENV === "1")
+        return "herdr";
+    if (env.TERM_PROGRAM === "Orca" && env.ORCA_TERMINAL_HANDLE !== undefined && env.ORCA_TERMINAL_HANDLE !== "")
+        return "orca";
+    return "none";
+}
+/**
+ * A config driver of herdr or orca whose host is not the classified one is refused naming the
+ * detected host, the config line and the --driver remedy. Any explicit --driver value bypasses
+ * this; auto and subprocess are never refused.
+ */
+export function preflightHostDriver(cfg, driverOverride, host) {
+    if (driverOverride !== undefined)
+        return;
+    if ((cfg.driver === "herdr" || cfg.driver === "orca") && cfg.driver !== host) {
+        const remedy = host === "none" ? "subprocess" : host;
+        throw new Error(`refusing driver '${cfg.driver}' (config line 'driver: ${cfg.driver}'): detected host is ${host}; use --driver ${remedy} to override`);
+    }
+}
 /**
  * Orca authors both markers on every terminal it creates. Requiring the pair avoids treating an
  * unrelated TERM_PROGRAM value or a copied terminal handle as host identity. This is deliberately
  * environment-only: selection must not execute a binary or contact the Orca runtime.
  */
 export function orcaHostDetected(env = process.env) {
-    return env.TERM_PROGRAM === "Orca" && env.ORCA_TERMINAL_HANDLE !== undefined;
+    return classifyHost(env) === "orca";
 }
 /** Validate argv at the CLI boundary rather than casting an arbitrary string into a driver choice. */
 export function parseDriverOverride(override) {
@@ -27,18 +56,16 @@ export function driverEvidence(cfg, driver, override) {
         return `${driver.id} (--driver)`;
     if (want !== "auto")
         return `${driver.id} (config)`;
-    const herdrAvailable = process.env.HERDR_ENV === "1";
-    if (herdrAvailable && driver.id === "herdr")
+    const host = hostByDriver.get(driver);
+    if (host === "herdr" && driver.id === "herdr")
         return "auto → herdr (HERDR_ENV=1)";
-    if (!herdrAvailable && orcaHostDetected() && driver.id === "orca") {
+    if (host === "orca" && driver.id === "orca")
         return "auto → orca (TERM_PROGRAM+ORCA_TERMINAL_HANDLE)";
-    }
-    if (!herdrAvailable && !orcaHostDetected() && driver.id === "subprocess") {
+    if (host === "none" && driver.id === "subprocess")
         return "auto → subprocess (HERDR_ENV unset)";
-    }
     return `auto → ${driver.id} (runtime)`;
 }
-export function pickDriver(cfg, override) {
+export function pickDriver(cfg, override, host = classifyHost()) {
     const selectedOverride = parseDriverOverride(override);
     const want = selectedOverride ?? cfg.driver;
     // VIS-09 item 2: plumb the per-tab cap into the HerdrDriver — the driver takes it as a constructor
@@ -49,10 +76,11 @@ export function pickDriver(cfg, override) {
             // Orca is an operator-selected execution surface. Its runtime failure stays on Orca; selection
             // must never substitute a hidden subprocess worker after an explicit or detected choice.
             : want === "orca" ? new OrcaDriver()
-                : HerdrDriver.available() ? new HerdrDriver("herdr", cfg.visibility.workersPerTab)
-                    : orcaHostDetected() ? new OrcaDriver()
+                : host === "herdr" ? new HerdrDriver("herdr", cfg.visibility.workersPerTab)
+                    : host === "orca" ? new OrcaDriver()
                         : new SubprocessDriver();
     if (selectedOverride !== undefined)
         overrideByDriver.set(driver, selectedOverride);
+    hostByDriver.set(driver, host);
     return driver;
 }

package/dist/drivers/orca.d.ts

@@ -1,8 +1,9 @@
 import { type ShResult } from "../run/git.js";
 import { type JournalEvent } from "../run/journal.js";
+import { type WatchBoardOwner } from "../run/supervision.js";
 import { type ExecutorDriver, type FocusTarget, type FocusResult, 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", "worktree-current", "worktree-set", "hooks-status"];
+export declare const ORCA_RESPONSE_FAMILIES: readonly ["status", "create", "list", "read", "send", "wait", "show", "close", "worktree-current", "worktree-set", "hooks-status", "split"];
 export type OrcaFamily = (typeof ORCA_RESPONSE_FAMILIES)[number];
 export declare const ORCA_FIXTURE_VERSION = "1.4.195";
 export declare const ORCA_CLI_COMMAND_ENV = "ORCA_CLI_COMMAND";
@@ -14,7 +15,6 @@ 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 declare const WORKTREE_ADOPTION_TIMEOUT_MS = 60000;
 /** A missing slot gets the same bounded chance to appear as a reaped shell gets to settle. */
 export declare const PENDING_PROJECT_GRACE_MS = 2000;
 export interface OrcaExec {
@@ -81,11 +81,62 @@ export declare function terminalWorktree(term: Record<string, unknown>): string
  * it keeps its resolved spelling: deterministic, and still comparable to another spelling of itself.
  */
 export declare function canonicalWorktreePath(path: string): string;
+/** The proof line a worker terminal prints first: recovery and focus read it back (FX-N01). */
+export declare const CHECKOUT_MARK = "TICKMARKR_CHECKOUT";
+/** The exact bytes the create command prints as its first line. */
+export declare function checkoutProofLine(checkout: string): string;
+/** Every complete frame in a scrollback, decoded and canonicalized; whether an incomplete one was seen. */
+export declare function checkoutFrames(text: string): {
+    complete: string[];
+    incomplete: boolean;
+};
+/** Does a scrollback prove exactly `checkout`: at least one complete frame equals it, no complete
+ *  frame names anything else, and no frame is incomplete. Full-path equality after canonicalization —
+ *  never a prefix, a substring, or a whitespace-terminated fragment. */
+export declare function provesCheckout(text: string, checkout: string): boolean;
+/**
+ * Everything a terminal on the tracked worktree runs before the payload: enter the checkout (a
+ * failed cd stops the whole line — nothing of the payload ever runs in the enclosing path), print
+ * the proof line, then hand the WHOLE payload to one `sh -c` so a background list, a `;` list or a
+ * subshell inside it all start in the checkout and its exit status is the payload's (FX-N02).
+ */
+export declare function checkoutPrefix(checkout: string): string;
+/** The command a terminal on the tracked worktree runs so that it executes INSIDE the checkout. */
+export declare function inCheckout(checkout: string, cmd: string): string;
+/** Every checkout the complete proof frames in a scrollback name, in order of appearance. */
+export declare function checkoutsNamed(text: 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 Orca board owner record is the board's ONE lifecycle, and it lives on disk: every step below is
+ * decided from the file (plus Orca's own terminal table), so a fresh OrcaDriver — a restarted daemon —
+ * reaches the same answer as the instance that placed the board. No instance map or set carries it.
+ *
+ *   reserved  pane "", no claim            narrator, create-only, before the split can read its token
+ *   claimed   pid + armId, pane ""         observer (observeNamedRun), written exactly once
+ *   bound     claim + the receipt's handle and the split envelope's runtimeId
+ *   retired   bound + retired:true         tombstone, CAS on the bound bytes; never answered again
+ *
+ * A retired record is replaced by a new reservation (CAS on the tombstone bytes) only once its pane
+ * is proven gone. Everything else — a reservation or claim with no bound pane, a failed cleanup, a
+ * record another driver holds with a live observer — refuses and keeps the record exactly as it is.
+ */
+type BoardRecord = WatchBoardOwner & {
+    retired?: true;
+    runtimeId?: string;
+};
+/**
+ * Whole-record compare-and-swap. The canonical path stays readable until commit: a mkdir lock
+ * excludes other writers, then create-only `link`s the new inode (fails if anything exists) or
+ * `rename`s the new file over the live path (POSIX atomic replace — readers see old or new, never
+ * absence). A crash that leaves a `.tmp` or `.lock` does not drop the previous record.
+ * ponytail: observeNamedRun (supervision.ts) renames without CAS. It cannot interleave with a swap
+ * because the narrator writes nothing between reserve and claim, and no transition here swaps one.
+ */
+export declare function casBoard(family: string, path: string, expected: string | undefined, next: BoardRecord): 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
@@ -105,6 +156,7 @@ export interface OrcaDriverOpts {
     pollMs?: number;
     /** Bounded, seam-adjustable staleness window for runtime probes before mutations. */
     probeStalenessMs?: number;
+    launchingHandle?: string;
 }
 export declare class OrcaDriver implements ExecutorDriver {
     id: string;
@@ -121,7 +173,12 @@ export declare class OrcaDriver implements ExecutorDriver {
     private narrate?;
     private hookCoverage?;
     private taskWorktrees;
+    private trackedByCheckout;
     private pendingProjects;
+    private env;
+    private launchingHandle?;
+    private serialQueue;
+    private serial;
     constructor(opts?: OrcaDriverOpts);
     private call;
     /** The live runtime's identity, or an explicit failure. A missing or unreachable runtime is a
@@ -144,14 +201,13 @@ export declare class OrcaDriver implements ExecutorDriver {
     private sendReceipt;
     private create;
     /**
-     * A freshly-created git checkout does not become a valid Orca selector atomically. Ask
-     * `worktree current` FROM that checkout until Orca itself resolves the exact filesystem identity;
-     * an enclosing checkout is still not adoption. Only selector_not_found is a retryable refusal —
-     * malformed envelopes and every other refusal remain explicit driver failures.
+     * OBS-1004: the tracked worktree that encloses a checkout, asked ONCE of `worktree current` from
+     * inside that checkout. Orca answers the exact path when it tracks the checkout itself, the
+     * enclosing tracked clone for a git worktree the daemon added beneath it (1.4.200, verified from
+     * `.tickmarkr/worktrees.noindex/<task>`), and selector_not_found when nothing it tracks encloses
+     * the cwd — which is a driver failure, not something to wait out: Orca has no adopt verb.
      */
-    private awaitWorktreeAdoption;
-    /** Same repo/run/narration path Herdr uses for its driver-owned dispatch-retry row. */
-    private appendAdoptionWait;
+    private trackedWorktree;
     /**
      * 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
@@ -161,6 +217,19 @@ export declare class OrcaDriver implements ExecutorDriver {
      * the handle exactly once, then re-issues the operation against the replacement.
      */
     private terminalOp;
+    /**
+     * FX-N01/N05/N06: under a shared enclosing worktree every task terminal lists with the same
+     * worktreePath, so the tracked path + owned title cannot tell two nested checkouts apart. The
+     * runtime's own proof is the terminal's earliest scrollback, where the create command printed a
+     * framed `TICKMARKR_CHECKOUT` line before its payload (checkoutProofLine). READ-only calls: the
+     * anchor (for `oldestCursor`), then pages from the oldest cursor until a frame is complete or the
+     * bound is hit. Every page is evidence only when the response's own identity is the candidate's:
+     * the terminal record must name `handle` and `_meta.runtimeId` must be `runtimeId` — the runtime
+     * that supplied the ownership listing — else another terminal's or another runtime's bytes were
+     * answered and nothing is proven. Proven means provesCheckout: exact canonical full-path equality
+     * of a complete frame, no other checkout named, no incomplete frame.
+     */
+    private checkoutProven;
     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
@@ -200,7 +269,24 @@ export declare class OrcaDriver implements ExecutorDriver {
     waitAgentStatus(slot: Slot, status: string, timeoutMs: number): Promise<boolean>;
     sendKey(slot: Slot, key: string): Promise<void>;
     nudge(slot: Slot, message: string): Promise<boolean>;
-    narrator(_cwd: string, _command: string, runId?: string): Promise<Slot>;
+    narrator(cwd: string, command: string, runId?: string): Promise<Slot>;
+    private boardPath;
+    /** A recorded pane (a receipt's handle bound to the split envelope's runtime, never a guess) is
+     *  gone when that runtime no longer lists it, or when a handle-bound close receipt names it.
+     *  A handle listed by a different runtime is a different pane — not closed, treated as gone. */
+    private closeRecordedPane;
+    /** bound → retired, decided from the record alone: it must be this driver's board for exactly this
+     *  slot's pane. Already retired is returned as it is. */
+    private retireBoard;
+    /** bound → retired first: whatever fails below, no later call answers this board again. A live
+     *  observer is asked to stop and its acknowledgement awaited on injected time before the
+     *  handle-bound close (timeout keeps the tombstone and the pane); a dead one never acknowledges,
+     *  so it is only asked. */
+    private retireAndClose;
+    /** WB-1 seam: the daemon reports this board lost. "Lost" can be a stale beat or missing presence
+     *  under a still-live owner pid, so it is not proof of a dead observer — retirement keeps close's
+     *  acknowledgement discipline (Leg-2 T9 P1). */
+    retireLostWatch(slot: Slot): Promise<void>;
     focus(target: FocusTarget): Promise<FocusResult>;
     project(taskId: string, state: "in-progress" | "in-review" | "completed"): Promise<void>;
     private setWorkspaceStatus;
@@ -243,5 +329,8 @@ export declare class OrcaDriver implements ExecutorDriver {
     reconcile(desired: Set<string>, runId: string, opts?: {
         spareLiveLlm?: boolean;
     }): Promise<void>;
+    private isRecordedWatchHandle;
+    private isRecordedWorkerHandle;
     worktree(repo: string, branch: string, baseRef: string): Promise<string>;
 }
+export {};