@ours.network/fleet 0.10.4 → 0.11.0

package/dist/watchdog/service.d.ts

@@ -0,0 +1,46 @@
+import { type Exec } from '../exec.js';
+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
+ * `WebServiceManager` (src/web/service.ts) supervises the web console: a
+ * private systemd --user unit on Linux, a launchd LaunchAgent on macOS.
+ */
+export declare class WatchdogServiceManager {
+    private readonly exec;
+    private readonly platform;
+    constructor(exec?: Exec, platform?: NodeJS.Platform);
+    get definitionPath(): string;
+    /** false when explicitly disabled (OURS_FLEET_SUPERVISOR=none) or on an unsupported platform. */
+    supervised(): boolean;
+    /**
+     * Writes the unit/plist and returns whether its content actually changed
+     * (finding #4): `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
+     * signals reconcileWatchdogScheduler (ops.ts) combines with a config
+     * fingerprint before deciding restart vs. the idempotent start.
+     */
+    install(binPath: string, configPath?: string): Promise<{
+        changed: boolean;
+    }>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * `start()` is a no-op on an already-active unit — systemctl start against
+     * 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
+     * unconditional restart on Linux, and `kickstart -k` (force-restart) on
+     * macOS, falling back to stop+start if the kickstart itself fails.
+     */
+    restart(): Promise<void>;
+    status(): Promise<string>;
+    uninstall(): Promise<void>;
+    private requireInstalled;
+    private must;
+}

package/dist/watchdog/service.js

@@ -0,0 +1,179 @@
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { replaceFileAtomically } from '../atomic-file.js';
+import { FleetError } from '../application/errors.js';
+import { realExec } from '../exec.js';
+import { home } from '../paths.js';
+export const WATCHDOG_SYSTEMD_UNIT = 'ours-fleet-watchdogs.service';
+export 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
+ * `WebServiceManager` (src/web/service.ts) supervises the web console: a
+ * private systemd --user unit on Linux, a launchd LaunchAgent on macOS.
+ */
+export class WatchdogServiceManager {
+    exec;
+    platform;
+    constructor(exec = realExec, platform = process.platform) {
+        this.exec = exec;
+        this.platform = platform;
+    }
+    get definitionPath() {
+        return this.platform === 'linux'
+            ? join(home(), '.config', 'systemd', 'user', WATCHDOG_SYSTEMD_UNIT)
+            : join(home(), 'Library', 'LaunchAgents', `${WATCHDOG_LAUNCHD_LABEL}.plist`);
+    }
+    /** false when explicitly disabled (OURS_FLEET_SUPERVISOR=none) or on an unsupported platform. */
+    supervised() {
+        if (process.env.OURS_FLEET_SUPERVISOR === 'none')
+            return false;
+        return this.platform === 'linux' || this.platform === 'darwin';
+    }
+    /**
+     * Writes the unit/plist and returns whether its content actually changed
+     * (finding #4): `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
+     * signals reconcileWatchdogScheduler (ops.ts) combines with a config
+     * fingerprint before deciding restart vs. the idempotent start.
+     */
+    async install(binPath, configPath) {
+        const resolvedScript = resolveExecutable(binPath, 'ours-fleet CLI script');
+        const runtime = resolveExecutable(process.execPath, 'Node runtime');
+        const config = configPath ? resolve(configPath) : undefined;
+        const content = this.platform === 'linux'
+            ? watchdogSystemdUnit(runtime, resolvedScript, config)
+            : watchdogLaunchdPlist(runtime, resolvedScript, config);
+        let previous;
+        try {
+            previous = readFileSync(this.definitionPath, 'utf8');
+        }
+        catch { /* absent: definitely changed */ }
+        const changed = previous !== content;
+        mkdirSync(dirname(this.definitionPath), { recursive: true, mode: 0o700 });
+        replaceFileAtomically(this.definitionPath, content, 0o600);
+        if (this.platform === 'linux') {
+            await this.must('systemctl', ['--user', 'daemon-reload']);
+            await this.must('systemctl', ['--user', 'enable', WATCHDOG_SYSTEMD_UNIT]);
+        }
+        return { changed };
+    }
+    async start() {
+        this.requireInstalled();
+        if (this.platform === 'linux') {
+            await this.must('systemctl', ['--user', 'start', WATCHDOG_SYSTEMD_UNIT]);
+            return;
+        }
+        const domain = `gui/${uid()}`;
+        const loaded = await this.exec('launchctl', ['print', `${domain}/${WATCHDOG_LAUNCHD_LABEL}`]);
+        if (loaded.code === 0)
+            await this.must('launchctl', ['kickstart', `${domain}/${WATCHDOG_LAUNCHD_LABEL}`]);
+        else
+            await this.must('launchctl', ['bootstrap', domain, this.definitionPath]);
+    }
+    async stop() {
+        if (this.platform === 'linux') {
+            // Tolerate "not loaded" (systemctl exit 5) the same way the launchd
+            // branch below tolerates "could not find service": a watchdog-less
+            // fleet's `up`/`down` calls stop() defensively even when the unit was
+            // never installed, and that must not surface as an error (final
+            // review #3).
+            const result = await this.exec('systemctl', ['--user', 'stop', WATCHDOG_SYSTEMD_UNIT]);
+            if (result.code !== 0 && result.code !== 5 && !/not loaded/i.test(`${result.stdout}\n${result.stderr}`))
+                throw new FleetError('control_unavailable', `systemctl --user stop ${WATCHDOG_SYSTEMD_UNIT} failed: ${result.stderr.trim() || `exit ${result.code}`}`);
+            return;
+        }
+        const result = await this.exec('launchctl', ['bootout', `gui/${uid()}/${WATCHDOG_LAUNCHD_LABEL}`]);
+        if (result.code !== 0 && !/could not find service|no such process/i.test(`${result.stdout}\n${result.stderr}`))
+            throw new FleetError('control_unavailable', `launchctl bootout failed: ${result.stderr.trim()}`);
+    }
+    /**
+     * `start()` is a no-op on an already-active unit — systemctl start against
+     * 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
+     * unconditional restart on Linux, and `kickstart -k` (force-restart) on
+     * macOS, falling back to stop+start if the kickstart itself fails.
+     */
+    async restart() {
+        this.requireInstalled();
+        if (this.platform === 'linux') {
+            await this.must('systemctl', ['--user', 'restart', WATCHDOG_SYSTEMD_UNIT]);
+            return;
+        }
+        const result = await this.exec('launchctl', ['kickstart', '-k', `gui/${uid()}/${WATCHDOG_LAUNCHD_LABEL}`]);
+        if (result.code !== 0) {
+            await this.stop();
+            await this.start();
+        }
+    }
+    async status() {
+        if (this.platform === 'linux') {
+            const result = await this.exec('systemctl', [
+                '--user', 'show', WATCHDOG_SYSTEMD_UNIT, '-p', 'LoadState', '-p', 'ActiveState',
+                '-p', 'SubState', '-p', 'ExecMainPID', '--no-pager',
+            ]);
+            return result.stdout.trim() || result.stderr.trim() || `exit ${result.code}`;
+        }
+        const result = await this.exec('launchctl', ['print', `gui/${uid()}/${WATCHDOG_LAUNCHD_LABEL}`]);
+        return result.code === 0 ? result.stdout.trim() : `not loaded (${WATCHDOG_LAUNCHD_LABEL})`;
+    }
+    async uninstall() {
+        if (this.platform === 'linux') {
+            await this.exec('systemctl', ['--user', 'disable', '--now', WATCHDOG_SYSTEMD_UNIT]);
+            rmSync(this.definitionPath, { force: true });
+            await this.exec('systemctl', ['--user', 'daemon-reload']);
+        }
+        else {
+            await this.stop();
+            rmSync(this.definitionPath, { force: true });
+        }
+    }
+    requireInstalled() {
+        if (!existsSync(this.definitionPath))
+            throw new FleetError('prerequisite_unavailable', 'watchdog scheduler service is not installed');
+    }
+    async must(command, args) {
+        const result = await this.exec(command, args);
+        if (result.code !== 0)
+            throw new FleetError('control_unavailable', `${command} ${args.join(' ')} failed: ${result.stderr.trim() || `exit ${result.code}`}`);
+    }
+}
+function uid() { return process.getuid?.() ?? 501; }
+function resolveExecutable(executable, label) {
+    const absolute = isAbsolute(executable) ? executable : resolve(executable);
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        throw new FleetError('prerequisite_unavailable', `${label} does not exist: ${absolute}`);
+    }
+}
+function systemdQuote(value) {
+    return `"${value.replace(/[%\\"]/g, char => char === '%' ? '%%' : `\\${char}`)}"`;
+}
+function watchdogSystemdUnit(runtime, script, configuration) {
+    const config = configuration ? ` -c ${systemdQuote(configuration)}` : '';
+    return `[Unit]\nDescription=ours-fleet watchdog scheduler\nAfter=default.target\n\n`
+        + `[Service]\nType=simple\nExecStart=${systemdQuote(runtime)} ${systemdQuote(script)} _run-watchdogs${config}\n`
+        + `Restart=on-failure\nRestartSec=5\nTimeoutStopSec=15\n\n`
+        + `[Install]\nWantedBy=default.target\n`;
+}
+const xml = (value) => value.replace(/[&<>"']/g, char => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;',
+}[char]));
+function watchdogLaunchdPlist(runtime, script, configuration) {
+    const config = configuration
+        ? `<string>-c</string><string>${xml(configuration)}</string>` : '';
+    return `<?xml version="1.0" encoding="UTF-8"?>\n`
+        + `<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n`
+        + `<plist version="1.0"><dict>\n<key>Label</key><string>${WATCHDOG_LAUNCHD_LABEL}</string>\n`
+        + `<key>ProgramArguments</key><array><string>${xml(runtime)}</string><string>${xml(script)}</string>`
+        + `<string>_run-watchdogs</string>${config}</array>\n`
+        + `<key>RunAtLoad</key><true/><key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>\n`
+        + `<key>ProcessType</key><string>Background</string>\n</dict></plist>\n`;
+}

package/dist/watchdog/store.d.ts

@@ -0,0 +1,85 @@
+import type { WatchdogReport, WatchdogReportStatus } from './report.js';
+/**
+ * A lock directory briefly exists before acquireRunLock can rename its
+ * prewritten owner.json into it. Missing/corrupt owner metadata is therefore
+ * reclaimable only after this grace period, never while that acquisition
+ * window may still be in progress.
+ */
+export declare const RUN_LOCK_OWNER_GRACE_MS = 10000;
+/**
+ * Choke point every other helper in this module goes through to reach a
+ * watchdog's on-disk state. Validates `name` BEFORE any join/mkdir (defense
+ * in depth, finding #1): a caller that forgets its own ROLE_NAME_RE guard
+ * (as the CLI's `watchdogKnown` once did) must not be able to turn an
+ * unvalidated `name` into `join(watchdogsRoot(), '../../victim')` and mkdir
+ * an arbitrary path on disk.
+ */
+export declare function watchdogDir(name: string): string;
+export declare function reportsDir(name: string): string;
+export interface RunLockOwner {
+    pid: number;
+    at: string;
+}
+/**
+ * mkdir-as-mutex: atomic across processes, unlike a lock file (open+O_EXCL
+ * would work too, but a directory needs no cleanup of file contents and
+ * can't be partially written). EEXIST means another run holds it.
+ *
+ * Stamps `owner.json` with our pid (finding #2): ownership metadata is what
+ * lets a later `reclaimStaleRunLock` tell a lock abandoned by a dead process
+ * apart from one genuinely held by a live run. A naive "mkdir, then
+ * writeFileSync(owner.json)" leaves an unnecessarily wide window —
+ * between the mkdir succeeding and the write landing — where the lock dir
+ * exists but owner.json doesn't yet. A `reclaimStaleRunLock` call from
+ * another process landing in exactly that window would see a lock with no
+ * (or corrupt) owner metadata and treat a genuinely live lock as a legacy
+ * one, reclaiming it out from under us. Do all slow work (building the JSON,
+ * writing it, chmod) to a per-pid temp file BEFORE mkdir, then publish it with
+ * one rename. There is still an unavoidable interval between those two
+ * syscalls; reclaimStaleRunLock protects it by treating a fresh ownerless lock
+ * as held for RUN_LOCK_OWNER_GRACE_MS. The temp file is unique per-pid (this
+ * function is synchronous, so there's no same-process concurrent-call hazard
+ * either) and is cleaned up if mkdir loses the race.
+ */
+export declare function acquireRunLock(name: string): boolean;
+/**
+ * Release-tolerant of absence: a lock already gone (or never acquired) is not
+ * an error. Recursive because the lock dir now holds `owner.json` alongside
+ * the mkdir mutex itself (finding #2) — a plain rmdir would fail ENOTEMPTY.
+ */
+export declare function releaseRunLock(name: string): void;
+/** Reads a run lock's owner metadata; missing or corrupt yields undefined. */
+export declare function readRunLockOwner(name: string): RunLockOwner | undefined;
+/**
+ * Owner-mandated (finding #2): only a DEMONSTRABLY stale run lock may be
+ * reclaimed — a lock is stale iff it isn't held at all, its owner metadata
+ * names a dead pid, or its owner metadata is missing/corrupt AND the lock dir
+ * is older than RUN_LOCK_OWNER_GRACE_MS. The age gate closes the interprocess
+ * interval between acquireRunLock's mkdir and owner.json rename: a concurrent
+ * scheduler sees a fresh ownerless lock as held, not stale. A live owner (a
+ * foreground `watchdog-run`, another scheduler instance, an in-progress run)
+ * is left strictly alone: reclaiming it would let two runs share the same temp
+ * dir.
+ * Returns true when the lock is (now) not held — whether because it was
+ * already absent or because a stale lock was just removed; false when a live
+ * lock was found and deliberately left in place.
+ */
+export declare function reclaimStaleRunLock(name: string): boolean;
+/** Lexical-chronological UTC run id, e.g. '20260731T115000Z'. */
+export declare function formatRunId(d: Date): string;
+export interface RunListEntry {
+    runId: string;
+    status: WatchdogReportStatus;
+    startedAt: string;
+    finishedAt: string;
+    summary: WatchdogReport['summary'];
+    error: string | null;
+}
+export declare function writeReport(name: string, report: WatchdogReport): string;
+/** Newest-first run listing; a corrupt report file yields a synthetic 'error' entry rather than throwing. */
+export declare function listRuns(name: string): RunListEntry[];
+/** Reads one run's full report. Rejects non-conforming runIds (path-traversal guard) and corrupt files by returning undefined. */
+export declare function readReport(name: string, runId: string): WatchdogReport | undefined;
+export declare function latestReport(name: string): WatchdogReport | undefined;
+/** Deletes all but the `keep` newest reports (oldest first); returns the number pruned. */
+export declare function pruneReports(name: string, keep: number): number;

package/dist/watchdog/store.js

@@ -0,0 +1,226 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { watchdogsRoot } from '../paths.js';
+// store.ts imports config.ts (ROLE_NAME_RE) but not the reverse — config.ts's
+// import graph (config-yaml, isolation/policy, harness/registry, watchdog/config)
+// never reaches back into watchdog/store.ts, so this does not create a cycle.
+import { ROLE_NAME_RE } from '../config.js';
+const RUN_ID_RE = /^\d{8}T\d{6}Z$/;
+const REPORT_FILE_RE = /^\d{8}T\d{6}Z\.json$/;
+/**
+ * A lock directory briefly exists before acquireRunLock can rename its
+ * prewritten owner.json into it. Missing/corrupt owner metadata is therefore
+ * reclaimable only after this grace period, never while that acquisition
+ * window may still be in progress.
+ */
+export const RUN_LOCK_OWNER_GRACE_MS = 10_000;
+/**
+ * mkdirSync's `mode` is masked by the process umask and ignored outright when
+ * the directory already exists, so an explicit chmod after mkdir is the only
+ * way to guarantee 0700 regardless of umask or prior state.
+ */
+function ensureDir(dir) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+    return dir;
+}
+/**
+ * Choke point every other helper in this module goes through to reach a
+ * watchdog's on-disk state. Validates `name` BEFORE any join/mkdir (defense
+ * in depth, finding #1): a caller that forgets its own ROLE_NAME_RE guard
+ * (as the CLI's `watchdogKnown` once did) must not be able to turn an
+ * unvalidated `name` into `join(watchdogsRoot(), '../../victim')` and mkdir
+ * an arbitrary path on disk.
+ */
+export function watchdogDir(name) {
+    if (!ROLE_NAME_RE.test(name))
+        throw new Error(`invalid watchdog name '${name}'`);
+    return ensureDir(join(watchdogsRoot(), name));
+}
+export function reportsDir(name) {
+    return ensureDir(join(watchdogDir(name), 'reports'));
+}
+function runLockPath(name) {
+    return join(watchdogDir(name), '.run-lock');
+}
+function runLockOwnerPath(name) {
+    return join(runLockPath(name), 'owner.json');
+}
+/**
+ * mkdir-as-mutex: atomic across processes, unlike a lock file (open+O_EXCL
+ * would work too, but a directory needs no cleanup of file contents and
+ * can't be partially written). EEXIST means another run holds it.
+ *
+ * Stamps `owner.json` with our pid (finding #2): ownership metadata is what
+ * lets a later `reclaimStaleRunLock` tell a lock abandoned by a dead process
+ * apart from one genuinely held by a live run. A naive "mkdir, then
+ * writeFileSync(owner.json)" leaves an unnecessarily wide window —
+ * between the mkdir succeeding and the write landing — where the lock dir
+ * exists but owner.json doesn't yet. A `reclaimStaleRunLock` call from
+ * another process landing in exactly that window would see a lock with no
+ * (or corrupt) owner metadata and treat a genuinely live lock as a legacy
+ * one, reclaiming it out from under us. Do all slow work (building the JSON,
+ * writing it, chmod) to a per-pid temp file BEFORE mkdir, then publish it with
+ * one rename. There is still an unavoidable interval between those two
+ * syscalls; reclaimStaleRunLock protects it by treating a fresh ownerless lock
+ * as held for RUN_LOCK_OWNER_GRACE_MS. The temp file is unique per-pid (this
+ * function is synchronous, so there's no same-process concurrent-call hazard
+ * either) and is cleaned up if mkdir loses the race.
+ */
+export function acquireRunLock(name) {
+    const dir = watchdogDir(name);
+    const owner = { pid: process.pid, at: new Date().toISOString() };
+    const tempOwnerPath = join(dir, `.owner.${process.pid}.tmp`);
+    writeFileSync(tempOwnerPath, JSON.stringify(owner), { mode: 0o600 });
+    chmodSync(tempOwnerPath, 0o600);
+    try {
+        mkdirSync(runLockPath(name));
+    }
+    catch (e) {
+        try {
+            unlinkSync(tempOwnerPath);
+        }
+        catch { /* best effort cleanup */ }
+        if (e.code === 'EEXIST')
+            return false;
+        throw e;
+    }
+    renameSync(tempOwnerPath, runLockOwnerPath(name));
+    return true;
+}
+/**
+ * Release-tolerant of absence: a lock already gone (or never acquired) is not
+ * an error. Recursive because the lock dir now holds `owner.json` alongside
+ * the mkdir mutex itself (finding #2) — a plain rmdir would fail ENOTEMPTY.
+ */
+export function releaseRunLock(name) {
+    try {
+        rmSync(runLockPath(name), { recursive: true });
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return;
+        throw e;
+    }
+}
+/** Reads a run lock's owner metadata; missing or corrupt yields undefined. */
+export function readRunLockOwner(name) {
+    try {
+        const raw = JSON.parse(readFileSync(runLockOwnerPath(name), 'utf8'));
+        if (!Number.isInteger(raw.pid) || raw.pid <= 0 || typeof raw.at !== 'string')
+            return undefined;
+        return { pid: raw.pid, at: raw.at };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** True iff `pid` names a live process. EPERM means the process exists but we can't signal it — still alive. */
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+/**
+ * Owner-mandated (finding #2): only a DEMONSTRABLY stale run lock may be
+ * reclaimed — a lock is stale iff it isn't held at all, its owner metadata
+ * names a dead pid, or its owner metadata is missing/corrupt AND the lock dir
+ * is older than RUN_LOCK_OWNER_GRACE_MS. The age gate closes the interprocess
+ * interval between acquireRunLock's mkdir and owner.json rename: a concurrent
+ * scheduler sees a fresh ownerless lock as held, not stale. A live owner (a
+ * foreground `watchdog-run`, another scheduler instance, an in-progress run)
+ * is left strictly alone: reclaiming it would let two runs share the same temp
+ * dir.
+ * Returns true when the lock is (now) not held — whether because it was
+ * already absent or because a stale lock was just removed; false when a live
+ * lock was found and deliberately left in place.
+ */
+export function reclaimStaleRunLock(name) {
+    const path = runLockPath(name);
+    if (!existsSync(path))
+        return true;
+    const owner = readRunLockOwner(name);
+    if (owner !== undefined && pidAlive(owner.pid))
+        return false;
+    if (owner === undefined) {
+        try {
+            if (Date.now() - statSync(path).mtimeMs < RUN_LOCK_OWNER_GRACE_MS)
+                return false;
+        }
+        catch (e) {
+            // The holder may have released between existsSync and statSync.
+            if (e.code === 'ENOENT')
+                return true;
+            throw e;
+        }
+    }
+    releaseRunLock(name);
+    return true;
+}
+/** Lexical-chronological UTC run id, e.g. '20260731T115000Z'. */
+export function formatRunId(d) {
+    return d.toISOString().replace(/\.\d{3}Z$/, 'Z').replace(/[-:]/g, '');
+}
+const CORRUPT_SUMMARY = { checked: 0, healthy: 0, idle: 0, anomalies: 0 };
+function reportPath(name, runId) {
+    return join(reportsDir(name), `${runId}.json`);
+}
+/** Newest-first run ids currently on disk, derived from filenames alone. */
+function runIdsDesc(name) {
+    return readdirSync(reportsDir(name))
+        .filter(f => REPORT_FILE_RE.test(f))
+        .sort()
+        .reverse()
+        .map(f => f.slice(0, -'.json'.length));
+}
+export function writeReport(name, report) {
+    const path = reportPath(name, report.run_id);
+    writeFileSync(path, JSON.stringify(report, null, 2) + '\n', { mode: 0o600 });
+    chmodSync(path, 0o600);
+    return path;
+}
+/** Newest-first run listing; a corrupt report file yields a synthetic 'error' entry rather than throwing. */
+export function listRuns(name) {
+    return runIdsDesc(name).map((runId) => {
+        try {
+            const report = JSON.parse(readFileSync(reportPath(name, runId), 'utf8'));
+            return {
+                runId, status: report.status, startedAt: report.started_at, finishedAt: report.finished_at,
+                summary: report.summary, error: report.error,
+            };
+        }
+        catch {
+            return { runId, status: 'error', startedAt: '', finishedAt: '', summary: CORRUPT_SUMMARY, error: 'unreadable report file' };
+        }
+    });
+}
+/** Reads one run's full report. Rejects non-conforming runIds (path-traversal guard) and corrupt files by returning undefined. */
+export function readReport(name, runId) {
+    if (!RUN_ID_RE.test(runId))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(reportPath(name, runId), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function latestReport(name) {
+    const [newest] = runIdsDesc(name);
+    return newest === undefined ? undefined : readReport(name, newest);
+}
+/** Deletes all but the `keep` newest reports (oldest first); returns the number pruned. */
+export function pruneReports(name, keep) {
+    const stale = runIdsDesc(name).slice(keep);
+    for (const runId of stale) {
+        try {
+            unlinkSync(reportPath(name, runId));
+        }
+        catch { /* best effort */ }
+    }
+    return stale.length;
+}

package/dist/web/runtime.js

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
 import { existsSync, realpathSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { loadConfig } from '../config.js';
 import { RoleRepository } from '../application/role-repository.js';
 import { FleetQueryService } from '../application/fleet-query-service.js';
 import { AcpRoleSessionAdapter, TmuxRoleSessionAdapter } from '../application/session-control.js';
@@ -21,6 +22,24 @@ import { acquireWebServerLock } from './lock.js';
 import { TrustedDeviceStore } from './device-store.js';
 import { WebAuth } from './auth.js';
 import { startWebControlServer } from './control.js';
+import { buildWatchdogFindings, cachedWatchdogFindingsProvider, WatchdogQueryService } from '../watchdog/query.js';
+import { latestReport } from '../watchdog/store.js';
+const CONFIG_CACHE_TTL_MS = 5_000;
+/**
+ * loadConfig re-parses YAML from disk on every call; the watchdog list/reports
+ * routes get polled by the console UI, so cache the resolved config for a
+ * short TTL rather than re-parsing per request. Runtime-only concern (not the
+ * scheduler's), so a plain Date.now() clock is fine.
+ */
+function cachedConfigProvider(configPath) {
+    let cached;
+    return () => {
+        const now = Date.now();
+        if (!cached || now - cached.at >= CONFIG_CACHE_TTL_MS)
+            cached = { at: now, cfg: loadConfig(configPath) };
+        return cached.cfg;
+    };
+}
 export async function startWebConsole(options) {
     const requestedPort = options.port ?? 49_271;
     if (!Number.isInteger(requestedPort) || requestedPort < 0 || requestedPort > 65_535)
@@ -51,11 +70,35 @@ export async function startWebConsole(options) {
     const audit = new AuditSink();
     const terminals = new TerminalBridgeManager({ repository, audit, tmux });
     const terminalAvailable = await terminals.available();
+    const watchdogConfigProvider = cachedConfigProvider(options.configPath);
+    const log = options.log ?? (() => { });
+    let loggedWatchdogFindingsError = false;
+    // Needs-attention integration (Task 19): worst per-role watchdog finding,
+    // rebuilt from stored reports. A store hiccup (corrupt state, unreadable
+    // report) must never break the fleet list, so it degrades to an empty map
+    // and logs once rather than repeating on every poll. status() calls this
+    // once per role, so list()'s O(roles) sweep would otherwise cost
+    // O(roles x watchdogs) disk reads every 1-3s of console polling —
+    // cachedWatchdogFindingsProvider memoizes the whole build behind the same
+    // TTL as the config cache above.
+    const watchdogFindings = cachedWatchdogFindingsProvider(() => {
+        try {
+            return buildWatchdogFindings(watchdogConfigProvider(), latestReport);
+        }
+        catch (error) {
+            if (!loggedWatchdogFindingsError) {
+                loggedWatchdogFindingsError = true;
+                log(`watchdog findings unavailable: ${error.message}`);
+            }
+            return new Map();
+        }
+    }, CONFIG_CACHE_TTL_MS);
     const query = new FleetQueryService({
         repository, supervisor: backend, tmux,
         capabilityContext: { terminalPtyAvailable: terminalAvailable },
+        watchdogFindings,
     });
-    const ops = { backend, binPath: options.binPath, log: options.log ?? (() => { }) };
+    const ops = { backend, binPath: options.binPath, log };
     const creation = new RoleCreationService({
         configPath: options.configPath, ops, binPath: options.binPath,
         allowedCwdRoots: [realpathSync(home()), realpathSync(process.cwd())],
@@ -84,10 +127,11 @@ export async function startWebConsole(options) {
         },
     });
     const logs = new StructuredLogService(backend, realExec);
+    const watchdogs = new WatchdogQueryService(watchdogConfigProvider);
     let server;
     try {
         server = await buildWebServer({
-            query, repository, logs, commands, creation, audit, events,
+            query, repository, logs, commands, creation, audit, events, watchdogs,
             terminalUpgrade: terminalAvailable
                 ? async (socket, _request, roleId, _ticket, hello) => terminals.connect(socket, roleId, hello)
                 : undefined,

package/dist/web/server.d.ts

@@ -6,6 +6,7 @@ import type { RoleSessionControl } from '../application/session-control.js';
 import type { StructuredLogService } from '../application/log-service.js';
 import type { RoleCommandService } from '../application/role-command-service.js';
 import type { RoleCreationService } from '../application/role-creation-service.js';
+import type { WatchdogQueryService } from '../watchdog/query.js';
 import { AuditSink } from './audit.js';
 import { WebAuth } from './auth.js';
 import { FleetEventBus } from './events.js';
@@ -18,6 +19,7 @@ export interface WebServices {
     creation: RoleCreationService;
     audit?: AuditSink;
     events?: FleetEventBus;
+    watchdogs?: WatchdogQueryService;
     terminalUpgrade?: (socket: WebSocket, request: FastifyRequest, roleId: string, ticket: string, hello: Record<string, unknown>) => Promise<void>;
 }
 export interface WebServer {

package/dist/web/server.js

@@ -186,6 +186,24 @@ export async function buildWebServer(services, boundary, options = {}) {
         auth.authenticate(request);
         return { records: audit.list() };
     });
+    app.get('/api/v1/watchdogs', async (request) => {
+        auth.authenticate(request);
+        if (!services.watchdogs)
+            throw new FleetError('capability_unavailable', 'watchdogs are unavailable');
+        return services.watchdogs.list();
+    });
+    app.get('/api/v1/watchdogs/:name/reports', async (request) => {
+        auth.authenticate(request);
+        if (!services.watchdogs)
+            throw new FleetError('capability_unavailable', 'watchdogs are unavailable');
+        return services.watchdogs.reports(request.params.name, request.query.limit ? Number(request.query.limit) : undefined);
+    });
+    app.get('/api/v1/watchdogs/:name/reports/:runId', async (request) => {
+        auth.authenticate(request);
+        if (!services.watchdogs)
+            throw new FleetError('capability_unavailable', 'watchdogs are unavailable');
+        return services.watchdogs.report(request.params.name, request.params.runId);
+    });
     app.get('/api/v1/events', { websocket: true }, (socket, request) => {
         requireSubprotocol(request, 'ours-fleet-events.v1');
         authorizeSocket(socket, request, async (hello) => {