tickmarkr 2.1.5 → 2.1.7

package/dist/run/daemon.js

@@ -1,6 +1,6 @@
 import { createHash, randomBytes } from "node:crypto";
 import { shq } from "../adapters/types.js";
-import { appendFileSync, closeSync, constants, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readlinkSync, readSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { appendFileSync, closeSync, constants, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, readlinkSync, readSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { stringify } from "yaml";
@@ -15,7 +15,7 @@ import { herdrSealShellPrefix, SubprocessDriver } from "../drivers/subprocess.js
 import { formatOwnedName } from "../drivers/types.js";
 import { captureBaseline, detectGateCommands, detectVacuousOracles } from "../gates/baseline.js";
 import { runGates } from "../gates/run-gates.js";
-import { addEvidence, attributeBlocked, blockedTasks, getTask, graphDefinitionHash, loadGraph, pendingTasks, readyTasks, saveGraph, setStatus, taskContentDigest } from "../graph/graph.js";
+import { addEvidence, attributeBlocked, blockedTasks, getTask, graphDefinitionHash, loadGraph, pendingTasks, readyTasks, saveGraph, setStatus, taskContentDigest, tickmarkrDir } from "../graph/graph.js";
 import { GATE_NAMES } from "../graph/schema.js";
 import { augmentRetryBrief, consult, renderRetryGuidance } from "./consult.js";
 import { runEnvironment } from "./environment.js";
@@ -23,7 +23,7 @@ import { cleanupRunWorktrees, gitHead, linkNodeModules, npmDependencyInstallComm
 import { runInteractiveSeed } from "./interactive-seed.js";
 import { activeRetryBan, classifyTaskFailure, classifyWorkerResultCause, deferredReviewFindings, engagementComparable, formatPriorFindingEvidence, GATE_FINGERPRINT_CAP, GATE_SATISFIED_RELEASE, identicalGateFailures, isDeferredFinding, journaledFailureBrief, Journal, loadRoutingProfile, newRunId, normalizeGateFailure, outstandingReviewFindings, pendingRepairFindings, phaseForGate, readPriorRunEvidence, recordedTaskFailureKind, renderStructuredReviewFinding, repairsSinceApproval, reviewRoundsSinceApproval, runHasEnded, structuredFindings, upheldFeedbackByTask } from "./journal.js";
 import { isDiffCapPark } from "../gates/review.js";
-import { acquireApprovalSerialization, acquireRunLock, releaseRunLock } from "./lock.js";
+import { acquireApprovalSerialization, acquireRunLock, isPidLive, releaseRunLock } from "./lock.js";
 import { ensureIntegration, integrationBranch, integrationHead, mergeTask, verifyIntegrationTip } from "./merge.js";
 import { nextChannel, route } from "../route/router.js";
 import { desiredPanes } from "./reconcile.js";
@@ -521,6 +521,35 @@ async function gateCommitSubject(base, head, wt) {
         return head; // fail closed to the exact object id if canonicalization fails
     return createHash("sha256").update(history.stdout).digest("hex");
 }
+// A CPU total cannot prove a tree empty: a newly launched live process can still have a measured
+// total of zero at the host's clock resolution. This probe asks the narrower cardinality question
+// OBS-737 needs. A readable process table with no marker root is measured empty; a failed or empty
+// table is unmeasurable. Descendants are closed over PPID because not every child retains the
+// dispatch-script marker in its own argv.
+async function observeWorkerProcessTree(marker, cwd) {
+    const snapshot = await shGit("ps -Awwo pid=,ppid=,command=", cwd, 15_000);
+    if (snapshot.code !== 0)
+        return "unmeasurable";
+    const rows = [];
+    for (const line of snapshot.stdout.split("\n")) {
+        const match = /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(line);
+        if (match)
+            rows.push({ pid: match[1], ppid: match[2], command: match[3] });
+    }
+    if (rows.length === 0)
+        return "unmeasurable";
+    const tree = new Set(rows.filter((row) => row.command.includes(marker)).map((row) => row.pid));
+    for (let grew = true; grew;) {
+        grew = false;
+        for (const row of rows) {
+            if (!tree.has(row.pid) && tree.has(row.ppid)) {
+                tree.add(row.pid);
+                grew = true;
+            }
+        }
+    }
+    return tree.size === 0 ? "empty" : "running";
+}
 const OBSERVE_CHUNK_BYTES = 64 * 1024;
 const OBSERVE_BUDGET_BYTES = 256 * 1024 * 1024;
 let observeBudgetBytes = OBSERVE_BUDGET_BYTES;
@@ -605,6 +634,20 @@ async function boundedGitObservation(command, worktree, budget) {
         return undefined;
     return result.stdout;
 }
+// "No worktree delta" means no staged/unstaged/untracked bytes AND no commits beyond the task's
+// dispatch base. Both reads are bounded and preserve the observer's third state: a failed probe is
+// unreadable, never clean.
+async function observeWorktreeDelta(base, worktree) {
+    let budget = observeBudgetBytes;
+    const status = await boundedGitObservation("GIT_OPTIONAL_LOCKS=0 git status --porcelain=v1 -z --untracked-files=all", worktree, budget);
+    if (status === undefined)
+        return "unreadable";
+    budget -= Buffer.byteLength(status);
+    const ahead = await boundedGitObservation(`GIT_OPTIONAL_LOCKS=0 git rev-list --count ${shq(base)}..HEAD`, worktree, budget);
+    if (ahead === undefined || !/^\d+$/.test(ahead.trim()))
+        return "unreadable";
+    return status.length === 0 && ahead.trim() === "0" ? "unchanged" : "changed";
+}
 // The signature has four git-owned inputs: HEAD, staged blob/mode/path identity, porcelain path and
 // state, and the set of worktree paths whose bytes Git cannot supply. Those paths contribute their
 // filesystem identity, mode, symlink text, and content. A failed or over-budget leg is a third
@@ -721,6 +764,37 @@ function recordFatalRunEnd(journal, runId, branch, err) {
         console.error(`tickmarkr ${runId}: run crashed — no terminal record written; journal sink unwritable at ${journalPath} (${retryErr instanceof Error ? retryErr.message : String(retryErr)}) — original error: ${original}`);
     }
 }
+// OBS-777: the fleet fold cannot distinguish an orphan from another repository's live worker. Give
+// it one repository-scoped snapshot instead: terminal journals are ended, and an open lifecycle is
+// ended only when the shared lock predicate can prove its last recorded daemon pid dead.
+function endedRunIdsForReconcile(repoRoot) {
+    const ended = new Set();
+    const dir = join(tickmarkrDir(repoRoot), "runs");
+    if (!existsSync(dir))
+        return ended;
+    let runIds;
+    try {
+        runIds = readdirSync(dir);
+    }
+    catch {
+        return ended;
+    }
+    for (const runId of runIds) {
+        try {
+            const events = Journal.open(repoRoot, runId).read();
+            if (runHasEnded(events)) {
+                ended.add(runId);
+                continue;
+            }
+            const lifecycle = [...events].reverse().find((event) => (event.event === "run-start" || event.event === "run-resume")
+                && Number.isInteger(event.data.pid) && event.data.pid > 0);
+            if (lifecycle && !isPidLive(lifecycle.data.pid))
+                ended.add(runId);
+        }
+        catch { /* incomplete or foreign run directory — it proves nothing */ }
+    }
+    return ended;
+}
 export async function runDaemon(repoRoot, opts = {}) {
     // v1.51 T2 / OBS-89 (v1.60): retired --quality env seam. Mode resolution owns premium routing;
     // route() no longer reads the retired env at all, so the old entrypoint scrub is gone with it.
@@ -738,6 +812,7 @@ export async function runDaemon(repoRoot, opts = {}) {
     // subprocess, so the optional-chain open below is a no-op there). Cosmetic-only: any failure is
     // swallowed (never affects the run); the operator closes a surviving watch pane.
     const lock = acquireRunLock(repoRoot, runId);
+    const endedRunIds = endedRunIdsForReconcile(repoRoot); // one snapshot for every sweep this caller makes
     // D10: the lock is this daemon's liveness record and already carries its pid; status prints that
     // identity beside the supervision row. The `orchestrator` tier belongs exclusively to the seated
     // supervisor, so a run never beats or stands down that seat's record on the daemon's behalf.
@@ -835,7 +910,7 @@ export async function runDaemon(repoRoot, opts = {}) {
             // Termination (SIGINT/SIGTERM): record the daemon-controlled exit before closing every live slot,
             // reconcile owned panes against an EMPTY
             // desired set (herdr panes not in memory; panesToClose spares foreign names, watch panes, and
-            // other runs' panes by construction), release the run lock, then exit. There is still no run-end,
+            // live/unknown other runs' panes by construction), release the run lock, then exit. There is still no run-end,
             // so stop-amend-resume keeps resuming; exit-cause distinguishes this deliberate stop from an
             // observer-classified abrupt death. keepPanes:"forever" (the
             // keep-everything debug override) preserves panes but still releases the lock and exits.
@@ -864,7 +939,7 @@ export async function runDaemon(repoRoot, opts = {}) {
                                 catch { /* cosmetic — reconcile is the backstop */ }
                             }
                             try {
-                                await driver.reconcile?.(new Set(), runId);
+                                await driver.reconcile?.(new Set(), runId, { endedRunIds });
                             }
                             catch { /* cosmetic — visibility is never a gate */ }
                         }
@@ -1050,7 +1125,7 @@ export async function runDaemon(repoRoot, opts = {}) {
                     // herdr's watches bookkeeping lives in close(), and a raw pane-close in the sweep would
                     // leave narrator() a stale cache) — the driver always sees it as desired; its lifecycle is
                     // decided here from the fold alone.
-                    await driver.reconcile?.(new Set([...desired, watchName]), runId, opts);
+                    await driver.reconcile?.(new Set([...desired, watchName]), runId, { ...opts, endedRunIds });
                     // OBS-103: when the fold retires the watch (run-end boundary), close the narrator. The
                     // decision keys on the run identity in the pane name — narrator() adopts a prior daemon
                     // instance's pane under the same owned name, so a stop→resume cycle's leftover narrator
@@ -1066,7 +1141,10 @@ export async function runDaemon(repoRoot, opts = {}) {
                     /* cosmetic — visibility is never a gate */
                 }
             };
-            await reconcile(); // run start/resume boundary: nothing in flight — full sweep, incl. older runs' leftovers
+            // run start/resume boundary: nothing in flight, so the sweep takes this run's judge/review/consult
+            // panes too. OBS-777: the one startup snapshot lets it reclaim only older runs proven ended, while
+            // every live or unknown run remains spared.
+            await reconcile();
             // v1.4 self-reference guard: a random nonce on the worker trailer AND exit marker. Displayed
             // source/diffs (e.g. a worker editing tickmarkr's own prompt.ts/daemon.ts) can't know it, so an echoed
             // TICKMARKR_RESULT/TICKMARKR_EXIT literal can never premature-harvest the worker. Quote-split keeps the
@@ -1091,10 +1169,10 @@ export async function runDaemon(repoRoot, opts = {}) {
             };
             // gateFails/consults are execTask-scoped counters passed in so a park row is a rich verified-failure
             // observation (e.g. ladder-exhausted + gateFails:4); every task-human row has a closed kind, never prose alone.
-            const park = async (t, reason, kind, assignment, attempts, startMs, gateFails = 0, consults = 0, tokens, metered = 0, retryMode = "fresh") => {
+            const park = async (t, reason, kind, assignment, attempts, startMs, gateFails = 0, consults = 0, tokens, metered = 0, retryMode = "fresh", details = {}) => {
                 graph = setStatus(graph, t.id, "human");
                 saveGraph(repoRoot, graph);
-                journal.append("task-human", t.id, { reason, kind });
+                journal.append("task-human", t.id, { ...details, reason, kind });
                 if (assignment) {
                     // OBS-547: `metered` counts CHARGEABLE metered attempts, so an unchargeable dispatch passes 0 and
                     // the count is omitted rather than written as 0 or as `1` beside `attempts: 0` — a row claiming
@@ -1172,6 +1250,22 @@ export async function runDaemon(repoRoot, opts = {}) {
                         journal.append("worktree-preserved", t.id, { ref });
                     return driver.worktree(repoRoot, taskBranch, taskBase);
                 };
+                // A dead worker with a clean checkout still needs a durable recovery handle: there may be no
+                // pane left to identify even the commit it was dispatched from. preserveWorktree deliberately
+                // creates no ref for ordinary clean recreations, so this exceptional terminal path pins HEAD
+                // explicitly under the same recovery namespace. Reconfirm the delta immediately before the
+                // ref write; a change or unreadable recheck withdraws the park.
+                const preserveDeadWorker = async (worktree, taskBase) => {
+                    const state = await observeWorktreeDelta(taskBase, worktree);
+                    if (state !== "unchanged")
+                        return { state };
+                    const head = await gitHead(worktree);
+                    const ref = `refs/tickmarkr/preserved/${head}`;
+                    const updated = await shGit(`git update-ref ${shq(ref)} ${shq(head)}`, worktree);
+                    if (updated.code !== 0)
+                        throw new Error(`could not preserve dead worker HEAD at ${ref}: ${updated.stderr || updated.stdout}`);
+                    return { state, ref };
+                };
                 const r = route(t, cfg, channels, profile, undefined, demotedChannels);
                 for (const lint of r.lints)
                     journal.append("routing-lint", t.id, { lint });
@@ -2184,6 +2278,7 @@ export async function runDaemon(repoRoot, opts = {}) {
                     // subprocess tree that REACHED its exit marker, not about what the worker claimed.
                     let processExited = false;
                     let earlyLaunchDead = false;
+                    let deadWorkerPark;
                     let settleParsed;
                     let seedResult;
                     // v1.22 T5 / OBS-19: auto-answer a fingerprint-matched trust dialog exactly once per slot.
@@ -2323,6 +2418,8 @@ export async function runDaemon(repoRoot, opts = {}) {
                                 let quotaStreak = 0;
                                 let rowSaturationHeld = false; // journaled once per attempt when the kill stands down
                                 let cpuHeld = false; // likewise for the CPU leg's stand-down (OBS-548)
+                                let paneReadHeld = false;
+                                let paneStatusHeld = false;
                                 while (Date.now() - lastProgressAt < stallWindowMs) {
                                     const sliceStart = Date.now();
                                     const remaining = stallWindowMs - (sliceStart - lastProgressAt);
@@ -2350,7 +2447,39 @@ export async function runDaemon(repoRoot, opts = {}) {
                                             break;
                                         }
                                     }
-                                    const paneText = await driver.read(slot, PANE_READ_ROWS);
+                                    // A failed pane read is absence of evidence, never evidence of an absent pane. Keep the
+                                    // rolling taskTimeoutMinutes window as the backstop and name the held probe once.
+                                    let paneText;
+                                    try {
+                                        paneText = await driver.read(slot, PANE_READ_ROWS);
+                                    }
+                                    catch (error) {
+                                        // Preserve the pre-existing exception path when the independent status probe still
+                                        // sees a pane. The outer attempt finally owns accountant cleanup on that path. Only
+                                        // an undetectable status makes the read failure relevant to the death detector, and
+                                        // that genuinely unmeasurable pair fails open to the rolling timeout.
+                                        let paneUndetectable = true;
+                                        try {
+                                            paneUndetectable = await driver.status(slot) === "unknown";
+                                        }
+                                        catch {
+                                            // Two unreadable pane probes are still unmeasurable, never proof of death.
+                                        }
+                                        if (!paneUndetectable)
+                                            throw error;
+                                        if (!paneReadHeld) {
+                                            paneReadHeld = true;
+                                            journal.append("worker-dead-held", t.id, {
+                                                slot: slot.name, attempt, reason: "pane-read-unreadable",
+                                                error: error instanceof Error ? error.message : String(error),
+                                            });
+                                        }
+                                        await armCpuLeg(false);
+                                        const spent = Date.now() - sliceStart;
+                                        if (spent < slice)
+                                            await new Promise((r) => setTimeout(r, Math.min(slice - spent, 1_000)));
+                                        continue;
+                                    }
                                     if (paneText.length > 0)
                                         everHadOutput = true;
                                     // OBS-117 (v1.71 T6): zero raw output by the early-launch deadline is a dead channel now.
@@ -2419,7 +2548,24 @@ export async function runDaemon(repoRoot, opts = {}) {
                                     // gate held. page on "idle" too: herdr's blocked-scrape is strict and proved flaky
                                     // for TUI dialogs (live check: cursor's trust dialog scraped as idle).
                                     // "unknown"/"working" never page.
-                                    const st = await driver.status(slot);
+                                    let st;
+                                    try {
+                                        st = await driver.status(slot);
+                                    }
+                                    catch (error) {
+                                        if (!paneStatusHeld) {
+                                            paneStatusHeld = true;
+                                            journal.append("worker-dead-held", t.id, {
+                                                slot: slot.name, attempt, reason: "pane-status-unreadable",
+                                                error: error instanceof Error ? error.message : String(error),
+                                            });
+                                        }
+                                        await armCpuLeg(false);
+                                        const spent = Date.now() - sliceStart;
+                                        if (spent < slice)
+                                            await new Promise((r) => setTimeout(r, Math.min(slice - spent, 1_000)));
+                                        continue;
+                                    }
                                     if (st !== lastStatus) {
                                         lastStatus = st;
                                         journal.append("worker-status", t.id, { slot: slot.name, status: st, attempt });
@@ -2459,6 +2605,95 @@ export async function runDaemon(repoRoot, opts = {}) {
                                     // daemon has nothing left to do — the pane falls back under the fast-kill and page
                                     // watchdogs like any other, instead of riding the whole rolling window untended.
                                     const nudgePending = nudgeable && (!nudged || nudgeDeadline !== undefined);
+                                    // OBS-737: disposition for the one fully measured death state. `unknown` alone is not
+                                    // absence (status parsing can fail), and an empty read alone is not absence (a live pane
+                                    // can be quiet); together they are the existing driver-level pane absence witness. The
+                                    // process probe and both worktree observations retain their own third states. Only the
+                                    // explicit conjunction parks; every other state falls through to the unchanged rolling
+                                    // timeout below. Seeded launches are excluded because their process marker is knowingly
+                                    // unmeasurable (armCpuLeg documents that contract above).
+                                    const paneAbsentCandidate = st === "unknown" && paneText.trim().length === 0;
+                                    // A subprocess can exit between waitOutput and read while its stdout is still draining.
+                                    // Confirm emptiness in this same poll before paying for `ps`; then confirm once more
+                                    // after the process probe yielded the event loop. Any bytes or read error withdraw the
+                                    // absence witness, so a fast completed worker cannot be parked in that drain race.
+                                    let paneAbsent = paneAbsentCandidate;
+                                    if (paneAbsent) {
+                                        try {
+                                            const confirmation = await driver.read(slot, PANE_READ_ROWS);
+                                            paneAbsent = confirmation.trim().length === 0;
+                                            if (!paneAbsent) {
+                                                everHadOutput = true;
+                                                if (stallProgress.observe({ paneText: confirmation, contextTokens }))
+                                                    lastProgressAt = Date.now();
+                                            }
+                                        }
+                                        catch (error) {
+                                            paneAbsent = false;
+                                            if (!paneReadHeld) {
+                                                paneReadHeld = true;
+                                                journal.append("worker-dead-held", t.id, {
+                                                    slot: slot.name, attempt, reason: "pane-read-unreadable",
+                                                    error: error instanceof Error ? error.message : String(error),
+                                                });
+                                            }
+                                        }
+                                    }
+                                    const processTree = paneAbsent && worktreeSinceLaunch === "unchanged" && !hasSeed
+                                        ? await observeWorkerProcessTree(dispatchScript, wt)
+                                        : "unmeasurable";
+                                    if (processTree === "empty") {
+                                        try {
+                                            const confirmation = await driver.read(slot, PANE_READ_ROWS);
+                                            paneAbsent = confirmation.trim().length === 0;
+                                            if (!paneAbsent) {
+                                                everHadOutput = true;
+                                                if (stallProgress.observe({ paneText: confirmation, contextTokens }))
+                                                    lastProgressAt = Date.now();
+                                            }
+                                        }
+                                        catch (error) {
+                                            paneAbsent = false;
+                                            if (!paneReadHeld) {
+                                                paneReadHeld = true;
+                                                journal.append("worker-dead-held", t.id, {
+                                                    slot: slot.name, attempt, reason: "pane-read-unreadable",
+                                                    error: error instanceof Error ? error.message : String(error),
+                                                });
+                                            }
+                                        }
+                                    }
+                                    const worktreeDelta = processTree === "empty"
+                                        && paneAbsent ? await observeWorktreeDelta(taskBase, wt)
+                                        : "unreadable";
+                                    // The first process snapshot can race a just-starting child after the dispatch pane
+                                    // disappeared. Re-read it after the pane and worktree legs have both held: preservation
+                                    // is terminal, so a process appearing in that interval must withdraw the park rather
+                                    // than be orphaned by it. The final worktree recheck remains inside preserveDeadWorker.
+                                    const confirmedProcessTree = worktreeDelta === "unchanged"
+                                        ? await observeWorkerProcessTree(dispatchScript, wt)
+                                        : "unmeasurable";
+                                    const deathCertain = paneAbsent
+                                        && processTree === "empty"
+                                        && confirmedProcessTree === "empty"
+                                        && worktreeDelta === "unchanged";
+                                    if (deathCertain) {
+                                        const preservation = await preserveDeadWorker(wt, taskBase);
+                                        if (!preservation.ref) {
+                                            journal.append("worker-dead-held", t.id, {
+                                                slot: slot.name, attempt, reason: `worktree-${preservation.state}`,
+                                            });
+                                            continue;
+                                        }
+                                        const ref = preservation.ref;
+                                        const reason = `worker is unambiguously dead: pane absent, process tree empty, and worktree unchanged; preserved at ${ref}`;
+                                        deadWorkerPark = { ref, reason };
+                                        journal.append("worktree-preserved", t.id, { ref });
+                                        journal.append("worker-dead-held", t.id, {
+                                            slot: slot.name, attempt, reason: "unambiguous-worker-death", ref,
+                                        });
+                                        break;
+                                    }
                                     // T1 review fix: the kill's "no output growth" leg clocks off the RAW growth signals,
                                     // never lastProgressAt alone — the flat-token rule (stall.ts) deliberately suppresses
                                     // the re-arm report on row growth once tokens stick, and contextTokens is sticky across
@@ -2632,7 +2867,13 @@ export async function runDaemon(repoRoot, opts = {}) {
                                 if (!finished && exitCode === null) {
                                     // timed out (or only ever saw false positives): harvest whatever the pane holds now
                                     timedOut = Date.now() - lastProgressAt >= stallWindowMs;
-                                    output = await driver.read(slot, PANE_READ_ROWS);
+                                    try {
+                                        output = await driver.read(slot, PANE_READ_ROWS);
+                                    }
+                                    catch {
+                                        // The poll loop already recorded the unreadable pane. Retain the last readable bytes
+                                        // so this ambiguous path still reaches the ordinary timeout/consult backstop.
+                                    }
                                     finished = new RegExp(trailerPattern(nonce)).test(output);
                                     const exit = exitRe.exec(output);
                                     exitCode = exit ? Number(exit[1]) : null;
@@ -2766,6 +3007,10 @@ export async function runDaemon(repoRoot, opts = {}) {
                         tokens = addUsage(tokens, attemptUsage);
                         metered++;
                     }
+                    if (deadWorkerPark) {
+                        await park(t, deadWorkerPark.reason, "stall", assignment, attempt + 1, startMs, gateFails, consults, tokens, metered, retryMode, { ref: deadWorkerPark.ref });
+                        return;
+                    }
                     let result = settleParsed ?? adapter.parse(output, nonce);
                     const workerFinished = finished;
                     const workerCause = classifyWorkerResultCause({ output, ok: result.ok, finished, exitCode, summary: result.summary, timedOut, deadChannel: deadChannelKilled });

package/dist/run/journal.d.ts

@@ -29,6 +29,11 @@ export declare const ATTEMPT_CAP_RELEASE: "attempt-cap";
 export declare const GATE_SATISFIED_RELEASE: "gate-satisfied";
 export declare const REVIEW_UPHELD_RELEASE: "review-upheld";
 export declare const RECHECK_RELEASE: "recheck";
+export interface PreservedRef {
+    ref: string;
+    diffCommand: string;
+}
+export declare function preservedRefsByTask(events: JournalEvent[]): Map<string, PreservedRef[]>;
 export declare function reviewRoundsSinceApproval(events: JournalEvent[], taskId: string): number;
 export declare function upheldFeedbackByTask(events: JournalEvent[]): Map<string, string>;
 export interface StructuredFinding {

package/dist/run/journal.js

@@ -2,11 +2,12 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
-import { channelKey, TokenUsageSchema } from "../adapters/types.js";
+import { channelKey, shq, TokenUsageSchema } from "../adapters/types.js";
 import { stateDirName, taskContentDigest, tickmarkrDir } from "../graph/graph.js";
 import { GATE_NAMES, TIERS } from "../graph/schema.js";
 import { buildProfile, classify } from "../route/profile.js";
 import { DecisionEventSchema, trackJournalRows, } from "./protocol.js";
+import { normalizeGateOutcome } from "./outcome.js";
 import { redactSecrets } from "./redact.js";
 export function phaseForGate(gate) {
     if (gate === "acceptance")
@@ -15,6 +16,23 @@ export function phaseForGate(gate) {
         return "review";
     return `gate:${gate}`;
 }
+/** The pipe projects the same normalized gate outcome as the TTY rail. The selected-test field only
+ * chooses the held outcome's operator noun after the accessor has classified it; it is not a second
+ * verdict read. */
+const journalGateDetail = (data) => {
+    if (typeof data.gate !== "string")
+        return undefined;
+    switch (normalizeGateOutcome(data).kind) {
+        case "passed":
+            return `${data.gate} passed`;
+        case "failed":
+            return `${data.gate} failed`;
+        case "held":
+            return Array.isArray(data.selectedTests) ? `${data.gate} selected-test screen` : `${data.gate} held`;
+        default:
+            return data.gate;
+    }
+};
 export function formatJournalNarration({ event, taskId, data }) {
     const assignment = data.assignment;
     const direct = [data.summary, data.reason, data.error, data.step, data.action, data.lint, data.branch, data.from]
@@ -26,7 +44,9 @@ export function formatJournalNarration({ event, taskId, data }) {
                 ? `${data.gate} failed${typeof data.lastMergedTask === "string" ? ` after ${data.lastMergedTask}` : ""}`
                 : event === "tip-verify"
                     ? `${data.gate} passed`
-                    : `${data.gate}${data.pass === true ? " passed" : data.pass === false ? " failed" : ""}`
+                    : event === "gate-result"
+                        ? journalGateDetail(data)
+                        : `${data.gate}`
             : typeof data.code === "number" ? `exit ${data.code}`
                 : typeof data.pid === "number" ? `pid ${data.pid}`
                     : typeof data.baseRef === "string" ? `base ${data.baseRef.slice(0, 12)}`
@@ -56,6 +76,24 @@ export const REVIEW_UPHELD_RELEASE = "review-upheld";
 // so the corrected declaration is the thing that earns the green. Budget semantics match attempt-cap
 // (fresh attempts, tried survives) because the park cost the task its remaining budget.
 export const RECHECK_RELEASE = "recheck";
+// OBS-738: one authority for every recovery surface. The ref is accepted only from the row that
+// preservation itself writes; task-human prose, branch heads and commit history are deliberately
+// absent from this fold. Keep every row in journal order — one task can be recreated more than once,
+// and the terminal record owes the operator every resulting recovery handle, not merely the newest.
+export function preservedRefsByTask(events) {
+    const byTask = new Map();
+    for (const event of events) {
+        if (event.event !== "worktree-preserved" || !event.taskId || typeof event.data.ref !== "string"
+            || event.data.ref === "")
+            continue;
+        const ref = event.data.ref;
+        byTask.set(event.taskId, [
+            ...(byTask.get(event.taskId) ?? []),
+            { ref, diffCommand: `git diff ${shq(`${ref}^!`)}` },
+        ]);
+    }
+    return byTask;
+}
 // OBS-189: review rounds are scoped to the current ENGAGEMENT — the stretch since the newest operator
 // approval for the task. A whole-journal count re-parks an upheld task before its funded attempt can
 // dispatch (measured live on run-20260726-213539), making a fresh journal the only escape. A T15
@@ -1069,19 +1107,36 @@ export class Journal {
             ? undefined
             : DecisionEventSchema.parse({ ...eventOrDecision, ts: new Date().toISOString() });
         const event = decisionRow?.event ?? eventOrDecision;
+        const rowTaskId = decisionRow && "taskId" in decisionRow ? decisionRow.taskId : taskId;
         const inputData = decisionRow?.data ?? data;
+        // OBS-738: terminal and resume records reduce the journal that precedes them. Neither re-derives
+        // recovery facts from task-human prose: preserved refs come from preservedRefsByTask, and the
+        // upheld brief comes from the established prompt/replay reducer.
+        const priorEvents = event === "run-end" || event === "resume-restore" ? this.read() : [];
+        const reducedData = event === "run-end"
+            ? (() => {
+                const preservedRefs = [...preservedRefsByTask(priorEvents)].flatMap(([preservedTaskId, refs]) => refs.map(({ ref, diffCommand }) => ({ taskId: preservedTaskId, ref, diffCommand })));
+                return preservedRefs.length > 0 ? { ...inputData, preservedRefs } : inputData;
+            })()
+            : event === "resume-restore" && rowTaskId && upheldFeedbackByTask(priorEvents).has(rowTaskId)
+                ? {
+                    ...inputData,
+                    upheldFeedbackRestoredFor: rowTaskId,
+                    summary: `upheld feedback restored for ${rowTaskId}`,
+                }
+                : inputData;
         const evidence = judgePersistence.getStore();
         const failed = evidence?.invocations.filter((invocation) => invocation.transcript !== undefined) ?? [];
         const persistedData = event === "judge-retry" && failed.length > 0
             ? {
-                ...inputData,
+                ...reducedData,
                 transcript: failed[0].transcript,
                 ...(failed[1] ? { retryTranscript: failed[1].transcript } : {}),
             }
-            : inputData;
-        const row = decisionRow ?? {
-            ts: new Date().toISOString(), event, ...(taskId ? { taskId } : {}), data: persistedData,
-        };
+            : reducedData;
+        const row = decisionRow
+            ? { ...decisionRow, data: persistedData }
+            : { ts: new Date().toISOString(), event, ...(taskId ? { taskId } : {}), data: persistedData };
         // T3 secret redaction: only the persisted bytes are masked — the caller's data stays untouched in
         // memory. The narrator receives the persisted (masked) row so a pane sink never shows a credential.
         const line = redactSecrets(JSON.stringify(row));

package/dist/run/outcome.js

@@ -88,7 +88,14 @@ export function normalizeGateOutcome(source) {
         return { kind: "unavailable", reason: `malformed gate result: expected an object, read ${shape}` };
     }
     const row = source;
-    // `kind` selects the canonical format. It must validate as exactly one canonical arm without any
+    // A gate-result data wrapper states its canonical verdict in `outcome`. Consumers may pass either
+    // the wrapper or the outcome itself; both must read the same kind even if stale bare fields remain.
+    if (hasOwn(row, "outcome")) {
+        if (isGateOutcome(row.outcome))
+            return row.outcome;
+        return { kind: "unavailable", reason: reasonOf(row, "malformed gate result: invalid explicit outcome") };
+    }
+    // `kind` selects the canonical outcome object. It must validate as exactly one canonical arm without any
     // legacy truth discriminator; otherwise continuing through the legacy branches could reinterpret a
     // contradictory dual-write as passed, failed or infra. Mixed and malformed canonical rows stay
     // explicitly unavailable, retaining any reason/details the producer did manage to state.

package/dist/run/supervision.d.ts

@@ -3,6 +3,8 @@ export declare const SUPERVISION_BEAT_MS = 10000;
 /** Ceiling before a beat reads STALE: SIX beats, lock.ts's ratio — five may be missed before alarm. */
 export declare const SUPERVISION_STALE_MS: number;
 export declare const SUPERVISION_FUTURE_GRACE_MS = 1000;
+/** Context watchers act at 75% unless their invocation declares another threshold. */
+export declare const SUPERVISION_DEFAULT_THRESHOLD_PCT = 75;
 export declare const SUPERVISION_TIERS: readonly ["orchestrator", "orchestrator-context", "overseer", "overseer-context", "watch"];
 export type SupervisionTier = (typeof SUPERVISION_TIERS)[number];
 export declare const SUPERVISION_SEAT_TIERS: readonly ["orchestrator", "orchestrator-context", "overseer", "overseer-context"];
@@ -17,16 +19,28 @@ export interface TierLiveness {
     beatAgeMs?: number;
     /** The seat the record names, when it names one. Always present on a seat tier that is not ABSENT. */
     seat?: string;
+    /** The alarm's durable duty, orthogonal to whether its watcher is armed, stale or stood down. */
+    clearOwedSince?: string;
+    /** The latch exists but cannot be decoded; never mistaken for no duty owed. */
+    clearOwedUnreadable?: true;
+}
+/** A watcher observation that can raise or discharge the seat's clear obligation. */
+export interface SupervisionBeatObservation {
+    armId: string;
+    pct: number;
+    thresholdPct: number;
 }
 export declare const supervisionBeatPath: (repoRoot: string, tier: SupervisionTier) => string;
 /** Where a watcher records that it STOOD DOWN. Its own file: the beat keeps meaning only "alive". */
 export declare const supervisionStandDownPath: (repoRoot: string, tier: SupervisionTier) => string;
-export declare function beatSupervision(repoRoot: string, tier: SupervisionTier, seat?: string): void;
+export declare function beatSupervision(repoRoot: string, tier: SupervisionTier, seat?: string, observation?: SupervisionBeatObservation): void;
 /** Handle a watcher holds for as long as it is supervising; disarm stands it down and is idempotent. */
 export interface ArmedSupervision {
     disarm: () => void;
 }
 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. */
+export declare function armWatchSupervision(repoRoot: string, beatMs?: number): ArmedSupervision;
 export declare function readTierLiveness(repoRoot: string, tier: SupervisionTier, now?: number): TierLiveness;
 export declare function supervisionStatus(repoRoot: string, tier: SupervisionTier, now?: number): TierLiveness;
 /** Every KNOWN tier, always — a tier omitted from this list would read as one that is fine. */