@ours.network/fleet 0.10.4 → 0.11.0

package/dist/application/fleet-query-service.d.ts

@@ -10,6 +10,17 @@ export interface FleetQueryOptions {
     tmux?: Tmux;
     control?: typeof controlRequest;
     capabilityContext?: CapabilityContext;
+    /**
+     * Watchdog anomalies feeding into Needs Attention (Task 19): roleId -> worst
+     * current finding across all watchdogs. Optional and absent by default so
+     * every pre-existing caller (and its tests) is unaffected; runtime.ts wires
+     * the real provider, built from watchdog reports on disk.
+     */
+    watchdogFindings?: () => Map<string, {
+        watchdog: string;
+        status: string;
+        reason: string;
+    }>;
 }
 export declare class FleetQueryService {
     private readonly options;

package/dist/application/fleet-query-service.js

@@ -45,7 +45,8 @@ function readIsolation(dir) {
 }
 function sessionOverall(supervisor, session, restart, monitor, isolation, problems) {
     if (restart.circuit === 'open' || monitor.health === 'failed' || monitor.health === 'degraded'
-        || isolation.degraded || problems.some(problem => problem.severity === 'error')
+        || isolation.degraded
+        || problems.some(problem => problem.severity === 'error' || problem.source === 'watchdog')
         || session.readiness === 'failed')
         return 'attention';
     // A reachable ACP/tmux session is the user's live interaction surface. Its
@@ -111,6 +112,13 @@ export class FleetQueryService {
                 code: 'session_supervisor_disagreement', severity: 'warning',
                 detail: 'session is live while its permanent supervisor service is inactive',
             });
+        const watchdogFinding = this.options.watchdogFindings?.().get(role.id);
+        if (watchdogFinding)
+            problems.push({
+                code: 'watchdog_finding', severity: 'warning',
+                detail: `${watchdogFinding.watchdog}: ${watchdogFinding.status} — ${watchdogFinding.reason}`,
+                source: 'watchdog',
+            });
         const supervisor = {
             backend: this.options.supervisor.id, liveness: live.state,
             nativeState: live.detail.split(/\s/)[0], detail: clean(live.detail),

package/dist/cli.js

@@ -6,13 +6,19 @@ import { join as joinPath } from 'node:path';
 import { createInterface } from 'node:readline';
 import { Command } from 'commander';
 import { VERSION } from './version.js';
-import { agentDir, agentsRoot, tmpRoot, logsRoot, deriveXdgRuntimeDir } from './paths.js';
-import { loadConfig } from './config.js';
+import { agentDir, agentsRoot, tmpRoot, logsRoot, deriveXdgRuntimeDir, watchdogsRoot } from './paths.js';
+import { loadConfig, ROLE_NAME_RE } from './config.js';
+import { formatDuration } from './duration.js';
 import { resolvedPlan } from './resolved-plan.js';
 import { Tmux, tmuxArgs } from './tmux.js';
 import { pickBackend } from './supervisor/index.js';
 import { up, down, restartRoles, rmRole } from './ops.js';
 import { readRestartLedger, runSupervised, runTemp } from './runner.js';
+import { executeWatchdogRun, runWatchdogAgent } from './watchdog/run.js';
+import { readSchedulerState, resetSchedulerState, runScheduler } from './watchdog/scheduler.js';
+import { partitionRestartNames } from './watchdog/config.js';
+import { WatchdogServiceManager } from './watchdog/service.js';
+import { acquireRunLock, latestReport, listRuns, readReport, releaseRunLock, reportsDir, } from './watchdog/store.js';
 import { lastProvenance, spawnDryRun, spawnPermanent, spawnTemp, } from './spawn.js';
 import { stringify } from 'yaml';
 import { resolvedRolePlan } from './resolved-plan.js';
@@ -40,6 +46,7 @@ const deps = () => ({
     backend: pickBackend(),
     binPath,
     log: l => console.log(l),
+    watchdogService: new WatchdogServiceManager(),
 });
 const die = (e) => { console.error(String(e instanceof Error ? e.message : e)); process.exit(1); };
 /** Exec a child with our stdio (logs/attach). */
@@ -179,6 +186,19 @@ cOpt(program.command('config').description('validate + print the merged plan (no
             for (const w of perms ? allWarnings(perms) : [])
                 console.log(`    warning:     ${w}`);
         }
+        if (cfg.watchdogs.length) {
+            console.log('watchdogs:');
+            for (const w of cfg.watchdogs) {
+                console.log(`● ${w.name}${w.enabled ? '' : '  (disabled)'}`
+                    + `${readSchedulerState(w.name).heldDown ? '  (held down)' : ''}`);
+                console.log(`  every ${formatDuration(w.intervalMs)} -> ${w.coordinator}`);
+                console.log(`  harness:  ${w.harness} (${w.session})${w.model ? `, model: ${w.model}` : ''}`);
+                console.log(`  identity: ${w.identity}`);
+                console.log(`  watch:    ${w.watch.join(', ')}`);
+                if (w.promptFile)
+                    console.log(`  focus:    ${w.promptFile}`);
+            }
+        }
     }
     catch (e) {
         die(e);
@@ -205,7 +225,21 @@ cOpt(program.command('down [names...]').description('stop roles'))
 cOpt(program.command('restart [names...]').description('re-sync config + bounce, RESUMING context'))
     .action(async (names, opts) => {
     try {
-        await restartRoles(loadConfig(opts.configuration), names, deps(), 'keep', opts.configuration);
+        const cfg = loadConfig(opts.configuration);
+        // 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. Release each
+        // named watchdog directly instead of handing it to restartRoles, which
+        // only knows about roles and would reject it as unknown (3.2 release path).
+        const { watchdogNames, roleNames } = partitionRestartNames(cfg, names);
+        for (const wn of watchdogNames) {
+            resetSchedulerState(wn);
+            console.log(`released watchdog '${wn}' — scheduler resumes on its next poll`);
+        }
+        // Bare `restart` (no names) restarts every role — that meaning must
+        // survive even though filtering an empty array also yields [].
+        if (names.length === 0 || roleNames.length > 0)
+            await restartRoles(cfg, roleNames, deps(), 'keep', opts.configuration);
     }
     catch (e) {
         die(e);
@@ -398,6 +432,144 @@ program.command('status <name>').description('unit/agent state')
         }
     }
 });
+/**
+ * A watchdog is addressable if it's still configured, or its store dir survives
+ * config removal. The name-shape check runs BEFORE any filesystem lookup
+ * (finding #1): a hostile `name` (path separators, '..', etc.) must never
+ * reach `join(watchdogsRoot(), name)` — treated as simply unknown, same as
+ * store.ts's own `watchdogDir` choke-point guard (defense in depth).
+ */
+function watchdogKnown(name, configPath) {
+    try {
+        if (loadConfig(configPath).watchdogs.some(w => w.name === name))
+            return true;
+    }
+    catch { /* config missing/broken: fall through to the store check */ }
+    return ROLE_NAME_RE.test(name) && existsSync(joinPath(watchdogsRoot(), name));
+}
+function renderHeldDownLine(state) {
+    if (!state.heldDown)
+        return undefined;
+    return `HELD DOWN since ${state.heldSince ?? 'unknown'} after ${state.consecutiveFailures} `
+        + `consecutive failures: ${state.lastError ?? 'unknown error'}`;
+}
+/** Full human rendering of one report: header, held-down warning, counts, then non-healthy roles + evidence. */
+function renderReport(report, heldState) {
+    const lines = [`● ${report.watchdog} — run ${report.run_id} (${report.status})`];
+    const held = renderHeldDownLine(heldState);
+    if (held)
+        lines.push(held);
+    const s = report.summary;
+    lines.push(`  checked=${s.checked} healthy=${s.healthy} idle=${s.idle} anomalies=${s.anomalies}`);
+    if (report.error)
+        lines.push(`  error: ${report.error}`);
+    for (const role of report.roles) {
+        if (role.status === 'healthy')
+            continue;
+        lines.push(`  ${role.role}  ${role.status}  ${role.reason ?? ''}`.trimEnd());
+        for (const ev of role.evidence ?? [])
+            lines.push(`    - [${ev.source}] ${ev.detail} (${ev.observed_at})`);
+        if (role.alerted) {
+            const alert = report.alerts.find(a => a.role === role.role);
+            lines.push(`    alerted -> ${alert?.coordinator ?? '?'}`);
+        }
+    }
+    const tail = report.tail;
+    if (report.status === 'error' && tail) {
+        lines.push('  --- output tail ---');
+        for (const l of tail.split('\n'))
+            lines.push(`  ${l}`);
+    }
+    return lines.join('\n');
+}
+function renderRunDuration(startedAt, finishedAt) {
+    const started = Date.parse(startedAt);
+    const finished = Date.parse(finishedAt);
+    return Number.isFinite(started) && Number.isFinite(finished)
+        ? formatDuration(Math.max(0, finished - started)) : '-';
+}
+/** `--list` table: run-id, started, duration, status, checked/healthy/idle/anomalies, [error]. */
+function renderRunList(entries) {
+    const header = ['run-id'.padEnd(18), 'started'.padEnd(22), 'duration'.padEnd(8),
+        'status'.padEnd(10), 'checked/healthy/idle/anomalies', 'error'].join('  ');
+    const rows = entries.map(e => {
+        const s = e.summary;
+        const cols = [
+            e.runId.padEnd(18), (e.startedAt || '-').padEnd(22),
+            renderRunDuration(e.startedAt, e.finishedAt).padEnd(8), e.status.padEnd(10),
+            `${s.checked}/${s.healthy}/${s.idle}/${s.anomalies}`.padEnd(31),
+        ];
+        if (e.error)
+            cols.push(e.error);
+        return cols.join('  ').trimEnd();
+    });
+    return [header, ...rows].join('\n');
+}
+cOpt(program.command('watchdog-run <name>')
+    .description('run one watchdog check now, foreground, same storage as the scheduler'))
+    .action(async (name, opts) => {
+    try {
+        const cfg = loadConfig(opts.configuration);
+        const wd = cfg.watchdogs.find(w => w.name === name);
+        if (!wd)
+            throw new Error(`unknown watchdog '${name}'`);
+        if (!acquireRunLock(name))
+            throw new Error(`watchdog '${name}' is already running (run lock held)`);
+        try {
+            const { report, storedPath } = await executeWatchdogRun(wd, {
+                binPath, log: l => console.log(l), cfg,
+            });
+            console.log(`stored: ${storedPath}`);
+            console.log(renderReport(report, readSchedulerState(name)));
+        }
+        finally {
+            releaseRunLock(name);
+        }
+    }
+    catch (e) {
+        die(e);
+    }
+});
+cOpt(program.command('watchdog-report <name> [runId]')
+    .description('show a watchdog run report: latest by default, a specific run by id, --list, or --json'))
+    .option('--list', 'list runs instead of showing one')
+    .option('--json', 'print the stored report file bytes unmodified')
+    .action((name, runId, opts) => {
+    try {
+        if (!watchdogKnown(name, opts.configuration))
+            throw new Error(`unknown watchdog '${name}'`);
+        if (opts.list) {
+            // --list has no single stored file to echo byte-for-byte, so --json here can't
+            // mean "raw stored bytes" the way it does for a single report. Contract: emit
+            // machine-readable run metadata instead (JSON.stringify of listRuns()'s
+            // RunListEntry[], wrapped in { runs }) — the single-report --json path below is
+            // unaffected and still prints the exact stored bytes.
+            if (opts.json) {
+                console.log(JSON.stringify({ runs: listRuns(name) }, null, 2));
+                return;
+            }
+            const held = renderHeldDownLine(readSchedulerState(name));
+            if (held)
+                console.log(held);
+            console.log(renderRunList(listRuns(name)));
+            return;
+        }
+        const report = runId !== undefined ? readReport(name, runId) : latestReport(name);
+        if (!report) {
+            throw new Error(runId !== undefined
+                ? `watchdog '${name}': no such run '${runId}'`
+                : `watchdog '${name}' has no reports`);
+        }
+        if (opts.json) {
+            console.log(readFileSync(joinPath(reportsDir(name), `${runId ?? report.run_id}.json`), 'utf8'));
+            return;
+        }
+        console.log(renderReport(report, readSchedulerState(name)));
+    }
+    catch (e) {
+        die(e);
+    }
+});
 cOpt(program.command('rm <name>').description('stop + delete state dir (+ its fleet.d file if spawned)'))
     .action(async (name, opts) => {
     try {
@@ -670,4 +842,29 @@ program.command('_run-temp <name>', { hidden: true }).description('internal: tem
         die(e);
     }
 });
+program.command('_run-watchdog <name>', { hidden: true })
+    .description('internal: one watchdog agent run (no cleanup — parent harvests)')
+    .action(async (name) => {
+    try {
+        await runWatchdogAgent(name);
+    }
+    catch (e) {
+        die(e);
+    }
+});
+cOpt(program.command('_run-watchdogs', { hidden: true }))
+    .description('internal: the watchdog scheduler process')
+    .action(async (opts) => {
+    try {
+        let stop = false;
+        process.on('SIGTERM', () => { stop = true; });
+        await runScheduler(opts.configuration, {
+            now: () => new Date(), sleep: ms => new Promise(r => setTimeout(r, ms)),
+            log: l => console.log(l), binPath, shouldStop: () => stop,
+        });
+    }
+    catch (e) {
+        die(e);
+    }
+});
 program.parseAsync(process.argv);

package/dist/config.d.ts

@@ -1,5 +1,6 @@
 import { type ConfigDiagnostic, type YamlMode } from './config-yaml.js';
 import type { IsolationConfig, WrapContext } from './isolation/types.js';
+import type { ResolvedWatchdog } from './watchdog/config.js';
 export interface OverseeEntry {
     role: string;
     interval: string;
@@ -114,6 +115,7 @@ export interface FleetConfig {
     startStaggerMs: number;
     /** Warning-first non-plain YAML migration diagnostics, in source order. */
     diagnostics: ConfigDiagnostic[];
+    watchdogs: ResolvedWatchdog[];
 }
 export declare class ConfigError extends Error {
 }

package/dist/config.js

@@ -4,6 +4,7 @@ import { agentDir, defaultConfigPath, fleetDDir, home } from './paths.js';
 import { parseFleetDocument, } from './config-yaml.js';
 import { harnessRuntimeDir, resolveIsolation, validateIsolationConfig, } from './isolation/policy.js';
 import { getAdapter } from './harness/registry.js';
+import { resolveWatchdogs } from './watchdog/config.js';
 /** The 8 content-free event types the ours daemon appends to notifications.log. */
 export const NOTIFY_EVENT_TYPES = [
     'message_received', 'file_received', 'sibling_contact_added', 'local_contact_request',
@@ -234,7 +235,8 @@ export function loadConfig(configPath, options = {}) {
             }
         }
     }
-    return { roles, vars, defaults, files, startStaggerMs, diagnostics };
+    const watchdogs = resolveWatchdogs(baseDoc, base, roles, vars, defaults);
+    return { roles, vars, defaults, files, startStaggerMs, diagnostics, watchdogs };
 }
 export function resolveModelChain(model, chain, file = 'config', name = 'role') {
     if (chain === undefined)

package/dist/docs.d.ts

@@ -4,7 +4,7 @@
  * Keep this concise enough to place directly in an agent context. Unlike
  * Commander's per-command help, this describes how the pieces compose.
  */
-export declare const AI_DOCS = "# ours-fleet reference\n\nours-fleet runs persistent or temporary, identity-bound AI roles. A role selects\na harness independently from its session backend:\n\n- harness: `claude-code` or `codex`\n- session: `tmux` (default) or `acp`\n- lifetime: permanent (supervised, restartable) or `spawn --temp`\n\n## Discover and validate\n\n```sh\nours-fleet docs                         # this complete reference (`man` is an alias)\nours-fleet help <command>               # exact flags for one command\nours-fleet config [-c FILE]             # validate and print the merged plan; no changes\nours-fleet doctor [-c FILE] [--harness codex|claude-code]\n```\n\nDefault configuration is `~/fleet.yaml` plus sorted `~/fleet.d/*.yaml` role\ndrop-ins. An explicit `-c FILE` replaces `~/fleet.yaml`; fleet.d still adds\nroles. Validate with `config` and `doctor` before starting or restarting.\n\n## Lifecycle and console commands\n\n```sh\nours-fleet init\nours-fleet up|down [Name...]\nours-fleet restart [Name...]            # preserve/resume harness context\nours-fleet force-restart [Name...]      # fresh context; briefing is reloaded\nours-fleet ls\nours-fleet status|peek|attach|logs Name\nours-fleet logs -f Name\nours-fleet send Name \"prompt\"\nours-fleet send Name --key Enter        # tmux only\nours-fleet rm Name\n```\n\n`peek`, `attach`, and text `send` work with tmux and ACP. ACP attachment\nalso accepts `/permit <permission-id> <option-id>`, `/interrupt`, and\n`/detach`. Raw `--key` input is tmux-only.\n\n## Local web console\n\nThe npm package includes the web console; installed users do not clone the repo\nor run `npm run build`:\n\n```sh\nnpm i -g @ours.network/fleet\nours-fleet init\nours-fleet doctor\nours-fleet web                         # install/update service, start, pair browser\n```\n\nThe normal command uses stable `http://127.0.0.1:49271/`, installs an\nowner-level systemd user service (Linux) or LaunchAgent (macOS), and opens a\nfive-minute one-use pairing link in the local browser. After pairing, bookmark\nthe plain URL or install the PWA. To pair a new, signed-out, or revoked browser,\nrun `ours-fleet web open`.\n\n```sh\nours-fleet web status\nours-fleet web start|stop|restart\nours-fleet web open\nours-fleet web revoke-all              # revoke every browser and active session\nours-fleet web uninstall\nours-fleet web serve --port 0 --no-open # isolated foreground/testing mode\n```\n\nThe console is intentionally IPv4-loopback-only. It has no LAN/Internet host,\nproxy, TLS, or remote-access mode. Do not expose port 49271 through a reverse\nproxy. Browser credentials are HttpOnly/SameSite, and `revoke-all` invalidates\nall trusted devices. Role creation offers harness-scoped known-model choices\nwhile still accepting a typed model ID; blank explicitly uses the selected\nharness's own default.\n\n## Spawn\n\n```sh\nours-fleet spawn [--temp] Name \\\n  --harness codex|claude-code --session tmux|acp \\\n  --mission \"one line\" --cwd /absolute/path --identity Identity \\\n  --coordinator Coordinator --model MODEL \\\n  --approval ask|allow|deny \\\n  --filesystem read-only|workspace|unrestricted \\\n  --unattended deny|wait \\\n  --bio-file /path/bio.md --persona-file /path/persona.md\n```\n\nPermanent spawn writes `~/fleet.d/Name.yaml` and starts a supervised role.\n`--temp` writes ephemeral state, starts a detached supervisor, and removes the\nrole after exit/reboot. Both lifetimes support `--session acp`.\n\nCodex-specific spawn flags: `--sandbox`, `--permission-mode`, `--launcher`,\n`--profile`, `--search`, repeatable `--codex-config key=value`, repeatable\n`--add-dir`, and legacy `--monitor` (consent for the native Codex monitor,\nnot the `monitor.mode` wake-owner selector). Run `ours-fleet help spawn` for\nexact values.\n\n## fleet.yaml\n\n```yaml\nvars:\n  work_root: /home/me/work\nstart_stagger_ms: 0\ndefaults:\n  harness: codex\n  session: acp\n  model: gpt-model-id\n  permissions:\n    approval: ask\n    filesystem: workspace\n    unattended: deny\n  monitor:\n    mode: fleet                          # fleet (default) | native\nroles:\n  Coordinator:\n    harness: codex\n    session: acp\n    identity: Coordinator\n    cwd: ${work_root}/project\n    mission: Coordinate work and delegate implementation.\n    model: gpt-model-id\n    permissions:\n      approval: ask\n      filesystem: workspace\n      unattended: deny\n    session_options:                    # advanced overrides; normally omit\n      # acp:\n      #   command: [/custom/codex-acp, --flag]\n      tmux:\n        boot_grace_ms: 10000\n    monitor:\n      mode: fleet                        # fleet supervisor | native harness monitor\n      interrupt: false                    # true cancels active work before every configured wake\n      wake_sources: [message_received, file_received, local_contact_request, pending_message]\n      batch_ms: 2000\n      inject: notification\n      turn_fail_threshold: 3\n    harness_options:\n      launcher: auto\n      sandbox: workspace-write\n      approval: on-request\n      search: false\n      profile: fleet\n      add_dirs: [/data/shared]\n      config:\n        model_reasoning_effort: high\n    bio: Public role card and when peers should engage it.\n    persona: Local operating contract, boundaries, and escalation policy.\n    briefing_file: /absolute/custom-briefing.md\n    coordinator: AnotherCoordinator\n    env:\n      KEY: value\n    oversee:\n      - { role: Worker, interval: 5m }\n```\n\nRole values override defaults. `${name}` substitutes entries from `vars`.\nOther role fields include `max_tokens`, `autocompact_pct`, and `isolation`.\nUse README.md for the complete isolation policy and resource-cap schema.\n\n## Permissions\n\nPrefer the harness-neutral `permissions` block:\n\n- `approval: ask|allow|deny`: whether actions may request or receive approval\n- `filesystem: read-only|workspace|unrestricted`: filesystem intent\n- `unattended: deny|wait`: what ACP does when no console can answer a request\n\nThe backend translates this common intent. Harness-native settings in\n`harness_options` take precedence where supplied. Do not choose\n`allow`/`unrestricted`, Codex `never`/`danger-full-access`, or Claude\n`bypassPermissions` without explicit authorization.\n\n### Creation-time isolation\n\n`ours-fleet spawn --isolation-file <path>` supplies a role's sandbox policy at\ncreation, so the FIRST launch is already confined \u2014 a role that only gains\n`isolation:` on a later `up` ran unsandboxed until then.\n\nThe file holds exactly the `isolation:` mapping documented above and nothing\nelse \u2014 the same schema, validated by the same code, so a policy written here\ncannot mean something different from the identical block in fleet.yaml:\n\n```yaml\nnetwork: deny\nfs:\n  read: [/opt/reference]\nresources:\n  mem: 2G\n```\n\nInvalid files are rejected before anything is created: no config, no state\ndirectory, no identity reservation. Works for both permanent and `--temp` roles.\n\n### Never-prompt failure\n\nThe failure this section exists to prevent leaves no error message anywhere.\n\nAn unattended role has no console. When the harness needs a permission decision\nthere is nobody to ask, so the request is refused INSIDE the harness \u2014 no\nprompt, no error, no log line. The agent simply does less than its briefing told\nit to, reports success, and nothing distinguishes that from having done the\nwork. Two settings produce it:\n\n1. a permission mode that suppresses the prompt without granting the action\n   (Claude `dontAsk`, which is why neutral `allow` maps to\n   `bypassPermissions` instead); and\n2. `unattended: deny`, which refuses every request that reaches it.\n\n**Automatic decisions are now recorded.** Every permission request decided\nwithout a human emits a completed event into\n`~/.ours-fleet/agents/<Name>/.session-events.jsonl` carrying the decision,\nwhether policy or a person made it, the policy that produced it\n(`permissions.unattended=deny` vs `permissions.approval=deny`/`=allow`),\nthe reason, and the option selected. `ours-fleet peek` and `attach` render\nthem. Automatic denial asks for a one-shot rejection, never a standing one, so a\nsingle unattended refusal cannot disable a tool for the rest of the session.\n\nA role that can auto-deny logs one line at startup saying so.\n\nTo detect an under-permissioned role BEFORE it runs, use the capability floor\nbelow: `ours-fleet doctor` fails such a role rather than letting it discover\nthe problem silently at work.\n\n### The unattended capability floor\n\nAn unattended role has no console, so a permission request cannot be answered \u2014\nit is refused, silently, inside the harness. The agent then does less than it\nwas told to and reports no error. To make that visible before launch,\n`ours-fleet config` and `ours-fleet doctor` resolve each role's neutral\npermissions through its harness and check the result against a fixed floor:\n\n- `read-state` \u2014 read its briefing, ROUTINES.md, and WORKLOG.md\n- `write-state` \u2014 append its WORKLOG and its own state files\n- `messaging` \u2014 bind its identity, send and receive ours mail\n- `monitor` \u2014 arm and observe its mail monitor\n- `workspace-edit` \u2014 edit and test files in its working directory\n- `status-commands` \u2014 run the inspection commands its briefing prescribes\n\n`doctor` reports this per role as `unattended floor: <Role>`. A role with\n`unattended: deny` that cannot meet the floor FAILS doctor, because it will\ndeny those requests with nobody to see it; with `unattended: wait` it warns,\nbecause a human can still attach and answer.\n\nSecurity meaning: `approval: allow` maps to Claude's `bypassPermissions`,\nwhich genuinely permits the actions the role was authorized to take \u2014\n`dontAsk` only suppresses the prompt while still refusing the action. Nothing\nother than an explicit `allow` is elevated: `ask` stays on Claude's default\nmode and `deny` maps to `plan`. `allow` is therefore a real grant and\nrequires explicit authorization; per-role `isolation:` remains the outer\nboundary that a permission mode cannot cross.\n\nSee also: `spawn --approval/--filesystem/--unattended` set this intent at\ncreation, and `ours-fleet config` prints each role's neutral settings, their\nnative translation, and any warning \u2014 the same text `doctor` reports.\n\nClaude `harness_options`: `permission_mode` (default, acceptEdits, plan,\ndontAsk, bypassPermissions), `plugins`, `mem_palace`, and\n`mem_palace_midsession_autosave`.\n\nCodex `harness_options`: `launcher` (auto, ours-codex, codex), `sandbox`\n(read-only, workspace-write, danger-full-access), `approval` or\n`permission_mode` (untrusted, on-request, never), `profile`, `search`,\n`config`, `add_dirs`, and `monitor`.\n\n## ACP adapters\n\nThe maintained `@agentclientprotocol/codex-acp` and\n`@agentclientprotocol/claude-agent-acp` runtimes are bundled automatically as\noptional ours-fleet dependencies. The supervisor resolves their executable\nentrypoints internally, so default ACP roles do not depend on global PATH.\nThe maintained Claude adapter requires Node 22; tmux and Codex ACP continue to\nwork on the ours-fleet core minimum of Node 20.\n\nOverride an adapter only when necessary with `session_options.acp.command`\n(string or argv list). If optional dependencies were deliberately omitted,\nours-fleet falls back to a compatible globally installed `codex-acp` or\n`claude-agent-acp`. `ours-fleet doctor -c FILE` verifies the resolved adapter.\n\n## Reliable mail wake\n\n`monitor.mode` selects exactly one wake owner:\n\n- `fleet` (default): the ours-fleet supervisor consumes body-free daemon\n  events and advances its durable cursor only after delivery is accepted. ACP\n  uses live steering when supported and falls back to structured\n  `session/prompt`; tmux uses verified console injection.\n- `native`: ours-fleet starts no supervisor monitor; the generated briefing\n  instructs Claude Code or Codex to arm its harness-native wake mechanism.\n\nSet `monitor.interrupt: true` in fleet mode to cancel active work before every\nconfigured wake. The policy is content-blind because the supervisor cannot\ninspect encrypted message bodies. Message bodies are released only when the\nrole calls the ours `get_messages` tool.\n\nLegacy `monitor.enabled: true|false` remains accepted as an alias for\n`mode: fleet|native`; use `mode` in new configuration. Codex's separate\n`harness_options.monitor: true` is native-monitor consent, not monitor-owner\nselection.\nInspect `ours-fleet status Name`, `peek Name`, role logs, and\n`~/.ours-fleet/agents/Name/.monitor-status` when diagnosing delivery.\n\n## Stable config and YAML migration\n\n`ours-fleet config --json` emits schemaVersion 1 resolved plans. Environment\nvalues and mission/persona/bio bodies are withheld; environment keys are sorted\nand values are marked redacted. Additive fields may appear in schema 1, while a\nremoval or semantic reuse requires a new schema version.\n\nYAML parsing always rejects duplicate keys. The current default\n`--yaml-mode compat` warns with file/line/column for anchors, aliases, explicit\ntags, non-scalar keys, and multiple documents. Use `--yaml-mode strict` in CI\nnow; strict becomes the next-major default and compat is the temporary migration\nescape hatch.\n\n## Bounded worklogs, auth proxy, and model recovery\n\nAn optional `worklog: { max_kb, keep_tail_kb, max_archives }` policy rotates a\nstable snapshot at fleet-owned lifecycle points. Concurrent changes defer\nrotation. Archives remain beside WORKLOG.md with the same sensitive-state\nboundary; retention deletes only recognized fleet archive names.\n\n`auth_proxy: { kind: anthropic, base_url, required, health_url }` is Claude-only\nand loopback-only. Fleet injects only ANTHROPIC_BASE_URL and doctor rejects\ncredential env keys. The privileged reference companion is\n`contrib/anthropic-auth-proxy.mjs`; deploy it separately as a dedicated account\nwith a 0600 token file and per-role listener access. Fleet never installs it or\nreads its credential.\n\n`model_chain` is an ordered authorization list and its first entry must equal\n`model`. Only sustained high-confidence entitlement/quota 429 evidence advances\none entry. Transient 429, overload, auth, policy, and unknown errors never\ndown-shift. Runtime state is atomic in .model-recovery.json; exhaustion is\nfail-closed and held down. Change the declared chain/model and restart to\nreconcile explicitly; no chain preserves detection-only behavior.\n";
+export declare const AI_DOCS = "# ours-fleet reference\n\nours-fleet runs persistent or temporary, identity-bound AI roles. A role selects\na harness independently from its session backend:\n\n- harness: `claude-code` or `codex`\n- session: `tmux` (default) or `acp`\n- lifetime: permanent (supervised, restartable) or `spawn --temp`\n\n## Discover and validate\n\n```sh\nours-fleet docs                         # this complete reference (`man` is an alias)\nours-fleet help <command>               # exact flags for one command\nours-fleet config [-c FILE]             # validate and print the merged plan; no changes\nours-fleet doctor [-c FILE] [--harness codex|claude-code]\n```\n\nDefault configuration is `~/fleet.yaml` plus sorted `~/fleet.d/*.yaml` role\ndrop-ins. An explicit `-c FILE` replaces `~/fleet.yaml`; fleet.d still adds\nroles. Validate with `config` and `doctor` before starting or restarting.\n\n## Lifecycle and console commands\n\n```sh\nours-fleet init\nours-fleet up|down [Name...]\nours-fleet restart [Name...]            # preserve/resume harness context\nours-fleet force-restart [Name...]      # fresh context; briefing is reloaded\nours-fleet ls\nours-fleet status|peek|attach|logs Name\nours-fleet logs -f Name\nours-fleet send Name \"prompt\"\nours-fleet send Name --key Enter        # tmux only\nours-fleet rm Name\nours-fleet watchdog-report <name> [run-id] [--list] [--json]\nours-fleet watchdog-run <name>\n```\n\n`peek`, `attach`, and text `send` work with tmux and ACP. ACP attachment\nalso accepts `/permit <permission-id> <option-id>`, `/interrupt`, and\n`/detach`. Raw `--key` input is tmux-only.\n\n## Local web console\n\nThe npm package includes the web console; installed users do not clone the repo\nor run `npm run build`:\n\n```sh\nnpm i -g @ours.network/fleet\nours-fleet init\nours-fleet doctor\nours-fleet web                         # install/update service, start, pair browser\n```\n\nThe normal command uses stable `http://127.0.0.1:49271/`, installs an\nowner-level systemd user service (Linux) or LaunchAgent (macOS), and opens a\nfive-minute one-use pairing link in the local browser. After pairing, bookmark\nthe plain URL or install the PWA. To pair a new, signed-out, or revoked browser,\nrun `ours-fleet web open`.\n\n```sh\nours-fleet web status\nours-fleet web start|stop|restart\nours-fleet web open\nours-fleet web revoke-all              # revoke every browser and active session\nours-fleet web uninstall\nours-fleet web serve --port 0 --no-open # isolated foreground/testing mode\n```\n\nThe console is intentionally IPv4-loopback-only. It has no LAN/Internet host,\nproxy, TLS, or remote-access mode. Do not expose port 49271 through a reverse\nproxy. Browser credentials are HttpOnly/SameSite, and `revoke-all` invalidates\nall trusted devices. Role creation offers harness-scoped known-model choices\nwhile still accepting a typed model ID; blank explicitly uses the selected\nharness's own default.\n\n## Spawn\n\n```sh\nours-fleet spawn [--temp] Name \\\n  --harness codex|claude-code --session tmux|acp \\\n  --mission \"one line\" --cwd /absolute/path --identity Identity \\\n  --coordinator Coordinator --model MODEL \\\n  --approval ask|allow|deny \\\n  --filesystem read-only|workspace|unrestricted \\\n  --unattended deny|wait \\\n  --bio-file /path/bio.md --persona-file /path/persona.md\n```\n\nPermanent spawn writes `~/fleet.d/Name.yaml` and starts a supervised role.\n`--temp` writes ephemeral state, starts a detached supervisor, and removes the\nrole after exit/reboot. Both lifetimes support `--session acp`.\n\nCodex-specific spawn flags: `--sandbox`, `--permission-mode`, `--launcher`,\n`--profile`, `--search`, repeatable `--codex-config key=value`, repeatable\n`--add-dir`, and legacy `--monitor` (consent for the native Codex monitor,\nnot the `monitor.mode` wake-owner selector). Run `ours-fleet help spawn` for\nexact values.\n\n## fleet.yaml\n\n```yaml\nvars:\n  work_root: /home/me/work\nstart_stagger_ms: 0\ndefaults:\n  harness: codex\n  session: acp\n  model: gpt-model-id\n  permissions:\n    approval: ask\n    filesystem: workspace\n    unattended: deny\n  monitor:\n    mode: fleet                          # fleet (default) | native\nroles:\n  Coordinator:\n    harness: codex\n    session: acp\n    identity: Coordinator\n    cwd: ${work_root}/project\n    mission: Coordinate work and delegate implementation.\n    model: gpt-model-id\n    permissions:\n      approval: ask\n      filesystem: workspace\n      unattended: deny\n    session_options:                    # advanced overrides; normally omit\n      # acp:\n      #   command: [/custom/codex-acp, --flag]\n      tmux:\n        boot_grace_ms: 10000\n    monitor:\n      mode: fleet                        # fleet supervisor | native harness monitor\n      interrupt: false                    # true cancels active work before every configured wake\n      wake_sources: [message_received, file_received, local_contact_request, pending_message]\n      batch_ms: 2000\n      inject: notification\n      turn_fail_threshold: 3\n    harness_options:\n      launcher: auto\n      sandbox: workspace-write\n      approval: on-request\n      search: false\n      profile: fleet\n      add_dirs: [/data/shared]\n      config:\n        model_reasoning_effort: high\n    bio: Public role card and when peers should engage it.\n    persona: Local operating contract, boundaries, and escalation policy.\n    briefing_file: /absolute/custom-briefing.md\n    coordinator: AnotherCoordinator\n    env:\n      KEY: value\n    oversee:\n      - { role: Worker, interval: 5m }\nwatchdogs:\n  nightwatch:                       # [A-Za-z0-9_-], must not collide with a role name\n    coordinator: FleetCoordinator   # required \u2014 where alerts go\n    # everything below is optional\n    enabled: true                   # default true; false = configured but never scheduled\n    interval: 10m                   # default 10m; 30s | 10m | 2h, minimum 1m\n    watch: [Alice, CodexReviewer]   # default: every role in the merged config\n    harness: claude-code            # default: defaults.harness\n    model: claude-fable-5           # default: same resolution rule roles use (resolveRoleModel)\n    session: acp                    # default: defaults.session\n    identity: Watchdog-nightwatch   # default: Watchdog-<name>\n    timeout: 5m                     # default 5m; a run past this is killed and recorded as error\n    keep_reports: 50                # default 50 reports retained per watchdog\n    alert_cooldown: 60m             # default 60m before the same finding alerts again\n    prompt_file: /abs/extra.md      # optional extra focus, APPENDED to the fixed contract\n```\n\nA watchdog observes and reports; it never restarts, stops, spawns, or removes a\nrole, answers a pending permission, edits a workspace, or approves anything on\nthe owner's behalf. `watchdogs:` may appear only in the base config\n(`~/fleet.yaml` or `-c FILE`), not in `~/fleet.d/*.yaml` drop-ins.\n\nRole values override defaults. `${name}` substitutes entries from `vars`.\nOther role fields include `max_tokens`, `autocompact_pct`, and `isolation`.\nUse README.md for the complete isolation policy and resource-cap schema.\n\n## Permissions\n\nPrefer the harness-neutral `permissions` block:\n\n- `approval: ask|allow|deny`: whether actions may request or receive approval\n- `filesystem: read-only|workspace|unrestricted`: filesystem intent\n- `unattended: deny|wait`: what ACP does when no console can answer a request\n\nThe backend translates this common intent. Harness-native settings in\n`harness_options` take precedence where supplied. Do not choose\n`allow`/`unrestricted`, Codex `never`/`danger-full-access`, or Claude\n`bypassPermissions` without explicit authorization.\n\n### Creation-time isolation\n\n`ours-fleet spawn --isolation-file <path>` supplies a role's sandbox policy at\ncreation, so the FIRST launch is already confined \u2014 a role that only gains\n`isolation:` on a later `up` ran unsandboxed until then.\n\nThe file holds exactly the `isolation:` mapping documented above and nothing\nelse \u2014 the same schema, validated by the same code, so a policy written here\ncannot mean something different from the identical block in fleet.yaml:\n\n```yaml\nnetwork: deny\nfs:\n  read: [/opt/reference]\nresources:\n  mem: 2G\n```\n\nInvalid files are rejected before anything is created: no config, no state\ndirectory, no identity reservation. Works for both permanent and `--temp` roles.\n\n### Never-prompt failure\n\nThe failure this section exists to prevent leaves no error message anywhere.\n\nAn unattended role has no console. When the harness needs a permission decision\nthere is nobody to ask, so the request is refused INSIDE the harness \u2014 no\nprompt, no error, no log line. The agent simply does less than its briefing told\nit to, reports success, and nothing distinguishes that from having done the\nwork. Two settings produce it:\n\n1. a permission mode that suppresses the prompt without granting the action\n   (Claude `dontAsk`, which is why neutral `allow` maps to\n   `bypassPermissions` instead); and\n2. `unattended: deny`, which refuses every request that reaches it.\n\n**Automatic decisions are now recorded.** Every permission request decided\nwithout a human emits a completed event into\n`~/.ours-fleet/agents/<Name>/.session-events.jsonl` carrying the decision,\nwhether policy or a person made it, the policy that produced it\n(`permissions.unattended=deny` vs `permissions.approval=deny`/`=allow`),\nthe reason, and the option selected. `ours-fleet peek` and `attach` render\nthem. Automatic denial asks for a one-shot rejection, never a standing one, so a\nsingle unattended refusal cannot disable a tool for the rest of the session.\n\nA role that can auto-deny logs one line at startup saying so.\n\nTo detect an under-permissioned role BEFORE it runs, use the capability floor\nbelow: `ours-fleet doctor` fails such a role rather than letting it discover\nthe problem silently at work.\n\n### The unattended capability floor\n\nAn unattended role has no console, so a permission request cannot be answered \u2014\nit is refused, silently, inside the harness. The agent then does less than it\nwas told to and reports no error. To make that visible before launch,\n`ours-fleet config` and `ours-fleet doctor` resolve each role's neutral\npermissions through its harness and check the result against a fixed floor:\n\n- `read-state` \u2014 read its briefing, ROUTINES.md, and WORKLOG.md\n- `write-state` \u2014 append its WORKLOG and its own state files\n- `messaging` \u2014 bind its identity, send and receive ours mail\n- `monitor` \u2014 arm and observe its mail monitor\n- `workspace-edit` \u2014 edit and test files in its working directory\n- `status-commands` \u2014 run the inspection commands its briefing prescribes\n\n`doctor` reports this per role as `unattended floor: <Role>`. A role with\n`unattended: deny` that cannot meet the floor FAILS doctor, because it will\ndeny those requests with nobody to see it; with `unattended: wait` it warns,\nbecause a human can still attach and answer.\n\nSecurity meaning: `approval: allow` maps to Claude's `bypassPermissions`,\nwhich genuinely permits the actions the role was authorized to take \u2014\n`dontAsk` only suppresses the prompt while still refusing the action. Nothing\nother than an explicit `allow` is elevated: `ask` stays on Claude's default\nmode and `deny` maps to `plan`. `allow` is therefore a real grant and\nrequires explicit authorization; per-role `isolation:` remains the outer\nboundary that a permission mode cannot cross.\n\nSee also: `spawn --approval/--filesystem/--unattended` set this intent at\ncreation, and `ours-fleet config` prints each role's neutral settings, their\nnative translation, and any warning \u2014 the same text `doctor` reports.\n\nClaude `harness_options`: `permission_mode` (default, acceptEdits, plan,\ndontAsk, bypassPermissions), `plugins`, `mem_palace`, and\n`mem_palace_midsession_autosave`.\n\nCodex `harness_options`: `launcher` (auto, ours-codex, codex), `sandbox`\n(read-only, workspace-write, danger-full-access), `approval` or\n`permission_mode` (untrusted, on-request, never), `profile`, `search`,\n`config`, `add_dirs`, and `monitor`.\n\n## ACP adapters\n\nThe maintained `@agentclientprotocol/codex-acp` and\n`@agentclientprotocol/claude-agent-acp` runtimes are bundled automatically as\noptional ours-fleet dependencies. The supervisor resolves their executable\nentrypoints internally, so default ACP roles do not depend on global PATH.\nThe maintained Claude adapter requires Node 22; tmux and Codex ACP continue to\nwork on the ours-fleet core minimum of Node 20.\n\nOverride an adapter only when necessary with `session_options.acp.command`\n(string or argv list). If optional dependencies were deliberately omitted,\nours-fleet falls back to a compatible globally installed `codex-acp` or\n`claude-agent-acp`. `ours-fleet doctor -c FILE` verifies the resolved adapter.\n\n## Reliable mail wake\n\n`monitor.mode` selects exactly one wake owner:\n\n- `fleet` (default): the ours-fleet supervisor consumes body-free daemon\n  events and advances its durable cursor only after delivery is accepted. ACP\n  uses live steering when supported and falls back to structured\n  `session/prompt`; tmux uses verified console injection.\n- `native`: ours-fleet starts no supervisor monitor; the generated briefing\n  instructs Claude Code or Codex to arm its harness-native wake mechanism.\n\nSet `monitor.interrupt: true` in fleet mode to cancel active work before every\nconfigured wake. The policy is content-blind because the supervisor cannot\ninspect encrypted message bodies. Message bodies are released only when the\nrole calls the ours `get_messages` tool.\n\nLegacy `monitor.enabled: true|false` remains accepted as an alias for\n`mode: fleet|native`; use `mode` in new configuration. Codex's separate\n`harness_options.monitor: true` is native-monitor consent, not monitor-owner\nselection.\nInspect `ours-fleet status Name`, `peek Name`, role logs, and\n`~/.ours-fleet/agents/Name/.monitor-status` when diagnosing delivery.\n\n## Stable config and YAML migration\n\n`ours-fleet config --json` emits schemaVersion 1 resolved plans. Environment\nvalues and mission/persona/bio bodies are withheld; environment keys are sorted\nand values are marked redacted. Additive fields may appear in schema 1, while a\nremoval or semantic reuse requires a new schema version.\n\nYAML parsing always rejects duplicate keys. The current default\n`--yaml-mode compat` warns with file/line/column for anchors, aliases, explicit\ntags, non-scalar keys, and multiple documents. Use `--yaml-mode strict` in CI\nnow; strict becomes the next-major default and compat is the temporary migration\nescape hatch.\n\n## Bounded worklogs, auth proxy, and model recovery\n\nAn optional `worklog: { max_kb, keep_tail_kb, max_archives }` policy rotates a\nstable snapshot at fleet-owned lifecycle points. Concurrent changes defer\nrotation. Archives remain beside WORKLOG.md with the same sensitive-state\nboundary; retention deletes only recognized fleet archive names.\n\n`auth_proxy: { kind: anthropic, base_url, required, health_url }` is Claude-only\nand loopback-only. Fleet injects only ANTHROPIC_BASE_URL and doctor rejects\ncredential env keys. The privileged reference companion is\n`contrib/anthropic-auth-proxy.mjs`; deploy it separately as a dedicated account\nwith a 0600 token file and per-role listener access. Fleet never installs it or\nreads its credential.\n\n`model_chain` is an ordered authorization list and its first entry must equal\n`model`. Only sustained high-confidence entitlement/quota 429 evidence advances\none entry. Transient 429, overload, auth, policy, and unknown errors never\ndown-shift. Runtime state is atomic in .model-recovery.json; exhaustion is\nfail-closed and held down. Change the declared chain/model and restart to\nreconcile explicitly; no chain preserves detection-only behavior.\n";
 /**
  * What every shipped spawn-skill variant must say, and must not say (7.1).
  *

package/dist/docs.js

@@ -39,6 +39,8 @@ ours-fleet logs -f Name
 ours-fleet send Name "prompt"
 ours-fleet send Name --key Enter        # tmux only
 ours-fleet rm Name
+ours-fleet watchdog-report <name> [run-id] [--list] [--json]
+ours-fleet watchdog-run <name>
 \`\`\`
 
 \`peek\`, \`attach\`, and text \`send\` work with tmux and ACP. ACP attachment
@@ -159,8 +161,28 @@ roles:
       KEY: value
     oversee:
       - { role: Worker, interval: 5m }
+watchdogs:
+  nightwatch:                       # [A-Za-z0-9_-], must not collide with a role name
+    coordinator: FleetCoordinator   # required — where alerts go
+    # everything below is optional
+    enabled: true                   # default true; false = configured but never scheduled
+    interval: 10m                   # default 10m; 30s | 10m | 2h, minimum 1m
+    watch: [Alice, CodexReviewer]   # default: every role in the merged config
+    harness: claude-code            # default: defaults.harness
+    model: claude-fable-5           # default: same resolution rule roles use (resolveRoleModel)
+    session: acp                    # default: defaults.session
+    identity: Watchdog-nightwatch   # default: Watchdog-<name>
+    timeout: 5m                     # default 5m; a run past this is killed and recorded as error
+    keep_reports: 50                # default 50 reports retained per watchdog
+    alert_cooldown: 60m             # default 60m before the same finding alerts again
+    prompt_file: /abs/extra.md      # optional extra focus, APPENDED to the fixed contract
 \`\`\`
 
+A watchdog observes and reports; it never restarts, stops, spawns, or removes a
+role, answers a pending permission, edits a workspace, or approves anything on
+the owner's behalf. \`watchdogs:\` may appear only in the base config
+(\`~/fleet.yaml\` or \`-c FILE\`), not in \`~/fleet.d/*.yaml\` drop-ins.
+
 Role values override defaults. \`\${name}\` substitutes entries from \`vars\`.
 Other role fields include \`max_tokens\`, \`autocompact_pct\`, and \`isolation\`.
 Use README.md for the complete isolation policy and resource-cap schema.

package/dist/duration.d.ts

@@ -0,0 +1,5 @@
+export declare function parseDuration(text: string, opts?: {
+    name?: string;
+    minMs?: number;
+}): number;
+export declare function formatDuration(ms: number): string;

package/dist/duration.js

@@ -0,0 +1,20 @@
+/** Parse `30s | 10m | 2h` duration strings to milliseconds (spec §2). */
+const UNIT_MS = { s: 1_000, m: 60_000, h: 3_600_000 };
+const RE = /^(\d+)([smh])$/;
+export function parseDuration(text, opts = {}) {
+    const label = opts.name ?? 'duration';
+    const m = RE.exec(text);
+    if (!m)
+        throw new Error(`${label}: invalid duration '${text}' (expected e.g. 30s, 10m, 2h)`);
+    const ms = Number(m[1]) * UNIT_MS[m[2]];
+    if (opts.minMs !== undefined && ms < opts.minMs)
+        throw new Error(`${label}: '${text}' is below the minimum ${formatDuration(opts.minMs)}`);
+    return ms;
+}
+export function formatDuration(ms) {
+    if (ms % 3_600_000 === 0 && ms >= 3_600_000)
+        return `${ms / 3_600_000}h`;
+    if (ms % 60_000 === 0 && ms >= 60_000)
+        return `${ms / 60_000}m`;
+    return `${Math.round(ms / 1_000)}s`;
+}

package/dist/ops.d.ts

@@ -16,6 +16,22 @@ export interface OpsDeps {
      * `ours-fleet up` has no transaction to tell.
      */
     onInstalled?(outcome: InstallOutcome): void;
+    /**
+     * Optional: supervises the single watchdog-scheduler process (Task 10).
+     * Absent for callers that predate watchdogs — `up`/`down` must never throw
+     * just because this hook is missing.
+     */
+    watchdogService?: {
+        /** `changed` is true when the unit/plist content itself differs from what's on disk (or was absent). */
+        install(binPath: string, configPath?: string): Promise<{
+            changed: boolean;
+        }>;
+        start(): Promise<void>;
+        stop(): Promise<void>;
+        /** Bounces an already-running scheduler so a config change actually reaches it — `start()` is a no-op on an active unit. */
+        restart(): Promise<void>;
+        supervised(): boolean;
+    };
 }
 /** Materialize a role's state dir from config: briefing + markers. Returns the dir. */
 export declare function applyRole(role: ResolvedRole, opts?: {

package/dist/ops.js

@@ -1,7 +1,7 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, unlinkSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, unlinkSync, } from 'node:fs';
 import { join } from 'node:path';
-import { randomUUID } from 'node:crypto';
-import { agentDir, fleetDDir } from './paths.js';
+import { randomUUID, createHash } from 'node:crypto';
+import { agentDir, fleetDDir, watchdogsRoot } from './paths.js';
 import { findRole } from './config.js';
 import { getAdapter } from './harness/registry.js';
 import { generateBriefing } from './briefing.js';
@@ -75,8 +75,103 @@ export async function up(cfg, names, deps, configPath, identityGuarantee) {
         outcomes.push(outcome);
         deps.log(`↑ up: ${role.name} (harness: ${role.harness}, identity: ${role.identity}${role.cwd ? `, cwd: ${role.cwd}` : ''})`);
     }
+    await reconcileWatchdogScheduler(cfg, deps, configPath);
     return outcomes;
 }
+const WATCHDOG_FINGERPRINT_FILE = '.config-fingerprint';
+/** Deterministic JSON: object keys sorted recursively, so key-insertion order never affects the hash. */
+function stableStringify(value) {
+    return JSON.stringify(value, (_key, v) => {
+        if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
+            return Object.keys(v).sort()
+                .reduce((acc, k) => { acc[k] = v[k]; return acc; }, {});
+        }
+        return v;
+    });
+}
+/** sha256 over the resolved enabled-watchdog set, stable regardless of config source order (finding #4). */
+function watchdogFingerprint(enabled) {
+    const sorted = [...enabled].sort((a, b) => a.name.localeCompare(b.name));
+    return createHash('sha256').update(stableStringify(sorted)).digest('hex');
+}
+function fingerprintPath() {
+    return join(watchdogsRoot(), WATCHDOG_FINGERPRINT_FILE);
+}
+function readStoredFingerprint() {
+    try {
+        return readFileSync(fingerprintPath(), 'utf8').trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeFingerprint(fingerprint) {
+    mkdirSync(watchdogsRoot(), { recursive: true, mode: 0o700 });
+    writeFileSync(fingerprintPath(), fingerprint + '\n', { mode: 0o600 });
+    chmodSync(fingerprintPath(), 0o600); // mkdirSync/writeFileSync's mode is masked by umask; force it
+}
+/**
+ * Install/start (or stop) the single supervised watchdog-scheduler process
+ * (Task 10) to match the config's enabled watchdogs. Runs on every `up`,
+ * including a named `up <Role>` — cheap and idempotent, and the alternative
+ * (only reconciling on a whole-fleet `up`) would leave a newly-enabled
+ * watchdog unscheduled until the next bare `up`. Never throws: a scheduler
+ * hiccup must not fail the role installs that already succeeded.
+ *
+ * Restarts ONLY when something the scheduler actually needs to pick up
+ * changed (finding #4): an unconditional `restart()` on every `up` —
+ * including a named `up <SomeUnrelatedRole>` — interrupted whatever the
+ * scheduler was mid-run (a 15s stop timeout can kill a long check without a
+ * report). Two independent signals decide: `svc.install()`'s own `changed`
+ * (the unit/plist content — binPath/configPath — differs), and a config
+ * fingerprint over the resolved enabled-watchdog set (sha256, stored at
+ * `<watchdogsRoot>/.config-fingerprint`) — needed because interval/watch/etc.
+ * never appear in the unit content itself (the unit just re-execs `-c
+ * <configPath>`), so `install()` alone can never see them change. Either
+ * signal true -> restart(); neither -> the idempotent start() (a no-op if
+ * already active, otherwise brings up a stopped unit).
+ */
+async function reconcileWatchdogScheduler(cfg, deps, configPath) {
+    const svc = deps.watchdogService;
+    if (!svc)
+        return;
+    const enabled = cfg.watchdogs.filter(w => w.enabled);
+    try {
+        // Check supervised() before any stop (final review #3): on an
+        // unsupervised platform/config, the scheduler was never installed, so
+        // stopping it is not just a no-op — on Linux, stop() throws for a unit
+        // that was never loaded. A watchdog-less fleet must not see that
+        // failure surface as a spurious "! watchdogs scheduler: ..." warning.
+        if (!enabled.length) {
+            if (svc.supervised())
+                await svc.stop();
+            return;
+        }
+        if (!svc.supervised()) {
+            deps.log("! watchdogs configured but OURS_FLEET_SUPERVISOR=none — run 'ours-fleet _run-watchdogs' in the foreground");
+            return;
+        }
+        const { changed: unitChanged } = await svc.install(deps.binPath, configPath);
+        const fingerprint = watchdogFingerprint(enabled);
+        const fingerprintChanged = readStoredFingerprint() !== fingerprint;
+        if (unitChanged || fingerprintChanged) {
+            // restart(), not start(): start() is a no-op on an already-active unit,
+            // so a config change (new/changed watchdogs) would never reach a
+            // scheduler that's already running (final review #4).
+            await svc.restart();
+            deps.log(`↑ watchdogs scheduler (${enabled.map(w => w.name).join(', ')})`);
+        }
+        else {
+            // Idempotent: a no-op on an already-active unit, but still brings up a
+            // stopped one (e.g. the scheduler crashed and systemd gave up retrying).
+            await svc.start();
+        }
+        writeFingerprint(fingerprint);
+    }
+    catch (e) {
+        deps.log(`  ! watchdogs scheduler: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
 export async function down(cfg, names, deps) {
     for (const role of selectRoles(cfg, names)) {
         // Never swallow the backend's reason. "maybe not running" hid real stop
@@ -89,6 +184,20 @@ export async function down(cfg, names, deps) {
             deps.log(`  ! could not stop ${role.name}: ${e instanceof Error ? e.message : String(e)}`);
         }
     }
+    // Only a whole-fleet `down` (no names) stops the scheduler — stopping one
+    // named role is not a decision to stop watching the others (tolerate
+    // absence/errors: a never-installed scheduler must not fail `down`).
+    // supervised() gates the call itself (final review #3): on an
+    // unsupervised platform/config there is nothing installed to stop, and
+    // Linux's stop() throws for a unit that was never loaded.
+    if (names.length === 0 && deps.watchdogService?.supervised()) {
+        try {
+            await deps.watchdogService.stop();
+        }
+        catch (e) {
+            deps.log(`  ! could not stop watchdogs scheduler: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
 }
 /** Re-sync from config + bounce. mode 'keep' resumes context; 'fresh' wipes it. */
 export async function restartRoles(cfg, names, deps, mode, configPath) {

package/dist/paths.d.ts

@@ -14,6 +14,7 @@ export declare const stateRoot: () => string;
 export declare const agentsRoot: () => string;
 export declare const tmpRoot: () => string;
 export declare const logsRoot: () => string;
+export declare const watchdogsRoot: () => string;
 export declare const agentDir: (name: string, temp?: boolean) => string;
 export declare const defaultConfigPath: () => string;
 export declare const fleetDDir: () => string;

package/dist/paths.js

@@ -24,6 +24,7 @@ export const stateRoot = () => join(home(), '.ours-fleet');
 export const agentsRoot = () => join(stateRoot(), 'agents');
 export const tmpRoot = () => join(stateRoot(), 'tmp');
 export const logsRoot = () => join(stateRoot(), 'logs');
+export const watchdogsRoot = () => join(stateRoot(), 'watchdogs');
 export const agentDir = (name, temp = false) => join(temp ? tmpRoot() : agentsRoot(), name);
 export const defaultConfigPath = () => join(home(), 'fleet.yaml');
 export const fleetDDir = () => join(home(), 'fleet.d');