@tiphys/kernel 0.0.0 → 0.2.0

package/dist/src/hooks.js

@@ -0,0 +1,125 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { taskDir, turnEndPath } from "./task.js";
+/**
+ * Turn-end hook (kernel plan v1, M1-P4 step 3; R-082b, PR-209).
+ *
+ * The hook is a generated script in the TASK directory (never inside the
+ * worktree, FM-059) that the executor invokes when the payload command
+ * exits. It writes tasks/<id>/turn-end as JSON:
+ *
+ *   {"endedAt": "<ISO-8601>", "exitCode": <number>}
+ *
+ * That file is the M1-P5 watcher's wake signal. It is a notification,
+ * not the task's state: meta.json status plus this exit code together
+ * are the single current-state authority (plan constraint C-1), and a
+ * MISSING turn-end file never means success (tuition T-002: an agent
+ * that dies quietly leaves no turn-end and a dirty worktree).
+ *
+ * The hook takes the payload's exit code as its single argument, so any
+ * adapter (the M1 subprocess adapter, and the window or cloud-session
+ * adapters of the M4 era) can invoke it without knowing anything else
+ * about the task. It is written with the .mjs extension so it parses as
+ * ESM regardless of the nearest package.json, since it runs inside the
+ * fleet home rather than inside this package.
+ */
+/** The generated hook script for a task. */
+export function turnEndHookPath(fleet, taskId) {
+    return join(taskDir(fleet, taskId), "turn-end-hook.mjs");
+}
+/**
+ * Generate the hook script. The turn-end path is baked in as a literal,
+ * so the hook needs no fleet resolution.
+ *
+ * THE CHILD-OBSERVED POINTER RECORD (CR-B-001, the half that closes the hole
+ * rather than the half that stops mis-asserting it).
+ *
+ * `observeNames`, when given, is baked in as a literal array and the hook
+ * writes an `env` object holding what each of those names ACTUALLY IS in the
+ * environment the hook was launched with, or `null` where the name is unset.
+ * The kernel compares those against the harness-owned paths it handed over.
+ *
+ * WHY THIS IS STRONGER THAN AN ADAPTER'S REPORT AND WHY IT IS NOT PROOF.
+ * This script is written BY THE KERNEL and, for every adapter that honours
+ * the documented contract, runs in the SAME environment as the payload (the
+ * built-in adapter spreads the same `request.env` into both spawnSync calls,
+ * and M2R-004 edit 4 is the record of why a second unscrubbed launch is
+ * itself the leak). Against an adapter that does not invoke this script at
+ * all it proves nothing, and the record no longer says otherwise.
+ *
+ * THE COST SENTENCE THAT STOOD HERE IS WITHDRAWN, BECAUSE IT WAS REFUTED BY
+ * MEASUREMENT (CR-F-CRED-001, MEDIUM).
+ *
+ * It read: an adapter that quietly reverted `HOME` for the payload "has to
+ * revert it for the payload and NOT for the hook, which means launching two
+ * children with two different environments and is a substantially different
+ * act from passing a mutated copy once". Two children is one way to do it and
+ * it is not the cheap way. The cheap way is ONE child with the mutated
+ * environment plus a single `writeFileSync` of the turn-end path, which is
+ * STRICTLY LESS work than the honest path, because the honest path also
+ * spawns the hook. The turn-end path is handed to the adapter beside
+ * `hookPath`, and this generated script names it as a literal, so an adapter
+ * that never runs it can still produce a byte-identical record.
+ *
+ * WHY A NONCE DOES NOT CLOSE THIS, stated because it is the obvious repair and
+ * it was considered and refused rather than overlooked. Baking a per-task
+ * secret into this script and requiring it in the record moves the forgery
+ * from "know the path" to "read the file", and the adapter is HANDED the path
+ * of this file: it runs at the same uid, on the same filesystem, in a
+ * directory it must be able to read to invoke the hook at all. A guard whose
+ * condition the adversary can satisfy by reading one file is green and
+ * worthless, which is this repository's own recorded shape (T-008's
+ * postscript, the red-witness rule one level up). No artifact this script can
+ * write is unforgeable by a party that can read this script.
+ *
+ * So the repair is on the RECORD rather than on the check: the value is
+ * `turn-end-record`, it names the artifact the values were read from, and
+ * `CredentialHandoverRecord` (src/task.ts) says the artifact is
+ * adapter-reachable. A dishonest adapter is still not caught here, and that
+ * residue is declared at delivery/work-history/m4-p8.md item 3; what changed
+ * is that `meta.json` no longer positively asserts a child-side observation
+ * that no child made.
+ *
+ * The hook still reads no environment it was not told to read, and a hook
+ * generated with no `observeNames` behaves exactly as it did before.
+ */
+export function renderTurnEndHook(turnEndFile, observeNames) {
+    const observing = observeNames !== undefined && observeNames.length > 0;
+    const envLines = observing
+        ? `const observed = {};
+for (const name of ${JSON.stringify([...observeNames])}) {
+  const value = process.env[name];
+  observed[name] = typeof value === "string" ? value : null;
+}
+record.env = observed;
+`
+        : "";
+    return `#!/usr/bin/env node
+// Generated by tiphys spawn (kernel plan v1, M1-P4 step 3). Invoked by the
+// executor adapter when the payload command exits, with the payload's exit
+// code as its single argument. Writes the turn-end record the M1-P5 watcher
+// wakes on. Do not edit: spawn regenerates it.
+import { writeFileSync } from "node:fs";
+
+const exitCode = Number(process.argv[2]);
+if (!Number.isInteger(exitCode)) {
+  process.stderr.write(
+    "tiphys turn-end hook: expected one integer exit-code argument\\n",
+  );
+  process.exit(64);
+}
+const record = { endedAt: new Date().toISOString(), exitCode };
+${envLines}writeFileSync(
+  ${JSON.stringify(turnEndFile)},
+  \`\${JSON.stringify(record, null, 2)}\\n\`,
+);
+`;
+}
+/** Write the hook for a task and return its path. */
+export function writeTurnEndHook(fleet, taskId, observeNames) {
+    const path = turnEndHookPath(fleet, taskId);
+    writeFileSync(path, renderTurnEndHook(turnEndPath(fleet, taskId), observeNames), {
+        mode: 0o755,
+    });
+    return path;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * THE KERNEL'S PUBLIC ENTRY POINT (kernel plan M4, M4-P4 criteria 7 and 8).
+ *
+ * Until this phase `@tiphys/kernel` declared `bin` and nothing else
+ * (package.json:14): no `main`, no `exports`, no `types`, and no
+ * `src/index.ts`. A separately published plugin could therefore not import
+ * `ExecutorAdapter` at all, which made the executor seam unreachable from
+ * outside this repository however well the interface was written.
+ *
+ * WHAT IS PUBLISHED HERE IS A COMMITMENT AND IS DELIBERATELY SMALL. An
+ * `exports` map is a semver promise and a patch release cannot take one back,
+ * so this file names the adapter CONTRACT and nothing else. In particular it
+ * does not export `spawnTask`, the fleet accessors, the gate runner or
+ * anything under `src/exec/`: those are the kernel's internals, they change
+ * without notice, and `package.json`'s `exports` map has no wildcard subpath
+ * precisely so that they stay unreachable through the package name
+ * (criterion 8, whose dangerous state is an `exports` map written
+ * `"./*": "./dist/src/*"`, which satisfies criterion 7 and publishes the
+ * entire kernel as API).
+ *
+ * THE TWO VALUES ARE PART OF THE CONTRACT, not a convenience. An adapter
+ * author has to answer two questions that types cannot answer at runtime:
+ * which names may appear in `requires` (the closed set the kernel checks
+ * against, src/spawn.ts's `requirableRequestFields`), and which name is
+ * reserved for the built-in adapter (`BUILT_IN_ADAPTER_NAME`, refused by the
+ * loader). Publishing the answers is cheaper than publishing a document that
+ * drifts from them.
+ */
+export type { ExecutorAdapter, ExecutorRecord, ExecutorRequest, LaunchOutcome, } from "./spawn.ts";
+export { requirableRequestFields } from "./spawn.ts";
+export { BUILT_IN_ADAPTER_NAME } from "./adapters/load.ts";

package/dist/src/index.js

@@ -0,0 +1,30 @@
+/**
+ * THE KERNEL'S PUBLIC ENTRY POINT (kernel plan M4, M4-P4 criteria 7 and 8).
+ *
+ * Until this phase `@tiphys/kernel` declared `bin` and nothing else
+ * (package.json:14): no `main`, no `exports`, no `types`, and no
+ * `src/index.ts`. A separately published plugin could therefore not import
+ * `ExecutorAdapter` at all, which made the executor seam unreachable from
+ * outside this repository however well the interface was written.
+ *
+ * WHAT IS PUBLISHED HERE IS A COMMITMENT AND IS DELIBERATELY SMALL. An
+ * `exports` map is a semver promise and a patch release cannot take one back,
+ * so this file names the adapter CONTRACT and nothing else. In particular it
+ * does not export `spawnTask`, the fleet accessors, the gate runner or
+ * anything under `src/exec/`: those are the kernel's internals, they change
+ * without notice, and `package.json`'s `exports` map has no wildcard subpath
+ * precisely so that they stay unreachable through the package name
+ * (criterion 8, whose dangerous state is an `exports` map written
+ * `"./*": "./dist/src/*"`, which satisfies criterion 7 and publishes the
+ * entire kernel as API).
+ *
+ * THE TWO VALUES ARE PART OF THE CONTRACT, not a convenience. An adapter
+ * author has to answer two questions that types cannot answer at runtime:
+ * which names may appear in `requires` (the closed set the kernel checks
+ * against, src/spawn.ts's `requirableRequestFields`), and which name is
+ * reserved for the built-in adapter (`BUILT_IN_ADAPTER_NAME`, refused by the
+ * loader). Publishing the answers is cheaper than publishing a document that
+ * drifts from them.
+ */
+export { requirableRequestFields } from "./spawn.js";
+export { BUILT_IN_ADAPTER_NAME } from "./adapters/load.js";

package/dist/src/liveness.d.ts

@@ -0,0 +1,321 @@
+import type { Fleet } from "./fleet.ts";
+/**
+ * Liveness guard and the one cadence configuration both halves of this
+ * phase share (kernel plan v1, M1-P5 step 2; R-079, R-095; PR-009,
+ * PR-206; plan constraint C-2).
+ *
+ * WHAT LIVENESS MEANS HERE. Freshness of the beacon FILE, and nothing
+ * else. This module never asks the operating system about any running
+ * program, never inspects a process table, and holds no identity of any
+ * kind (plan constraint C-2, FM-053). "Supervision is alive" means "a
+ * watcher evaluation wrote state/watcher.beacon recently enough", which
+ * is true in exactly the same way for a resident watcher and for an
+ * external scheduler driving watch --once (DR-0007, PR-206).
+ *
+ * WHAT THE GUARD IS FOR (R-079). Supervision must never silently
+ * disappear while work is in flight. So the predicate has TWO halves and
+ * both are load-bearing: work in flight (read from the C-1 state
+ * authority, tasks/<id>/meta.json status, never from a log tail) AND a
+ * beacon that is not evidence of recent supervision. A fleet with no
+ * open task cannot be stale, because there is nothing to supervise; a
+ * fleet with open tasks and a silent watcher is exactly the T-002
+ * incident shape, and the guard says so.
+ *
+ * NO HEALTH FROM AN ABSENCE OF EVIDENCE (fix round). Both halves are
+ * evaluated so that the QUIET outcome is the one that needs evidence,
+ * never the loud one:
+ *
+ *   - in flight counts open tasks AND tasks whose meta.json exists and
+ *     cannot be read, because an unreadable record is not evidence that
+ *     a task finished (second reviewer, finding 2);
+ *   - a beacon that is absent, unparseable, or dated in the FUTURE are
+ *     one class, no evidence that supervision ran (CR-501);
+ *   - the freshness threshold is at least the cadence the watcher itself
+ *     declared in the beacon it wrote, so a differently configured
+ *     reader cannot call a healthy watcher stale (CR-503).
+ *
+ * The first draft of this module got each of these the other way round,
+ * and every one of them turned into a fleet that reported health it
+ * could not support.
+ *
+ * THE PR-009 INVARIANT, enforced at load. A healthy resident watcher
+ * writes the beacon on its heartbeat schedule, which backs off by
+ * doubling up to a cap, and it notices that a heartbeat is due only at
+ * its next poll tick. The oldest a healthy beacon can therefore be is
+ * one backoff cap plus one poll interval. The stale threshold must be
+ * strictly greater than that sum or a perfectly healthy idle watcher
+ * reads as stale, so loadCadence refuses any configuration that
+ * violates it, naming both values. In --once-only operation the same
+ * threshold additionally bounds the acceptable external trigger period:
+ * a scheduler must fire at least as often as the threshold to keep the
+ * fleet fresh (PR-206), which is an operator setting, not something the
+ * kernel can enforce.
+ *
+ * WARN, NEVER BLOCK (blueprint liveness-guard contract). The guard's
+ * consumers (spawn, teardown, doctor) print one stderr line containing
+ * "watcher stale" and then do exactly what they would have done anyway.
+ * A raise inside an advisory must not be able to take down the command it
+ * is advising, and this project has already paid twice for raises walking
+ * past handlers that only understood returned failures (M1-P4 F-1 and
+ * F-2). So guard() classifies rather than propagates: every filesystem
+ * read it performs is wrapped, and a raised error becomes "this file is
+ * not readable".
+ *
+ * WHAT THAT SENTENCE DOES NOT SAY, corrected in place (CR-520). An earlier
+ * version of this paragraph read "guard() is TOTAL: every filesystem read
+ * it performs is wrapped". The wrapping was real and the word TOTAL did
+ * not follow from it. Totality against RAISES is not totality against
+ * BLOCKS, and open(2) on a named pipe with no writer blocks in the kernel
+ * without raising anything. While that sentence stood, a named pipe at
+ * state/watcher.beacon hung guard() forever, and with it doctor, spawn,
+ * teardown and both watcher entry modes, each producing no output at all.
+ * The claim was written without being executed; tuition T-006 is about
+ * exactly that habit.
+ *
+ * What is true now, and only this: guard() reads two kinds of path, task
+ * records and the beacon, and BOTH go through readRegularFileIfPresent in
+ * src/task.ts, which establishes the type before it opens anything. A
+ * non-regular entry at either path is classified as unreadable without
+ * being opened, which the guard already treats as "no evidence", so the
+ * advisory stays loud instead of stopping. Two syscalls remain between the
+ * probe and the open, and that residual is stated at the helper.
+ */
+/** Cadence and freshness, in milliseconds. One authority for both. */
+export interface WatchCadence {
+    /** First heartbeat interval; it doubles from here (FM-044). */
+    baseIntervalMs: number;
+    /** How often a resident watcher re-checks its wake sources. */
+    pollIntervalMs: number;
+    /** Ceiling the doubling heartbeat interval stops at. */
+    backoffCapMs: number;
+    /** Beacon age at which supervision counts as stale. */
+    staleThresholdMs: number;
+}
+/**
+ * Defaults, in seconds. FM-044 is a calibration starting point, not a
+ * measured optimum, and these are chosen so the PR-009 invariant holds
+ * with room to spare (900 + 15 = 915 < 1200).
+ */
+export declare const DEFAULT_BASE_INTERVAL_SECONDS = 60;
+export declare const DEFAULT_POLL_INTERVAL_SECONDS = 15;
+export declare const DEFAULT_BACKOFF_CAP_SECONDS = 900;
+export declare const DEFAULT_STALE_THRESHOLD_SECONDS = 1200;
+/**
+ * Environment overrides. The watch command also carries --interval,
+ * --poll and --backoff-cap flags for a single invocation (the M1-P6
+ * harness needs the cadence short); these variables exist because the
+ * guard runs inside spawn, teardown and doctor, which have no watch
+ * flags, and because a fleet's cadence and its freshness threshold have
+ * to agree across all four commands.
+ */
+export declare const ENV_BASE_INTERVAL = "TIPHYS_WATCH_INTERVAL_SECONDS";
+export declare const ENV_POLL_INTERVAL = "TIPHYS_WATCH_POLL_SECONDS";
+export declare const ENV_BACKOFF_CAP = "TIPHYS_WATCH_BACKOFF_CAP_SECONDS";
+export declare const ENV_STALE_THRESHOLD = "TIPHYS_WATCH_STALE_SECONDS";
+/**
+ * The PR-009 invariant, enforced wherever a cadence is built (at module
+ * load for the process-wide one, and again for every set of watch
+ * flags). The message names both sides because the operator has to know
+ * which of the two to change.
+ */
+export declare function assertCadenceInvariant(cadence: WatchCadence): void;
+/** Build a cadence from environment overrides, validated. */
+export declare function loadCadence(env: NodeJS.ProcessEnv): WatchCadence;
+/**
+ * Apply per-invocation overrides (the watch flags) and re-validate, so
+ * a short --backoff-cap or a long one can never quietly break the
+ * invariant the guard depends on.
+ */
+export declare function withCadenceOverrides(base: WatchCadence, overrides: Partial<WatchCadence>): WatchCadence;
+/**
+ * The process-wide cadence. Building it at module load is what makes
+ * criterion 12's second clause real: importing this module under a
+ * configuration that violates the invariant FAILS, with both values in
+ * the message, instead of running on with a guard that cries wolf.
+ */
+export declare const CADENCE: WatchCadence;
+/** The beacon record (JSON per DR-0006, plan decision D-3). */
+export interface BeaconRecord {
+    /** ISO-8601 instant of the evaluation that wrote it. */
+    writtenAt: string;
+    /** Backoff streak at that moment, so a reader can see the cadence. */
+    backoffStreak: number;
+    /** The heartbeat interval in force at that moment, milliseconds. */
+    intervalMs: number;
+}
+export declare function renderBeacon(record: BeaconRecord): string;
+/**
+ * Read the beacon, or undefined when it is absent, is not a regular file,
+ * cannot be read, or does not parse. All of those are the same thing to
+ * the guard: no evidence that supervision ran. That is the
+ * fail-toward-warning direction, and for an advisory that never blocks it
+ * is the right one.
+ *
+ * The type probe is INSIDE this reader (CR-520). It is not enough for
+ * judgeBeacon to have lstat'ed the path first: that call establishes
+ * PRESENCE, not TYPE, and this reader has a second caller in
+ * src/watcher.ts (writeBeacon) which does not lstat at all. A probe in
+ * front of one caller protects one caller.
+ */
+export declare function readBeacon(beaconPath: string): BeaconRecord | undefined;
+/** What the guard reports (the plan's shape, M1-P5 step 2). */
+export interface GuardReport {
+    /**
+     * Work this fleet cannot be shown to be free of: tasks whose meta.json
+     * says open, PLUS tasks whose meta.json exists and cannot be read (see
+     * surveyTasks).
+     */
+    inFlight: number;
+    /** How many of inFlight are unreadable records rather than open tasks. */
+    unreadable: number;
+    /** Beacon age in milliseconds, or undefined when there is no evidence. */
+    beaconAgeMs: number | undefined;
+    /** Open work exists and supervision has not been witnessed recently. */
+    stale: boolean;
+    /** One line of detail; the warning text when stale. */
+    detail: string;
+}
+/**
+ * How far a beacon may sit in the FUTURE before it stops counting as
+ * evidence. Nothing legitimate puts it there: writeBeacon stamps the
+ * current time and only ever bumps by a millisecond to keep the advance
+ * strict. A beacon well ahead of the local clock means the clock moved
+ * backwards under a running watcher (an NTP step, a suspend and resume,
+ * a session resumed on another host), and until it is rewritten from the
+ * present it proves nothing about whether supervision is still running.
+ * The allowance absorbs ordinary jitter and the monotonic bump.
+ */
+export declare const BEACON_FUTURE_TOLERANCE_MS = 5000;
+export interface TaskSurvey {
+    /** Task ids whose meta.json parses and says open, sorted. */
+    open: string[];
+    /**
+     * Task ids where SOMETHING EXISTS at tasks/<id>/meta.json, by any file
+     * type, and cannot be read as a task record. Sorted.
+     */
+    unreadable: string[];
+    /**
+     * Things this survey could not establish at all (the tasks directory
+     * could not be listed, an entry could not be stat'ed), one reason line
+     * each. NEITHER CALLER MAY READ AN EMPTY RESULT AS "no work": the
+     * watcher reports these loudly and the guard counts them as in flight,
+     * because a survey that did not complete is not evidence of an idle
+     * fleet.
+     */
+    problems: string[];
+}
+/**
+ * THE ONE CLASSIFIER OF TASK RECORDS. src/watcher.ts and this module both
+ * call it, and neither has a second opinion about what a task record is.
+ *
+ * This exists because the fix round wrote the same classification twice
+ * with different conditions, and the copies disagreed: one asked whether
+ * the meta path was a regular FILE, the other only that a stat succeeded,
+ * so a meta.json that existed as a directory was surfaced by the watcher
+ * and reported by the guard as nothing in flight, which is a
+ * counterexample to the very property that round declared (delta review
+ * NEW-1, and tuition T-005 on rules that fail to propagate). One property
+ * gets one implementation; two that agree today drift the moment someone
+ * edits one of them.
+ *
+ * The rules, in one place:
+ *
+ * - A TASK IS A DIRECTORY under tasks/. The entry is resolved with stat,
+ *   so a symlink to a real task directory is a task; init's own .gitkeep
+ *   and any other stray file is not, which is checked by TYPE and never
+ *   by name.
+ * - A record that PARSES is authoritative: its status decides open or
+ *   closed (plan constraint C-1).
+ * - THE RECORD IS PROBED BEFORE IT IS READ, AND THE PROBE IS NOT HERE.
+ *   Only a path that resolves to a REGULAR FILE is ever opened; anything
+ *   else that exists there (a directory, a FIFO, a socket, a device node,
+ *   a symlink resolving to any of those, a dangling symlink) is classified
+ *   as a record that cannot be read WITHOUT opening it. That ordering is
+ *   load-bearing: opening a FIFO with no writer blocks in the kernel and
+ *   is not an exception, so a classifier that read first would hang
+ *   instead of classifying, and would take the guard's three callers down
+ *   with it.
+ *
+ *   The ordering is enforced INSIDE readTaskMeta (src/task.ts), not in
+ *   front of the call below. A fix round put it here instead, which
+ *   protected this one call site and left every other caller of
+ *   readTaskMeta exposed; src/teardown.ts is one, and a named pipe at a
+ *   task record hung teardown forever while this classifier reported the
+ *   same file cleanly (CR-520, CR-521). The recorded reason for declining
+ *   to protect the other callers was that it would mean a second reader
+ *   beside readTaskMeta. That reason was wrong: moving the probe INTO
+ *   readTaskMeta is still exactly one implementation of "read a task
+ *   record", and it is the shape now shipped. What this classifier keeps
+ *   is the finer split it genuinely needs, unreadable versus a survey that
+ *   did not complete, computed from the same classifyEntry the reader uses.
+ * - A regular file that does not parse is likewise unreadable: it exists
+ *   and it is not evidence that the task finished.
+ * - NOTHING at the meta.json path is not a record at all: that is the
+ *   normal transient shape of a spawn in progress or a rollback residue.
+ * - Residual, stated rather than papered over: the probe and the read are
+ *   two syscalls, so a path that changes type between them could still be
+ *   opened as something other than a regular file. Nothing in this kernel
+ *   writes that state. The residual is stated once, at classifyEntry.
+ *
+ * Total by construction: it never raises, because one of its two callers
+ * is an advisory that must not be able to take down the command it is
+ * advising. It does not swallow either: what it could not establish comes
+ * back in problems, and both callers are required to act on that.
+ */
+export declare function surveyTaskRecords(fleet: Fleet): TaskSurvey;
+/**
+ * THE ONE FRESHNESS THRESHOLD. The configured threshold, raised to the
+ * cadence the WATCHER ITSELF declared in the beacon it wrote plus one
+ * poll interval (CR-503). Every consumer of beacon freshness calls this,
+ * so a single run cannot produce two verdicts about one file.
+ */
+export declare function effectiveThresholdMs(beacon: BeaconRecord | undefined, cadence: WatchCadence): number;
+/**
+ * What a beacon file is evidence of. THE ONE BEACON VERDICT: the guard
+ * and doctor's own beacon check both call this, so they cannot disagree
+ * about the same file in the same run (delta review CR-508, where they
+ * did). Each caller decides how to PRESENT the verdict; neither decides
+ * what it is.
+ */
+export type BeaconVerdict = {
+    kind: "absent";
+} | {
+    kind: "unreadable";
+} | {
+    kind: "ahead";
+    aheadMs: number;
+    thresholdMs: number;
+} | {
+    kind: "fresh";
+    ageMs: number;
+    thresholdMs: number;
+} | {
+    kind: "stale";
+    ageMs: number;
+    thresholdMs: number;
+};
+export declare function judgeBeacon(beaconPath: string, nowMs?: number, cadence?: WatchCadence): BeaconVerdict;
+/** Counts, for the guard. The classification itself is not repeated. */
+export declare function surveyTasks(fleet: Fleet): {
+    open: number;
+    unreadable: number;
+};
+/**
+ * The guard predicate (plan step 2). Total: it never raises, whatever
+ * the filesystem does, because its callers use it as an advisory.
+ *
+ * NO HEALTH FROM AN ABSENCE OF EVIDENCE. "Not stale" is only said when
+ * this function can point at the evidence for it: either nothing is in
+ * flight, or a beacon judged fresh. What counts as work in flight comes
+ * from surveyTaskRecords and what a beacon is evidence of comes from
+ * judgeBeacon; this function decides neither of those questions itself,
+ * so doctor and the guard cannot answer them differently.
+ */
+export declare function guard(fleet: Fleet, nowMs?: number, cadence?: WatchCadence): GuardReport;
+/**
+ * The one call site shape spawn, teardown and doctor share: evaluate the
+ * guard and, when stale, write exactly one stderr line containing
+ * "watcher stale". It returns the report so a caller can use it, and it
+ * never changes what the caller does next (warn, never block).
+ */
+export declare function warnIfWatcherStale(fleet: Fleet, write?: (text: string) => void): GuardReport;