@ours.network/fleet 0.10.3 → 0.11.0

package/dist/watchdog/briefing.js

@@ -0,0 +1,181 @@
+import { formatDuration } from '../duration.js';
+/**
+ * The "bind or mint your identity" block shared by every watchdog-family briefing (the
+ * inspection contract and the notifier contract alike): call bindTool, and if the identity
+ * wasn't verified when configured, fall back to createTool on first run.
+ */
+function bindSection(heading, wd, v, guarantee) {
+    const L = ['', heading];
+    L.push(`Call the **${v.bindTool}** tool with name "${wd.identity}" force=true (search the`);
+    L.push('deferred tool registry first if needed).');
+    if (guarantee === 'unverified') {
+        L.push(`- This identity was NOT verified when this watchdog was configured, so it may not`);
+        L.push(`  exist yet. If binding reports no such identity, call **${v.createTool}** name`);
+        L.push(`  "${wd.identity}" once to mint it on this first run, then you are bound. Re-binding`);
+        L.push('  your OWN identity is always allowed.');
+    }
+    else {
+        L.push(`- It was ${guarantee === 'created' ? 'created' : 'verified to exist'} when this`);
+        L.push('  watchdog was configured, so binding should succeed. If it unexpectedly reports no');
+        L.push(`  such identity, call **${v.createTool}** name "${wd.identity}" once and report the`);
+        L.push('  discrepancy — something removed it since.');
+    }
+    return L;
+}
+/**
+ * Render a watchdog run's fixed contract (briefing.md-equivalent for a one-shot clean-context
+ * 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
+ * below is unconditional except the identity-guarantee wording and the trailing focus append.
+ */
+export function generateWatchdogBriefing(opts) {
+    const { wd, manifestPath, reportPath, vocabulary: v, identityGuarantee: guarantee } = opts;
+    const L = [];
+    // 1. Header + bind instructions (mirrors src/briefing.ts:43-57; mint on first run when the
+    // identity was not verified when this watchdog was created).
+    L.push(`# Watchdog run: ${wd.name} (ours identity: ${wd.identity})`, '');
+    L.push(`You are a fresh, one-shot inspection agent for the **${wd.name}** watchdog. You carry`);
+    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).
+    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 ' +
+        "owner's behalf. You do exactly three things: run read-only inspections, send at most one " +
+        'message to your coordinator, and write one report.json.');
+    // 3. Procedure.
+    L.push('', '## 3. Procedure');
+    L.push(`1. Read \`${manifestPath}\` (watch.json). It is JSON with this shape:`);
+    L.push('   ```json');
+    L.push('   {');
+    L.push(`     "watchdog": "${wd.name}", "run_id": "...", "coordinator": "${wd.coordinator}",`);
+    L.push('     "started_at": "...",');
+    L.push('     "roles": [{ "name": "Alice", "stateDir": "/home/.../agents/Alice" }],');
+    L.push('     "digest": { "cooldown_ms": 3600000, "open": [');
+    L.push('       { "role": "Alice", "status": "blocked", "since": "...", "realert_after": "..." }');
+    L.push('     ] }');
+    L.push('   }');
+    L.push('   ```');
+    L.push('   Use its `watchdog`, `run_id` and `started_at` values verbatim in your report — do not');
+    L.push('   invent your own.');
+    L.push('2. For each entry in `roles`, gather evidence — read-only, nothing written outside your');
+    L.push('   own report — from two sources:');
+    L.push("   - Files under that role's `stateDir`: `briefing.md`, `WORKLOG.md` (size/mtime),");
+    L.push('     `.worklog-rotation.json`, `.monitor-status`, `.monitor-owner`, `.restart-ledger.json`,');
+    L.push('     `.exit-status`, `.model-status`, `.isolation-degraded`.');
+    L.push('   - The sanctioned commands: `ours-fleet status <Role>`, `ours-fleet peek <Role>`,');
+    L.push('     `ours-fleet logs <Role>`, `ours-fleet config`. No other `ours-fleet` subcommand is');
+    L.push('     available to you, and none would be honoured even if invoked.');
+    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.
+    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('- `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).');
+    L.push('- `unreachable` = configured and enabled but not running.');
+    L.push('- `unknown` — evidence insufficient (e.g. control plane unanswered); unknown is never ' +
+        'reported as healthy.');
+    // 5. Evidence rules.
+    L.push('', '## 5. Evidence rules');
+    L.push('Every non-`healthy` entry carries a one-sentence `reason` and at most 3 `evidence`');
+    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.
+    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`).');
+    L.push('2. Re-alert an unchanged open finding only after `alert_cooldown`.');
+    L.push('3. Send one **resolved** notice when an open finding returns to `healthy`.');
+    L.push('4. One message per run, listing all qualifying findings — never one message per role.');
+    L.push('');
+    L.push('Severity ordering, lowest to highest: healthy = idle (0) < unknown (1) < stale (2) < ' +
+        "blocked = unreachable (3) < off_briefing (4); a finding is escalated when its status ranks " +
+        "strictly higher than the digest entry's status.");
+    L.push('');
+    L.push('the suppression digest in watch.json is authoritative: alert only on findings that are new ' +
+        '(role not in digest.open), escalated (higher severity than the digest entry), or past ' +
+        '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.
+    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,');
+    L.push('and you never set `error` yourself — that field is for the scheduler):');
+    L.push('```json');
+    L.push('{');
+    L.push('  "schema_version": 1,');
+    L.push(`  "watchdog": "${wd.name}",`);
+    L.push('  "run_id": "<run_id from watch.json>",');
+    L.push('  "started_at": "<started_at from watch.json>",');
+    L.push('  "finished_at": "2026-07-31T11:51:12Z",');
+    L.push('  "status": "anomalies",');
+    L.push('  "summary": { "checked": 4, "healthy": 2, "idle": 1, "anomalies": 1 },');
+    L.push('  "roles": [');
+    L.push('    { "role": "Bob", "status": "healthy" },');
+    L.push('    {');
+    L.push('      "role": "Alice",');
+    L.push('      "status": "blocked",');
+    L.push('      "reason": "Waiting on a trust dialog for 34 minutes with no progress.",');
+    L.push('      "evidence": [');
+    L.push('        { "source": "status", "detail": "session.readiness=awaiting_permission",');
+    L.push('          "observed_at": "2026-07-31T11:50:31Z" },');
+    L.push('        { "source": "worklog", "detail": "WORKLOG.md unchanged since 11:16Z",');
+    L.push('          "observed_at": "2026-07-31T11:50:33Z" }');
+    L.push('      ],');
+    L.push('      "alerted": true');
+    L.push('    }');
+    L.push('  ],');
+    L.push('  "alerts": [');
+    L.push('    { "role": "Alice", "code": "blocked", "coordinator": "FleetCoordinator",');
+    L.push('      "sent_at": "2026-07-31T11:51:10Z" }');
+    L.push('  ],');
+    L.push('  "error": null');
+    L.push('}');
+    L.push('```');
+    L.push(`Write the report to \`${reportPath}\` (your cwd) as your LAST action — writing it ends ` +
+        'the run. Send your coordinator message BEFORE writing report.json.');
+    // 8. Appended prompt_file focus — extra emphasis only, contract stays non-negotiable.
+    if (opts.promptFocus) {
+        L.push('', '## Extra focus (from prompt_file)', '');
+        L.push(opts.promptFocus);
+        L.push('', 'The extra focus adds emphasis only. The report schema, the observe-only rules and the ' +
+            'alert rules above are unchanged and non-negotiable.');
+    }
+    return L.join('\n') + '\n';
+}
+/**
+ * Render a scheduler-alert notifier run's entire contract: a minimal one-shot agent whose sole
+ * job is to bind its identity, send one exact message to the coordinator, and write `sent.json`
+ * as its completion sentinel. Used only for scheduler-level alerts (e.g. held-down) — the fleet
+ * process itself cannot send ours messages (deviation 4), so this is how it delegates the send.
+ * Unlike `generateWatchdogBriefing`, there is no report.json, no manifest, and no inspection.
+ */
+export function generateNotifierBriefing(opts) {
+    const { wd, vocabulary: v, identityGuarantee: guarantee, text } = opts;
+    const L = [];
+    L.push(`# Watchdog alert notifier: ${wd.name} (ours identity: ${wd.identity})`, '');
+    L.push('You are a minimal one-shot notifier agent. You carry no memory from any previous run —');
+    L.push('this run stands alone, and it has exactly one job: relay one message, then stop.');
+    L.push(...bindSection('## Bind your identity', wd, v, guarantee));
+    L.push('', '## Send the message');
+    L.push(`Send exactly this message to ${wd.coordinator} using **${v.sendTool}**:`);
+    L.push('');
+    L.push(text);
+    L.push('', '## Finish');
+    L.push(`Then write a file \`sent.json\` containing \`{"sent": true}\` in your cwd as your LAST ` +
+        'action — it ends the run. Do nothing else: no inspection, no report.json, no other messages.');
+    return L.join('\n') + '\n';
+}

package/dist/watchdog/config.d.ts

@@ -0,0 +1,49 @@
+import type { FleetConfig, ResolvedRole, SessionBackendId } from '../config.js';
+export interface WatchdogConfig {
+    coordinator?: string;
+    enabled?: boolean;
+    interval?: string;
+    watch?: string[];
+    harness?: string;
+    model?: string | null;
+    session?: string;
+    identity?: string;
+    timeout?: string;
+    keep_reports?: number;
+    alert_cooldown?: string;
+    prompt_file?: string;
+}
+export interface ResolvedWatchdog {
+    name: string;
+    coordinator: string;
+    enabled: boolean;
+    intervalMs: number;
+    watch: string[];
+    harness: string;
+    session: SessionBackendId;
+    model?: string;
+    identity: string;
+    timeoutMs: number;
+    keepReports: number;
+    alertCooldownMs: number;
+    promptFile?: string;
+    sourceFile: string;
+}
+export declare const WATCHDOG_DEFAULT_INTERVAL_MS = 600000;
+export declare const WATCHDOG_MIN_INTERVAL_MS = 60000;
+export declare const WATCHDOG_DEFAULT_TIMEOUT_MS = 300000;
+export declare const WATCHDOG_DEFAULT_KEEP_REPORTS = 50;
+export declare const WATCHDOG_DEFAULT_COOLDOWN_MS = 3600000;
+export declare function resolveWatchdogs(baseDoc: Record<string, unknown>, baseFile: string, roles: ResolvedRole[], vars: Record<string, string>, defaults: Record<string, unknown>): ResolvedWatchdog[];
+/**
+ * Split `restart`'s argument names into watchdogs (a release, handled
+ * directly) and roles (handed to restartRoles). Watchdog names can't collide
+ * with role names (config validation guarantees dispatch is unambiguous), so
+ * a name matching a configured watchdog is always a release, never a role
+ * restart. Order is preserved within each bucket; unknown names fall through
+ * to roleNames — findRole errors later, same as today.
+ */
+export declare function partitionRestartNames(cfg: FleetConfig, names: string[]): {
+    watchdogNames: string[];
+    roleNames: string[];
+};

package/dist/watchdog/config.js

@@ -0,0 +1,114 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { parseDuration } from '../duration.js';
+import { ConfigError, ROLE_NAME_RE, resolveRoleModel } from '../config.js';
+const WATCHDOG_KEYS = [
+    'coordinator', 'enabled', 'interval', 'watch', 'harness', 'model', 'session',
+    'identity', 'timeout', 'keep_reports', 'alert_cooldown', 'prompt_file',
+];
+export const WATCHDOG_DEFAULT_INTERVAL_MS = 600_000;
+export const WATCHDOG_MIN_INTERVAL_MS = 60_000;
+export const WATCHDOG_DEFAULT_TIMEOUT_MS = 300_000;
+export const WATCHDOG_DEFAULT_KEEP_REPORTS = 50;
+export const WATCHDOG_DEFAULT_COOLDOWN_MS = 3_600_000;
+function deepSub(v, vars) {
+    if (typeof v === 'string')
+        return v.replace(/\$\{(\w+)\}/g, (m, k) => (k in vars ? String(vars[k]) : m));
+    if (Array.isArray(v))
+        return v.map(x => deepSub(x, vars));
+    if (v && typeof v === 'object')
+        return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, deepSub(x, vars)]));
+    return v;
+}
+export function resolveWatchdogs(baseDoc, baseFile, roles, vars, defaults) {
+    const block = baseDoc.watchdogs;
+    if (block === undefined || block === null)
+        return [];
+    if (typeof block !== 'object' || Array.isArray(block))
+        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):
+    // 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.
+    const watchdogIdentities = new Map();
+    const out = [];
+    for (const [name, rawEntry] of Object.entries(block)) {
+        const where = `${baseFile}: watchdog '${name}'`;
+        if (!ROLE_NAME_RE.test(name))
+            throw new ConfigError(`${baseFile}: invalid watchdog name '${name}' (allowed: [A-Za-z0-9_-])`);
+        if (roleNames.has(name))
+            throw new ConfigError(`${baseFile}: watchdog '${name}' collides with a role name`);
+        const w = deepSub(rawEntry ?? {}, vars);
+        const bad = Object.keys(w).filter(k => !WATCHDOG_KEYS.includes(k));
+        if (bad.length)
+            throw new ConfigError(`${where} has unknown key(s) ${bad.join(', ')}; allowed: ${WATCHDOG_KEYS.join(', ')}`);
+        if (typeof w.coordinator !== 'string' || !w.coordinator.trim())
+            throw new ConfigError(`${where}: coordinator is required`);
+        const watch = w.watch === undefined ? roles.map(r => r.name) : w.watch;
+        if (!Array.isArray(watch) || watch.some(x => typeof x !== 'string'))
+            throw new ConfigError(`${where}: watch must be a list of role names`);
+        for (const r of watch)
+            if (!roleNames.has(r))
+                throw new ConfigError(`${where}: watch names missing role '${r}'`);
+        const identity = w.identity ?? `Watchdog-${name}`;
+        if (roleNames.has(identity) || roleIdentities.has(identity))
+            throw new ConfigError(`${where}: identity '${identity}' collides with a role name or identity`);
+        const collidingWatchdog = watchdogIdentities.get(identity);
+        if (collidingWatchdog !== undefined)
+            throw new ConfigError(`${where}: identity '${identity}' collides with watchdog '${collidingWatchdog}'`);
+        watchdogIdentities.set(identity, name);
+        const harness = w.harness ?? defaults.harness ?? 'claude-code';
+        const sessionRaw = w.session ?? defaults.session ?? 'tmux';
+        if (sessionRaw !== 'tmux' && sessionRaw !== 'acp')
+            throw new ConfigError(`${where}: session must be 'tmux' or 'acp'`);
+        if (w.prompt_file !== undefined) {
+            if (typeof w.prompt_file !== 'string' || !isAbsolute(w.prompt_file))
+                throw new ConfigError(`${where}: prompt_file must be an absolute path`);
+            if (!existsSync(w.prompt_file))
+                throw new ConfigError(`${where}: prompt_file not found: ${w.prompt_file}`);
+        }
+        const dur = (v, key, fallback, minMs) => {
+            if (v === undefined)
+                return fallback;
+            try {
+                return parseDuration(v, { name: key, minMs });
+            }
+            catch (e) {
+                throw new ConfigError(`${where}: ${e.message}`);
+            }
+        };
+        const keepReports = w.keep_reports ?? WATCHDOG_DEFAULT_KEEP_REPORTS;
+        if (!Number.isInteger(keepReports) || keepReports < 1)
+            throw new ConfigError(`${where}: keep_reports must be a positive integer`);
+        if (w.enabled !== undefined && typeof w.enabled !== 'boolean')
+            throw new ConfigError(`${where}: enabled must be true or false`);
+        out.push({
+            name, coordinator: w.coordinator.trim(),
+            enabled: w.enabled ?? true,
+            intervalMs: dur(w.interval, 'interval', WATCHDOG_DEFAULT_INTERVAL_MS, WATCHDOG_MIN_INTERVAL_MS),
+            watch, harness, session: sessionRaw,
+            model: resolveRoleModel(w.model, w.harness, defaults),
+            identity,
+            timeoutMs: dur(w.timeout, 'timeout', WATCHDOG_DEFAULT_TIMEOUT_MS),
+            keepReports,
+            alertCooldownMs: dur(w.alert_cooldown, 'alert_cooldown', WATCHDOG_DEFAULT_COOLDOWN_MS),
+            promptFile: w.prompt_file, sourceFile: baseFile,
+        });
+    }
+    return out;
+}
+/**
+ * Split `restart`'s argument names into watchdogs (a release, handled
+ * directly) and roles (handed to restartRoles). Watchdog names can't collide
+ * with role names (config validation guarantees dispatch is unambiguous), so
+ * a name matching a configured watchdog is always a release, never a role
+ * restart. Order is preserved within each bucket; unknown names fall through
+ * to roleNames — findRole errors later, same as today.
+ */
+export function partitionRestartNames(cfg, names) {
+    const watchdogNames = names.filter(n => cfg.watchdogs.some(w => w.name === n));
+    const roleNames = names.filter(n => !watchdogNames.includes(n));
+    return { watchdogNames, roleNames };
+}

package/dist/watchdog/query.d.ts

@@ -0,0 +1,78 @@
+import { type FleetConfig } from '../config.js';
+import type { WatchdogReport, WatchdogRoleStatus } from './report.js';
+import { type RunListEntry } from './store.js';
+export interface WatchdogRoleFinding {
+    watchdog: string;
+    status: WatchdogRoleStatus;
+    reason: string;
+}
+/**
+ * Needs-attention integration (Task 19): 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
+ * reconcileLedger rule. Healthy/idle findings (rank 0) never surface here —
+ * only actionable anomalies do. "Worst" is decided by WATCHDOG_STATUS_RANK;
+ * ties keep whichever watchdog was seen first. Takes `latestReport` as a
+ * 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
+ * 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
+ * findings it already produced go away.
+ */
+export declare function buildWatchdogFindings(cfg: {
+    watchdogs: Array<{
+        name: string;
+        enabled: boolean;
+    }>;
+}, latestReport: (name: string) => WatchdogReport | undefined): Map<string, WatchdogRoleFinding>;
+/**
+ * Memoizes a findings-map builder with a short TTL (mirrors runtime.ts's
+ * cachedConfigProvider pattern). status() calls its injected watchdogFindings
+ * provider once per role, so an unmemoized thunk turns a single list() sweep
+ * into O(roles x watchdogs) disk reads, repeated every 1-3s of console
+ * polling. `now` is injectable (defaults to Date.now) so the TTL boundary is
+ * unit-testable without real timers.
+ */
+export declare function cachedWatchdogFindingsProvider(build: () => Map<string, WatchdogRoleFinding>, ttlMs: number, now?: () => number): () => Map<string, WatchdogRoleFinding>;
+export interface WatchdogSummary {
+    name: string;
+    enabled: boolean;
+    heldDown: boolean;
+    heldSince: string | null;
+    intervalMs: number;
+    coordinator: string;
+    watch: string[];
+    lastRunAt: string | null;
+    nextRunAt: string | null;
+    latest: RunListEntry | null;
+}
+/**
+ * Read-only view over watchdog config + on-disk scheduler state + stored
+ * reports, for the authenticated web console. Never mutates: `list()` reads
+ * config plus `readSchedulerState`/`listRuns` (both already tolerant of a
+ * corrupt/missing state.json or an empty/nonexistent reports dir, per
+ * store.ts and scheduler.ts), and `reports()`/`report()` reject unknown
+ * watchdog names before touching disk.
+ */
+export declare class WatchdogQueryService {
+    private readonly cfgProvider;
+    constructor(cfgProvider: () => FleetConfig);
+    list(): {
+        watchdogs: WatchdogSummary[];
+    };
+    reports(name: string, limit?: number): {
+        runs: RunListEntry[];
+    };
+    report(name: string, runId: string): WatchdogReport;
+    /**
+     * Known means: configured today, OR a store directory already exists for a
+     * watchdog that used to be configured (its history should stay readable).
+     * The regex check runs before any filesystem lookup so a hostile `name`
+     * (path separators, '..', etc.) can never reach `join(watchdogsRoot(), name)`.
+     */
+    private requireKnown;
+}

package/dist/watchdog/query.js

@@ -0,0 +1,124 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { FleetError } from '../application/errors.js';
+import { ROLE_NAME_RE } from '../config.js';
+import { watchdogsRoot } from '../paths.js';
+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
+ * 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
+ * reconcileLedger rule. Healthy/idle findings (rank 0) never surface here —
+ * only actionable anomalies do. "Worst" is decided by WATCHDOG_STATUS_RANK;
+ * ties keep whichever watchdog was seen first. Takes `latestReport` as a
+ * 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
+ * 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
+ * findings it already produced go away.
+ */
+export function buildWatchdogFindings(cfg, latestReport) {
+    const findings = new Map();
+    for (const wd of cfg.watchdogs) {
+        if (!wd.enabled)
+            continue;
+        const report = latestReport(wd.name);
+        if (!report || report.status === 'error')
+            continue;
+        for (const finding of report.roles) {
+            const rank = WATCHDOG_STATUS_RANK[finding.status];
+            if (rank <= 0)
+                continue;
+            const existing = findings.get(finding.role);
+            if (existing && WATCHDOG_STATUS_RANK[existing.status] >= rank)
+                continue;
+            findings.set(finding.role, { watchdog: wd.name, status: finding.status, reason: finding.reason ?? '' });
+        }
+    }
+    return findings;
+}
+/**
+ * Memoizes a findings-map builder with a short TTL (mirrors runtime.ts's
+ * cachedConfigProvider pattern). status() calls its injected watchdogFindings
+ * provider once per role, so an unmemoized thunk turns a single list() sweep
+ * into O(roles x watchdogs) disk reads, repeated every 1-3s of console
+ * polling. `now` is injectable (defaults to Date.now) so the TTL boundary is
+ * unit-testable without real timers.
+ */
+export function cachedWatchdogFindingsProvider(build, ttlMs, now = Date.now) {
+    let cached;
+    return () => {
+        const at = now();
+        if (!cached || at - cached.at >= ttlMs)
+            cached = { at, value: build() };
+        return cached.value;
+    };
+}
+const DEFAULT_REPORTS_LIMIT = 50;
+const MAX_REPORTS_LIMIT = 500;
+/**
+ * Read-only view over watchdog config + on-disk scheduler state + stored
+ * reports, for the authenticated web console. Never mutates: `list()` reads
+ * config plus `readSchedulerState`/`listRuns` (both already tolerant of a
+ * corrupt/missing state.json or an empty/nonexistent reports dir, per
+ * store.ts and scheduler.ts), and `reports()`/`report()` reject unknown
+ * watchdog names before touching disk.
+ */
+export class WatchdogQueryService {
+    cfgProvider;
+    constructor(cfgProvider) {
+        this.cfgProvider = cfgProvider;
+    }
+    list() {
+        const cfg = this.cfgProvider();
+        const watchdogs = cfg.watchdogs.map((wd) => {
+            const state = readSchedulerState(wd.name);
+            const [latest = null] = listRuns(wd.name);
+            return {
+                name: wd.name, enabled: wd.enabled, heldDown: state.heldDown, heldSince: state.heldSince ?? null,
+                intervalMs: wd.intervalMs,
+                coordinator: wd.coordinator, watch: wd.watch,
+                lastRunAt: state.lastRunAt ?? null, nextRunAt: state.nextRunAt ?? null,
+                latest,
+            };
+        });
+        return { watchdogs };
+    }
+    reports(name, limit = DEFAULT_REPORTS_LIMIT) {
+        this.requireKnown(name);
+        const n = Number.isFinite(limit) ? Math.floor(limit) : DEFAULT_REPORTS_LIMIT;
+        const clamped = Math.min(Math.max(n, 1), MAX_REPORTS_LIMIT);
+        return { runs: listRuns(name).slice(0, clamped) };
+    }
+    report(name, runId) {
+        this.requireKnown(name);
+        // readReport parses the stored file with JSON.parse and returns the parsed object;
+        // fastify re-serializes it for the HTTP response, so what's actually verifiable (and
+        // what the tests assert) is deep equality with the stored JSON, not byte-for-byte
+        // identity of the response bytes against the file on disk.
+        const found = readReport(name, runId);
+        if (!found)
+            throw new FleetError('role_not_found', `no such report '${runId}' for watchdog '${name}'`);
+        return found;
+    }
+    /**
+     * Known means: configured today, OR a store directory already exists for a
+     * watchdog that used to be configured (its history should stay readable).
+     * The regex check runs before any filesystem lookup so a hostile `name`
+     * (path separators, '..', etc.) can never reach `join(watchdogsRoot(), name)`.
+     */
+    requireKnown(name) {
+        const cfg = this.cfgProvider();
+        if (cfg.watchdogs.some(wd => wd.name === name))
+            return;
+        if (ROLE_NAME_RE.test(name) && existsSync(join(watchdogsRoot(), name)))
+            return;
+        throw new FleetError('role_not_found', `no such watchdog '${name}'`);
+    }
+}

package/dist/watchdog/report.d.ts

@@ -0,0 +1,53 @@
+export declare const WATCHDOG_ROLE_STATUSES: readonly ["healthy", "idle", "stale", "blocked", "off_briefing", "unreachable", "unknown"];
+export type WatchdogRoleStatus = typeof WATCHDOG_ROLE_STATUSES[number];
+export interface WatchdogEvidence {
+    source: string;
+    detail: string;
+    observed_at: string;
+}
+export interface WatchdogFinding {
+    role: string;
+    status: WatchdogRoleStatus;
+    reason?: string;
+    evidence?: WatchdogEvidence[];
+    alerted?: boolean;
+}
+export interface WatchdogAlert {
+    role: string;
+    code: string;
+    coordinator: string;
+    sent_at: string;
+}
+export type WatchdogReportStatus = 'ok' | 'anomalies' | 'error';
+export interface WatchdogReport {
+    schema_version: 1;
+    watchdog: string;
+    run_id: string;
+    started_at: string;
+    finished_at: string;
+    status: WatchdogReportStatus;
+    summary: {
+        checked: number;
+        healthy: number;
+        idle: number;
+        anomalies: number;
+    };
+    roles: WatchdogFinding[];
+    alerts: WatchdogAlert[];
+    error: string | null;
+}
+export declare function validateWatchdogReport(v: unknown): string[];
+export declare function normalizeWatchdogReport(r: WatchdogReport, ctx: {
+    watchdog: string;
+    run_id: string;
+}): WatchdogReport;
+export declare function errorReport(ctx: {
+    watchdog: string;
+    run_id: string;
+    started_at: string;
+    finished_at: string;
+    error: string;
+    tail?: string;
+}): WatchdogReport & {
+    tail?: string;
+};