@ours.network/fleet 0.7.1 → 0.8.0

package/README.md

@@ -51,9 +51,11 @@ roles:
 
 Each role gets a state dir (`~/.ours-fleet/agents/<Name>/`) holding its briefing,
 logs, routines, and session markers. On boot the agent reads its briefing: bind
-identity, publish bio/persona, arm a mail monitor (`ours-mcp watch`), announce to
-its coordinator, work. On crash the supervisor relaunches it and the harness
-resumes the same session.
+identity, publish bio/persona, announce to its coordinator, work — while the
+supervisor delivers its mail wakes as `[fleet-monitor]` console lines (see
+[Mail monitor](#mail-monitor); `monitor.enabled: false` reverts to the agent
+arming its own `ours-mcp watch`). On crash the supervisor relaunches it and the
+harness resumes the same session.
 
 The state dir contract:
 
@@ -182,12 +184,22 @@ defaults:
   harness: claude-code                  # for roles that don't set one
   model: claude-fable-5                 # default model for roles that don't set one (per-role model / --model wins)
   max_tokens: 500000                    # session cap (harness-interpreted)
+  monitor:                              # supervisor-owned mail wake (fleet-wide default)
+    enabled: true                       # default true; a role block overrides key-by-key
 roles:
   Name:                                 # [A-Za-z0-9_-]+
     harness: claude-code
     identity: "Display Name"            # ours identity to bind (default: Name)
     cwd: ${work_root}/repo              # where the harness process runs
     coordinator: FleetCoordinator       # announce target on boot
+    monitor:                            # deterministic wake, owned by the supervisor
+      enabled: true                     # default (defaults.monitor.enabled ?? true);
+      #                                 #   false = legacy in-session `ours-mcp watch`
+      wake_sources:                     # which daemon events wake the console (default:
+        - message_received              #   message_received, file_received,
+        - file_received                 #   local_contact_request, pending_message)
+      batch_ms: 2000                    # coalesce a burst into one line (default 2000)
+      inject: notification              # notification (default) | full (bodies inline; roadmap)
     model: claude-fable-5               # launch on a specific model (pass-through id; default: launcher default)
     mission: one line
     persona: |                          # operating contract (published as persona)
@@ -225,7 +237,23 @@ Merge order: `fleet.yaml` ← `fleet.d/*.yaml`; a duplicate role name is a hard
 error naming both files. Identities and roles are decoupled — removing a role
 never deletes an identity. `defaults.harness_options` is shallow-merged with each
 role's `harness_options`, so a fleet can set common Codex permission/profile defaults
-and override individual keys per role.
+and override individual keys per role. `monitor` merges the same way — a role block
+overrides `defaults.monitor` key-by-key.
+
+### Mail monitor
+
+With `monitor.enabled` (the default), the **supervisor** delivers a role's mail
+wakes: the per-role runner long-polls the ours daemon's notification API and
+injects a single `[fleet-monitor] N new messages from … — run get_messages` line
+straight into the console. It is a deterministic program whose lifetime is fused to
+the tmux session — it primes the notification cursor *before* the session launches
+(no missed arrivals), cannot be orphaned or left deaf-but-armed, and writes its
+health to `<agentDir>/.monitor-status` (`armed | degraded | failed`), surfaced in
+`ours-fleet status`/`doctor`. The agent's briefing tells it **not** to arm an
+in-session Monitor. Set `monitor.enabled: false` to keep the legacy behavior where
+the agent arms its own `ours-mcp watch`. `inject: full` (pushing message bodies
+inline) is on the roadmap and needs two new ours-mcp daemon endpoints; today all
+roles deliver `notification` lines and drain via `get_messages`.
 
 ## Codex roles
 

package/dist/briefing.js

@@ -34,7 +34,12 @@ export function generateBriefing(role, v, opts) {
         : '   with a 1–2 sentence summary of your Charter above. Skip if it already matches.');
     L.push(`5. SET your **persona** (local operating contract, never shared in invites) via`);
     L.push(`   **${v.setPersonaTool}** with the **Charter** section above, verbatim. Skip if it matches.`);
-    L.push(`6. ${v.monitorInstruction(id, role)}`);
+    // When the supervisor owns the monitor (monitor.enabled), the agent must NOT arm
+    // its own in-session watch — wakes are injected as [fleet-monitor] lines (design §5).
+    const wakeNote = role.monitor?.enabled
+        ? v.supervisedWakeNote(id, role)
+        : v.monitorInstruction(id, role);
+    L.push(`6. ${wakeNote}`);
     if (role.coordinator) {
         L.push(`7. ANNOUNCE yourself: call **${v.sendTool}** to contact "${role.coordinator}" with text:`);
         L.push(`   "${role.name} online — identity '${id}' bound, ready."`);
@@ -70,7 +75,7 @@ export function generateBriefing(role, v, opts) {
     L.push('change between wakes without a restart; treat the file, not your memory of it, as current.');
     L.push('', '## On restart (you run under a supervised launcher)');
     L.push(`On restart, WITHOUT asking: re-bind (**${v.bindTool}** name "${id}" force=true), then`);
-    L.push(`${v.monitorInstruction(id, role)} Then continue from your WORKLOG.`);
+    L.push(`${wakeNote} Then continue from your WORKLOG.`);
     L.push('Do not blindly re-run whatever may have crashed you.');
     L.push('', '## House rules');
     L.push('- Never broad `rm -rf` on home/critical paths; quote globs; use explicit paths.');

package/dist/config.d.ts

@@ -3,6 +3,21 @@ export interface OverseeEntry {
     role: string;
     interval: string;
 }
+/** The 8 content-free event types the ours daemon appends to notifications.log. */
+export declare const NOTIFY_EVENT_TYPES: readonly ["message_received", "file_received", "sibling_contact_added", "local_contact_request", "pending_message", "contact_restored", "inbound_error", "state_import_failed"];
+export type NotifyEventType = (typeof NOTIFY_EVENT_TYPES)[number];
+export type InjectMode = 'notification' | 'full';
+/** Resolved per-role supervisor-monitor config (see DESIGN-external-monitor §2). */
+export interface MonitorConfig {
+    enabled: boolean;
+    wake_sources: string[];
+    batch_ms: number;
+    inject: InjectMode;
+}
+/** Default wake sources when a role does not list its own (design §2). */
+export declare const DEFAULT_WAKE_SOURCES: NotifyEventType[];
+/** Validate a raw (role-level or merged) `monitor:` block; returns human-readable problems. */
+export declare function validateMonitorConfig(raw: unknown): string[];
 export interface RoleConfig {
     harness?: string;
     identity?: string;
@@ -19,12 +34,14 @@ export interface RoleConfig {
     oversee?: OverseeEntry[];
     harness_options?: Record<string, unknown>;
     isolation?: IsolationConfig;
+    monitor?: Partial<MonitorConfig>;
 }
 export interface ResolvedRole extends RoleConfig {
     name: string;
     harness: string;
     identity: string;
     sourceFile: string;
+    monitor: MonitorConfig;
 }
 export interface FleetConfig {
     roles: ResolvedRole[];
@@ -36,4 +53,16 @@ export declare class ConfigError extends Error {
 }
 /** Load ~/fleet.yaml (or an explicit path) merged with ~/fleet.d/*.yaml drop-ins. */
 export declare function loadConfig(configPath?: string): FleetConfig;
+/**
+ * Merge `defaults.monitor` under the role's own `monitor:` key-by-key, validate the
+ * result, and fill code-constant defaults (design §2). `defaults.monitor.enabled`
+ * is the fleet-wide default; absent everywhere ⇒ enabled. Throws ConfigError on a
+ * malformed block so a typo fails loudly rather than silently disarming a monitor.
+ * Exported so temp-spawn (which builds a ResolvedRole by hand) resolves identically.
+ */
+export declare function resolveMonitorConfig(defMonitor: unknown, roleMonitor?: Partial<MonitorConfig>, labels?: {
+    base?: string;
+    file?: string;
+    name?: string;
+}): MonitorConfig;
 export declare function findRole(cfg: FleetConfig, name: string): ResolvedRole;

package/dist/config.js

@@ -3,13 +3,52 @@ import { join } from 'node:path';
 import { parse } from 'yaml';
 import { defaultConfigPath, fleetDDir } from './paths.js';
 import { validateIsolationConfig } from './isolation/policy.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',
+    'pending_message', 'contact_restored', 'inbound_error', 'state_import_failed',
+];
+/** Default wake sources when a role does not list its own (design §2). */
+export const DEFAULT_WAKE_SOURCES = ['message_received', 'file_received', 'local_contact_request', 'pending_message'];
+const MONITOR_KEYS = ['enabled', 'wake_sources', 'batch_ms', 'inject'];
+const INJECT_MODES = ['notification', 'full'];
+const MONITOR_DEFAULT_BATCH_MS = 2000;
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+/** Validate a raw (role-level or merged) `monitor:` block; returns human-readable problems. */
+export function validateMonitorConfig(raw) {
+    const problems = [];
+    if (!isPlainObject(raw))
+        return ['monitor: must be a mapping'];
+    const m = raw;
+    const bad = Object.keys(m).filter(k => !MONITOR_KEYS.includes(k));
+    if (bad.length)
+        problems.push(`monitor: unknown key(s) ${bad.join(', ')}; allowed: ${MONITOR_KEYS.join(', ')}`);
+    if (m.enabled !== undefined && typeof m.enabled !== 'boolean')
+        problems.push('monitor.enabled: must be true or false');
+    if (m.batch_ms !== undefined
+        && (typeof m.batch_ms !== 'number' || !Number.isFinite(m.batch_ms) || m.batch_ms < 0))
+        problems.push('monitor.batch_ms: must be a non-negative number');
+    if (m.inject !== undefined && !INJECT_MODES.includes(m.inject))
+        problems.push(`monitor.inject: invalid value '${m.inject}'; allowed: ${INJECT_MODES.join(', ')}`);
+    if (m.wake_sources !== undefined) {
+        if (!Array.isArray(m.wake_sources))
+            problems.push('monitor.wake_sources: must be a list');
+        else {
+            const unknown = m.wake_sources.filter(w => !NOTIFY_EVENT_TYPES.includes(w));
+            if (unknown.length)
+                problems.push(`monitor.wake_sources: unknown source(s) ${unknown.join(', ')}; ` +
+                    `allowed: ${NOTIFY_EVENT_TYPES.join(', ')}`);
+        }
+    }
+    return problems;
+}
 export class ConfigError extends Error {
 }
 const NAME_RE = /^[A-Za-z0-9_-]+$/;
 const ROLE_KEYS = [
     'harness', 'identity', 'cwd', 'coordinator', 'mission', 'persona', 'bio',
     'briefing_file', 'model', 'max_tokens', 'autocompact_pct', 'env', 'oversee', 'harness_options',
-    'isolation',
+    'isolation', 'monitor',
 ];
 function deepSub(v, vars) {
     if (typeof v === 'string')
@@ -78,6 +117,7 @@ export function loadConfig(configPath) {
                 if (problems.length)
                     throw new ConfigError(`${file}: role '${name}' ${problems.join('; ')}`);
             }
+            const monitor = resolveMonitorConfig(defaults.monitor, r.monitor, { base, file, name });
             roles.push({
                 ...r,
                 name,
@@ -88,11 +128,39 @@ export function loadConfig(configPath) {
                 max_tokens: r.max_tokens ?? defaults.max_tokens,
                 harness_options: harnessOptions,
                 isolation,
+                monitor,
             });
         }
     }
     return { roles, vars, defaults, files };
 }
+/**
+ * Merge `defaults.monitor` under the role's own `monitor:` key-by-key, validate the
+ * result, and fill code-constant defaults (design §2). `defaults.monitor.enabled`
+ * is the fleet-wide default; absent everywhere ⇒ enabled. Throws ConfigError on a
+ * malformed block so a typo fails loudly rather than silently disarming a monitor.
+ * Exported so temp-spawn (which builds a ResolvedRole by hand) resolves identically.
+ */
+export function resolveMonitorConfig(defMonitor, roleMonitor, labels = {}) {
+    const where = labels.file && labels.name ? `${labels.file}: role '${labels.name}' ` : '';
+    if (defMonitor !== undefined && !isPlainObject(defMonitor))
+        throw new ConfigError(`${labels.base ?? 'config'}: defaults.monitor must be a map`);
+    if (roleMonitor !== undefined && !isPlainObject(roleMonitor))
+        throw new ConfigError(`${where}monitor: must be a mapping`);
+    const merged = {
+        ...(defMonitor ?? {}),
+        ...(roleMonitor ?? {}),
+    };
+    const problems = validateMonitorConfig(merged);
+    if (problems.length)
+        throw new ConfigError(`${where}${problems.join('; ')}`);
+    return {
+        enabled: merged.enabled ?? true,
+        wake_sources: merged.wake_sources ?? [...DEFAULT_WAKE_SOURCES],
+        batch_ms: merged.batch_ms ?? MONITOR_DEFAULT_BATCH_MS,
+        inject: merged.inject ?? 'notification',
+    };
+}
 export function findRole(cfg, name) {
     const r = cfg.roles.find(r => r.name === name);
     if (!r)

package/dist/doctor.d.ts

@@ -1,7 +1,8 @@
 import { type Exec } from './exec.js';
+import { type FetchLike } from './monitor.js';
 import type { PrereqReport } from './harness/types.js';
 /** Host-level + per-harness prerequisite report with actionable messages. */
 export declare function doctor(opts?: {
     harness?: string;
     configPath?: string;
-}, exec?: Exec, platform?: NodeJS.Platform): Promise<PrereqReport>;
+}, exec?: Exec, platform?: NodeJS.Platform, fetchImpl?: FetchLike): Promise<PrereqReport>;

package/dist/doctor.js

@@ -20,7 +20,7 @@ function cgroupDelegationDetail() {
     }
 }
 /** Host-level + per-harness prerequisite report with actionable messages. */
-export async function doctor(opts = {}, exec = realExec, platform = process.platform) {
+export async function doctor(opts = {}, exec = realExec, platform = process.platform, fetchImpl = (u, i) => globalThis.fetch(u, i)) {
     const checks = [];
     const major = Number(process.versions.node.split('.')[0]);
     checks.push({
@@ -107,6 +107,38 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
             detail = `backend=${policy.backend} (not yet implemented)`;
         checks.push({ name: `isolation: ${r.name}`, ok, detail });
     }
+    // Monitor daemon-API reachability (design §5): only when a role is supervised.
+    // /state-dir is unauthenticated (liveness); /identities exercises the token so a
+    // shared-mode misconfig (401) surfaces here rather than as a silent deaf monitor.
+    if (roles.some(r => r.monitor?.enabled)) {
+        const port = Number(process.env.OURS_PORT) || 3050;
+        const token = process.env.OURS_API_TOKEN;
+        const headers = token ? { 'x-ours-api-token': token } : {};
+        let ok = false, detail;
+        try {
+            const live = await fetchImpl(`http://127.0.0.1:${port}/state-dir`, {});
+            if (!live.ok) {
+                detail = `daemon on :${port} answered /state-dir with HTTP ${live.status} — not the ours daemon?`;
+            }
+            else {
+                const auth = await fetchImpl(`http://127.0.0.1:${port}/identities`, { headers });
+                if (auth.status === 401)
+                    detail = `reachable on :${port} but the API token was rejected (401) — set OURS_API_TOKEN to the ` +
+                        `daemon's token (shared mode) or run the fleet as the daemon owner`;
+                else if (!auth.ok)
+                    detail = `reachable on :${port} but /identities returned HTTP ${auth.status}`;
+                else {
+                    ok = true;
+                    detail = `reachable on :${port}, authorized — supervisor wake stream available`;
+                }
+            }
+        }
+        catch (e) {
+            detail = `unreachable on :${port} — monitored roles run degraded until it is up ` +
+                `(start it: ours-mcp start) [${e?.message ?? e}]`;
+        }
+        checks.push({ name: 'monitor: daemon API', ok, detail });
+    }
     const harnesses = opts.harness
         ? [opts.harness]
         : [...new Set(roles.map(r => r.harness))];

package/dist/harness/claude-code.js

@@ -109,10 +109,15 @@ export function makeClaudeCodeAdapter(exec = realExec) {
             getMessagesTool: 'get_messages',
             watchCommand: id => `ours-mcp watch "${id}"`,
             monitorInstruction: id => `Arm a **persistent Monitor** running the shell command \`ours-mcp watch "${id}"\` so inbound ours mail wakes you.`,
+            supervisedWakeNote: () => 'Your mail wake-ups are delivered by the fleet supervisor directly into this console as ' +
+                '`[fleet-monitor]` lines — do NOT arm an in-session Monitor. When such a line appears, run ' +
+                '**get_messages** to drain the mail.',
             launchNote: name => `You were launched with \`--remote-control ${name}\`. Confirm you are running.`,
-            restartPrompt: (id, worklog) => `Session restarted. Re-bind your ours identity now (choose_identity name "${id}" force=true), ` +
-                `re-arm your monitor (ours-mcp watch "${id}"), then continue from ${worklog}. ` +
-                'Do not re-run whatever crashed you.',
+            restartPrompt: (id, worklog, role) => `Session restarted. Re-bind your ours identity now (choose_identity name "${id}" force=true), ` +
+                (role?.monitor?.enabled
+                    ? 'then continue from '
+                    : `re-arm your monitor (ours-mcp watch "${id}"), then continue from `) +
+                `${worklog}. Do not re-run whatever crashed you.`,
         },
         exitPolicy: { cleanExitIsFresh: true, fastFailSecs: 20 },
     };

package/dist/harness/codex.js

@@ -197,8 +197,15 @@ export function makeCodexAdapter(exec = realExec) {
                     `fallback. After each arrival, call **get_messages**, handle the mail, and re-enter ` +
                     `**foreground_monitor** while the approved monitoring session remains armed.`;
             },
+            supervisedWakeNote: () => 'Your mail wake-ups are delivered by the fleet supervisor directly into this console as ' +
+                '`[fleet-monitor]` lines — do NOT arm arm_monitor or foreground_monitor. When such a line ' +
+                'appears, call **get_messages**, handle the mail, and reply with send_message.',
             launchNote: name => `You were launched as the fleet role \`${name}\` under a Codex session. Confirm you are running.`,
             restartPrompt: (id, worklog, configuredRole) => {
+                if (configuredRole?.monitor?.enabled)
+                    return `Session restarted. Re-bind your ours identity now (choose_identity name "${id}" force=true); ` +
+                        'your mail wakes are delivered by the fleet supervisor as `[fleet-monitor]` console lines, so do ' +
+                        `NOT arm arm_monitor/foreground_monitor. Continue from ${worklog}. Do not re-run whatever crashed you.`;
                 const consented = configuredRole?.harness_options?.monitor === true;
                 return `Session restarted. Re-bind your ours identity now (choose_identity name "${id}" force=true), ` +
                     (consented

package/dist/harness/types.d.ts

@@ -37,6 +37,8 @@ export interface BriefingVocab {
     getMessagesTool: string;
     watchCommand(identity: string): string;
     monitorInstruction(identity: string, role?: ResolvedRole): string;
+    /** Wake-source wording for a role whose monitor is supervisor-owned (monitor.enabled). */
+    supervisedWakeNote(identity: string, role?: ResolvedRole): string;
     launchNote(name: string): string;
     restartPrompt(identity: string, worklogPath: string, role?: ResolvedRole): string;
 }

package/dist/monitor.d.ts

@@ -0,0 +1,103 @@
+import type { MonitorConfig, NotifyEventType } from './config.js';
+/** A content-free arrival event as the daemon serves it over the notifications API. */
+export interface NotifyEvent {
+    event?: NotifyEventType | string;
+    from?: string;
+    msg_id?: number | string;
+    file_id?: number | string;
+    date?: string;
+    queued?: number | string;
+}
+export interface FetchResponse {
+    status: number;
+    ok: boolean;
+    json(): Promise<{
+        cursor?: number;
+        events?: NotifyEvent[];
+    }>;
+}
+export type FetchLike = (url: string, init?: {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}) => Promise<FetchResponse>;
+export interface MonitorTmux {
+    has(name: string): Promise<boolean>;
+    capture(name: string, lines?: number): Promise<string>;
+    sendText(name: string, text: string): Promise<void>;
+    sendKey(name: string, key: string): Promise<void>;
+}
+export interface MonitorDeps {
+    fetch: FetchLike;
+    tmux: MonitorTmux;
+    isAlive(pid: number): boolean;
+    sleep(ms: number): Promise<void>;
+    now(): number;
+    log(line: string): void;
+    env: NodeJS.ProcessEnv;
+    timers: {
+        set(fn: () => void, ms: number): ReturnType<typeof setTimeout>;
+        clear(t: ReturnType<typeof setTimeout>): void;
+    };
+}
+/** Resolve the daemon endpoint + auth header from the environment (design §6c). */
+export declare function resolveEndpoint(env: NodeJS.ProcessEnv): {
+    url(name: string): string;
+    headers: Record<string, string>;
+};
+/** Keep only the events whose type the role asked to wake on. */
+export declare function filterEvents(events: NotifyEvent[], wakeSources: string[]): NotifyEvent[];
+/**
+ * Summarize a (coalesced) batch of events into one content-free console line —
+ * count + senders + ids, ending in the call to action. Falls back to compact
+ * counts when a burst would blow past the length cap (design §3, edge: burst).
+ */
+export declare function formatNotificationLine(events: NotifyEvent[]): string;
+/**
+ * Heuristic: does the pane show a modal selection dialog we must not `Enter`
+ * into? Markers are the deployed Claude Code trust/permission dialogs — a `❯`
+ * pointer beside numbered options, or a "Do you want …" prompt (design §3.2,
+ * open question (a): refine empirically). A running turn is NOT modal.
+ */
+export declare function looksModal(pane: string): boolean;
+export interface MonitorOpts {
+    name: string;
+    agentDir: string;
+    cfg: MonitorConfig;
+    deps: MonitorDeps;
+}
+/** The lifecycle surface the runner drives: prime pre-launch, run, stop on pid death. */
+export interface MonitorHandle {
+    prime(): Promise<void>;
+    run(pid: number): Promise<void>;
+    stop(): void;
+}
+export declare class Monitor {
+    private readonly name;
+    private readonly cfg;
+    private readonly deps;
+    private readonly ep;
+    private readonly statusPath;
+    private readonly cursorPath;
+    private cursor;
+    private fatal;
+    private stopped;
+    private bootDeadline;
+    private currentAbort;
+    constructor(o: MonitorOpts);
+    /** Prime at the stream tip (or resume a persisted cursor if the daemon is down). */
+    prime(): Promise<void>;
+    /** Long-poll → filter → coalesce → inject, until the pane pid dies or stop(). */
+    run(pid: number): Promise<void>;
+    stop(): void;
+    /** Gather stragglers arriving within batch_ms so a burst lands as one line. */
+    private coalesce;
+    private deliver;
+    /** Block until the console can accept input; classify offline/stopped/ready. */
+    private awaitInjectable;
+    private doFetch;
+    private advance;
+    private persistCursor;
+    private readPersistedCursor;
+    private setStatus;
+}
+export declare function createMonitor(o: MonitorOpts): Monitor;

package/dist/monitor.js

@@ -0,0 +1,298 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+// Code constants (not config — YAGNI, design §2).
+const DEFAULT_PORT = 3050;
+const LONGPOLL_TIMEOUT_MS = 35_000; // > the daemon's 25s hold
+const COALESCE_HOLD_MS = 500; // straggler poll must not block
+const BOOT_GRACE_MS = 15_000; // hold injection until the TUI is up
+const POST_VERIFY_MS = 1_000;
+const MAX_ENTER_RETRIES = 2;
+const MODAL_RETRY_MS = 5_000;
+const BACKOFF_STEP_MS = 1_000;
+const BACKOFF_MAX_MS = 5_000;
+const PREFIX = '[fleet-monitor]';
+const MAX_LINE = 260;
+class AuthError extends Error {
+}
+/** Resolve the daemon endpoint + auth header from the environment (design §6c). */
+export function resolveEndpoint(env) {
+    const port = Number(env.OURS_PORT) || DEFAULT_PORT;
+    const token = env.OURS_API_TOKEN;
+    return {
+        url: (name) => `http://127.0.0.1:${port}/identities/${encodeURIComponent(name)}/notifications`,
+        headers: token ? { 'x-ours-api-token': token } : {},
+    };
+}
+/** Keep only the events whose type the role asked to wake on. */
+export function filterEvents(events, wakeSources) {
+    const set = new Set(wakeSources);
+    return events.filter(e => e.event !== undefined && set.has(e.event));
+}
+const uniq = (xs) => [...new Set(xs)];
+const plural = (n, one, many = one + 's') => (n === 1 ? one : many);
+/**
+ * Summarize a (coalesced) batch of events into one content-free console line —
+ * count + senders + ids, ending in the call to action. Falls back to compact
+ * counts when a burst would blow past the length cap (design §3, edge: burst).
+ */
+export function formatNotificationLine(events) {
+    const of = (t) => events.filter(e => e.event === t);
+    const msgs = of('message_received');
+    const files = of('file_received');
+    const intros = of('local_contact_request');
+    const pending = of('pending_message');
+    const known = new Set(['message_received', 'file_received', 'local_contact_request', 'pending_message']);
+    const others = events.filter(e => !known.has(e.event ?? ''));
+    const senders = (list) => uniq(list.map(e => e.from ?? '?')).join(', ');
+    const ids = (list) => {
+        const xs = list.map(e => e.msg_id).filter(v => v !== undefined);
+        return xs.length ? ` (${xs.map(x => `#${x}`).join(', ')})` : '';
+    };
+    const clauses = [];
+    if (msgs.length)
+        clauses.push(`${msgs.length} new ${plural(msgs.length, 'message')} from ${senders(msgs)}${ids(msgs)}`);
+    if (files.length)
+        clauses.push(`${files.length} ${plural(files.length, 'file')} from ${senders(files)}`);
+    if (intros.length)
+        clauses.push(`${intros.length} pending ${plural(intros.length, 'introduction')} from ${senders(intros)}`);
+    if (pending.length)
+        clauses.push(`${pending.length} queued ${plural(pending.length, 'message')} from ${senders(pending)}`);
+    if (others.length)
+        clauses.push(`${others.length} other ${plural(others.length, 'event')} (${uniq(others.map(e => e.event ?? '?')).join(', ')})`);
+    const line = `${PREFIX} ${clauses.join(', ')} — run get_messages`;
+    if (line.length <= MAX_LINE)
+        return line;
+    const compact = [
+        msgs.length && `${msgs.length} messages`,
+        files.length && `${files.length} files`,
+        intros.length && `${intros.length} introductions`,
+        pending.length && `${pending.length} queued`,
+        others.length && `${others.length} other`,
+    ].filter(Boolean).join(', ');
+    return `${PREFIX} ${compact} — run get_messages`;
+}
+/**
+ * Heuristic: does the pane show a modal selection dialog we must not `Enter`
+ * into? Markers are the deployed Claude Code trust/permission dialogs — a `❯`
+ * pointer beside numbered options, or a "Do you want …" prompt (design §3.2,
+ * open question (a): refine empirically). A running turn is NOT modal.
+ */
+export function looksModal(pane) {
+    if (/Do you want\b/i.test(pane))
+        return true;
+    const hasPointer = /❯/.test(pane);
+    const hasNumbered = /(^|\n)\s*[❯>]?\s*\d+[.)]\s+\S/.test(pane);
+    return hasPointer && hasNumbered;
+}
+/** Is the injected line still sitting unsubmitted in the composer (bottom of pane)? */
+function stillInComposer(pane, line) {
+    const frag = line.slice(0, 48);
+    const tail = pane.split('\n').slice(-4).join('\n');
+    return tail.includes(frag);
+}
+export class Monitor {
+    name;
+    cfg;
+    deps;
+    ep;
+    statusPath;
+    cursorPath;
+    cursor = null;
+    fatal = false;
+    stopped = false;
+    bootDeadline = 0;
+    currentAbort = null;
+    constructor(o) {
+        this.name = o.name;
+        this.cfg = o.cfg;
+        this.deps = o.deps;
+        this.ep = resolveEndpoint(o.deps.env);
+        this.statusPath = join(o.agentDir, '.monitor-status');
+        this.cursorPath = join(o.agentDir, '.notify-cursor');
+    }
+    /** Prime at the stream tip (or resume a persisted cursor if the daemon is down). */
+    async prime() {
+        try {
+            const body = await this.doFetch('tip', LONGPOLL_TIMEOUT_MS);
+            this.cursor = typeof body.cursor === 'number' ? body.cursor : 0;
+            this.persistCursor();
+            this.setStatus('armed');
+        }
+        catch (e) {
+            if (e instanceof AuthError) {
+                this.fatal = true;
+                this.setStatus(`failed: ${e.message}`);
+            }
+            else {
+                this.cursor = this.readPersistedCursor();
+                this.setStatus(`degraded: prime failed (${msg(e)})`);
+            }
+        }
+    }
+    /** Long-poll → filter → coalesce → inject, until the pane pid dies or stop(). */
+    async run(pid) {
+        if (this.fatal)
+            return;
+        this.bootDeadline = this.deps.now() + BOOT_GRACE_MS;
+        let backoff = 0;
+        while (!this.stopped) {
+            if (!this.deps.isAlive(pid)) {
+                this.setStatus('degraded: session offline');
+                return;
+            }
+            let body;
+            try {
+                body = await this.doFetch(String(this.cursor ?? 0), LONGPOLL_TIMEOUT_MS);
+                backoff = 0;
+            }
+            catch (e) {
+                if (this.stopped)
+                    return;
+                if (e instanceof AuthError) {
+                    this.fatal = true;
+                    this.setStatus(`failed: ${e.message}`);
+                    return;
+                }
+                backoff = Math.min(backoff + BACKOFF_STEP_MS, BACKOFF_MAX_MS);
+                this.setStatus(`degraded: stream hiccup (${msg(e)})`);
+                await this.deps.sleep(backoff);
+                continue;
+            }
+            this.advance(body.cursor);
+            const batch = filterEvents(body.events ?? [], this.cfg.wake_sources);
+            if (batch.length === 0)
+                continue;
+            await this.coalesce(batch);
+            await this.deliver(pid, batch);
+        }
+    }
+    stop() {
+        this.stopped = true;
+        this.currentAbort?.abort();
+    }
+    // ── internals ──────────────────────────────────────────────────────────────
+    /** Gather stragglers arriving within batch_ms so a burst lands as one line. */
+    async coalesce(batch) {
+        if (this.cfg.batch_ms <= 0 || this.stopped)
+            return;
+        await this.deps.sleep(this.cfg.batch_ms);
+        if (this.stopped)
+            return;
+        try {
+            const more = await this.doFetch(String(this.cursor ?? 0), COALESCE_HOLD_MS);
+            this.advance(more.cursor);
+            batch.push(...filterEvents(more.events ?? [], this.cfg.wake_sources));
+        }
+        catch { /* no stragglers / abort — deliver what we have */ }
+    }
+    async deliver(pid, batch) {
+        const state = await this.awaitInjectable(pid);
+        if (state !== 'ready') {
+            if (state === 'offline')
+                this.setStatus('degraded: offline during delivery');
+            return; // events remain covered by unread.json / SessionStart backlog
+        }
+        const line = formatNotificationLine(batch);
+        await this.deps.tmux.sendText(this.name, line); // send-keys -l + Enter
+        let delivered = false;
+        // Verify submission for THIS line even if stop() arrives mid-flight: the text
+        // is already in the composer and we want it submitted (at-least-once). A truly
+        // dead pane makes safeCapture return '' ⇒ not-in-composer ⇒ breaks, no wasted Enter.
+        for (let i = 0; i < MAX_ENTER_RETRIES; i++) {
+            await this.deps.sleep(POST_VERIFY_MS);
+            const pane = await safeCapture(this.deps.tmux, this.name);
+            if (!stillInComposer(pane, line)) {
+                delivered = true;
+                break;
+            }
+            await this.deps.tmux.sendKey(this.name, 'Enter');
+        }
+        this.setStatus(delivered ? 'armed' : 'degraded: injection unverified');
+    }
+    /** Block until the console can accept input; classify offline/stopped/ready. */
+    async awaitInjectable(pid) {
+        for (;;) {
+            if (this.stopped)
+                return 'stopped';
+            if (!this.deps.isAlive(pid) || !(await this.deps.tmux.has(this.name)))
+                return 'offline';
+            const now = this.deps.now();
+            if (now < this.bootDeadline) {
+                await this.deps.sleep(this.bootDeadline - now);
+                continue;
+            }
+            const pane = await safeCapture(this.deps.tmux, this.name);
+            if (looksModal(pane)) {
+                await this.deps.sleep(MODAL_RETRY_MS);
+                continue;
+            }
+            return 'ready';
+        }
+    }
+    async doFetch(since, holdMs) {
+        const ctrl = new AbortController();
+        this.currentAbort = ctrl;
+        const timer = this.deps.timers.set(() => ctrl.abort(), holdMs);
+        let resp;
+        try {
+            resp = await this.deps.fetch(`${this.ep.url(this.name)}?since=${since}`, { headers: this.ep.headers, signal: ctrl.signal });
+        }
+        finally {
+            this.deps.timers.clear(timer);
+            this.currentAbort = null;
+        }
+        if (resp.status === 401)
+            throw new AuthError('daemon rejected the API token (401) — set OURS_API_TOKEN or run as the daemon owner');
+        if (!resp.ok)
+            throw new Error(`daemon returned HTTP ${resp.status}`);
+        return resp.json();
+    }
+    advance(cursor) {
+        if (typeof cursor === 'number' && cursor !== this.cursor) {
+            this.cursor = cursor;
+            this.persistCursor();
+        }
+    }
+    persistCursor() {
+        try {
+            if (this.cursor !== null)
+                writeFileSync(this.cursorPath, `${this.cursor}\n`);
+        }
+        catch (e) {
+            this.deps.log(`[${this.name}] monitor: failed to persist cursor: ${msg(e)}`);
+        }
+    }
+    readPersistedCursor() {
+        try {
+            if (!existsSync(this.cursorPath))
+                return null;
+            const n = parseInt(readFileSync(this.cursorPath, 'utf8').trim(), 10);
+            return Number.isFinite(n) ? n : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    setStatus(s) {
+        try {
+            writeFileSync(this.statusPath, `${s}\n`);
+        }
+        catch (e) {
+            this.deps.log(`[${this.name}] monitor: failed to write status: ${msg(e)}`);
+        }
+        if (!s.startsWith('armed'))
+            this.deps.log(`[${this.name}] monitor ${s}`);
+    }
+}
+export function createMonitor(o) {
+    return new Monitor(o);
+}
+async function safeCapture(tmux, name) {
+    try {
+        return await tmux.capture(name);
+    }
+    catch {
+        return '';
+    }
+}
+const msg = (e) => e?.message ?? String(e);

package/dist/runner.d.ts

@@ -1,6 +1,7 @@
 import { type ResolvedRole } from './config.js';
 import type { Launch } from './harness/types.js';
 import { Tmux } from './tmux.js';
+import { type MonitorHandle, type MonitorOpts, type FetchLike } from './monitor.js';
 import { type Exec } from './exec.js';
 export interface RunnerDeps {
     tmux: Tmux;
@@ -10,6 +11,10 @@ export interface RunnerDeps {
     sleep(ms: number): Promise<void>;
     now(): number;
     log(line: string): void;
+    /** HTTP transport for the monitor's daemon long-poll (injectable for tests). */
+    fetch: FetchLike;
+    /** Construct the supervisor mail monitor (injectable so tests stub it out). */
+    createMonitor(opts: MonitorOpts): MonitorHandle;
 }
 /**
  * Compose the tmux pane shell command: env prefix + argv + exit-status capture.

package/dist/runner.js

@@ -6,6 +6,7 @@ import { agentDir, home } from './paths.js';
 import { loadConfig, findRole } from './config.js';
 import { getAdapter } from './harness/registry.js';
 import { Tmux } from './tmux.js';
+import { createMonitor } from './monitor.js';
 import { realExec, shq } from './exec.js';
 import { resolveIsolation } from './isolation/policy.js';
 import { selectIsolationBackend } from './isolation/registry.js';
@@ -24,6 +25,8 @@ const defaultDeps = () => ({
     sleep: ms => new Promise(r => setTimeout(r, ms)),
     now: () => Date.now(),
     log: line => process.stderr.write(line + '\n'),
+    fetch: (url, init) => globalThis.fetch(url, init),
+    createMonitor: opts => createMonitor(opts),
 });
 /**
  * Compose the tmux pane shell command: env prefix + argv + exit-status capture.
@@ -38,6 +41,19 @@ export function buildPaneCommand(launch, roleEnv, exitStatusPath, paneArgv = lau
     const cmd = paneArgv.map(shq).join(' ');
     return `${envPfx} ${cmd}; echo $? > ${shq(exitStatusPath)}`;
 }
+/** Adapt the runner's injected deps into the monitor's dependency surface. */
+function monitorDeps(deps) {
+    return {
+        fetch: deps.fetch,
+        tmux: deps.tmux,
+        isAlive: deps.isAlive,
+        sleep: deps.sleep,
+        now: deps.now,
+        log: deps.log,
+        env: process.env,
+        timers: { set: (fn, ms) => setTimeout(fn, ms), clear: t => clearTimeout(t) },
+    };
+}
 /** Read a temp role's config snapshot written by spawnTemp. */
 export function loadTempRole(name) {
     const p = join(agentDir(name, true), 'role.yaml');
@@ -116,6 +132,17 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
         if (rprefix.length)
             paneArgv = [...rprefix, ...paneArgv];
     }
+    // Supervisor mail monitor (design §1): prime the notification cursor at the
+    // stream tip BEFORE the session launches so no arrival is missed during boot
+    // (backlog before the tip is the SessionStart hook's job). Disabled roles keep
+    // the legacy in-session watch. Temp snapshots predating `monitor:` are treated
+    // as disabled (monitor may be undefined on an old role.yaml).
+    const monitor = role.monitor?.enabled ? deps.createMonitor({
+        name, agentDir: dir, cfg: role.monitor,
+        deps: monitorDeps(deps),
+    }) : null;
+    if (monitor)
+        await monitor.prime();
     rmSync(exitFile, { force: true });
     await deps.tmux.kill(name);
     await deps.tmux.newSession(name, runCwd, buildPaneCommand(launch, role.env, exitFile, paneArgv));
@@ -128,9 +155,16 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
     if (pid === null)
         throw new Error(`[${name}] could not resolve tmux pane pid`);
     deps.log(`[${name}] up; pid=${pid} cwd=${runCwd} harness=${role.harness} mode=${mode}`);
+    // The monitor loop lives exactly as long as the session: it starts once the
+    // pane pid is known and is stopped when that pid dies (task dies with runner).
+    const monitorLoop = monitor?.run(pid);
     const start = deps.now();
     while (deps.isAlive(pid))
         await deps.sleep(2000);
+    if (monitor) {
+        monitor.stop();
+        await monitorLoop;
+    }
     const elapsed = (deps.now() - start) / 1000;
     const code = existsSync(exitFile) ? readFileSync(exitFile, 'utf8').trim() : 'crash';
     const rotate = (why) => {

package/dist/spawn.js

@@ -3,7 +3,7 @@ import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from 'no
 import { join } from 'node:path';
 import { stringify } from 'yaml';
 import { agentDir, fleetDDir } from './paths.js';
-import { loadConfig } from './config.js';
+import { loadConfig, resolveMonitorConfig } from './config.js';
 import { applyRole, up } from './ops.js';
 function roleFromOpts(o, defaultHarness) {
     const r = {};
@@ -90,6 +90,8 @@ export async function spawnTemp(o, binPath, launch = detachedSupervisor) {
         identity: o.identity ?? o.name,
         model: o.model?.trim() || cfg.defaults.model,
         harness_options: Object.keys(mergedHarnessOptions).length ? mergedHarnessOptions : undefined,
+        // Temp agents inherit the fleet-wide monitor defaults via the snapshot (design §2).
+        monitor: resolveMonitorConfig(cfg.defaults.monitor, fromOpts.monitor),
         sourceFile: '(temp)',
     };
     const dir = applyRole(role, { temp: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/fleet",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Harness-agnostic fleet of persistent, identity-bound AI agents. Declarative fleet.yaml, tmux consoles, systemd/launchd supervision, ours.network messaging.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",