tickmarkr 2.5.4 → 2.5.6

package/dist/config/fleet-overlay.js

@@ -1,6 +1,6 @@
 // Fleet-overlay mutation, serialization, and diff rendering for the `tickmarkr fleet` write path.
 import { isMap, isScalar, isSeq, parseDocument, stringify, visit } from "yaml";
-import { universeCovers } from "./config.js";
+import { universeCovers, universeEntryMatches } from "./config.js";
 /** Fleet-owned overlay keys — the only config surface `tickmarkr fleet` may write. */
 export const FLEET_OVERLAY_KEYS = ["routing", "tiers"];
 function fleetSubset(obj) {
@@ -21,17 +21,19 @@ function allowFormFromExclusions(universe, edited) {
     if (!universe.length) {
         throw new Error("fleet write: universe is empty — no classified models to compute routing.allow from; classify models in `tickmarkr fleet` first");
     }
-    const denyAdapters = new Set(edited.denyAdapters);
-    const denyModels = new Set(edited.denyModels);
+    // LEG2-T3 round 2 finding 1: every staged entry excludes what it NAMES — a bare model id every
+    // adapter serving it, an identity its alias — never only an adapter id or an adapter:model key.
+    // OBS-1046: the staged allow complement is a reason of its own, beside the authored deny lists.
+    const entries = [...edited.denyAdapters, ...edited.denyModels, ...(edited.allowOut ?? [])];
     const adapters = [];
     const models = [];
     let excluded = false;
     for (const row of universe) {
-        if (denyAdapters.has(row.adapter)) {
+        if (entries.includes(row.adapter)) {
             excluded = true;
             continue;
         }
-        const inFleet = row.models.filter((m) => !denyModels.has(`${row.adapter}:${m}`));
+        const inFleet = row.models.filter((m) => !entries.some((entry) => universeEntryMatches(row, m, entry)));
         if (inFleet.length === row.models.length) {
             adapters.push(row.adapter);
         }
@@ -49,6 +51,24 @@ function allowFormFromExclusions(universe, edited) {
 function residualDeny(universe, entries) {
     return sortedUnique(entries.filter((entry) => !universeCovers(universe, entry)));
 }
+// LEG2-T3 round 2 finding 2: the flat deny list a membership write leaves behind. Every entry the
+// repo overlay authored in THIS list that is still staged stays verbatim, in its authored order and
+// with its comments — one cleared reason never takes an independent one with it, and an untouched
+// list keeps its node. A staged entry the allow form cannot express as a membership key (outside the
+// probe universe, or a bare-model/identity spelling) is written verbatim too; canonical keys the
+// session added ride the allow form alone.
+function authoredEntries(doc, path) {
+    const node = doc.getIn(path, true);
+    return isSeq(node) ? node.items.flatMap((item) => (isScalar(item) ? [String(item.value)] : [])) : [];
+}
+function flatDenyAfterWrite(doc, path, after, universe) {
+    const authored = authoredEntries(doc, path);
+    const canonical = (entry) => universe.some((row) => entry === row.adapter || row.models.some((m) => entry === `${row.adapter}:${m}`));
+    const kept = authored.filter((entry) => after.includes(entry));
+    const verbatim = sortedUnique(after.filter((entry) => !kept.includes(entry)
+        && (!universeCovers(universe, entry) || !canonical(entry))));
+    return [...new Set([...kept, ...verbatim])];
+}
 // fleet.ts deliberately remains the sole overlay builder and writer. Its established classification
 // seam copies only `tier` and `note` into FleetEditable, so first-touch entry metadata rides inside a
 // private provenance envelope until this module writes the YAML. The envelope never reaches disk.
@@ -167,9 +187,12 @@ export function renderFleetOverlayWrite(priorBytes, write) {
     if (doc.errors.length)
         throw doc.errors[0];
     const { initial, edited } = write;
-    const denyChanged = sortedUnique(initial.denyAdapters).join() !== sortedUnique(edited.denyAdapters).join()
-        || sortedUnique(initial.denyModels).join() !== sortedUnique(edited.denyModels).join();
-    if (denyChanged) {
+    // OBS-1046: each flat scope (and the allow complement) is compared on its own — a scope the
+    // session never edited keeps its node byte for byte, whatever its sibling did.
+    const changed = (before = [], after = []) => sortedUnique(before).join() !== sortedUnique(after).join();
+    const adaptersChanged = changed(initial.denyAdapters, edited.denyAdapters);
+    const modelsChanged = changed(initial.denyModels, edited.denyModels);
+    if (adaptersChanged || modelsChanged || changed(initial.allowOut, edited.allowOut)) {
         if (write.universe) {
             // Membership write: the allow form IS the fleet; deny adapters/models scopes are tombstoned
             // so a lower layer can never re-exclude behind the operator's back (workers untouched).
@@ -199,18 +222,61 @@ export function renderFleetOverlayWrite(priorBytes, write) {
                 // Whole fleet in: no restriction to express — the allow block goes away entirely.
                 deleteAt(doc, ["routing", "allow"]);
             }
-            // Residuals stay in deny; covered scopes are tombstoned so a lower layer can never
+            // Authored and non-canonical entries stay in deny (LEG2-T3 finding 4, round 2 finding 2).
+            // OBS-1046: only an EDITED scope is rewritten, and only when its bytes must change — an
+            // addition the allow form carries leaves the list (an explicit `[]` included) untouched; a
+            // scope the press CLEARED down to nothing is tombstoned so a lower layer can never
             // re-exclude behind the operator's back (workers untouched).
-            const residualAdapters = residualDeny(write.universe, edited.denyAdapters);
-            const residualModels = residualDeny(write.universe, edited.denyModels);
-            setStringSequencePreservingComments(doc, ["routing", "deny", "adapters"], residualAdapters.length ? residualAdapters : null);
-            setStringSequencePreservingComments(doc, ["routing", "deny", "models"], residualModels.length ? residualModels : null);
+            // LEG2-T3 finding 4: an authored entry the edit admits (staged nowhere any more) must go
+            // even from a scope whose own set did not change, or the admitted channel stays excluded
+            // behind the preserved bytes.
+            const stagedAfter = new Set([...edited.denyAdapters, ...edited.denyModels, ...(edited.allowOut ?? [])]);
+            const admitted = [...initial.denyAdapters, ...initial.denyModels, ...(initial.allowOut ?? [])]
+                .filter((entry) => !stagedAfter.has(entry));
+            const scopes = [
+                ["adapters", initial.denyAdapters, edited.denyAdapters, adaptersChanged],
+                ["models", initial.denyModels, edited.denyModels, modelsChanged],
+            ];
+            for (const [scope, before, after, touched] of scopes) {
+                const path = ["routing", "deny", scope];
+                const authored = authoredEntries(doc, path);
+                const stale = authored.some((entry) => admitted.includes(entry));
+                if (!touched && !stale)
+                    continue;
+                const remaining = flatDenyAfterWrite(doc, path, after, write.universe);
+                if (remaining.length) {
+                    if (remaining.join("\n") !== authored.join("\n"))
+                        setStringSequencePreservingComments(doc, path, remaining);
+                }
+                else if (stale || before.some((entry) => !after.includes(entry))) {
+                    setStringSequencePreservingComments(doc, path, null);
+                }
+            }
         }
         else {
-            setStringSequencePreservingComments(doc, ["routing", "deny", "adapters"], edited.denyAdapters.length ? sortedUnique(edited.denyAdapters) : null);
-            setStringSequencePreservingComments(doc, ["routing", "deny", "models"], edited.denyModels.length ? sortedUnique(edited.denyModels) : null);
+            if (adaptersChanged) {
+                setStringSequencePreservingComments(doc, ["routing", "deny", "adapters"], edited.denyAdapters.length ? sortedUnique(edited.denyAdapters) : null);
+            }
+            if (modelsChanged) {
+                setStringSequencePreservingComments(doc, ["routing", "deny", "models"], edited.denyModels.length ? sortedUnique(edited.denyModels) : null);
+            }
         }
     }
+    // OBS-994/FL-1: routing.deny.workers is a literal deny list, never a universe-derived
+    // membership scope — it never routes through the allow-complement dance above, in either
+    // branch. Same tombstone/comment-preserving rules as the flat scopes.
+    const initialWorkersAdapters = initial.denyWorkersAdapters ?? [];
+    const editedWorkersAdapters = edited.denyWorkersAdapters ?? [];
+    const initialWorkersModels = initial.denyWorkersModels ?? [];
+    const editedWorkersModels = edited.denyWorkersModels ?? [];
+    // Each sub-path mutates independently — an untouched sibling must not be rewritten (a `null`
+    // tombstone over an absent/untouched sibling would mask a lower layer's own workers scope).
+    if (sortedUnique(initialWorkersAdapters).join() !== sortedUnique(editedWorkersAdapters).join()) {
+        setStringSequencePreservingComments(doc, ["routing", "deny", "workers", "adapters"], editedWorkersAdapters.length ? sortedUnique(editedWorkersAdapters) : null);
+    }
+    if (sortedUnique(initialWorkersModels).join() !== sortedUnique(editedWorkersModels).join()) {
+        setStringSequencePreservingComments(doc, ["routing", "deny", "workers", "models"], editedWorkersModels.length ? sortedUnique(editedWorkersModels) : null);
+    }
     for (const shape of new Set([...Object.keys(initial.map), ...Object.keys(edited.map)])) {
         const before = initial.map[shape];
         const after = edited.map[shape];
@@ -327,15 +393,19 @@ export function renderFleetOverlayWrite(priorBytes, write) {
     // operator reviews. commentString has no position context, but this writer owns the document:
     // scalar-trailing single-line comments (the only inline form fleet emits) are marked with a
     // private-use sentinel (the FIRST_TOUCH envelope precedent above), everything else renders
-    // byte-identical to yaml's own stringifyComment.
+    // byte-identical to yaml's own stringifyComment. OBS-1046: a scalar parsed from the prior bytes
+    // keeps the exact whitespace it had before its hash sign (yaml itself emits one space, so the
+    // sentinel carries the rest); only a comment fleet authored gets the two-space style.
     visit(doc, (_key, node) => {
         if (isScalar(node) && typeof node.comment === "string" && !node.comment.includes("\n")) {
-            node.comment = `${INLINE_COMMENT_SENTINEL}${node.comment}`;
+            const tail = node.range ? priorBytes.slice(node.range[1], node.range[2]) : "";
+            const gap = /^([ \t]+)#/.exec(tail)?.[1] ?? "  ";
+            node.comment = `${INLINE_COMMENT_SENTINEL}${gap.slice(1)}#${node.comment}`;
         }
     });
     return doc.toString({
         commentString: (comment) => comment.startsWith(INLINE_COMMENT_SENTINEL)
-            ? ` #${comment.slice(1)}`
+            ? comment.slice(1)
             : comment.replace(/^(?!$)(?: $)?/gm, "#"),
         // OBS-518: yaml's default pads flow collections (`[kimi]` → `[ kimi ]`), churning untouched
         // lines on the one confirmation surface an operator reviews. Hand-written overlays use the
@@ -351,7 +421,8 @@ export function fleetRepoOverlayFromDelta(initial, edited, existingRepo = {}, fi
     const routing = { ...out.routing };
     let routingTouched = false;
     const denyChanged = sortedUnique(initial.denyAdapters).join() !== sortedUnique(edited.denyAdapters).join()
-        || sortedUnique(initial.denyModels).join() !== sortedUnique(edited.denyModels).join();
+        || sortedUnique(initial.denyModels).join() !== sortedUnique(edited.denyModels).join()
+        || sortedUnique(initial.allowOut ?? []).join() !== sortedUnique(edited.allowOut ?? []).join();
     if (denyChanged) {
         if (universe) {
             const form = allowFormFromExclusions(universe, edited);
@@ -379,6 +450,30 @@ export function fleetRepoOverlayFromDelta(initial, edited, existingRepo = {}, fi
         }
         routingTouched = true;
     }
+    // OBS-994/FL-1: workers deny is a literal list, independent of the universe/allow dance above.
+    // Each sub-path is included only when it actually changed — an untouched sibling must not be
+    // rewritten as a `null` tombstone over whatever the existing repo overlay already held.
+    const initialWorkersAdapters = initial.denyWorkersAdapters ?? [];
+    const editedWorkersAdapters = edited.denyWorkersAdapters ?? [];
+    const initialWorkersModels = initial.denyWorkersModels ?? [];
+    const editedWorkersModels = edited.denyWorkersModels ?? [];
+    const workersAdaptersChanged = sortedUnique(initialWorkersAdapters).join() !== sortedUnique(editedWorkersAdapters).join();
+    const workersModelsChanged = sortedUnique(initialWorkersModels).join() !== sortedUnique(editedWorkersModels).join();
+    if (workersAdaptersChanged || workersModelsChanged) {
+        routing.deny = {
+            ...routing.deny,
+            workers: {
+                ...(routing.deny?.workers),
+                ...(workersAdaptersChanged
+                    ? { adapters: editedWorkersAdapters.length ? editedWorkersAdapters : null }
+                    : {}),
+                ...(workersModelsChanged
+                    ? { models: editedWorkersModels.length ? editedWorkersModels : null }
+                    : {}),
+            },
+        };
+        routingTouched = true;
+    }
     // pool widened to accept the null tombstone; MapEntry itself never carries null in memory.
     const mapDelta = {};
     for (const shape of new Set([...Object.keys(initial.map), ...Object.keys(edited.map)])) {

package/dist/config/fleet-why.d.ts

@@ -21,3 +21,10 @@ export type FleetWhyOptions = {
 export declare function projectFleetWhy<Id extends string>(values: readonly FleetWhyValue<Id>[], options: FleetWhyOptions): FleetWhyRow<Id>[];
 /** Plain line-mode twin of the Shapes rows; labels are projected, never reconstructed here. */
 export declare function renderFleetWhy(rows: readonly FleetWhyRow[]): string;
+/** LEG2-T3: one exclusion-collector scope as the reason a fleet row shows — its config path, then
+ * the entry that matched (a deny) or the fact the allowlist does not admit the channel. */
+export declare function exclusionReason(scope: {
+    by: "deny" | "allow";
+    configPath: string;
+    entry: string;
+}): string;

package/dist/config/fleet-why.js

@@ -40,3 +40,8 @@ export function projectFleetWhy(values, options) {
 export function renderFleetWhy(rows) {
     return ["tickmarkr fleet --why — effective shape routing", ...rows.map((row) => row.label)].join("\n");
 }
+/** LEG2-T3: one exclusion-collector scope as the reason a fleet row shows — its config path, then
+ * the entry that matched (a deny) or the fact the allowlist does not admit the channel. */
+export function exclusionReason(scope) {
+    return scope.by === "allow" ? `${scope.configPath} (not admitted)` : `${scope.configPath} (${scope.entry})`;
+}

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,43 @@ 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";
+    // A whitespace-only handle is no handle: the narrator trims it and would refuse the split.
+    if (env.TERM_PROGRAM === "Orca" && (env.ORCA_TERMINAL_HANDLE ?? "").trim() !== "")
+        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 +57,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 +77,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,71 @@ 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.
+ */
+/** `placer` is the pid of the narrator that wrote the reservation: a reserved or claimed record is a
+ *  normal intermediate state while that pid lives (another driver awaiting listing or bind) and a
+ *  crash to recover only once it is dead. */
+type BoardRecord = WatchBoardOwner & {
+    retired?: true;
+    runtimeId?: string;
+    placer?: number;
+};
+/**
+ * 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.
+ * Each lock generation publishes its pid and nonce atomically in a symlink target. A holder that died
+ * between taking and releasing it is recovered at once (its lock is taken over in place); a live
+ * holder bounds the wait on injected time and is then refused with the record untouched. A legacy
+ * pid-less or malformed generation is recoverable too: a contender atomically creates the next owner
+ * generation, and release removes the directory only while that exact generation is still current.
+ * 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, time?: OrcaTimeSource): Promise<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
@@ -95,6 +155,8 @@ export declare function mapAgentState(term: Record<string, unknown>, tuiIdle: bo
  * never depends on this.
  */
 export declare function joinWrapped(raw: string): string;
+/** The OBS-1011 add.1 capture: `status:"exited", tail:[], returnedLineCount 0` from a stream read. */
+export declare function isBlindStreamPage(term: Record<string, unknown>): boolean;
 export interface OrcaDriverOpts {
     bin?: string;
     env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
@@ -105,6 +167,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 +184,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 +212,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 +228,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
@@ -173,6 +253,15 @@ export declare class OrcaDriver implements ExecutorDriver {
     private liveShowTerm;
     private tailText;
     private readPage;
+    /**
+     * OBS-1011 add.1 / OBS-1016: the captured incident shape — a stream page answering status exited
+     * with an empty tail on a terminal that accepted a send seconds earlier — is BLIND, not dead, when
+     * the same handle's show record on the same runtime reports connected and not orphaned (show carries
+     * no status field; none is demanded) and its screen read reports running. Then the rendered frame is
+     * the terminal's bytes. Anything less — disconnected, orphaned, another handle or runtime, a screen
+     * that is unavailable or exited — is refused as unavailable, exactly as the dead record would be.
+     */
+    private screenBehindBlindStream;
     /** A rendered-frame liveness read. `--screen` and `--cursor` are mutually exclusive in Orca. */
     private readScreen;
     /** A single UNPAGED tail read — exactly what the caller asked for and nothing more. Markers split
@@ -200,7 +289,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 +349,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 {};