@ours.network/fleet 0.10.3 → 0.11.0

package/dist/spawn.js

@@ -4,18 +4,33 @@ import { join } from 'node:path';
 import { parse, stringify } from 'yaml';
 import { agentDir, fleetDDir } from './paths.js';
 import { validateIsolationConfig } from './isolation/policy.js';
-import { loadConfig, resolveAuthProxy, resolveModelChain, resolveMonitorConfig, resolvePermissions, resolveWorklogPolicy, } from './config.js';
+import { loadConfig, resolveAuthProxy, resolveModelChain, resolveMonitorConfig, resolvePermissions, resolveRoleModel, resolveWorklogPolicy, validateMonitorConfig, } from './config.js';
 import { applyRole, up } from './ops.js';
 import { START_STAGGER_FILE } from './runner.js';
 import { buildProvenance, daemonIdentityProvisioner, ensureIdentity, provenanceOf, withCreationTransaction, writeProvenance, writeRoleFile, } from './creation.js';
 import { VERSION } from './version.js';
+import './harness/claude-code.js';
+import './harness/codex.js';
 import { getAdapter } from './harness/registry.js';
 /**
  * The provenance record written by the most recent spawn in this process, so
  * the CLI can print the same summary it persisted rather than rebuilding it.
  */
 export let lastProvenance;
-function roleFromOpts(o, defaultHarness) {
+export function profileValues(o) {
+    if (o.bio !== undefined && o.bioFile)
+        throw new Error('bio and bioFile are mutually exclusive');
+    if (o.persona !== undefined && o.personaFile)
+        throw new Error('persona and personaFile are mutually exclusive');
+    return {
+        bio: o.bio !== undefined ? o.bio.trim()
+            : o.bioFile ? readFileSync(o.bioFile, 'utf8').trim() : undefined,
+        persona: o.persona !== undefined ? o.persona.trim()
+            : o.personaFile ? readFileSync(o.personaFile, 'utf8').trim() : undefined,
+    };
+}
+/** Pure option-to-role mapping shared by CLI and application services. */
+export function buildRoleConfig(o, defaultHarness) {
     const r = {};
     if (o.harness)
         r.harness = o.harness;
@@ -31,7 +46,9 @@ function roleFromOpts(o, defaultHarness) {
         r.mission = readMissionFile(o.missionFile);
     else if (o.mission !== undefined)
         r.mission = o.mission;
-    if (o.model?.trim())
+    if (o.model === null)
+        r.model = null;
+    else if (o.model?.trim())
         r.model = o.model.trim();
     const harness = o.harness ?? defaultHarness;
     const harnessOptions = {};
@@ -60,12 +77,15 @@ function roleFromOpts(o, defaultHarness) {
             ...(o.unattended ? { unattended: o.unattended } : {}),
         };
     }
-    if (o.bioFile)
-        r.bio = readFileSync(o.bioFile, 'utf8').trim();
-    if (o.personaFile)
-        r.persona = readFileSync(o.personaFile, 'utf8').trim();
+    const profile = profileValues(o);
+    if (profile.bio)
+        r.bio = profile.bio;
+    if (profile.persona)
+        r.persona = profile.persona;
     if (o.isolationFile)
         r.isolation = readIsolationFile(o.isolationFile);
+    if (o.monitorConfig)
+        r.monitor = { ...o.monitorConfig };
     return r;
 }
 /**
@@ -93,7 +113,7 @@ export function readIsolationFile(path) {
         throw new Error(`--isolation-file ${path}: ${problems.join('; ')}`);
     return cfg;
 }
-function validateSpawnOpts(o) {
+export function validateSpawnOpts(o) {
     if (o.mission !== undefined && o.missionFile)
         throw new Error('--mission and --mission-file are mutually exclusive');
     if (o.session && !['tmux', 'acp'].includes(o.session))
@@ -104,6 +124,17 @@ function validateSpawnOpts(o) {
         throw new Error(`invalid --filesystem '${o.filesystem}'; allowed: read-only, workspace, unrestricted`);
     if (o.unattended && !['deny', 'wait'].includes(o.unattended))
         throw new Error(`invalid --unattended '${o.unattended}'; allowed: deny, wait`);
+    if (!/^[A-Za-z0-9_-]+$/.test(o.name))
+        throw new Error(`invalid role name '${o.name}'`);
+    if (o.identity && !/^[A-Za-z0-9_-]+$/.test(o.identity))
+        throw new Error(`invalid identity name '${o.identity}'`);
+    if (o.model && (o.model.length > 128 || /[\0-\x1f\x7f]/.test(o.model)))
+        throw new Error('model must be printable and at most 128 characters');
+    if (o.monitorConfig) {
+        const problems = validateMonitorConfig(o.monitorConfig);
+        if (problems.length)
+            throw new Error(problems.join('; '));
+    }
 }
 /** Read mission text without trimming or newline rewriting. */
 export function readMissionFile(path) {
@@ -146,23 +177,29 @@ export function spawnDryRun(o) {
         readMissionFile(o.missionFile);
     assertNameFree(o);
     const cfg = loadConfig(o.configPath);
-    const raw = roleFromOpts(o, cfg.defaults.harness);
+    const raw = buildRoleConfig(o, cfg.defaults.harness);
     const harnessOptions = {
         ...(cfg.defaults.harness_options ?? {}),
         ...(raw.harness_options ?? {}),
     };
+    const harness = raw.harness ?? cfg.defaults.harness ?? 'claude-code';
+    const defaultHarness = cfg.defaults.harness ?? 'claude-code';
+    const inheritsModelDefaults = harness === defaultHarness && raw.model !== null;
+    const model = resolveRoleModel(raw.model, raw.harness, cfg.defaults);
     const resolvedRole = {
         ...raw,
         name: o.name,
         sourceFile: o.temp ? '(temp dry-run)' : join(fleetDDir(), `${o.name}.yaml`),
-        harness: raw.harness ?? cfg.defaults.harness ?? 'claude-code',
+        harness,
         session: raw.session ?? cfg.defaults.session ?? 'tmux',
         session_options: raw.session_options,
         permissions: resolvePermissions(cfg.defaults.permissions, raw.permissions),
         permissionsDeclared: raw.permissions !== undefined || cfg.defaults.permissions !== undefined,
         identity: effectiveIdentity(o),
-        model: raw.model ?? cfg.defaults.model,
-        model_chain: resolveModelChain(raw.model ?? cfg.defaults.model, raw.model_chain ?? cfg.defaults.model_chain),
+        model,
+        model_chain: resolveModelChain(model, raw.model_chain ?? (inheritsModelDefaults
+            ? cfg.defaults.model_chain
+            : undefined)),
         harness_options: Object.keys(harnessOptions).length ? harnessOptions : undefined,
         isolation: raw.isolation ?? cfg.defaults.isolation,
         monitor: resolveMonitorConfig(cfg.defaults.monitor, raw.monitor),
@@ -199,6 +236,8 @@ export function spawnDryRun(o) {
  */
 function provenanceSettings(o, defaults) {
     const perms = (defaults.permissions ?? {});
+    const explicitModel = typeof o.model === 'string' ? o.model.trim() : undefined;
+    const inheritedModel = resolveRoleModel(undefined, o.harness, defaults);
     return {
         harness: provenanceOf(o.harness, defaults.harness, 'claude-code'),
         session: provenanceOf(o.session, defaults.session, 'tmux'),
@@ -206,7 +245,11 @@ function provenanceSettings(o, defaults) {
             ? { value: o.identity, source: 'cli' }
             : { value: o.name, source: 'built-in' }, // defaults to the role name
         cwd: provenanceOf(o.cwd, undefined, undefined),
-        model: provenanceOf(o.model?.trim(), defaults.model, undefined),
+        model: o.model === null
+            ? { value: undefined, source: 'cli' }
+            : explicitModel
+                ? { value: explicitModel, source: 'cli' }
+                : { value: inheritedModel, source: inheritedModel ? 'fleet-default' : 'built-in' },
         coordinator: provenanceOf(o.coordinator, undefined, undefined),
         approval: provenanceOf(o.approval, perms.approval, 'ask'),
         filesystem: provenanceOf(o.filesystem, perms.filesystem, 'workspace'),
@@ -214,6 +257,7 @@ function provenanceSettings(o, defaults) {
         isolation: o.isolationFile
             ? { value: 'declared via --isolation-file', source: 'cli' }
             : { value: defaults.isolation ? 'from fleet defaults' : undefined, source: defaults.isolation ? 'fleet-default' : 'built-in' },
+        monitor: provenanceOf(o.monitorConfig, defaults.monitor, { mode: 'fleet' }),
     };
 }
 /** Permanent spawn: persist to ~/fleet.d/<Name>.yaml, then bring it up. */
@@ -225,13 +269,17 @@ export async function spawnPermanent(o, deps, creation = {}) {
         readMissionFile(o.missionFile); // fail before reserving
     // Name AND identity reserved together, before anything is written or started
     // (6.4). A loser of the race creates no config, no state, no service.
+    creation.onStage?.('reserving');
     return withCreationTransaction({ role: o.name, identity: effectiveIdentity(o) }, async (tx) => {
         assertNameFree(o);
         const cfg = loadConfig(o.configPath);
         // Establish the identity BEFORE the service is enabled (7.3), and record
         // what was actually guaranteed so the briefing can say something true.
-        const guarantee = await ensureIdentity(effectiveIdentity(o), { bio: o.bioFile ? readFileSync(o.bioFile, 'utf8').trim() : undefined,
-            persona: o.personaFile ? readFileSync(o.personaFile, 'utf8').trim() : undefined }, creation.identityProvisioner ?? daemonIdentityProvisioner(), deps.log);
+        creation.onStage?.('checking_identity');
+        const guarantee = await ensureIdentity(effectiveIdentity(o), profileValues(o), creation.identityProvisioner ?? daemonIdentityProvisioner(), deps.log);
+        creation.onStage?.('checking_identity', {
+            result: guarantee.evidence, guarantee: guarantee.state,
+        });
         if (guarantee.state === 'created')
             // We minted it; a failed creation must not leave an orphan identity
             // behind. Only ever removes an identity THIS transaction created.
@@ -242,9 +290,10 @@ export async function spawnPermanent(o, deps, creation = {}) {
                 },
             });
         mkdirSync(fleetDDir(), { recursive: true });
+        creation.onStage?.('writing_role');
         const file = join(fleetDDir(), `${o.name}.yaml`);
         writeRoleFile(tx, file, stringify({
-            roles: { [o.name]: roleFromOpts(o, cfg.defaults.harness) },
+            roles: { [o.name]: buildRoleConfig(o, cfg.defaults.harness) },
         }));
         // `up` materialises the state dir and registers the service. Journal the
         // dir before it exists so a failure leaves the name genuinely reusable
@@ -272,9 +321,11 @@ export async function spawnPermanent(o, deps, creation = {}) {
         const provenance = buildProvenance({
             role: o.name, lifetime: 'permanent', fleetVersion: VERSION,
             settings: provenanceSettings(o, cfg.defaults),
+            surface: o.surface, creationActionId: o.creationActionId,
         });
         mkdirSync(agentDir(o.name), { recursive: true });
         writeProvenance(agentDir(o.name), provenance);
+        creation.onStage?.('registering_supervisor');
         await up(loadConfig(o.configPath), [o.name], { ...deps, onInstalled: outcome => registered.push(outcome.role) }, o.configPath, guarantee.state);
         lastProvenance = provenance;
         return file;
@@ -298,29 +349,45 @@ export async function spawnTemp(o, binPath, launch = detachedSupervisor, creatio
         readMissionFile(o.missionFile); // fail before reserving
     // Temporary roles go through the SAME reservation boundary as permanent ones
     // (6.4): a temp agent competes for the same names.
+    creation.onStage?.('reserving');
     return withCreationTransaction({ role: o.name, identity: effectiveIdentity(o) }, async (tx) => {
+        creation.onStage?.('checking_identity');
         assertNameFree(o);
-        const guarantee = await ensureIdentity(effectiveIdentity(o), { bio: o.bioFile ? readFileSync(o.bioFile, 'utf8').trim() : undefined,
-            persona: o.personaFile ? readFileSync(o.personaFile, 'utf8').trim() : undefined }, creation.identityProvisioner ?? daemonIdentityProvisioner(), creation.log);
-        return spawnTempInner(o, binPath, launch, tx, guarantee);
+        const guarantee = await ensureIdentity(effectiveIdentity(o), profileValues(o), creation.identityProvisioner ?? daemonIdentityProvisioner(), creation.log);
+        creation.onStage?.('checking_identity', {
+            result: guarantee.evidence, guarantee: guarantee.state,
+        });
+        if (guarantee.state === 'created')
+            tx.record({
+                stage: `ours identity ${effectiveIdentity(o)}`,
+                undo: async () => {
+                    await creation.identityProvisioner?.remove?.(effectiveIdentity(o));
+                },
+            });
+        return spawnTempInner(o, binPath, launch, tx, guarantee, creation.onStage);
     }, creation);
 }
-async function spawnTempInner(o, binPath, launch, tx, guarantee) {
+async function spawnTempInner(o, binPath, launch, tx, guarantee, onStage) {
     const cfg = loadConfig(o.configPath);
     const defaultHarness = cfg.defaults.harness;
-    const fromOpts = roleFromOpts(o, defaultHarness);
+    const fromOpts = buildRoleConfig(o, defaultHarness);
     const mergedHarnessOptions = {
         ...(cfg.defaults.harness_options ?? {}),
         ...(fromOpts.harness_options ?? {}),
     };
+    const harness = o.harness ?? defaultHarness ?? 'claude-code';
+    const inheritsModelDefaults = harness === (defaultHarness ?? 'claude-code') && o.model !== null;
+    const model = resolveRoleModel(o.model, o.harness, cfg.defaults);
     const role = {
         ...fromOpts, // includes `isolation` when --isolation-file was given
         name: o.name,
-        harness: o.harness ?? defaultHarness ?? 'claude-code',
+        harness,
         session: o.session ?? cfg.defaults.session ?? 'tmux',
         identity: o.identity ?? o.name,
-        model: o.model?.trim() || cfg.defaults.model,
-        model_chain: resolveModelChain(o.model?.trim() || cfg.defaults.model, fromOpts.model_chain ?? cfg.defaults.model_chain),
+        model,
+        model_chain: resolveModelChain(model, fromOpts.model_chain ?? (inheritsModelDefaults
+            ? cfg.defaults.model_chain
+            : undefined)),
         harness_options: Object.keys(mergedHarnessOptions).length ? mergedHarnessOptions : undefined,
         permissions: resolvePermissions(cfg.defaults.permissions, fromOpts.permissions),
         permissionsDeclared: fromOpts.permissions !== undefined || cfg.defaults.permissions !== undefined,
@@ -337,10 +404,12 @@ async function spawnTempInner(o, binPath, launch, tx, guarantee) {
     };
     if (role.auth_proxy && role.harness !== 'claude-code')
         throw new Error('auth_proxy is supported only by claude-code');
+    onStage?.('writing_role');
     const dir = applyRole(role, { temp: true, identityGuarantee: guarantee.state });
     const provenance = buildProvenance({
         role: o.name, lifetime: 'temporary', fleetVersion: VERSION,
         settings: provenanceSettings(o, cfg.defaults),
+        surface: o.surface, creationActionId: o.creationActionId,
     });
     writeProvenance(dir, provenance);
     lastProvenance = provenance;
@@ -356,6 +425,7 @@ async function spawnTempInner(o, binPath, launch, tx, guarantee) {
     // agent itself; a supervisor sharing that session name would SIGHUP its own
     // process before the agent ever launches. Detaching mirrors how systemd hosts
     // the supervisor for permanent roles, leaving runOnce to own the <name> session.
+    onStage?.('starting_temp');
     launch(binPath, ['_run-temp', o.name], dir);
     return dir;
 }

package/dist/supervisor/launchd.js

@@ -177,6 +177,23 @@ export function makeLaunchdBackend(exec = realExec, uid = process.getuid?.() ??
                 return { state: 'stopped', detail: `not loaded (${labelFor(name)})` };
             return { state: 'unknown', detail: job.failure ?? `launchctl print ${labelFor(name)} failed` };
         },
+        async inspect(name) {
+            const job = await printJob(name);
+            if (job.loaded)
+                return {
+                    backend: 'launchd', state: 'running',
+                    nativeState: job.state, detail: job.state ? `loaded (state = ${job.state})` : 'loaded',
+                };
+            if (job.notFound)
+                return {
+                    backend: 'launchd', state: 'stopped',
+                    nativeState: 'not-loaded', detail: `not loaded (${labelFor(name)})`,
+                };
+            return {
+                backend: 'launchd', state: 'unknown',
+                detail: job.failure ?? `launchctl print ${labelFor(name)} failed`,
+            };
+        },
         async uninstall(name) {
             const existed = existsSync(plistPath(name));
             await exec('launchctl', ['bootout', `${domain}/${labelFor(name)}`]); // idempotent

package/dist/supervisor/none.js

@@ -31,6 +31,23 @@ export function makeNoneBackend(exec = realExec) {
                 return { state: 'stopped', detail: `no tmux session '${name}'` };
             return { state: 'unknown', detail: `tmux has-session '${name}' failed (${r.code}): ${r.stderr.trim() || 'no output'}` };
         },
+        async inspect(name) {
+            const r = await exec('tmux', tmuxArgs(name, ['has-session', '-t', name]));
+            if (r.code === 0)
+                return {
+                    backend: 'none', state: 'running',
+                    nativeState: 'tmux-present', detail: `tmux session '${name}' exists`,
+                };
+            if (r.code === 1)
+                return {
+                    backend: 'none', state: 'stopped',
+                    nativeState: 'tmux-absent', detail: `no tmux session '${name}'`,
+                };
+            return {
+                backend: 'none', state: 'unknown',
+                detail: `tmux has-session '${name}' failed (${r.code}): ${r.stderr.trim() || 'no output'}`,
+            };
+        },
         async uninstall(name) {
             const killed = await tmux.kill(name); // idempotent
             return killed

package/dist/supervisor/systemd.js

@@ -148,6 +148,10 @@ WantedBy=default.target
             return r.stdout || r.stderr;
         },
         liveness(name) { return probeLiveness(ctl, name); },
+        async inspect(name) {
+            const live = await probeLiveness(ctl, name);
+            return { backend: 'systemd', ...live, nativeState: live.detail.split(/\s/)[0] };
+        },
         async uninstall(name) {
             const before = await ctl('is-enabled', unitFor(name));
             const wasEnabled = before.stdout.trim() === 'enabled';

package/dist/supervisor/types.d.ts

@@ -19,6 +19,10 @@ export interface UninstallOutcome {
     removed: boolean;
     detail: string;
 }
+export interface SupervisorInspection extends Liveness {
+    backend: 'systemd' | 'launchd' | 'none';
+    nativeState?: string;
+}
 export interface SupervisorBackend {
     id: 'systemd' | 'launchd' | 'none';
     /** One-time host setup (unit template / dirs / linger). Returns human-readable messages. */
@@ -40,6 +44,8 @@ export interface SupervisorBackend {
      * probe is `unknown` with the failure in `detail`.
      */
     liveness(name: string): Promise<Liveness>;
+    /** Structured machine-derived status for application-service consumers. */
+    inspect?(name: string): Promise<SupervisorInspection>;
     /** Remove the registration. Idempotent; reports whether anything was there. */
     uninstall(name: string): Promise<UninstallOutcome>;
     /** Command the CLI execs (stdio inherited) to show logs. */

package/dist/tmux.d.ts

@@ -33,6 +33,8 @@ export declare class Tmux {
      */
     kill(name: string): Promise<boolean>;
     capture(name: string, lines?: number): Promise<string>;
+    /** Bounded ANSI/history seed for the browser terminal projection. */
+    captureHistory(name: string, lines?: number): Promise<string>;
     panePid(name: string): Promise<number | null>;
     /**
      * List the live sessions among `names`, asking each server in turn.

package/dist/tmux.js

@@ -49,6 +49,14 @@ export class Tmux {
         const all = r.stdout.replace(/\n+$/, '').split('\n');
         return all.slice(-lines).join('\n');
     }
+    /** Bounded ANSI/history seed for the browser terminal projection. */
+    async captureHistory(name, lines = 5_000) {
+        const bounded = Math.min(Math.max(Math.trunc(lines), 1), 20_000);
+        const r = await this.exec('tmux', tmuxArgs(name, ['capture-pane', '-t', name, '-p', '-e', '-J', '-S', `-${bounded}`]));
+        if (r.code !== 0)
+            throw new Error(`tmux capture-pane '${name}' failed: ${r.stderr.trim()}`);
+        return Buffer.from(r.stdout).subarray(0, 4 * 1024 * 1024).toString();
+    }
     async panePid(name) {
         const r = await this.exec('tmux', tmuxArgs(name, ['list-panes', '-t', name, '-F', '#{pane_pid}']));
         if (r.code !== 0)

package/dist/watchdog/alerts.d.ts

@@ -0,0 +1,34 @@
+import type { WatchdogReport, WatchdogRoleStatus } from './report.js';
+import type { WatchManifest } from './briefing.js';
+/**
+ * Severity ordering, lowest to highest (must match the briefing contract's alert-rules
+ * sentence verbatim, src/watchdog/briefing.ts): healthy = idle (0) < unknown (1) < stale (2)
+ * < blocked = unreachable (3) < off_briefing (4).
+ */
+export declare const WATCHDOG_STATUS_RANK: Record<WatchdogRoleStatus, number>;
+export interface OpenFinding {
+    role: string;
+    status: WatchdogRoleStatus;
+    since: string;
+    lastAlertedAt: string | null;
+}
+export interface AlertLedger {
+    version: 1;
+    open: Record<string, OpenFinding>;
+    heldDownAlerted: boolean;
+}
+/** Missing or corrupt ledger file yields a clean empty ledger rather than throwing. */
+export declare function readLedger(name: string): AlertLedger;
+export declare function writeLedger(name: string, l: AlertLedger): void;
+/**
+ * Reconcile rules (spec §5): an `error`-status report carries no role evidence, so the ledger
+ * is returned unchanged. For each finding with rank > 0: an existing open entry keeps its
+ * `since` and updates `status` on escalation/de-escalation; a new one opens with `since = now`.
+ * Any role reported `healthy`/`idle` closes (deletes) its open entry. Every role named in
+ * `report.alerts` gets `lastAlertedAt = now`. Roles absent from the report keep their entries —
+ * a watchdog with a narrowed `watch:` set doesn't silently resolve findings it never inspected.
+ * Never mutates `l` — always returns a new ledger object.
+ */
+export declare function reconcileLedger(l: AlertLedger, report: WatchdogReport, now: Date): AlertLedger;
+/** Ledger's open findings + cooldown, in the shape watch.json's `digest` field carries (Task 7 writes it, run reads it back). */
+export declare function computeDigest(l: AlertLedger, cooldownMs: number, now: Date): WatchManifest['digest'];

package/dist/watchdog/alerts.js

@@ -0,0 +1,78 @@
+import { chmodSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { watchdogDir } from './store.js';
+/**
+ * Severity ordering, lowest to highest (must match the briefing contract's alert-rules
+ * sentence verbatim, src/watchdog/briefing.ts): healthy = idle (0) < unknown (1) < stale (2)
+ * < blocked = unreachable (3) < off_briefing (4).
+ */
+export const WATCHDOG_STATUS_RANK = {
+    healthy: 0, idle: 0, unknown: 1, stale: 2, blocked: 3, unreachable: 3, off_briefing: 4,
+};
+function emptyLedger() {
+    return { version: 1, open: {}, heldDownAlerted: false };
+}
+function ledgerPath(name) {
+    return join(watchdogDir(name), 'alerts.json');
+}
+/** Missing or corrupt ledger file yields a clean empty ledger rather than throwing. */
+export function readLedger(name) {
+    try {
+        return JSON.parse(readFileSync(ledgerPath(name), 'utf8'));
+    }
+    catch {
+        return emptyLedger();
+    }
+}
+export function writeLedger(name, l) {
+    const path = ledgerPath(name);
+    writeFileSync(path, JSON.stringify(l, null, 2) + '\n', { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+/**
+ * Reconcile rules (spec §5): an `error`-status report carries no role evidence, so the ledger
+ * is returned unchanged. For each finding with rank > 0: an existing open entry keeps its
+ * `since` and updates `status` on escalation/de-escalation; a new one opens with `since = now`.
+ * Any role reported `healthy`/`idle` closes (deletes) its open entry. Every role named in
+ * `report.alerts` gets `lastAlertedAt = now`. Roles absent from the report keep their entries —
+ * a watchdog with a narrowed `watch:` set doesn't silently resolve findings it never inspected.
+ * Never mutates `l` — always returns a new ledger object.
+ */
+export function reconcileLedger(l, report, now) {
+    if (report.status === 'error')
+        return l;
+    const open = { ...l.open };
+    const nowIso = now.toISOString();
+    for (const finding of report.roles) {
+        const rank = WATCHDOG_STATUS_RANK[finding.status];
+        if (rank > 0) {
+            const existing = open[finding.role];
+            open[finding.role] = {
+                role: finding.role,
+                status: finding.status,
+                since: existing ? existing.since : nowIso,
+                lastAlertedAt: existing ? existing.lastAlertedAt : null,
+            };
+        }
+        else {
+            delete open[finding.role];
+        }
+    }
+    for (const alert of report.alerts) {
+        if (open[alert.role])
+            open[alert.role] = { ...open[alert.role], lastAlertedAt: nowIso };
+    }
+    return { ...l, open };
+}
+/** Ledger's open findings + cooldown, in the shape watch.json's `digest` field carries (Task 7 writes it, run reads it back). */
+export function computeDigest(l, cooldownMs, now) {
+    return {
+        cooldown_ms: cooldownMs,
+        open: Object.values(l.open).map(f => ({
+            role: f.role,
+            status: f.status,
+            since: f.since,
+            realert_after: f.lastAlertedAt ? new Date(new Date(f.lastAlertedAt).getTime() + cooldownMs).toISOString() : null,
+        })),
+    };
+}

package/dist/watchdog/briefing.d.ts

@@ -0,0 +1,65 @@
+import type { ResolvedWatchdog } from './config.js';
+import type { BriefingVocab } from '../harness/types.js';
+/** One entry in `watch.json`'s `roles` array — where to find a watched role's state. */
+export interface WatchManifestRole {
+    name: string;
+    stateDir: string;
+}
+/**
+ * The fixed run manifest a watchdog run reads at `manifestPath` (7.3 §3, Task 7 writes it,
+ * Task 12+ digest reads it back). It carries everything the run needs to identify itself in
+ * report.json (`watchdog`, `run_id`, `started_at`) plus the suppression digest that makes
+ * alerting idempotent across runs.
+ */
+export interface WatchManifest {
+    watchdog: string;
+    run_id: string;
+    coordinator: string;
+    started_at: string;
+    roles: WatchManifestRole[];
+    digest: {
+        cooldown_ms: number;
+        open: Array<{
+            role: string;
+            status: string;
+            since: string;
+            realert_after: string | null;
+        }>;
+    };
+}
+export interface WatchdogBriefingOpts {
+    wd: ResolvedWatchdog;
+    manifestPath: string;
+    reportPath: string;
+    vocabulary: BriefingVocab;
+    /** What spawn actually established about the watchdog's ours identity (7.3, decision 3). */
+    identityGuarantee: 'verified' | 'created' | 'unverified';
+    /** Raw prompt_file content, appended as extra focus — never a replacement (owner decision 1). */
+    promptFocus?: string;
+}
+/**
+ * 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 declare function generateWatchdogBriefing(opts: WatchdogBriefingOpts): string;
+export interface NotifierBriefingOpts {
+    wd: ResolvedWatchdog;
+    vocabulary: BriefingVocab;
+    /** What spawn actually established about the watchdog's ours identity (7.3, decision 3). */
+    identityGuarantee: 'verified' | 'created' | 'unverified';
+    /** The exact message to relay — the scheduler composed this, the notifier only delivers it. */
+    text: string;
+}
+/**
+ * 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 declare function generateNotifierBriefing(opts: NotifierBriefingOpts): string;