@tiphys/kernel 0.0.0 → 0.2.0

package/dist/src/watcher.js

@@ -0,0 +1,849 @@
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, fsyncSync, openSync, renameSync, statSync, unlinkSync, watch, writeFileSync, writeSync, } from "node:fs";
+import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { CADENCE, readBeacon, renderBeacon, surveyTaskRecords, } from "./liveness.js";
+import { classifyEntry, executorRecordPath, readRegularFileIfPresent, refuseOpenForWrite, runStep, runStepAsync, turnEndPath, } from "./task.js";
+/**
+ * The watcher (kernel plan v1, M1-P5 step 1; R-078, R-079; DR-0007;
+ * plan constraints C-1, C-2 and C-3).
+ *
+ * ONE CORE, TWO ENTRY MODES (DR-0007). Resident mode (tiphys watch) is a
+ * plain foreground process the caller owns. Single-pass mode (tiphys
+ * watch --once) performs exactly one evaluation of the same wake sources
+ * and exits, for external triggers on reclaimable substrates. Both modes
+ * run the same evaluation function over the same on-disk state; there is
+ * no adapter and no second implementation.
+ *
+ * C-3, and why there is nothing here to guard: the kernel never runs a
+ * watcher outside the caller's own foreground process. No flag exists
+ * that would make it outlive its caller, this module launches no child
+ * process of any kind, and arming is explicit: the operator starts it
+ * and the beacon is what proves it ran (FM-054, where about 30 minutes
+ * of supervision were lost to a shell that helpfully moved one out of
+ * sight).
+ *
+ * C-2: nothing here has any notion of a running program. Wake sources
+ * are FILES, currency comes from files, and the only clock question ever
+ * asked is "is this timestamp older than that one".
+ *
+ * C-1: task currency is read from tasks/<id>/meta.json status and the
+ * turn-end file, never from a log tail. state/last-wake.json is written
+ * and never read back by any code path in this kernel; deleting it or
+ * filling it with garbage changes no decision this module makes.
+ *
+ * REASON LINES (grammar harvested from firstmate, FM-002):
+ *
+ *   signal <task-id> turn-end   a turn-end file appeared for an open task
+ *   stale <task-id> deadline    an open task passed its executor.json
+ *                               deadline with no turn-end (PR-207)
+ *   check <name>                a one-shot check was requested through
+ *                               state/check-request
+ *   heartbeat <n>               the nth heartbeat since the last reset
+ *
+ * A wake is ONE line on stdout and then exit 0. The watcher surfaces
+ * wakes and never classifies, triages or absorbs them (FM-057:
+ * firstmate's absorb-triage grew to most of its 1126 lines because its
+ * completion signals were weak; a proposal to add classification here is
+ * a signal-design red flag, not a feature request).
+ *
+ * THE STALE ENUMERATION, and why it has exactly two entries in M1. The
+ * plan's grammar is "stale <what>" for "an open task whose worktree or
+ * meta is in a contradictory state, enumerated in the module docs", and
+ * PR-207 names the first entry:
+ *
+ *   stale <task-id> deadline   the executor record's deadline passed and
+ *                              no turn-end arrived (PR-207)
+ *   stale <task-id> meta       tasks/<id>/meta.json EXISTS and does not
+ *                              parse, so this module cannot establish
+ *                              whether the task is open (fix round,
+ *                              second reviewer finding 2)
+ *
+ * The second entry is the plan's own "meta is in a contradictory state"
+ * clause, not an invention: a record that exists and cannot be read is
+ * the one case where staying quiet would mean asserting "nothing to
+ * supervise here" from evidence this module does not have. A task
+ * directory with NO meta.json at all is a different thing (a spawn in
+ * progress or a rollback residue) and is not surfaced.
+ *
+ * Tuition T-002 asked for "task open, no turn-end, worktree dirty" as a
+ * wake condition; the declared-deadline half of that is what this module
+ * detects, from file evidence alone, and it is witnessed against a spawn
+ * that was genuinely stopped mid-payload rather than against a
+ * hand-built file state. The deadline-less half is not invented here,
+ * because the plan's own not-proven list states that abandonment of a
+ * task launched WITHOUT a deadline is not auto-detected in M1.
+ *
+ * WHAT AN EVALUATION IS, and why it matters for the beacon (PR-206,
+ * PR-009). An EVALUATION is a pass over the wake sources that also
+ * rewrites state/watcher.beacon: it happens when a resident watcher
+ * starts, on every heartbeat tick, whenever a wake is surfaced, and on
+ * every watch --once pass including a no-wake one. Between heartbeats a
+ * resident watcher SCANS its wake sources every poll interval (and
+ * immediately on a filesystem change); a scan that surfaces nothing
+ * writes nothing. That is what makes the beacon mean "supervision
+ * executed on schedule" rather than "a process is alive", and it is what
+ * puts the oldest healthy beacon age at one backoff cap plus one poll
+ * interval, which is the bound the guard's threshold has to clear
+ * (PR-009, enforced in src/liveness.ts).
+ *
+ * CADENCE LIVES ON DISK (FM-006, FM-045), never in process memory, so a
+ * resident restart and a single pass share one schedule:
+ * state/watcher.cadence.json holds {lastHeartbeatAt, backoffStreak}. On
+ * a virgin fleet the first evaluation initializes it to the current time
+ * and surfaces no heartbeat; the first heartbeat falls due one base
+ * interval later (PR-205).
+ *
+ * Turn-end currency (PR-204). A turn-end wake is surfaced at most once
+ * across both modes. state/watcher.seen.json records, per task, the
+ * identity of the last surfaced turn-end (size, modification time and a
+ * content signature, FM-005). The record is advanced under a claim file,
+ * written stage-then-rename and confirmed by reading it back, which is
+ * the discipline src/lock.ts established (it is mirrored rather than
+ * reused: the lock's primitive is lease-shaped and src/lock.ts is not in
+ * this phase's edit scope). The wake is appended to state/last-wake.json
+ * BEFORE the seen record advances (enqueue-before-suppress, FM-046: a
+ * stop between the two duplicates a wake rather than dropping it). Two
+ * passes racing on the same turn-end therefore resolve to exactly one
+ * surfacing; the loser reports no-wake.
+ *
+ * NO HEALTH FROM AN ABSENCE OF EVIDENCE (fix round, the property both
+ * reviewers' blocking findings share). Silence from this module means
+ * "there is nothing to surface", and it may only be said about states
+ * this module has POSITIVELY ESTABLISHED. Wherever it cannot establish
+ * one, the output is the loud one, never the quiet one:
+ *
+ *   - a seen-state claim it could not take within the bounded wait is a
+ *     STUCK CLAIM, not ordinary contention: nonzero exit, one reason
+ *     line naming the file, and NO beacon write, so the guard sees
+ *     supervision stop. This is src/lock.ts's rule, adopted verbatim
+ *     rather than reinvented (see the note below).
+ *   - a meta.json that exists and does not parse is surfaced as
+ *     "stale <task-id> meta" rather than skipped.
+ *   - any other raise ends the pass loudly (see the classification
+ *     below).
+ *
+ * WHERE THE STUCK-CLAIM RULE COMES FROM, recorded because it should have
+ * reached this module the first time and did not: src/lock.ts's
+ * applyLeaseMutation has used the identical O_EXCL claim-file pattern
+ * since M1-P3, and its module doc (src/lock.ts, "No steal protocol
+ * exists on purpose (FM-058)") states the rule this module now follows:
+ * a claim file left behind by a mutation that stopped makes later
+ * mutations FAIL LOUDLY after a bounded wait, naming the file for manual
+ * removal, and no code ever breaks someone else's claim. That behavior
+ * was established by M1-P3's CR-204 after the U-2 race investigation
+ * (delivery/verification/u2-race-flake-investigation.md,
+ * delivery/review/clean-room-m1-p3.md). The first draft of this module
+ * copied the mechanism and dropped the loudness, which the second
+ * M1-P5 reviewer reproduced as a permanent, silent loss of every future
+ * turn-end wake. Anyone adding a third claim-file user should read
+ * src/lock.ts first.
+ *
+ * HOW A RAISED ERROR IS CLASSIFIED, decided once and applied
+ * structurally, because this module does filesystem work in a loop and
+ * the previous phase's two worst defects were raises walking past
+ * handlers that only understood returned failures (M1-P4 F-1 and F-2):
+ *
+ *   - A file that is ABSENT is not an error. Task directories appear and
+ *     vanish under a concurrent teardown, so every read of task state
+ *     goes through a helper that turns ENOENT into "not there" and
+ *     rethrows everything else.
+ *   - Any OTHER raise ends the pass with a reason line and a nonzero
+ *     exit. The watcher stops loudly instead of looping blind: a stopped
+ *     watcher stops advancing the beacon, and the liveness guard then
+ *     tells the operator on the next spawn, teardown or doctor.
+ *   - The whole pass is wrapped by runStep (src/task.ts), so this holds
+ *     for every site in it without depending on remembering it at each.
+ */
+/** Exit code of a --once pass that found nothing actionable. */
+export const NO_WAKE_EXIT = 3;
+/** Wake-source and cadence state files, all under the fleet's state/. */
+export const CADENCE_STATE_FILE = join("state", "watcher.cadence.json");
+export const SEEN_STATE_FILE = join("state", "watcher.seen.json");
+export const LAST_WAKE_FILE = join("state", "last-wake.json");
+export const CHECK_REQUEST_FILE = join("state", "check-request");
+export function cadencePath(fleet) {
+    return join(fleet.root, CADENCE_STATE_FILE);
+}
+export function seenPath(fleet) {
+    return join(fleet.root, SEEN_STATE_FILE);
+}
+export function lastWakePath(fleet) {
+    return join(fleet.root, LAST_WAKE_FILE);
+}
+export function checkRequestPath(fleet) {
+    return join(fleet.root, CHECK_REQUEST_FILE);
+}
+/**
+ * Absent is not an error; anything else is (see the module docs).
+ *
+ * The read goes through readRegularFileIfPresent (src/task.ts), so the
+ * path's TYPE is established before anything is opened. Every wake source
+ * and every cadence file this module reads arrives here, and each of them
+ * used to block forever on a named pipe: turn-end, executor.json,
+ * check-request, watcher.seen.json and watcher.cadence.json, five of the
+ * paths CR-520 measured. The loud behavior is unchanged in kind, a
+ * nonzero exit with one reason line, and the line now NAMES THE PATH,
+ * which the raw EISDIR it replaces did not.
+ */
+function readIfPresent(path) {
+    const read = readRegularFileIfPresent(path);
+    if (read.kind === "absent") {
+        return undefined;
+    }
+    if (read.kind === "refused") {
+        throw new Error(read.reason);
+    }
+    return read.body;
+}
+function statIfPresent(path) {
+    try {
+        return statSync(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+export function sameIdentity(a, b) {
+    return a.size === b.size && a.mtimeMs === b.mtimeMs && a.signature === b.signature;
+}
+function identityOf(path) {
+    const stats = statIfPresent(path);
+    if (stats === undefined) {
+        return undefined;
+    }
+    const body = readIfPresent(path);
+    if (body === undefined) {
+        return undefined;
+    }
+    return {
+        size: stats.size,
+        mtimeMs: stats.mtimeMs,
+        signature: createHash("sha256").update(body).digest("hex"),
+    };
+}
+export function readSeenState(fleet) {
+    const raw = readIfPresent(seenPath(fleet));
+    if (raw === undefined) {
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        // A seen file that does not parse is treated as empty: the cost is a
+        // duplicated wake, and the alternative (refusing to surface) would
+        // lose one. Duplicate rather than drop is this phase's standing rule
+        // (FM-046).
+        return {};
+    }
+    if (parsed === null || typeof parsed !== "object") {
+        return {};
+    }
+    const out = {};
+    for (const [taskId, value] of Object.entries(parsed)) {
+        const candidate = value;
+        if (typeof candidate.size === "number" &&
+            typeof candidate.mtimeMs === "number" &&
+            typeof candidate.signature === "string") {
+            out[taskId] = {
+                size: candidate.size,
+                mtimeMs: candidate.mtimeMs,
+                signature: candidate.signature,
+            };
+        }
+    }
+    return out;
+}
+export function readCadenceState(fleet) {
+    const raw = readIfPresent(cadencePath(fleet));
+    if (raw === undefined) {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    const candidate = parsed;
+    if (typeof candidate.lastHeartbeatAt !== "string" ||
+        Number.isNaN(Date.parse(candidate.lastHeartbeatAt)) ||
+        typeof candidate.backoffStreak !== "number" ||
+        !Number.isFinite(candidate.backoffStreak) ||
+        candidate.backoffStreak < 0) {
+        return undefined;
+    }
+    return { lastHeartbeatAt: candidate.lastHeartbeatAt, backoffStreak: candidate.backoffStreak };
+}
+export function writeCadenceState(fleet, state) {
+    atomicWrite(cadencePath(fleet), `${JSON.stringify(state, null, 2)}\n`);
+}
+/** The doubling heartbeat interval, capped (FM-044). */
+export function intervalMsFor(streak, cadence) {
+    const exponent = Math.min(streak, 52);
+    const raw = cadence.baseIntervalMs * 2 ** exponent;
+    return Math.min(raw, cadence.backoffCapMs);
+}
+/** When the next heartbeat falls due, from on-disk state alone. */
+export function nextHeartbeatDueMs(state, cadence) {
+    return Date.parse(state.lastHeartbeatAt) + intervalMsFor(state.backoffStreak, cadence);
+}
+/**
+ * Write a file through a staged rename, so a reader (doctor, the guard,
+ * another pass) never sees a half-written state file.
+ *
+ * THE DESTINATION IS PROBED (fix round 4). rename(2) would silently
+ * replace a non-regular entry at the destination. That is not a block, but
+ * it is a SILENT SUCCESS where a directory at the same path is loud
+ * (rename refuses that one), and this module's rule is that an unexpected
+ * entry under state/ is reported rather than absorbed. Absent is fine:
+ * creating the file is the point.
+ *
+ * THE STAGE PATH IS UNIQUE PER WRITE, and that is a defect fix rather than
+ * a tidy-up (fix round 4). It used to be `${path}.stage`, a fixed name, so
+ * two passes writing the same state file raced on one temporary: both
+ * wrote it, the first renamed it away, and the second's rename failed with
+ * a raw ENOENT. Measured on this phase's head before this round, with two
+ * single passes released together onto one pending turn-end: the pass that
+ * had ALREADY advanced the seen state died on its beacon write before
+ * cmdWatch printed anything, and the other reported no-wake, so the wake
+ * was suppressed forever and NEITHER pass surfaced it. That is a drop
+ * where the plan's whole surfacing protocol is built to duplicate rather
+ * than drop (PR-204, FM-046), and it is criterion 7's own failure state.
+ *
+ * A unique name removes the contention instead of guarding it: two passes
+ * now stage into different files and rename(2) settles the order, which is
+ * what makes the write atomic in the first place. The name comes from
+ * randomUUID and deliberately NOT from any process identifier: plan
+ * constraint C-2 bars those, criterion 14 greps these sources for one, and
+ * a temporary filename must not be the one place it turns up. It also
+ * means nothing can pre-plant an entry at a stage path, so the write-side
+ * blocking hazard is eliminated at that path rather than classified there.
+ */
+function atomicWrite(path, body) {
+    const refusedTarget = refuseOpenForWrite(path);
+    if (refusedTarget !== undefined) {
+        throw new Error(`the state file could not be rewritten: ${refusedTarget}`);
+    }
+    const stage = `${path}.${randomUUID()}.stage`;
+    writeFileSync(stage, body);
+    try {
+        renameSync(stage, path);
+    }
+    catch (error) {
+        // A unique stage name is invisible to any cleanup, so this pass owns
+        // removing its own leavings before it reports the failure.
+        try {
+            unlinkSync(stage);
+        }
+        catch {
+            // Already gone; nothing to clean.
+        }
+        throw error;
+    }
+}
+/**
+ * Rewrite the beacon. The timestamp STRICTLY increases even when two
+ * evaluations land in the same millisecond, because criterion 8 turns on
+ * a no-wake pass advancing it and "advanced" has to mean something a
+ * reader can compare.
+ */
+export function writeBeacon(fleet, nowMs, streak, cadence) {
+    const previous = readBeacon(fleet.beaconPath);
+    const previousMs = previous === undefined ? undefined : Date.parse(previous.writtenAt);
+    const stampMs = previousMs === undefined || nowMs > previousMs ? nowMs : previousMs + 1;
+    atomicWrite(fleet.beaconPath, renderBeacon({
+        writtenAt: new Date(stampMs).toISOString(),
+        backoffStreak: streak,
+        intervalMs: intervalMsFor(streak, cadence),
+    }));
+    return stampMs;
+}
+export function wakeLine(wake) {
+    if (wake.kind === "signal") {
+        return `signal ${wake.taskId} ${wake.event}`;
+    }
+    if (wake.kind === "stale") {
+        return `stale ${wake.taskId} ${wake.what}`;
+    }
+    return `check ${wake.name}`;
+}
+export function heartbeatLine(n) {
+    return `heartbeat ${String(n)}`;
+}
+/** The executor launch record, as far as this module reads it (PR-207). */
+function deadlineOf(fleet, taskId) {
+    const raw = readIfPresent(executorRecordPath(fleet, taskId));
+    if (raw === undefined) {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    const deadline = parsed.deadline;
+    if (typeof deadline !== "string") {
+        return undefined;
+    }
+    const ms = Date.parse(deadline);
+    return Number.isNaN(ms) ? undefined : ms;
+}
+/**
+ * One scan of the wake sources, in the grammar's own priority order:
+ * turn-end signals first, then stale conditions, then a requested check.
+ * Task ids are visited in sorted order so two passes over the same fleet
+ * choose the same wake.
+ *
+ * Stale conditions are NOT suppressed by the seen-state, and that is
+ * deliberate: PR-204's at-most-once rule is about turn-end EDGES, while
+ * a passed deadline with no turn-end is a standing condition that stays
+ * true until an operator acts on it. Reporting it again on the next pass
+ * is the correct behavior for something nobody has dealt with yet.
+ */
+function scanUnsafe(fleet, nowMs) {
+    // ONE classifier of task records, shared with the liveness guard
+    // (src/liveness.ts surveyTaskRecords). This module does not carry a
+    // second opinion about what a task record is or about what an
+    // unreadable one means: two implementations of one property disagreed
+    // once already (delta review NEW-1, tuition T-005).
+    const survey = surveyTaskRecords(fleet);
+    const problem = survey.problems[0];
+    if (problem !== undefined) {
+        // A survey that did not complete is not an idle fleet. Raising here
+        // reaches runStep, which turns it into the module's loud outcome: a
+        // nonzero exit with one reason line, and no beacon write.
+        throw new Error(problem);
+    }
+    const open = survey.open;
+    const seen = readSeenState(fleet);
+    for (const id of open) {
+        const identity = identityOf(turnEndPath(fleet, id));
+        if (identity === undefined) {
+            continue;
+        }
+        const previous = seen[id];
+        if (previous !== undefined && sameIdentity(previous, identity)) {
+            continue;
+        }
+        return { kind: "signal", taskId: id, event: "turn-end", identity };
+    }
+    for (const id of open) {
+        if (statIfPresent(turnEndPath(fleet, id)) !== undefined) {
+            continue;
+        }
+        const deadlineMs = deadlineOf(fleet, id);
+        if (deadlineMs !== undefined && deadlineMs <= nowMs) {
+            return { kind: "stale", taskId: id, what: "deadline" };
+        }
+    }
+    const firstUnreadable = survey.unreadable[0];
+    if (firstUnreadable !== undefined) {
+        return { kind: "stale", taskId: firstUnreadable, what: "meta" };
+    }
+    const request = statIfPresent(checkRequestPath(fleet));
+    if (request !== undefined) {
+        return { kind: "check", name: "requested" };
+    }
+    return undefined;
+}
+/** Scan, with the module's raise classification applied structurally. */
+export function scanWakeSources(fleet, nowMs) {
+    const scanned = runStep("scanning the watcher wake sources", () => scanUnsafe(fleet, nowMs));
+    if (!scanned.ok) {
+        return { ok: false, reason: scanned.reason };
+    }
+    return { ok: true, wake: scanned.value };
+}
+/**
+ * Durably append one wake record, one JSON object per line (JSON per
+ * DR-0006; the line framing is what makes an append safe without a
+ * read-modify-write of the whole file). The plan fixes the file's name
+ * and its append discipline, not its internal framing; this is the
+ * choice, recorded rather than assumed.
+ *
+ * NOTHING IN THIS KERNEL READS THIS FILE (plan constraint C-1). It is a
+ * durability record for a human and for later milestones, never a source
+ * of currency: currency comes from meta.json, the turn-end file, the
+ * executor record and the seen state.
+ *
+ * WHAT ENQUEUE-BEFORE-SUPPRESS THEREFORE DOES AND DOES NOT BUY (CR-522,
+ * recorded rather than fixed). FM-046 and the plan put this append BEFORE
+ * the seen-state advance so a stop between the two duplicates a wake
+ * rather than dropping it. The at-most-once guarantee is real and is
+ * delivered by the seen state. The DURABILITY half is weaker than it
+ * reads: because nothing reads this file, no code path can restore a wake
+ * from it, and the channel that actually delivers a wake to a consumer is
+ * stdout, written by cmdWatch AFTER claimSignal has already advanced the
+ * seen state and released the claim. A stop inside that window suppresses
+ * the wake permanently, for every later pass and both modes, and the guard
+ * goes on reporting the fleet fresh. The window is small and closing it
+ * means printing inside the claim, which changes the surfacing protocol
+ * the plan fixes; it is carried as an M2 item, not improvised here.
+ */
+function appendWakeRecord(fleet, nowMs, line) {
+    const record = `${JSON.stringify({ at: new Date(nowMs).toISOString(), line })}\n`;
+    // Probed before it is opened, for the same reason every read here is
+    // (fix round 4). openSync with "a" is O_WRONLY|O_APPEND|O_CREAT, and on
+    // a named pipe with no reader that BLOCKS. This path is reached only
+    // when a wake is being surfaced, which is why the earlier round's probe
+    // of state/ files missed it, and blocking here hangs the watcher with a
+    // real pending signal, in both modes.
+    const refused = refuseOpenForWrite(lastWakePath(fleet));
+    if (refused !== undefined) {
+        throw new Error(`the wake record could not be appended: ${refused}`);
+    }
+    const handle = openSync(lastWakePath(fleet), "a");
+    try {
+        writeSync(handle, record);
+        fsyncSync(handle);
+    }
+    finally {
+        closeSync(handle);
+    }
+}
+const CLAIM_WAIT_TOTAL_MS = 5000;
+const CLAIM_WAIT_POLL_MS = 5;
+/**
+ * Deterministic interleave seam for the concurrency witness, modelled on
+ * the one src/commands/lock.ts already carries. When
+ * TIPHYS_WATCH_TEST_HOLD names a barrier path, a pass that has DECIDED to
+ * surface a turn-end writes <barrier>.observed and then waits for
+ * <barrier> to appear before it touches the seen state, so a test can
+ * place a second pass exactly inside the window. It is LOUD when it does
+ * not actually hold (the M1-P3 lesson): the wait is monotonic and a
+ * timeout raises rather than continuing with a stale observation, which
+ * is how a witness scores an interleave it never staged.
+ */
+const HOLD_WAIT_LIMIT_MS = 30_000;
+async function maybeHoldForTest() {
+    const barrier = process.env.TIPHYS_WATCH_TEST_HOLD;
+    if (barrier === undefined || barrier === "") {
+        return;
+    }
+    writeFileSync(`${barrier}.observed`, "");
+    const startNs = process.hrtime.bigint();
+    for (;;) {
+        if (statIfPresent(barrier) !== undefined) {
+            writeFileSync(`${barrier}.released`, "barrier appeared\n");
+            return;
+        }
+        const elapsedMs = Number(process.hrtime.bigint() - startNs) / 1e6;
+        if (elapsedMs >= HOLD_WAIT_LIMIT_MS) {
+            writeFileSync(`${barrier}.released`, "timed out without holding\n");
+            throw new Error(`watcher test hold at ${barrier} timed out after ` +
+                `${String(Math.round(elapsedMs))}ms: the interleave was never staged`);
+        }
+        await sleep(CLAIM_WAIT_POLL_MS);
+    }
+}
+/**
+ * Advance the seen state for one surfaced turn-end, under a claim file,
+ * stage-then-rename, confirmed by reading it back. "lost" means another
+ * pass got there first, which is the loser's cue to report no-wake
+ * (PR-204). "stuck" means the claim could not be taken at all.
+ */
+async function claimSignal(fleet, taskId, identity, nowMs, line) {
+    const claimPath = `${seenPath(fleet)}.mutex`;
+    const deadline = Date.now() + CLAIM_WAIT_TOTAL_MS;
+    for (;;) {
+        try {
+            writeFileSync(claimPath, "", { flag: "wx" });
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST") {
+                throw error;
+            }
+            if (Date.now() >= deadline) {
+                // Whether another pass is inside the window right now or one
+                // stopped inside it, this pass cannot establish anything about
+                // this wake, so it says so instead of reporting quiet. No steal
+                // protocol: the file is named for a human to remove, exactly as
+                // src/lock.ts does, and nothing here breaks someone else's claim.
+                return {
+                    kind: "stuck",
+                    reason: `supervision is stuck: the seen-state claim ${claimPath} was still ` +
+                        `present after ${String(CLAIM_WAIT_TOTAL_MS)}ms, so the turn-end of ` +
+                        `task ${taskId} could not be surfaced and no wake was reported; if no ` +
+                        `other watcher is running, remove that file and re-run`,
+                };
+            }
+            await sleep(CLAIM_WAIT_POLL_MS);
+        }
+    }
+    try {
+        const current = readSeenState(fleet);
+        const previous = current[taskId];
+        if (previous !== undefined && sameIdentity(previous, identity)) {
+            return { kind: "lost" };
+        }
+        // Enqueue before suppress (FM-046): the wake record is durable
+        // before anything can suppress the wake.
+        appendWakeRecord(fleet, nowMs, line);
+        const next = { ...current, [taskId]: identity };
+        atomicWrite(seenPath(fleet), `${JSON.stringify(next, null, 2)}\n`);
+        const confirmed = readSeenState(fleet)[taskId];
+        if (confirmed === undefined || !sameIdentity(confirmed, identity)) {
+            return { kind: "lost" };
+        }
+        return { kind: "won" };
+    }
+    finally {
+        try {
+            unlinkSync(claimPath);
+        }
+        catch {
+            // Already gone; nothing to release.
+        }
+    }
+}
+/**
+ * Take the one-shot check request, atomically: the rename is the
+ * exclusion, so two racing passes cannot both surface one request.
+ *
+ * PROBE BEFORE THE RENAME, not just before the read (CR-520). The rename
+ * is DESTRUCTIVE of the wake source: it is the exclusion mechanism, so by
+ * design nothing else can find the request afterwards. Reading second and
+ * probing third meant that a named pipe at state/check-request was first
+ * consumed and then blocked forever, so the fleet lost its wake source AND
+ * reported nothing. Ordering the probe first means a request this pass
+ * cannot consume is left exactly where an operator can see it, and the
+ * pass says so out loud instead.
+ */
+function claimCheckRequest(fleet) {
+    const path = checkRequestPath(fleet);
+    const taken = `${path}.taken`;
+    const entry = classifyEntry(path);
+    if (entry.kind === "irregular" || entry.kind === "unexaminable") {
+        throw new Error(`the check request could not be taken and was left in place: ${entry.reason}`);
+    }
+    try {
+        renameSync(path, taken);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+    const body = readIfPresent(taken) ?? "";
+    try {
+        unlinkSync(taken);
+    }
+    catch {
+        // Best effort: the request has already been taken by this pass.
+    }
+    const name = body.trim().split("\n")[0] ?? "";
+    return name === "" ? "unnamed" : name;
+}
+/**
+ * Surface a wake: make it durable, suppress repeats where the plan says
+ * repeats are wrong, and return the line to print. "lost" means another
+ * pass owns this wake and this one must report no-wake; "stuck" means
+ * this pass could not establish anything and must say so out loud.
+ */
+export async function surfaceWake(fleet, wake, nowMs) {
+    const line = wakeLine(wake);
+    if (wake.kind === "signal") {
+        await maybeHoldForTest();
+        const claimed = await claimSignal(fleet, wake.taskId, wake.identity, nowMs, line);
+        if (claimed.kind === "won") {
+            return { kind: "surfaced", line };
+        }
+        if (claimed.kind === "stuck") {
+            return { kind: "stuck", reason: claimed.reason };
+        }
+        return { kind: "lost" };
+    }
+    if (wake.kind === "check") {
+        const name = claimCheckRequest(fleet);
+        if (name === undefined) {
+            return { kind: "lost" };
+        }
+        const named = wakeLine({ kind: "check", name });
+        appendWakeRecord(fleet, nowMs, named);
+        return { kind: "surfaced", line: named };
+    }
+    appendWakeRecord(fleet, nowMs, line);
+    return { kind: "surfaced", line };
+}
+/** Read cadence state, initializing a virgin fleet in place (PR-205). */
+function loadOrInitCadence(fleet, nowMs) {
+    const existing = readCadenceState(fleet);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const fresh = {
+        lastHeartbeatAt: new Date(nowMs).toISOString(),
+        backoffStreak: 0,
+    };
+    writeCadenceState(fleet, fresh);
+    return fresh;
+}
+/**
+ * Scan and, if there is something to surface, surface it. Returns
+ * undefined ONLY when nothing was surfaced and that is a fact this pass
+ * established: no wake pending, or a wake another live pass owns. A
+ * stuck claim returns a loud outcome instead, and the beacon is written
+ * ONLY when a wake is surfaced (see the module docs on what an
+ * evaluation is, and on health from an absence of evidence).
+ */
+async function scanAndSurface(fleet, options, nowMs) {
+    const scanned = scanWakeSources(fleet, nowMs);
+    if (!scanned.ok) {
+        return { code: 1, line: "", reason: scanned.reason };
+    }
+    const wake = scanned.wake;
+    if (wake === undefined) {
+        return undefined;
+    }
+    const surfaced = await runStepAsync("surfacing the wake", () => surfaceWake(fleet, wake, nowMs));
+    if (!surfaced.ok) {
+        return { code: 1, line: "", reason: surfaced.reason };
+    }
+    const result = surfaced.value;
+    if (result.kind === "stuck") {
+        // Loud, and deliberately WITHOUT a beacon write: supervision did not
+        // execute, so the beacon must be allowed to go stale and the guard
+        // must be allowed to notice.
+        return { code: 1, line: "", reason: result.reason };
+    }
+    if (result.kind === "lost") {
+        return undefined;
+    }
+    // Any surfaced non-heartbeat wake resets the backoff (plan step 1).
+    writeCadenceState(fleet, {
+        lastHeartbeatAt: new Date(nowMs).toISOString(),
+        backoffStreak: 0,
+    });
+    writeBeacon(fleet, nowMs, 0, options.cadence);
+    return { code: 0, line: result.line };
+}
+/**
+ * A heartbeat evaluation: advance the streak, record it, rewrite the
+ * beacon. Returns the heartbeat ordinal since the last cadence reset,
+ * which is the n in "heartbeat <n>".
+ */
+export function heartbeatTick(fleet, state, cadence, nowMs) {
+    // CR-505: the ordinal is recomputed from the cadence file, never from
+    // the caller's snapshot. A resident watcher reads the cadence before
+    // its wait and ticks after it, so a concurrent single pass that reset
+    // the backoff inside that window would otherwise have its reset
+    // overwritten by snapshot + 1.
+    const current = readCadenceState(fleet) ?? state;
+    const n = current.backoffStreak + 1;
+    writeCadenceState(fleet, {
+        lastHeartbeatAt: new Date(nowMs).toISOString(),
+        backoffStreak: n,
+    });
+    writeBeacon(fleet, nowMs, n, cadence);
+    return n;
+}
+/**
+ * Single-pass mode: exactly one evaluation, then exit. A heartbeat that
+ * is due is surfaced (this pass may be the only supervision this fleet
+ * gets), and a pass with nothing actionable prints nothing and exits
+ * with the documented no-wake code. The beacon is rewritten either way
+ * (PR-206).
+ */
+export async function runOnce(fleet, options) {
+    const nowMs = (options.now ?? Date.now)();
+    const state = loadOrInitCadence(fleet, nowMs);
+    const surfaced = await scanAndSurface(fleet, options, nowMs);
+    if (surfaced !== undefined) {
+        return surfaced;
+    }
+    if (nowMs >= nextHeartbeatDueMs(state, options.cadence)) {
+        const n = heartbeatTick(fleet, state, options.cadence, nowMs);
+        appendWakeRecord(fleet, nowMs, heartbeatLine(n));
+        return { code: 0, line: heartbeatLine(n) };
+    }
+    writeBeacon(fleet, nowMs, state.backoffStreak, options.cadence);
+    return { code: NO_WAKE_EXIT, line: "" };
+}
+/**
+ * Wait for a filesystem change under the fleet's state/ and tasks/, or
+ * for the timeout, whichever comes first. Watching is an optimization
+ * over the poll interval, so a platform that cannot watch simply waits.
+ */
+async function waitForChange(fleet, timeoutMs) {
+    const watchers = [];
+    let resolveChange;
+    const changed = new Promise((resolve) => {
+        resolveChange = resolve;
+    });
+    const onEvent = () => {
+        resolveChange?.();
+    };
+    for (const [dir, recursive] of [
+        [fleet.stateDir, false],
+        [fleet.tasksDir, true],
+    ]) {
+        try {
+            const handle = watch(dir, { recursive }, onEvent);
+            handle.on("error", onEvent);
+            watchers.push(handle);
+        }
+        catch {
+            // No watch on this directory: the poll interval is the fallback,
+            // which is exactly what it is for.
+        }
+    }
+    try {
+        await Promise.race([changed, sleep(Math.max(0, timeoutMs))]);
+    }
+    finally {
+        for (const handle of watchers) {
+            handle.close();
+        }
+    }
+}
+/**
+ * Resident mode: a plain foreground loop the caller owns. It evaluates
+ * once at startup (so an already-pending wake is surfaced immediately
+ * and the beacon proves arming), then alternates cheap scans at the poll
+ * interval with heartbeat evaluations on the backoff schedule.
+ */
+export async function runResident(fleet, options) {
+    const now = options.now ?? Date.now;
+    // Startup evaluation: an already-pending wake is surfaced at once, and
+    // the beacon is written whatever happens, so "the watcher is armed" is
+    // an observable fact and not a claim (plan step 1, exit test A5).
+    const startupState = loadOrInitCadence(fleet, now());
+    const startupWake = await scanAndSurface(fleet, options, now());
+    if (startupWake !== undefined) {
+        return startupWake;
+    }
+    writeBeacon(fleet, now(), startupState.backoffStreak, options.cadence);
+    let ticksThisRun = 0;
+    for (;;) {
+        const state = readCadenceState(fleet) ?? loadOrInitCadence(fleet, now());
+        const dueMs = nextHeartbeatDueMs(state, options.cadence);
+        const waitMs = Math.min(options.cadence.pollIntervalMs, Math.max(0, dueMs - now()));
+        await waitForChange(fleet, waitMs);
+        const surfaced = await scanAndSurface(fleet, options, now());
+        if (surfaced !== undefined) {
+            return surfaced;
+        }
+        if (now() >= dueMs) {
+            const n = heartbeatTick(fleet, state, options.cadence, now());
+            ticksThisRun += 1;
+            // Resident mode is SILENT on heartbeats unless the caller asked for
+            // a bounded run: a supervisor that exited every heartbeat would be
+            // no supervisor at all (criterion 3).
+            if (options.maxHeartbeats !== undefined && ticksThisRun >= options.maxHeartbeats) {
+                appendWakeRecord(fleet, now(), heartbeatLine(n));
+                return { code: 0, line: heartbeatLine(n) };
+            }
+        }
+    }
+}