tickmarkr 2.4.2 → 2.5.0

package/dist/run/lock.js

@@ -1,4 +1,4 @@
-import { linkSync, readFileSync, statSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
+import { closeSync, constants, fstatSync, linkSync, lstatSync, mkdtempSync, openSync, readFileSync, renameSync, rmdirSync, statSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { tickmarkrDir, stateDirName } from "../graph/graph.js";
@@ -28,9 +28,10 @@ let approvalSequence = 0;
 process.once("exit", () => { if (heldPath)
     unlinkIfOurs(heldPath); });
 // LOCK-04: the ONE decision table. Both acquireRunLock and isRunLockLive consume this — the two
-// hand-maintained copies of the rule cannot drift. The table changes HERE, once. unlockRun uses the
-// SAME inspect() with its own live-holder refusal (`!dead && !garbage`) — it is the escape hatch, not
-// a second copy of the rule.
+// hand-maintained copies of the rule cannot drift. The table changes HERE, once. previewUnlock /
+// commitUnlock (below) read the SAME underlying snapshot shape with their own eligibility rules
+// (matching run ID, provably dead, not garbage) — they are the escape hatch, not a second copy of
+// the rule.
 // LOCK-02 (OBS-05): refuse iff garbage OR alive. dead (ESRCH) self-clears through the reclaim branch
 // below — no 60s heartbeat wait. Expiry no longer participates in the DECISION (Inspect still carries
 // `expired` for the race guard + reclaim audit); the heartbeat mechanism itself is untouched.
@@ -139,10 +140,10 @@ export function acquireRunLock(repoRoot, runId) {
         }
         const stateDir = stateDirName(repoRoot);
         if (garbage)
-            throw new Error(`${stateDir}/graph.lock holds an unreadable/garbage payload — refusing to reclaim it; run \`tickmarkr unlock\` to remove it`);
+            throw new Error(`${stateDir}/graph.lock holds an unreadable/garbage payload — refusing to reclaim it; run \`tickmarkr unlock --garbage\` to remove it`);
         // LOCK-02: shouldRefuse is false whenever dead, so this throw is reached only for a LIVE holder
         // (incl. EPERM = alive-but-not-ours). The dead-but-fresh case self-clears via the reclaim branch.
-        throw new Error(`${stateDir}/graph.lock held by pid ${pid ?? "?"}${heldRun ? ` (run ${heldRun})` : ""} — another tickmarkr run? (operator escape: \`tickmarkr unlock\`)`);
+        throw new Error(`${stateDir}/graph.lock held by pid ${pid ?? "?"}${heldRun ? ` (run ${heldRun})` : ""} — another tickmarkr run? (operator escape: \`tickmarkr unlock ${heldRun ?? "<run-id>"}\`)`);
     }
 }
 export function releaseRunLock(repoRoot) {
@@ -293,32 +294,189 @@ export function runStatusLine(repoRoot, runId, events) {
 export function isRunLockLive(repoRoot) {
     return runLockOwner(repoRoot)?.live ?? false;
 }
-// LOCK-03: operator escape hatch. Liveness-checked delete — removes a dead-holder or garbage lock,
-// REFUSES to remove one whose holder is alive (incl. EPERM = alive-but-not-ours). No --force: the
-// refusal names the pid; the operator kills the process. Liveness logic stays here (LOCK-04
-// discipline extends to this caller) — the CLI command is a thin formatter.
-// W4 TOCTOU: liveness is checked, THEN unlinked — a live holder that dies (or a dead pid reused)
-// between inspect() and unlinkSync is a window this does NOT close. Acceptable: unlock is
-// operator-initiated on an already-parked run; worst case is removing a lock a just-reborn process
-// would want, which the operator triggered and can recover by re-running. NOT an atomic re-check.
-export function unlockRun(repoRoot) {
-    const p = lockPath(repoRoot);
-    let insp;
+// Unlike inspect() (owned by the acquire/reclaim path this task must not change), a stat failure
+// here is never silently read as "no lock" — only ENOENT is. Any other stat error (e.g. EACCES)
+// propagates so the CLI fails closed and loud instead of returning the neutral "nothing to remove"
+// receipt over a lock it could not actually see (R41).
+//
+// A content READ failure (stat succeeds, the bytes don't — e.g. EACCES) is its OWN `unreadable`
+// state, distinct from `garbage`: we never observed the bytes, so we cannot confirm the payload is
+// malformed, and a well-formed live lock made merely unreadable must never become eligible for
+// either recovery route. `raw` stays a Buffer (never decoded) for identity: decoding invalid UTF-8
+// collapses distinct byte sequences to the same replacement-character string, which would let a
+// changed-bytes attack slip past a text-equality check (AC2's byte-confirmation requirement).
+function readLockSnapshot(p) {
+    let st;
     try {
-        insp = inspect(p);
+        st = lstatSync(p);
     }
-    catch {
-        return { held: false };
-    } // statSync ENOENT ⇒ no lock
-    if (!insp.dead && !insp.garbage) {
-        throw new Error(`${stateDirName(repoRoot)}/graph.lock held by LIVE pid ${insp.pid}${insp.runId ? ` (run ${insp.runId})` : ""} — refusing to unlock; stop that run first`);
+    catch (e) {
+        if (e.code === "ENOENT")
+            return undefined;
+        throw e;
     }
+    const unreadable = () => ({ garbage: false, unreadable: true, dead: true, ino: st.ino, mtimeMs: st.mtimeMs, raw: Buffer.alloc(0) });
+    if (!st.isFile())
+        return unreadable();
+    let raw;
+    let fd;
     try {
-        unlinkSync(p);
+        // Read bytes and inode from the same open file. Refuse symlinks/non-files even if the path
+        // changes after lstat; NONBLOCK prevents a substituted FIFO from hanging the command.
+        fd = openSync(p, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        st = fstatSync(fd);
+        if (!st.isFile())
+            return unreadable();
+        raw = readFileSync(fd);
     }
     catch (e) {
-        if (e.code !== "ENOENT")
+        if (e.code === "ENOENT")
+            return undefined; // raced away between stat and read
+        return unreadable();
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+    let parsedJson = null;
+    try {
+        parsedJson = JSON.parse(raw.toString("utf8"));
+    }
+    catch { /* not JSON ⇒ garbage below */ }
+    const parsed = PayloadSchema.safeParse(parsedJson);
+    const pid = parsed.success ? parsed.data.pid : undefined;
+    return {
+        pid,
+        runId: parsed.success ? parsed.data.runId : undefined,
+        garbage: !parsed.success,
+        unreadable: false,
+        dead: pid === undefined ? true : !isPidLive(pid),
+        ino: st.ino,
+        mtimeMs: st.mtimeMs,
+        raw,
+    };
+}
+// rename is the single capture operation, not a snapshot followed by an unlink of graph.lock.
+// mkdtemp gives this commit a private destination on the same filesystem. All validation and
+// deletion happens there, so a later acquisition at graph.lock survives even during the read.
+function commitCapturedLock(repoRoot, validate) {
+    const p = lockPath(repoRoot);
+    const dir = mkdtempSync(`${p}.unlock-`);
+    const captured = join(dir, "graph.lock");
+    const restore = (reason) => {
+        try {
+            // Never rename back: that would clobber a successor installed while we validated.
+            linkSync(captured, p);
+        }
+        catch (e) {
+            return { removed: false, reason: `${reason}; could not restore graph.lock (${e.code}) — captured entry retained at ${captured}` };
+        }
+        try {
+            unlinkSync(captured);
+        }
+        catch (e) {
+            if (e.code !== "ENOENT") {
+                return { removed: false, reason: `${reason}; graph.lock restored, additional captured link retained at ${captured}: ${e.message}` };
+            }
+        }
+        return { removed: false, reason };
+    };
+    try {
+        try {
+            renameSync(p, captured);
+        }
+        catch (e) {
+            if (e.code === "ENOENT")
+                return { removed: false, reason: "graph.lock no longer exists — nothing captured or removed" };
             throw e;
+        }
+        try {
+            const snap = readLockSnapshot(captured);
+            if (!snap)
+                return { removed: false, reason: "captured graph.lock no longer exists — not removed" };
+            const reason = validate(snap);
+            if (reason)
+                return restore(reason);
+            unlinkSync(captured);
+            return { removed: true, snap };
+        }
+        catch (e) {
+            if (e.code === "ENOENT")
+                return { removed: false, reason: "captured graph.lock no longer exists — not removed" };
+            return restore(`graph.lock could not be removed: ${e.message}`);
+        }
+    }
+    finally {
+        // Best-effort empty-directory cleanup only. Never recursively delete a refused capture that
+        // could not be restored, or obscure its recovery path with a cleanup error.
+        try {
+            rmdirSync(dir);
+        }
+        catch { /* retained capture or directory cleanup failure */ }
+    }
+}
+// AC1: eligible only for a matching-run, provably-dead, non-garbage lock. Live, EPERM and any other
+// signal-probe error all read `dead: false` through the one shared isPidLive predicate — never a
+// second copy that would treat an unknown errno as death. A different run ID refuses even when the
+// holder is dead: the operator named a run, and this is not it.
+export function previewUnlock(repoRoot, runId) {
+    const snap = readLockSnapshot(lockPath(repoRoot));
+    if (!snap)
+        return { held: false };
+    const stateDir = stateDirName(repoRoot);
+    if (snap.unreadable) {
+        return { held: true, eligible: false, reason: `${stateDir}/graph.lock content could not be read — refusing to unlock without observing its payload` };
+    }
+    if (snap.garbage) {
+        return { held: true, eligible: false, reason: `${stateDir}/graph.lock holds an unreadable/garbage payload — run \`tickmarkr unlock --garbage\` to recover it, not a named unlock`, pid: snap.pid, runId: snap.runId };
+    }
+    if (snap.runId !== runId) {
+        return { held: true, eligible: false, reason: `${stateDir}/graph.lock is held for run ${snap.runId ?? "?"}, not ${runId} — refusing to unlock a different run`, pid: snap.pid, runId: snap.runId };
+    }
+    if (!snap.dead) {
+        return { held: true, eligible: false, reason: `${stateDir}/graph.lock held by LIVE pid ${snap.pid}${snap.runId ? ` (run ${snap.runId})` : ""} — refusing to unlock; stop that run first`, pid: snap.pid, runId: snap.runId };
+    }
+    return { held: true, eligible: true, pid: snap.pid, runId: snap.runId, ino: snap.ino, mtimeMs: snap.mtimeMs, raw: snap.raw };
+}
+export function commitUnlock(repoRoot, target) {
+    const commit = commitCapturedLock(repoRoot, (snap) => {
+        if (snap.unreadable || snap.garbage || snap.ino !== target.ino || snap.mtimeMs !== target.mtimeMs || snap.pid !== target.pid || !snap.raw.equals(target.raw)) {
+            return "graph.lock changed since preview — refusing to remove the new holder";
+        }
+        if (snap.runId !== target.runId)
+            return `graph.lock now names run ${snap.runId ?? "?"}, not ${target.runId}`;
+        if (!snap.dead)
+            return `holder pid ${snap.pid} is alive`;
+    });
+    if (!commit.removed)
+        return commit;
+    return { removed: true, pid: commit.snap.pid, runId: commit.snap.runId };
+}
+// AC2: eligible only for an ACTUALLY malformed snapshot — a well-formed payload (dead or live) is
+// refused here and pointed at the ordinary named route instead, so --garbage can never become a
+// second, run-ID-free way to remove a legitimate lock. An unreadable payload is refused too: its
+// bytes were never observed, so it is neither confirmed malformed nor confirmed well-formed.
+export function previewGarbageUnlock(repoRoot) {
+    const snap = readLockSnapshot(lockPath(repoRoot));
+    if (!snap)
+        return { held: false };
+    if (snap.unreadable) {
+        return { held: true, eligible: false, reason: `${stateDirName(repoRoot)}/graph.lock content could not be read — refusing to treat it as garbage without observing its bytes` };
     }
-    return { held: true, removed: true, pid: insp.pid, runId: insp.runId, garbage: insp.garbage };
+    if (!snap.garbage) {
+        return { held: true, eligible: false, reason: `${stateDirName(repoRoot)}/graph.lock holds a well-formed payload — run \`tickmarkr unlock ${snap.runId ?? "<run-id>"}\` instead of --garbage`, pid: snap.pid, runId: snap.runId };
+    }
+    return { held: true, eligible: true, ino: snap.ino, raw: snap.raw };
+}
+export function commitGarbageUnlock(repoRoot, target) {
+    const commit = commitCapturedLock(repoRoot, (snap) => {
+        if (snap.unreadable)
+            return "graph.lock content became unreadable since preview — refusing to remove it blind";
+        if (!snap.garbage)
+            return "graph.lock now holds a well-formed payload — refusing to remove a valid holder";
+        if (snap.ino !== target.ino || !snap.raw.equals(target.raw)) {
+            return "graph.lock bytes/inode changed since preview — refusing to remove the new file";
+        }
+    });
+    return commit.removed ? { removed: true } : commit;
 }

package/dist/run/operator-state.d.ts

@@ -0,0 +1,86 @@
+import { type RunGraph } from "../graph/schema.js";
+import { type JournalEvent } from "./journal.js";
+/** An evidence identity is a physical journal line, never a filtered row ordinal. */
+export interface EvidenceIdentity {
+    source: string;
+    line: number;
+    id: string;
+    generation?: number;
+}
+export interface OperatorRecord extends EvidenceIdentity {
+    event: JournalEvent;
+}
+export type OperatorTaskState = "unknown" | "pending" | "running" | "completed" | "merged" | "failed" | "human" | "blocked";
+export type OperatorGateState = "unknown" | "not-run" | "disabled" | "running" | "passed" | "failed";
+export interface OperatorGate {
+    state: OperatorGateState;
+    evidence?: EvidenceIdentity;
+}
+export interface OperatorTask {
+    id: string;
+    title?: string;
+    state: OperatorTaskState;
+    merged: boolean;
+    dispatches: number;
+    attempt?: number;
+    path?: string;
+    pane?: string;
+    alarmMs?: number;
+    parkKind?: string;
+    evidence?: EvidenceIdentity;
+    mergeEvidence?: EvidenceIdentity;
+    gates: Record<string, OperatorGate>;
+}
+export interface OperatorSnapshot {
+    sequence: number;
+    observedAt: number;
+    lastEventAt?: string;
+    lifecycle: "PENDING" | "RUNNING" | "PARTIAL" | "APPROVED" | "COMPLETE" | "UNKNOWN";
+    label: string;
+    green: boolean;
+    currentTip: "passed" | "not required" | "pending" | "failed" | "unknown";
+    comparable: boolean;
+    comparison: "matching graph" | "not comparable";
+    merged: number;
+    planned?: number;
+    tasks: readonly OperatorTask[];
+    buckets: Record<"failed" | "human" | "blocked" | "pending", readonly string[] | undefined>;
+    gatesRan: {
+        passed: number;
+        total: number;
+    };
+    latestRunEnd?: EvidenceIdentity;
+    approvedResumeRequired: boolean;
+}
+/** Incremental pure lifecycle fold. Retains facts per task/gate, never verdict bodies or event history. */
+export declare class OperatorStateFold {
+    private tasks;
+    private start?;
+    private startEvent?;
+    private latestGraphRehash?;
+    private end?;
+    private active;
+    private approved;
+    private tipFailed;
+    private lastEventAt?;
+    private passed;
+    private total;
+    apply(record: OperatorRecord): void;
+    private task;
+    snapshot({ graph, sequence, observedAt, readable }?: {
+        graph?: RunGraph;
+        sequence?: number;
+        observedAt?: number;
+        readable?: boolean;
+    }): OperatorSnapshot;
+    private comparableTo;
+}
+/** C1/C6 share this pure reader; callers supply the same observation and journal snapshot. */
+export declare function readOperatorState({ events, source, ...options }: {
+    events: readonly (JournalEvent | OperatorRecord)[];
+    source?: string;
+    graph?: RunGraph;
+    sequence?: number;
+    observedAt?: number;
+    readable?: boolean;
+}): OperatorSnapshot;

package/dist/run/operator-state.js

@@ -0,0 +1,165 @@
+import { graphDefinitionHash } from "../graph/graph.js";
+import { GATE_NAMES } from "../graph/schema.js";
+import { engagementComparable } from "./journal.js";
+const bucketNames = ["failed", "human", "blocked", "pending"];
+const strings = (value) => Array.isArray(value) && value.every(v => typeof v === "string") ? [...value] : undefined;
+const identity = ({ source, line, id, generation }) => ({ source, line, id, generation });
+const emptyGates = () => Object.fromEntries(GATE_NAMES.map(g => [g, { state: "not-run" }]));
+/** Incremental pure lifecycle fold. Retains facts per task/gate, never verdict bodies or event history. */
+export class OperatorStateFold {
+    tasks = new Map();
+    start;
+    startEvent;
+    latestGraphRehash;
+    end;
+    active = false;
+    approved = false;
+    tipFailed = false;
+    lastEventAt;
+    passed = 0;
+    total = 0;
+    apply(record) {
+        const { event: e } = record;
+        this.lastEventAt = e.ts;
+        const ref = identity(record);
+        if (e.event === "run-start" || e.event === "run-resume") {
+            if (e.event === "run-start" && !this.start) {
+                const startEvent = { ...e, data: { graphDefinitionHash: e.data.graphDefinitionHash } };
+                this.start = { ...ref, event: startEvent };
+                this.startEvent = startEvent;
+            }
+            this.end = undefined;
+            this.active = true;
+            this.approved = false;
+            this.tipFailed = false;
+        }
+        if (e.event === "graph-rehash")
+            this.latestGraphRehash = { ...e, data: { from: e.data.from, to: e.data.to } };
+        if (e.event === "tip-verify-failed" || (e.event === "tip-verify" && e.data.pass === false))
+            this.tipFailed = true;
+        if (e.event === "run-end") {
+            const tip = e.data.tipVerify;
+            this.end = {
+                evidence: ref,
+                buckets: Object.fromEntries(bucketNames.map(k => [k, strings(e.data[k])])),
+                tip: tip === "passed" ? "passed" : tip === "failed" ? "failed" : tip === "not required" || tip === "not-required" || tip === "skipped" ? "not required" : "unknown",
+            };
+            this.active = false;
+            this.approved = false;
+            for (const key of bucketNames)
+                for (const id of this.end.buckets[key] ?? []) {
+                    const task = this.task(id);
+                    task.state = key;
+                    task.evidence = ref;
+                }
+        }
+        if (e.event === "gate-result" && e.data.skipped !== true && e.data.disabled !== true && typeof e.data.pass === "boolean") {
+            this.total++;
+            if (e.data.pass)
+                this.passed++;
+        }
+        if (!e.taskId)
+            return;
+        const t = this.task(e.taskId);
+        t.evidence = ref;
+        if (e.event === "task-dispatch") {
+            t.state = "running";
+            t.dispatches++;
+            t.parkKind = undefined;
+            t.gates = emptyGates();
+            t.attempt = typeof e.data.attempt === "number" ? e.data.attempt : undefined;
+            // These are recorded values only: no guessed directory or universal silence threshold.
+            t.path = typeof e.data.worktree === "string" ? e.data.worktree : typeof e.data.cwd === "string" ? e.data.cwd : undefined;
+            t.pane = typeof e.data.pane === "string" ? e.data.pane : undefined;
+            t.alarmMs = typeof e.data.alarmMs === "number" ? e.data.alarmMs : undefined;
+        }
+        if (e.event === "task-done")
+            t.state = "completed";
+        if (e.event === "merge") {
+            t.state = "merged";
+            t.merged = true;
+            t.mergeEvidence = ref;
+            t.parkKind = undefined;
+        }
+        if (e.event === "task-failed")
+            t.state = "failed";
+        if (e.event === "task-human") {
+            t.state = "human";
+            t.parkKind = typeof e.data.kind === "string" ? e.data.kind : undefined;
+        }
+        if (e.event === "task-blocked")
+            t.state = "blocked";
+        if (e.event === "task-approved") {
+            t.state = "pending";
+            t.parkKind = undefined;
+            this.approved = !this.active;
+        }
+        const gate = e.data.gate;
+        if (typeof gate === "string" && GATE_NAMES.includes(gate)) {
+            if (e.event === "gate-start")
+                t.gates[gate] = { state: "running", evidence: ref };
+            if (e.event === "gate-result")
+                t.gates[gate] = {
+                    state: e.data.disabled === true ? "disabled" : e.data.skipped === true ? "not-run" : e.data.pass === true ? "passed" : e.data.pass === false ? "failed" : "unknown", evidence: ref,
+                };
+        }
+    }
+    task(id) {
+        let t = this.tasks.get(id);
+        if (!t) {
+            t = { id, state: "unknown", merged: false, dispatches: 0, gates: emptyGates() };
+            this.tasks.set(id, t);
+        }
+        return t;
+    }
+    snapshot({ graph, sequence = 0, observedAt = Date.now(), readable = true } = {}) {
+        const hash = graph && graphDefinitionHash(graph);
+        const comparable = this.comparableTo(hash);
+        const ids = comparable ? [...graph.tasks.map(t => t.id), ...[...this.tasks.keys()].filter(id => !graph.tasks.some(t => t.id === id))] : [...this.tasks.keys()];
+        const tasks = ids.map(id => {
+            const t = this.tasks.get(id) ?? { id, state: "unknown", merged: false, dispatches: 0, gates: emptyGates() };
+            return { ...t, title: comparable ? graph.tasks.find(g => g.id === id)?.title : undefined, gates: Object.fromEntries(Object.entries(t.gates).map(([g, cell]) => [g, { ...cell }])) };
+        });
+        const buckets = Object.fromEntries(bucketNames.map(k => [k, this.end?.buckets[k] === undefined ? undefined : [...this.end.buckets[k]]]));
+        // A matching graph contributes planned tasks even when the journal has never named them.
+        // Their silence is unknown evidence, not completion. Comparison itself is also required for
+        // green: without the recorded graph identity there is no trustworthy planned denominator.
+        const merged = tasks.filter(t => t.merged && (!comparable || graph.tasks.some(g => g.id === t.id))).length;
+        const planned = comparable ? graph.tasks.length : undefined;
+        const unresolved = tasks.some(t => ["unknown", "failed", "human", "blocked", "pending", "running"].includes(t.state));
+        const allPlannedMerged = comparable && merged === planned;
+        const currentTip = this.active ? "pending" : this.tipFailed ? "failed" : this.end?.tip ?? "unknown";
+        const green = readable && comparable && allPlannedMerged && !!this.start && !!this.end && !this.approved && !unresolved
+            && (currentTip === "passed" || currentTip === "not required")
+            && bucketNames.every(k => buckets[k]?.length === 0);
+        const lifecycle = !readable || !this.start ? "UNKNOWN" : this.active ? "RUNNING" : this.approved ? "APPROVED" : green ? "COMPLETE" : this.end ? "PARTIAL" : "PENDING";
+        return {
+            sequence, observedAt, lastEventAt: this.lastEventAt, lifecycle,
+            label: this.approved ? "approved; resume required" : lifecycle,
+            green, currentTip, comparable, comparison: comparable ? "matching graph" : "not comparable",
+            merged,
+            planned, tasks, buckets,
+            gatesRan: { passed: this.passed, total: this.total }, latestRunEnd: this.end?.evidence,
+            approvedResumeRequired: this.approved,
+        };
+    }
+    comparableTo(hash) {
+        if (!hash)
+            return false;
+        const events = [this.startEvent, this.latestGraphRehash].filter((e) => e !== undefined);
+        const baseline = engagementComparable(events, hash);
+        if (this.latestGraphRehash) {
+            const from = baseline.comparable ? baseline.recorded : baseline.reason === "mismatch" ? baseline.recorded : null;
+            return this.latestGraphRehash.data.to === hash && this.latestGraphRehash.data.from === from;
+        }
+        return baseline.comparable;
+    }
+}
+/** C1/C6 share this pure reader; callers supply the same observation and journal snapshot. */
+export function readOperatorState({ events, source = "journal.jsonl", ...options }) {
+    const fold = new OperatorStateFold();
+    events.forEach((event, i) => fold.apply(typeof event.event === "object" ? event : {
+        source, line: i + 1, id: `${source}#L${i + 1}`, event: event,
+    }));
+    return fold.snapshot(options);
+}

package/dist/run/supervision.d.ts

@@ -43,6 +43,9 @@ export declare function beatSupervision(repoRoot: string, tier: SupervisionTier,
 /** Handle a watcher holds for as long as it is supervising; disarm stands it down and is idempotent. */
 export interface ArmedSupervision {
     disarm: () => void;
+    readonly id?: string;
+    /** True only after this handle removed its own presence. */
+    released?: () => boolean;
 }
 export declare function armSupervision(repoRoot: string, tier: SupervisionTier, beatMs?: number, seat?: string): ArmedSupervision;
 /** Arm the live status board's own tier through the normal supervision writer and lifecycle. */
@@ -53,3 +56,32 @@ export declare function supervisionStatus(repoRoot: string, tier: SupervisionTie
 export declare const readSupervision: (repoRoot: string, now?: number) => TierLiveness[];
 /** One line, one word per tier. Shared by both status surfaces so neither can render a state twice. */
 export declare const supervisionText: (tiers: readonly TierLiveness[], divider?: string) => string;
+/** A board's durable identity is independent of its short title and of other observers. */
+export interface WatchBoardOwner {
+    repo: string;
+    runId: string;
+    driver: string;
+    workspace: string;
+    pane: string;
+    name: string;
+    token: string;
+    pid?: number;
+    armId?: string;
+}
+export declare const WATCH_OWNER_ENV = "TICKMARKR_WATCH_OWNER";
+export declare function readWatchBoard(repo: string, runId: string): WatchBoardOwner | undefined;
+/** Only a driver that has just verified placement may reserve this binding. */
+export declare function reserveWatchBoard(owner: Omit<WatchBoardOwner, "repo" | "token" | "pid" | "armId"> & {
+    repo: string;
+}): WatchBoardOwner;
+export declare function requestWatchBoardStop(owner: WatchBoardOwner): void;
+export declare function watchBoardAcknowledged(owner: WatchBoardOwner): boolean;
+export declare function stopWatchBoard(owner: WatchBoardOwner, time?: {
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+}, timeoutMs?: number): Promise<void>;
+/** The UI alone publishes acknowledgement, after releasing its own presence. */
+export declare function observeNamedRun(repo: string, runId: string, env?: NodeJS.ProcessEnv): {
+    stopRequested: () => boolean;
+    close: () => void;
+};