@ours.network/fleet 0.19.0-nightly.8 → 1.0.0

package/dist/supervisor/systemd.js

@@ -106,7 +106,7 @@ Type=simple
 ${environmentLines}
 ExecStart=${unitArg(process.execPath)} ${unitArg(binPath)} _run %i
 # The RUNNER owns the child-session restart loop, with a counted, backed-off
-# circuit breaker (3.2). systemd must only recover the runner PROCESS crashing —
+# circuit breaker. systemd must only recover the runner PROCESS crashing —
 # Restart=always here would resume the uncounted two-second relaunch loop, and
 # would also restart a runner that is deliberately holding a failing agent down.
 Restart=on-failure
@@ -126,12 +126,12 @@ WantedBy=default.target
         },
         async install(name) {
             // Ask FIRST whether this unit was already enabled, so a rollback can tell
-            // "we registered this" from "it was already here" (6.2).
+            // "we registered this" from "it was already here".
             const before = await ctl('is-enabled', unitFor(name));
             const alreadyEnabled = before.stdout.trim() === 'enabled';
             const r = await ctl('enable', '--now', unitFor(name));
             // Undo only what WE enabled. A unit that was already enabled belongs to
-            // whoever enabled it, and rollback may never remove that (6.2).
+            // whoever enabled it, and rollback may never remove that.
             const undo = async () => { if (!alreadyEnabled)
                 await ctl('disable', '--now', unitFor(name)); };
             if (r.code !== 0) {
@@ -156,7 +156,7 @@ WantedBy=default.target
             // care whether this systemd propagates a start failure into the exit
             // code, so it is correct both on versions that do and versions that do
             // not. Only a DEFINITE stop counts. An unanswerable probe is `unknown`
-            // and must never be read as a failed start (1.1) — the unit may be
+            // and must never be read as a failed start — the unit may be
             // perfectly fine and the bus merely unreachable.
             const live = await probeLiveness(ctl, name);
             if (live.state === 'stopped') {

package/dist/supervisor/types.d.ts

@@ -31,7 +31,7 @@ export interface SupervisorBackend {
      * Ensure the role's unit exists and is enabled + started. Idempotent, and
      * EXPLICIT about whether it created the registration: rollback may only
      * remove what this transaction made, so "did I create this?" has to be
-     * answerable rather than assumed (6.2).
+     * answerable rather than assumed.
      */
     install(name: string, binPath: string): Promise<InstallOutcome>;
     start(name: string): Promise<void>;

package/dist/temp-lifecycle.d.ts

@@ -46,11 +46,24 @@ export declare function markTempSupervisorActive(dir: string, pid?: number): Pro
 export declare function requestedTempStopReason(dir: string): 'operator-stop' | undefined;
 /** Move retired state out of the live roster without deleting any evidence. */
 export declare function archiveTempState(role: string, reason: TempTerminationReason, outcome: TempTerminationRecord['outcome'], detail: string, now?: Date): string | undefined;
-interface TempLifecycleDeps {
+/** Resolve only an exact role+launch archive; names and timestamps are never proof. */
+export declare function tempArchiveForLaunch(role: string, launchId: string): string | undefined;
+/** Resolve one terminated archive by exact role + durable creation action. */
+export declare function tempArchiveForCreationAction(role: string, creationActionId: string): {
+    path: string;
+    launchId: string;
+} | undefined;
+/**
+ * Preserve a definitively stopped launch as recovery evidence, or prove that
+ * its supervisor already did so. Never creates a second archive.
+ */
+export declare function secureStoppedTempArchive(role: string, launchId: string, deps?: TempLifecycleDeps): Promise<string>;
+export interface TempLifecycleDeps {
     exec?: Exec;
     now?(): number;
     kill?(pid: number, signal: NodeJS.Signals | 0): void;
     log?(line: string): void;
+    sleep?(ms: number): Promise<void>;
 }
 export declare function tempSupervisorLiveness(dir: string, deps?: TempLifecycleDeps): Promise<'running' | 'stopped' | 'unknown'>;
 export declare function stopTempSupervisor(role: string, deps?: TempLifecycleDeps): Promise<'stopped' | 'already-stopped'>;
@@ -59,4 +72,3 @@ export declare function stopTempSupervisor(role: string, deps?: TempLifecycleDep
  * Unknown/legacy/live entries are preserved; absence of proof is never cleanup authority.
  */
 export declare function reclaimStaleTempState(deps?: TempLifecycleDeps): Promise<string[]>;
-export {};

package/dist/temp-lifecycle.js

@@ -191,6 +191,96 @@ export function archiveTempState(role, reason, outcome, detail, now = new Date()
     }
     return paths.target;
 }
+function isArchiveForLaunch(path, role, launchId) {
+    const supervisor = readTempSupervisor(path);
+    if (supervisor?.role !== role || supervisor.launchId !== launchId)
+        return false;
+    try {
+        return readFileSync(join(path, TEMP_TERMINATION_FILE), 'utf8')
+            .split('\n')
+            .filter(Boolean)
+            .some(line => {
+            const record = JSON.parse(line);
+            return record.version === 1 && record.role === role && record.launchId === launchId;
+        });
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve only an exact role+launch archive; names and timestamps are never proof. */
+export function tempArchiveForLaunch(role, launchId) {
+    let entries;
+    try {
+        entries = readdirSync(archiveRoot(), { withFileTypes: true })
+            .filter(entry => entry.isDirectory() && !entry.isSymbolicLink() && !entry.name.startsWith('.'))
+            .map(entry => join(archiveRoot(), entry.name));
+    }
+    catch {
+        return undefined;
+    }
+    const matches = entries.filter(path => isArchiveForLaunch(path, role, launchId));
+    if (matches.length > 1) {
+        throw new Error(`temporary role '${role}' launch ${launchId} has ${matches.length} recovery archives; refusing ambiguity`);
+    }
+    return matches[0];
+}
+/** Resolve one terminated archive by exact role + durable creation action. */
+export function tempArchiveForCreationAction(role, creationActionId) {
+    let entries;
+    try {
+        entries = readdirSync(archiveRoot(), { withFileTypes: true })
+            .filter(entry => entry.isDirectory() && !entry.isSymbolicLink() && !entry.name.startsWith('.'))
+            .map(entry => join(archiveRoot(), entry.name));
+    }
+    catch {
+        return undefined;
+    }
+    const matches = entries.flatMap(path => {
+        const supervisor = readTempSupervisor(path);
+        if (!supervisor || supervisor.role !== role || !isArchiveForLaunch(path, role, supervisor.launchId))
+            return [];
+        try {
+            const provenance = JSON.parse(readFileSync(join(path, 'creation.json'), 'utf8'));
+            return provenance.role === role && provenance.creationActionId === creationActionId
+                ? [{ path, launchId: supervisor.launchId }] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+    if (matches.length > 1) {
+        throw new Error(`temporary role '${role}' action ${creationActionId} has ${matches.length} recovery archives; refusing ambiguity`);
+    }
+    return matches[0];
+}
+/**
+ * Preserve a definitively stopped launch as recovery evidence, or prove that
+ * its supervisor already did so. Never creates a second archive.
+ */
+export async function secureStoppedTempArchive(role, launchId, deps = {}) {
+    const dir = join(tmpRoot(), role);
+    if (existsSync(dir)) {
+        const supervisor = readTempSupervisor(dir);
+        if (!supervisor || supervisor.role !== role || supervisor.launchId !== launchId) {
+            throw new Error(`temporary role '${role}' no longer matches recorded launch ${launchId}; refusing to archive`);
+        }
+        const live = await tempSupervisorLiveness(dir, deps);
+        if (live !== 'stopped') {
+            throw new Error(`temporary role '${role}' supervisor is ${live}; refusing to archive before proven stop`);
+        }
+        const archived = archiveTempState(role, 'operator-stop', 'retired', 'room close proved the supervisor stopped; full role evidence preserved');
+        if (!archived || !isArchiveForLaunch(archived, role, launchId)) {
+            throw new Error(`temporary role '${role}' archive could not be verified for launch ${launchId}`);
+        }
+        return archived;
+    }
+    const archived = tempArchiveForLaunch(role, launchId);
+    if (!archived) {
+        throw new Error(`temporary role '${role}' live state disappeared without an exact recovery archive for launch ${launchId}`);
+    }
+    return archived;
+}
 /** Finish bounded archive renames interrupted by process or host termination. */
 function recoverInterruptedArchives(now) {
     let names;

package/dist/watchdog/alerts.d.ts

@@ -21,7 +21,7 @@ export interface AlertLedger {
 export declare function readLedger(name: string): AlertLedger;
 export declare function writeLedger(name: string, l: AlertLedger): void;
 /**
- * Reconcile rules (spec §5): an `error`-status report carries no role evidence, so the ledger
+ * An `error`-status report carries no role evidence, so the ledger
  * is returned unchanged. For each finding with rank > 0: an existing open entry keeps its
  * `since` and updates `status` on escalation/de-escalation; a new one opens with `since = now`.
  * Any role reported `healthy`/`idle` closes (deletes) its open entry. Every role named in
@@ -30,5 +30,5 @@ export declare function writeLedger(name: string, l: AlertLedger): void;
  * Never mutates `l` — always returns a new ledger object.
  */
 export declare function reconcileLedger(l: AlertLedger, report: WatchdogReport, now: Date): AlertLedger;
-/** Ledger's open findings + cooldown, in the shape watch.json's `digest` field carries (Task 7 writes it, run reads it back). */
+/** Ledger open findings and cooldown in the shape carried by watch.json's `digest` field. */
 export declare function computeDigest(l: AlertLedger, cooldownMs: number, now: Date): WatchManifest['digest'];

package/dist/watchdog/alerts.js

@@ -30,7 +30,7 @@ export function writeLedger(name, l) {
     chmodSync(path, 0o600);
 }
 /**
- * Reconcile rules (spec §5): an `error`-status report carries no role evidence, so the ledger
+ * An `error`-status report carries no role evidence, so the ledger
  * is returned unchanged. For each finding with rank > 0: an existing open entry keeps its
  * `since` and updates `status` on escalation/de-escalation; a new one opens with `since = now`.
  * Any role reported `healthy`/`idle` closes (deletes) its open entry. Every role named in
@@ -64,7 +64,7 @@ export function reconcileLedger(l, report, now) {
     }
     return { ...l, open };
 }
-/** Ledger's open findings + cooldown, in the shape watch.json's `digest` field carries (Task 7 writes it, run reads it back). */
+/** Ledger open findings and cooldown in the shape carried by watch.json's `digest` field. */
 export function computeDigest(l, cooldownMs, now) {
     return {
         cooldown_ms: cooldownMs,

package/dist/watchdog/briefing.d.ts

@@ -6,8 +6,8 @@ export interface WatchManifestRole {
     stateDir: string;
 }
 /**
- * The fixed run manifest a watchdog run reads at `manifestPath` (7.3 §3, Task 7 writes it,
- * Task 12+ digest reads it back). It carries everything the run needs to identify itself in
+ * The fixed run manifest a watchdog run reads at `manifestPath`. It carries everything the
+ * run and digest reader need to identify the run in
  * report.json (`watchdog`, `run_id`, `started_at`) plus the suppression digest that makes
  * alerting idempotent across runs.
  */
@@ -34,7 +34,7 @@ export interface WatchdogBriefingOpts {
     vocabulary: BriefingVocab;
     /** What spawn actually established about the watchdog's ours identity (7.3, decision 3). */
     identityGuarantee: 'verified' | 'created' | 'unverified';
-    /** Raw prompt_file content, appended as extra focus — never a replacement (owner decision 1). */
+    /** Raw prompt_file content, appended as extra focus — never a replacement. */
     promptFocus?: string;
 }
 /**
@@ -42,8 +42,8 @@ export interface WatchdogBriefingOpts {
  * run): bind, observe-only rules, procedure, status vocabulary, evidence rules, alert rules,
  * report schema, and — if the watchdog configures one — an appended prompt_file focus.
  *
- * The contract is fixed for every watchdog (spec §5: "The schema is fixed for every watchdog,
- * including ones with a prompt_file; the override adds focus, never fields"), so every section
+ * The contract is fixed for every watchdog, including ones with a prompt_file; the override
+ * adds focus, never fields. Therefore every section
  * below is unconditional except the identity-guarantee wording and the trailing focus append.
  */
 export declare function generateWatchdogBriefing(opts: WatchdogBriefingOpts): string;

package/dist/watchdog/briefing.js

@@ -27,8 +27,8 @@ function bindSection(heading, wd, v, guarantee) {
  * run): bind, observe-only rules, procedure, status vocabulary, evidence rules, alert rules,
  * report schema, and — if the watchdog configures one — an appended prompt_file focus.
  *
- * The contract is fixed for every watchdog (spec §5: "The schema is fixed for every watchdog,
- * including ones with a prompt_file; the override adds focus, never fields"), so every section
+ * The contract is fixed for every watchdog, including ones with a prompt_file; the override
+ * adds focus, never fields. Therefore every section
  * below is unconditional except the identity-guarantee wording and the trailing focus append.
  */
 export function generateWatchdogBriefing(opts) {
@@ -41,7 +41,7 @@ export function generateWatchdogBriefing(opts) {
     L.push('no memory from any previous run — this run stands alone, and nothing you learn here');
     L.push('persists past writing your report.');
     L.push(...bindSection('## 1. Bind your identity', wd, v, guarantee));
-    // 2. Observe-only rules, verbatim (spec §1).
+    // 2. Observe-only rules.
     L.push('', '## 2. Observe-only — non-negotiable');
     L.push('You observe and report. You never restart, stop, spawn or remove a role, never answer a ' +
         'pending permission, never edit a workspace or fleet.yaml, and never approve anything on the ' +
@@ -73,13 +73,20 @@ export function generateWatchdogBriefing(opts) {
     L.push('3. If a command fails, times out, or the control plane is otherwise unanswerable for a');
     L.push('   role, that role degrades to `unknown` — never guess `healthy`. `unknown` means the');
     L.push('   evidence is insufficient, not that the role is fine.');
-    // 4. Status vocabulary — spec §4 definitions, verbatim where quoted.
+    // 4. Status vocabulary and definitions.
     L.push('', '## 4. Status vocabulary (fixed)');
     L.push(`interval = ${formatDuration(wd.intervalMs)} — thresholds below are multiples of this.`);
     L.push('');
     L.push('- `healthy` — alive, on-briefing, recent progress.');
     L.push('- `idle` — alive, nothing assigned or nothing to do. Not an anomaly.');
     L.push('- `stale` = no worklog append and no console progress for ≥ 3 intervals.');
+    L.push('');
+    L.push('`session.readiness` from `ours-fleet status` is TURN OCCUPANCY, not activity: a mail');
+    L.push('wake delivered by ACP steering runs an entire turn while readiness stays `idle`. Never');
+    L.push('report `idle` or `stale` from `readiness=idle` alone — corroborate with the');
+    L.push('`activity:` line of the same `status` output (`active` means the agent is working),');
+    L.push('the worklog, or `ours-fleet peek`. `activity: unobservable` is missing evidence, not');
+    L.push('an idle agent.');
     L.push('- `blocked` = waiting on a permission/prompt/modal longer than one interval.');
     L.push('- `off_briefing` — activity contradicts the briefing (wrong repo, out-of-scope work,');
     L.push('  ignored routine).');
@@ -92,7 +99,7 @@ export function generateWatchdogBriefing(opts) {
     L.push('items (`{source, detail, observed_at}`), each ≤280 characters. Never include env');
     L.push('values, tokens, file contents beyond quoted evidence, or a full pane dump — quote only');
     L.push('the specific line(s) that support the finding.');
-    // 6. Alert rules — spec §5 rules 1-4, plus the digest-authoritative sentence, verbatim.
+    // 6. Alert rules plus the digest-authoritative sentence.
     L.push('', '## 6. Alert rules');
     L.push('1. Alert on a finding that is **new** (role+status not open) or **escalated** (e.g.');
     L.push('   `stale` → `blocked`).');
@@ -109,7 +116,7 @@ export function generateWatchdogBriefing(opts) {
         'realert_after; send one resolved notice when a digest-open role is now healthy; ONE message ' +
         `per run listing all qualifying findings, sent with **${v.sendTool}** to "${wd.coordinator}"; ` +
         'set alerted:true and add an alerts[] entry for each. If nothing qualifies, send nothing.');
-    // 7. Report schema — spec §5 example, plus the write-order sentence, verbatim.
+    // 7. Report schema plus the write-order sentence.
     L.push('', '## 7. Write your report');
     L.push('`report.json` has this fixed schema (`schema_version` is always the literal `1`;');
     L.push('`status` is `ok` when every role is `healthy`/`idle`, `anomalies` when any role is not,');

package/dist/watchdog/config.js

@@ -29,7 +29,7 @@ export function resolveWatchdogs(baseDoc, baseFile, roles, vars, defaults) {
         throw new ConfigError(`${baseFile}: watchdogs: must be a map`);
     const roleNames = new Set(roles.map(r => r.name));
     const roleIdentities = new Set(roles.map(r => r.identity));
-    // Tracks identity -> owning watchdog name across entries (final review #5):
+    // Tracks identity -> owning watchdog name across entries:
     // two watchdogs declaring the same identity would otherwise share a temp
     // dir, tmux session, and run lock with no error until they collide at
     // runtime.

package/dist/watchdog/query.d.ts

@@ -7,7 +7,7 @@ export interface WatchdogRoleFinding {
     reason: string;
 }
 /**
- * Needs-attention integration (Task 19): worst current finding per role across
+ * Needs-attention integration: worst current finding per role across
  * every configured watchdog, for FleetQueryService.status() to fold into a
  * role's problems. An `error`-status report carries no role evidence (the run
  * itself failed) so it's skipped outright, matching alerts.ts's
@@ -17,7 +17,7 @@ export interface WatchdogRoleFinding {
  * parameter (rather than importing store.ts directly) so it stays a pure,
  * disk-free function for unit testing; runtime.ts wires the real store.
  *
- * Skips disabled watchdogs (finding #5): a watchdog turned off in config
+ * Skips disabled watchdogs: a watchdog turned off in config
  * still has its last stored report sitting on disk, and without this check
  * that stale report's findings would pin roles in "Needs attention" forever
  * — an operator disabling a noisy/broken watchdog has no way to make the

package/dist/watchdog/query.js

@@ -7,7 +7,7 @@ import { WATCHDOG_STATUS_RANK } from './alerts.js';
 import { readSchedulerState } from './scheduler.js';
 import { listRuns, readReport } from './store.js';
 /**
- * Needs-attention integration (Task 19): worst current finding per role across
+ * Needs-attention integration: worst current finding per role across
  * every configured watchdog, for FleetQueryService.status() to fold into a
  * role's problems. An `error`-status report carries no role evidence (the run
  * itself failed) so it's skipped outright, matching alerts.ts's
@@ -17,7 +17,7 @@ import { listRuns, readReport } from './store.js';
  * parameter (rather than importing store.ts directly) so it stays a pure,
  * disk-free function for unit testing; runtime.ts wires the real store.
  *
- * Skips disabled watchdogs (finding #5): a watchdog turned off in config
+ * Skips disabled watchdogs: a watchdog turned off in config
  * still has its last stored report sitting on disk, and without this check
  * that stale report's findings would pin roles in "Needs attention" forever
  * — an operator disabling a noisy/broken watchdog has no way to make the

package/dist/watchdog/report.js

@@ -84,7 +84,7 @@ export function normalizeWatchdogReport(r, ctx) {
     copy.watchdog = ctx.watchdog;
     copy.run_id = ctx.run_id;
     copy.roles = copy.roles.map(role => {
-        // Rebuilt from ONLY the known fields (final review #6a) — the old
+        // Rebuilt from ONLY the known fields — the old
         // `{ ...role }` spread let any unknown per-finding key (e.g. an agent
         // dumping a huge `pane_dump`) ride unbounded into the store. Report-level
         // extras (tail/isolation) are untouched here and stay tolerated; this is
@@ -119,7 +119,7 @@ export function errorReport(ctx) {
         // Scheduler-built error strings can embed raw agent-controlled bytes
         // (JSON.parse messages, validator interpolations of agent-supplied
         // values) and are stored+printed as-is elsewhere — clean them the same
-        // way finding-level text is cleaned (final review #6b).
+        // way finding-level text is cleaned.
         error: cleanEvidence(ctx.error),
         ...(ctx.tail !== undefined ? { tail: ctx.tail.slice(-4096) } : {}),
     };

package/dist/watchdog/run.d.ts

@@ -36,7 +36,7 @@ export interface WatchdogRunOutcome {
  * didn't), store the result, and always clean up the temp dir.
  *
  * The scheduler's run-lock guarantees only one run per watchdog at a time;
- * this function itself takes no lock (Task 8).
+ * this function itself takes no lock.
  */
 export declare function executeWatchdogRun(wd: ResolvedWatchdog, deps: WatchdogRunDeps): Promise<WatchdogRunOutcome>;
 /**
@@ -46,7 +46,7 @@ export declare function executeWatchdogRun(wd: ResolvedWatchdog, deps: WatchdogR
  * (owner-approved deviation 4), so this is how a scheduler tick that can't reach an operator any
  * other way still gets a message out.
  *
- * Reuses the Task 7/8 run machinery (temp-dir prep, ensureIdentity, ResolvedRole shape, child
+ * Reuses the ordinary run machinery (temp-dir prep, ensureIdentity, ResolvedRole shape, child
  * launch, kill mechanics) but stores no report, touches no ledger findings, and writes no
  * watch.json manifest — `sent.json` is this run's only completion sentinel. A fixed 2-minute
  * deadline applies regardless of `wd.timeoutMs`.

package/dist/watchdog/run.js

@@ -23,7 +23,7 @@ const POLL_MS = 1000;
 const WRITE_STABLE_MS = 2000;
 /** Grace given to the agent after a stable report before the session is killed. */
 const HARVEST_GRACE_MS = 5000;
-/** Fixed deadline for a one-shot notifier run — always 2 minutes, never wd.timeoutMs (Task 14). */
+/** Fixed deadline for a one-shot notifier run — always 2 minutes, never wd.timeoutMs. */
 const NOTIFIER_TIMEOUT_MS = 120_000;
 /**
  * Poll for a completion sentinel file (report.json for an inspection run, sent.json for a
@@ -145,7 +145,7 @@ async function discoverLiveTemporaryRoles() {
  * didn't), store the result, and always clean up the temp dir.
  *
  * The scheduler's run-lock guarantees only one run per watchdog at a time;
- * this function itself takes no lock (Task 8).
+ * this function itself takes no lock.
  */
 export async function executeWatchdogRun(wd, deps) {
     const now = deps.now ?? (() => new Date());
@@ -196,7 +196,7 @@ export async function executeWatchdogRun(wd, deps) {
         writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
         // Snapshot the fleet start-stagger so the detached run (no config path
         // threaded through `_run-watchdog`) honors the same host-wide launch gate
-        // as every other role (spec §3) — mirrors src/spawn.ts:503-504.
+        // as every other role — mirrors the spawn path.
         if (cfg.startStaggerMs > 0)
             writeFileSync(join(dir, START_STAGGER_FILE), String(cfg.startStaggerMs));
         const launch = deps.launchChild ?? defaultLaunchChild;
@@ -234,7 +234,7 @@ export async function executeWatchdogRun(wd, deps) {
                 report.finished_at = now().toISOString();
             }
         }
-        // Isolation degradation (spec §7): a weaker guarantee must never look like
+        // A weaker isolation guarantee must never look like
         // the strong one, so stamp it on every outcome, error reports included.
         if (existsSync(join(dir, '.isolation-degraded')))
             report.isolation = 'degraded';
@@ -257,7 +257,7 @@ export async function executeWatchdogRun(wd, deps) {
  * (owner-approved deviation 4), so this is how a scheduler tick that can't reach an operator any
  * other way still gets a message out.
  *
- * Reuses the Task 7/8 run machinery (temp-dir prep, ensureIdentity, ResolvedRole shape, child
+ * Reuses the ordinary run machinery (temp-dir prep, ensureIdentity, ResolvedRole shape, child
  * launch, kill mechanics) but stores no report, touches no ledger findings, and writes no
  * watch.json manifest — `sent.json` is this run's only completion sentinel. A fixed 2-minute
  * deadline applies regardless of `wd.timeoutMs`.
@@ -308,7 +308,7 @@ export async function executeNotifierRun(wd, text, deps) {
         }));
         // loadTempRole (runner.ts) needs this to run the child via `_run-watchdog`.
         writeFileSync(join(dir, 'role.yaml'), stringify(role));
-        // Same host-wide launch-gate snapshot executeWatchdogRun writes (spec §3).
+        // Use the same host-wide launch-gate snapshot executeWatchdogRun writes.
         if (cfg.startStaggerMs > 0)
             writeFileSync(join(dir, START_STAGGER_FILE), String(cfg.startStaggerMs));
         const launch = deps.launchChild ?? defaultLaunchChild;

package/dist/watchdog/scheduler.d.ts

@@ -15,14 +15,14 @@ export declare function readSchedulerState(name: string): WatchdogSchedulerState
 /** Write never throws: scheduler diagnostics must never take the loop down. */
 export declare function writeSchedulerState(name: string, s: WatchdogSchedulerState): void;
 /**
- * Operator release (Task 15): clears failures and heldDown so a held-down
+ * Operator release clears failures and heldDown so a held-down
  * loop's next held-down poll sees a clean state and resumes running. Also
  * clears the ledger's `heldDownAlerted` flag — that flag is what makes "alert
  * once per hold-down" durable across scheduler restarts (it lives in
  * alerts.json, not state.json), so a release must reset it too or a
  * subsequent hold-down would silently alert zero times.
  *
- * Also reclaims a STALE run lock (final review #2, tightened by finding #2):
+ * Also reclaims a demonstrably stale run lock:
  * a watchdog SIGKILLed mid-run (e.g. systemd's TimeoutStopSec on a
  * fleet-wide stop) leaves `.run-lock` behind forever — the loop's `finally`
  * that would normally release it never runs. Without this, every future tick
@@ -40,7 +40,7 @@ export declare function writeSchedulerState(name: string, s: WatchdogSchedulerSt
 export declare function resetSchedulerState(name: string): void;
 export declare const WATCHDOG_HOLD_THRESHOLD = 3;
 export declare const WATCHDOG_BACKOFF_MAX_MS = 3600000;
-/** Bounded exponential backoff: 1x, 2x, 4x, ... capped at WATCHDOG_BACKOFF_MAX_MS (spec §3). */
+/** Bounded exponential backoff: 1x, 2x, 4x, ... capped at WATCHDOG_BACKOFF_MAX_MS. */
 export declare function watchdogBackoffMs(intervalMs: number, failures: number): number;
 export interface SchedulerDeps {
     now(): Date;
@@ -49,7 +49,7 @@ export interface SchedulerDeps {
     binPath: string;
     /**
      * The fleet config `runScheduler` loaded from the `-c FILE`/default path
-     * (final review #1). Threaded into both `runOnceFor`'s and the notifier's
+     * Threaded into both `runOnceFor`'s and the notifier's
      * deps so a run under a non-default config doesn't silently fall back to
      * `loadConfig()`'s default `~/fleet.yaml`. `runWatchdogLoop` callers that
      * bypass `runScheduler` (tests) may omit it — the run/notifier machinery
@@ -61,7 +61,7 @@ export interface SchedulerDeps {
     /** Loop exit for tests + SIGTERM (wired by the CLI, not here). */
     shouldStop?(): boolean;
     /**
-     * Scheduler-level alert hook (Task 14, spec §5.5): fired once per hold-down
+     * Scheduler-level alert hook: fired once per hold-down
      * transition (guarded in `settle` by `ledger.heldDownAlerted`, cleared by
      * `resetSchedulerState`). Default: `executeNotifierRun` — the fleet
      * process can't message on its own (deviation 4), so the default delivers
@@ -82,7 +82,7 @@ export interface SchedulerDeps {
      * Injectable run-lock primitives. Default: store's acquireRunLock /
      * releaseRunLock. Both are mkdir/rmdir-backed and can throw (EACCES, EIO,
      * ENOTEMPTY on release) — the loop always classifies such a throw as a
-     * failed tick rather than letting it escape (review finding #1).
+     * failed tick rather than letting it escape.
      */
     locks?: {
         acquire(name: string): boolean;
@@ -99,7 +99,7 @@ export interface SchedulerDeps {
 export declare function runWatchdogLoop(wd: ResolvedWatchdog, deps: SchedulerDeps): Promise<void>;
 /**
  * Run every enabled watchdog's loop concurrently until deps.shouldStop().
- * SIGTERM wiring into shouldStop is the CLI's job (Task 10), not this
+ * SIGTERM wiring into shouldStop is the CLI's job, not this
  * function's.
  */
 export declare function runScheduler(configPath: string | undefined, deps: SchedulerDeps): Promise<void>;

package/dist/watchdog/scheduler.js

@@ -27,14 +27,14 @@ export function writeSchedulerState(name, s) {
     catch { /* diagnostics must never take the loop down */ }
 }
 /**
- * Operator release (Task 15): clears failures and heldDown so a held-down
+ * Operator release clears failures and heldDown so a held-down
  * loop's next held-down poll sees a clean state and resumes running. Also
  * clears the ledger's `heldDownAlerted` flag — that flag is what makes "alert
  * once per hold-down" durable across scheduler restarts (it lives in
  * alerts.json, not state.json), so a release must reset it too or a
  * subsequent hold-down would silently alert zero times.
  *
- * Also reclaims a STALE run lock (final review #2, tightened by finding #2):
+ * Also reclaims a demonstrably stale run lock:
  * a watchdog SIGKILLed mid-run (e.g. systemd's TimeoutStopSec on a
  * fleet-wide stop) leaves `.run-lock` behind forever — the loop's `finally`
  * that would normally release it never runs. Without this, every future tick
@@ -61,7 +61,7 @@ export function resetSchedulerState(name) {
 }
 export const WATCHDOG_HOLD_THRESHOLD = 3;
 export const WATCHDOG_BACKOFF_MAX_MS = 3_600_000;
-/** Bounded exponential backoff: 1x, 2x, 4x, ... capped at WATCHDOG_BACKOFF_MAX_MS (spec §3). */
+/** Bounded exponential backoff: 1x, 2x, 4x, ... capped at WATCHDOG_BACKOFF_MAX_MS. */
 export function watchdogBackoffMs(intervalMs, failures) {
     if (failures <= 0)
         return intervalMs;
@@ -91,7 +91,7 @@ export async function runWatchdogLoop(wd, deps) {
      * before the next tick. On the tick that transitions into hold-down, sleep
      * `heldPollMs` rather than the (possibly hour-long) backoff delay — an
      * operator's resetSchedulerState must be noticed within one poll cycle,
-     * not after the last backoff finishes (review finding #2).
+     * not after the last backoff finishes.
      */
     const settle = async (isFailure, errorMessage, startedAt) => {
         const s = readSchedulerState(wd.name);
@@ -116,7 +116,7 @@ export async function runWatchdogLoop(wd, deps) {
         if (justHeld) {
             const msg = `watchdog ${wd.name} held down after ${WATCHDOG_HOLD_THRESHOLD} consecutive failed runs: ${s.lastError}`;
             deps.log(msg);
-            // "Once per state change" (spec §5.5) must survive a scheduler restart, so the guard
+            // "Once per state change" must survive a scheduler restart, so the guard
             // lives in the ledger (alerts.json), not in memory — resetSchedulerState clears it.
             const ledger = readLedger(wd.name);
             if (!ledger.heldDownAlerted) {
@@ -141,7 +141,7 @@ export async function runWatchdogLoop(wd, deps) {
         // rethrows non-ENOENT failures). Never let that throw escape this loop:
         // runScheduler drives every watchdog's loop via Promise.all, so an
         // uncaught throw here would kill every OTHER watchdog's loop too.
-        // Classify it as this tick's failure instead (review finding #1).
+        // Classify it as this tick's failure instead.
         let acquired = false;
         let acquireError;
         try {
@@ -166,7 +166,7 @@ export async function runWatchdogLoop(wd, deps) {
             // Failure count is untouched by a skip; only lastRunAt/nextRunAt move.
             // The backoff cadence (not the raw interval) still governs during an
             // active failure streak: a skip isn't a finished run, so it shouldn't
-            // reset the retry cadence to full speed either (spec §3).
+            // reset the retry cadence to full speed either.
             const skipState = readSchedulerState(wd.name);
             const delay = watchdogBackoffMs(wd.intervalMs, skipState.consecutiveFailures);
             writeSchedulerState(wd.name, {
@@ -216,14 +216,14 @@ export async function runWatchdogLoop(wd, deps) {
 }
 /**
  * Run every enabled watchdog's loop concurrently until deps.shouldStop().
- * SIGTERM wiring into shouldStop is the CLI's job (Task 10), not this
+ * SIGTERM wiring into shouldStop is the CLI's job, not this
  * function's.
  */
 export async function runScheduler(configPath, deps) {
     const cfg = loadConfig(configPath);
     const watchdogs = cfg.watchdogs.filter(w => w.enabled);
-    // Recover from a SIGKILLed prior run (final review #2a, tightened by
-    // finding #2): a scheduler restart is EVIDENCE, not proof, that no
+    // Recover from a SIGKILLed prior run: a scheduler restart is EVIDENCE,
+    // not proof, that no
     // scheduler-owned run is in flight — a foreground `watchdog-run`, or
     // another scheduler instance, may genuinely still hold a watchdog's lock.
     // Only a DEMONSTRABLY stale lock (dead owner pid, or a legacy lock with no

package/dist/watchdog/service.d.ts

@@ -3,7 +3,7 @@ export declare const WATCHDOG_SYSTEMD_UNIT = "ours-fleet-watchdogs.service";
 export declare const WATCHDOG_LAUNCHD_LABEL = "network.ours.fleet.watchdogs";
 /**
  * Supervises the single long-running watchdog-scheduler process (the hidden
- * `_run-watchdogs` command, Task 9's `runScheduler`) the same way
+ * `_run-watchdogs` command and `runScheduler`) the same way
  * `WebServiceManager` (src/web/service.ts) supervises the web console: a
  * private systemd --user unit on Linux, a launchd LaunchAgent on macOS.
  */
@@ -16,7 +16,7 @@ export declare class WatchdogServiceManager {
     supervised(): boolean;
     /**
      * Writes the unit/plist and returns whether its content actually changed
-     * (finding #4): `binPath`/`configPath` are the only inputs that ever
+     * `binPath`/`configPath` are the only inputs that ever
      * change this content, and neither reflects a watchdog's `interval:` or
      * any other config value inside `watchdogs:` — so `changed` here can never
      * by itself justify a restart on every config edit. It's one of the two
@@ -33,8 +33,8 @@ export declare class WatchdogServiceManager {
      * a running service just returns 0 without reloading anything, and
      * launchctl kickstart (without -k) behaves the same way. That means a
      * config change (new/changed watchdogs) never reaches a live scheduler
-     * process via reconcileWatchdogScheduler's `install` + `start` pair (final
-     * review #4). `restart()` mirrors WebServiceManager.restart: an
+     * process via reconcileWatchdogScheduler's `install` + `start` pair.
+     * `restart()` mirrors WebServiceManager.restart: an
      * unconditional restart on Linux, and `kickstart -k` (force-restart) on
      * macOS, falling back to stop+start if the kickstart itself fails.
      */