@ours.network/fleet 0.10.0-nightly.3 → 0.10.0

package/dist/cli.js

@@ -8,14 +8,17 @@ import { Command } from 'commander';
 import { VERSION } from './version.js';
 import { agentDir, agentsRoot, tmpRoot, logsRoot, deriveXdgRuntimeDir } from './paths.js';
 import { loadConfig } from './config.js';
-import { Tmux } from './tmux.js';
+import { Tmux, tmuxArgs } from './tmux.js';
 import { pickBackend } from './supervisor/index.js';
 import { up, down, restartRoles, rmRole } from './ops.js';
-import { runOnce, runTemp } from './runner.js';
-import { spawnPermanent, spawnTemp } from './spawn.js';
+import { readRestartLedger, runSupervised, runTemp } from './runner.js';
+import { lastProvenance, spawnPermanent, spawnTemp } from './spawn.js';
+import { formatProvenance } from './creation.js';
 import { doctor } from './doctor.js';
+import { allWarnings, analyzeFleetPermissions, formatNative } from './permissions.js';
 import { AI_DOCS } from './docs.js';
-import { controlRequest, controlSocketPath, followControl, } from './session/control.js';
+import { controlRequest, controlSocketPath, followControl, livenessNote, } from './session/control.js';
+import { SessionControlError } from './session/types.js';
 import './harness/claude-code.js'; // registers the claude-code adapter
 import './harness/codex.js'; // registers the codex adapter
 // sudo/su shells lack XDG_RUNTIME_DIR, breaking every systemctl/journalctl
@@ -68,6 +71,17 @@ function renderSessionEvent(event) {
             console.log(`\n[${event.kind}] ${event.title ?? event.toolCallId ?? ''} ${event.status ?? ''}`.trimEnd());
             break;
         case 'permission':
+            if (event.status === 'completed') {
+                // A settled request. Automatic decisions are the ones nobody saw happen,
+                // so peek/attach must show what was decided and which policy decided it.
+                console.log(`\n[permission ${event.permissionId}] ${event.title ?? ''}`.trimEnd());
+                console.log(`  ${event.decisionSource ?? 'manual'} decision: ${event.decision ?? 'unknown'}`
+                    + `${event.optionId ? ` (${event.optionId})` : ''}`
+                    + `${event.policy ? ` via ${event.policy}` : ''}`);
+                if (event.reason)
+                    console.log(`  reason: ${event.reason}`);
+                break;
+            }
             console.log(`\n[permission ${event.permissionId}] ${event.title ?? ''}`);
             for (const option of event.options ?? [])
                 console.log(`  ${option.optionId}: ${option.name} (${option.kind})`);
@@ -106,11 +120,20 @@ cOpt(program.command('config').description('validate + print the merged plan (no
     try {
         const cfg = loadConfig(opts.configuration);
         console.log(`config: ${cfg.files.join(' + ') || '(none)'}`);
+        const analyses = analyzeFleetPermissions(cfg.roles);
         for (const r of cfg.roles) {
+            const perms = analyses.find(a => a.role === r.name);
             console.log(`\n● ${r.name}`);
             console.log(`    harness:     ${r.harness}`);
             console.log(`    session:     ${r.session}`);
+            console.log(`    monitor:     ${r.monitor.mode}`
+                + (r.monitor.mode === 'fleet' ? ` (interrupt=${r.monitor.interrupt})` : ''));
             console.log(`    identity:    ${r.identity}`);
+            console.log(`    permissions: approval=${r.permissions.approval} `
+                + `filesystem=${r.permissions.filesystem} unattended=${r.permissions.unattended}`);
+            if (perms?.supported)
+                console.log(`    native:      ${formatNative(perms.native)}`
+                    + `${perms.exact ? '' : ' (not an exact representation)'}`);
             console.log(`    source:      ${r.sourceFile}`);
             if (r.cwd)
                 console.log(`    cwd:         ${r.cwd}`);
@@ -134,6 +157,8 @@ cOpt(program.command('config').description('validate + print the merged plan (no
                 console.log(`    isolation:   backend=${iso.backend ?? 'auto'} net=${iso.network ?? 'broker'} `
                     + `on_unavailable=${iso.on_unavailable ?? 'warn'} caps=${caps}`);
             }
+            for (const w of perms ? allWarnings(perms) : [])
+                console.log(`    warning:     ${w}`);
         }
     }
     catch (e) {
@@ -178,12 +203,15 @@ cOpt(program.command('force-restart [names...]').description('re-sync + bounce F
 });
 program.command('ls').description('list running fleet sessions')
     .action(async () => {
-    const tmux = await new Tmux().list();
+    // Each session has its own tmux server (#32), so there is no single server
+    // to ask: the known role names ARE the list of servers to poll.
+    const names = [];
     const acp = [];
     for (const root of [agentsRoot(), tmpRoot()]) {
         if (!existsSync(root))
             continue;
         for (const name of readdirSync(root)) {
+            names.push(name);
             const stateDir = joinPath(root, name);
             if (!existsSync(controlSocketPath(stateDir)))
                 continue;
@@ -195,13 +223,14 @@ program.command('ls').description('list running fleet sessions')
             catch { /* ignore stale sockets */ }
         }
     }
+    const tmux = await new Tmux().list(names);
     console.log([tmux, ...acp].filter(Boolean).join('\n') || '(none)');
 });
 program.command('attach <name>').description('open the live console (Ctrl-b d to leave)')
     .action(async (name) => {
     const stateDir = acpStateDir(name);
     if (!stateDir)
-        process.exit(await passthrough('tmux', ['attach', '-t', name]));
+        process.exit(await passthrough('tmux', tmuxArgs(name, ['attach', '-t', name])));
     try {
         const { socket, send } = await followControl(stateDir, message => {
             if ('event' in message)
@@ -238,12 +267,30 @@ program.command('attach <name>').description('open the live console (Ctrl-b d to
         die(e);
     }
 });
+/** Classify a raw tmux failure: only "no such session" proves the pane is gone. */
+const asControlError = (e) => {
+    if (e instanceof SessionControlError)
+        return e;
+    const message = e instanceof Error ? e.message : String(e);
+    return new SessionControlError(/can't find session|no server running|session not found/i.test(message) ? 'offline' : 'backend', message);
+};
+/**
+ * Report what actually went wrong, then say what it proves about the agent.
+ * The old handler replaced every failure — timeouts, socket errors, refusals —
+ * with "is not running", which is how an overseer came to restart busy agents.
+ */
+const controlFailure = (name, action, e, extra = '') => {
+    const err = asControlError(e);
+    return `${action} ${name}: ${err.message}\n  ${livenessNote(err.kind, name)}${extra}`;
+};
 program.command('peek <name> [lines]').description('pane snapshot without attaching')
     .action(async (name, lines) => {
     try {
         const stateDir = acpStateDir(name);
         if (stateDir) {
             const response = await controlRequest(stateDir, { command: 'follow', since: 0 });
+            if (!response.ok)
+                throw new SessionControlError(response.kind ?? 'backend', response.error ?? 'peek failed');
             const events = response.result?.events ?? [];
             for (const event of events.slice(-(lines ? Number(lines) : 40)))
                 renderSessionEvent(event);
@@ -252,33 +299,40 @@ program.command('peek <name> [lines]').description('pane snapshot without attach
             console.log(await new Tmux().capture(name, lines ? Number(lines) : 40));
         }
     }
-    catch {
-        die(`'${name}' is not running; try: ours-fleet status ${name}`);
+    catch (e) {
+        die(controlFailure(name, 'peek', e));
     }
 });
 program.command('send <name> [text...]').description("type into the agent's console")
     .option('--key <key>', 'send a raw key instead (Escape, Up, C-c, ...)')
     .action(async (name, text, opts) => {
+    const stateDir = acpStateDir(name);
+    if (stateDir && opts.key)
+        die('--key is available only for tmux sessions');
+    if (!stateDir && !opts.key && !text?.length)
+        die('nothing to send: give text or --key');
+    if (stateDir && !text?.length)
+        die('nothing to send: give text');
     try {
-        const stateDir = acpStateDir(name);
         if (stateDir) {
-            if (opts.key)
-                die('--key is available only for tmux sessions');
-            if (!text?.length)
-                die('nothing to send: give text');
+            // Returns on queue acceptance: a turn already running is not a failure.
             const response = await controlRequest(stateDir, { command: 'submit_prompt', text: text.join(' ') });
             if (!response.ok)
-                throw new Error(response.error ?? 'prompt rejected');
+                throw new SessionControlError(response.kind ?? 'backend', response.error ?? 'prompt rejected');
+            const queued = response.result;
+            console.log(queued?.queuedBehind
+                ? `queued for ${name} behind ${queued.queuedBehind} running turn(s)`
+                : `queued for ${name}`);
         }
         else if (opts.key)
             await new Tmux().sendKey(name, opts.key);
-        else if (text?.length)
-            await new Tmux().sendText(name, text.join(' '));
         else
-            die('nothing to send: give text or --key');
+            await new Tmux().sendText(name, text.join(' '));
     }
-    catch {
-        die(`'${name}' is not running; try: ours-fleet status ${name}`);
+    catch (e) {
+        die(controlFailure(name, 'send', e, asControlError(e).kind === 'timeout'
+            ? '\n  The prompt may already have been delivered — do not assume it was lost.'
+            : ''));
     }
 });
 program.command('logs <name>').description('show the role log').option('-f, --follow', 'follow')
@@ -289,6 +343,16 @@ program.command('logs <name>').description('show the role log').option('-f, --fo
 program.command('status <name>').description('unit/agent state')
     .action(async (name) => {
     console.log(await pickBackend().status(name));
+    // A held-down role looks like a healthy running unit from the outside — the
+    // runner is alive on purpose. Say so, with the reason and when (3.2).
+    const ledger = readRestartLedger(agentDir(name));
+    if (ledger.circuit === 'open')
+        console.log(`HELD DOWN since ${ledger.openedAt ?? ledger.updatedAt} after `
+            + `${ledger.consecutiveImmediateFailures} immediate failures: ${ledger.lastReason}`
+            + `\n  release it with: ours-fleet restart ${name}`);
+    else if (ledger.consecutiveImmediateFailures > 0)
+        console.log(`restarts: ${ledger.consecutiveImmediateFailures} consecutive immediate `
+            + `failures, next delay ${ledger.nextDelayMs}ms (${ledger.lastReason})`);
     const stateDir = acpStateDir(name);
     if (stateDir) {
         try {
@@ -329,9 +393,10 @@ cOpt(program.command('spawn <name>').description('spawn a new agent (permanent b
     .option('--search', 'enable Codex live web search')
     .option('--codex-config <key=value>', 'Codex config override (repeatable)', collect, [])
     .option('--add-dir <dir>', 'additional Codex writable directory (repeatable)', collect, [])
-    .option('--monitor', 'explicitly consent to arm this Codex role\'s ours mail monitor')
+    .option('--monitor', 'legacy: consent to arm Codex\'s native monitor (wake owner is monitor.mode in YAML)')
     .option('--bio-file <file>', 'public bio (file)')
     .option('--persona-file <file>', 'persona / operating contract (file)')
+    .option('--isolation-file <path>', 'file holding an isolation: mapping (same schema as fleet.yaml)')
     .action(async (name, opts) => {
     try {
         const o = {
@@ -343,7 +408,8 @@ cOpt(program.command('spawn <name>').description('spawn a new agent (permanent b
             sandbox: opts.sandbox, profile: opts.profile,
             launcher: opts.launcher, search: opts.search,
             codexConfig: parseCodexConfig(opts.codexConfig), addDirs: opts.addDir, monitor: opts.monitor,
-            bioFile: opts.bioFile, personaFile: opts.personaFile, configPath: opts.configuration,
+            bioFile: opts.bioFile, personaFile: opts.personaFile,
+            isolationFile: opts.isolationFile, configPath: opts.configuration,
         };
         if (o.temp) {
             const dir = await spawnTemp(o, binPath);
@@ -353,6 +419,14 @@ cOpt(program.command('spawn <name>').description('spawn a new agent (permanent b
             const file = await spawnPermanent(o, deps());
             console.log(`spawned '${name}' (config: ${file})`);
         }
+        // The same provenance that was persisted, so what the operator reads now
+        // and what a reviewer reads later cannot disagree (6.6).
+        if (lastProvenance) {
+            console.log(`  created by ${lastProvenance.command} v${lastProvenance.fleetVersion} `
+                + `at ${lastProvenance.createdAt} (${lastProvenance.lifetime})`);
+            for (const line of formatProvenance(lastProvenance))
+                console.log(line);
+        }
         console.log(`→ watch it: ours-fleet peek ${name}   |   attach: ours-fleet attach ${name}`);
     }
     catch (e) {
@@ -378,8 +452,10 @@ program.command('init').description('one-time host setup (units, dirs, linger)')
 program.command('_run <name>', { hidden: true }).description('internal: supervisor entrypoint')
     .option('-c, --configuration <file>')
     .action(async (name, opts) => {
+    // The supervised loop, not a single session: restart policy lives here now,
+    // where it can count across attempts (3.2).
     try {
-        await runOnce(name, { configPath: opts.configuration });
+        await runSupervised(name, { configPath: opts.configuration });
     }
     catch (e) {
         die(e);

package/dist/config.d.ts

@@ -1,4 +1,4 @@
-import type { IsolationConfig } from './isolation/types.js';
+import type { IsolationConfig, WrapContext } from './isolation/types.js';
 export interface OverseeEntry {
     role: string;
     interval: string;
@@ -7,6 +7,7 @@ export interface OverseeEntry {
 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';
+export type MonitorMode = 'fleet' | 'native';
 export type SessionBackendId = 'tmux' | 'acp';
 export type ApprovalMode = 'ask' | 'allow' | 'deny';
 export type FilesystemMode = 'read-only' | 'workspace' | 'unrestricted';
@@ -27,10 +28,15 @@ export interface SessionOptions {
 }
 /** Resolved per-role supervisor-monitor config (see DESIGN-external-monitor §2). */
 export interface MonitorConfig {
+    /** Who owns mail wake delivery: ours-fleet supervisor or the native harness. */
+    mode: MonitorMode;
+    /** @deprecated Legacy alias retained in resolved snapshots; use mode. */
     enabled: boolean;
     wake_sources: string[];
     batch_ms: number;
     inject: InjectMode;
+    /** Cancel the active agent turn before delivering every configured wake. */
+    interrupt: boolean;
     /**
      * Consecutive delivered wakes that must end in an `API Error:`-terminated turn
      * (with no completed turn in between) before `.monitor-status` degrades to
@@ -69,6 +75,13 @@ export interface ResolvedRole extends RoleConfig {
     harness: string;
     session: SessionBackendId;
     permissions: CommonPermissions;
+    /**
+     * Whether `permissions:` was actually written by the operator (on the role or
+     * in defaults), as opposed to resolved from built-in defaults. A role that
+     * states its intent only once — neutrally OR natively — has nothing to
+     * contradict, and must not be warned at (2.4).
+     */
+    permissionsDeclared: boolean;
     identity: string;
     sourceFile: string;
     monitor: MonitorConfig;
@@ -83,13 +96,21 @@ export interface FleetConfig {
 }
 export declare class ConfigError extends Error {
 }
+/**
+ * The runtime facts the isolation resolver needs for a role. Single-sourced so
+ * config validation, doctor, and the runner all judge the SAME mount set — a
+ * policy checked against a different context than the one that launches is not
+ * a check at all.
+ */
+export declare function isolationContextFor(role: ResolvedRole): WrapContext;
 /** Load ~/fleet.yaml (or an explicit path) merged with ~/fleet.d/*.yaml drop-ins. */
 export declare function loadConfig(configPath?: string): FleetConfig;
 export declare function resolvePermissions(defaults: unknown, role: Partial<CommonPermissions> | undefined, file?: string, name?: string): CommonPermissions;
 /**
  * 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
+ * result, and fill code-constant defaults (design §2). `monitor.mode` selects
+ * fleet-owned or native-harness monitoring; absent everywhere ⇒ fleet. The old
+ * `enabled` boolean remains a compatibility alias. 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.
  */

package/dist/config.js

@@ -1,8 +1,9 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { parse } from 'yaml';
-import { defaultConfigPath, fleetDDir } from './paths.js';
-import { validateIsolationConfig } from './isolation/policy.js';
+import { agentDir, defaultConfigPath, fleetDDir, home } from './paths.js';
+import { harnessRuntimeDir, resolveIsolation, validateIsolationConfig, } from './isolation/policy.js';
+import { getAdapter } from './harness/registry.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',
@@ -10,8 +11,11 @@ export const NOTIFY_EVENT_TYPES = [
 ];
 /** 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', 'turn_fail_threshold'];
+const MONITOR_KEYS = [
+    'mode', 'enabled', 'wake_sources', 'batch_ms', 'inject', 'interrupt', 'turn_fail_threshold',
+];
 const INJECT_MODES = ['notification', 'full'];
+const MONITOR_MODES = ['fleet', 'native'];
 const MONITOR_DEFAULT_BATCH_MS = 2000;
 const MONITOR_DEFAULT_TURN_FAIL_THRESHOLD = 3;
 const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
@@ -26,11 +30,18 @@ export function validateMonitorConfig(raw) {
         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.mode !== undefined && !MONITOR_MODES.includes(m.mode))
+        problems.push(`monitor.mode: invalid value '${m.mode}'; allowed: ${MONITOR_MODES.join(', ')}`);
+    if (m.mode !== undefined && typeof m.enabled === 'boolean'
+        && m.enabled !== (m.mode === 'fleet'))
+        problems.push(`monitor.mode '${m.mode}' conflicts with legacy monitor.enabled ${m.enabled}`);
     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.interrupt !== undefined && typeof m.interrupt !== 'boolean')
+        problems.push('monitor.interrupt: must be true or false');
     if (m.turn_fail_threshold !== undefined
         && (typeof m.turn_fail_threshold !== 'number' || !Number.isInteger(m.turn_fail_threshold)
             || m.turn_fail_threshold < 1))
@@ -49,6 +60,37 @@ export function validateMonitorConfig(raw) {
 }
 export class ConfigError extends Error {
 }
+/**
+ * The runtime facts the isolation resolver needs for a role. Single-sourced so
+ * config validation, doctor, and the runner all judge the SAME mount set — a
+ * policy checked against a different context than the one that launches is not
+ * a check at all.
+ */
+export function isolationContextFor(role) {
+    const stateDir = agentDir(role.name, role.__temp === true);
+    const runCwd = role.cwd ?? stateDir;
+    // Ask the harness how its host state splits (5.1). An adapter that declares
+    // none keeps the historical whole-home mount.
+    let split;
+    try {
+        split = getAdapter(role.harness).isolationPaths?.(role, { stateDir, runCwd });
+    }
+    catch {
+        split = undefined;
+    }
+    return {
+        stateDir,
+        runCwd,
+        home: home(),
+        harness: role.harness,
+        additionalWriteDirs: role.harness === 'codex'
+            ? (role.harness_options?.add_dirs ?? [])
+            : [],
+        harnessHome: split?.home,
+        harnessRuntimeDir: split?.home ? harnessRuntimeDir(stateDir, role.harness) : undefined,
+        harnessSharedPaths: split?.shared,
+    };
+}
 const NAME_RE = /^[A-Za-z0-9_-]+$/;
 const ROLE_KEYS = [
     'harness', 'session', 'session_options', 'permissions', 'identity', 'cwd', 'coordinator', 'mission', 'persona', 'bio',
@@ -110,6 +152,7 @@ export function loadConfig(configPath) {
             const session = resolveSession(r.session ?? defaults.session, file, name);
             const sessionOptions = resolveSessionOptions(defaults.session_options, r.session_options, session, file, name);
             const permissions = resolvePermissions(defaults.permissions, r.permissions, file, name);
+            const permissionsDeclared = r.permissions !== undefined || defaults.permissions !== undefined;
             const defaultHarnessOptions = defaults.harness_options;
             if (defaultHarnessOptions !== undefined
                 && (typeof defaultHarnessOptions !== 'object' || defaultHarnessOptions === null
@@ -135,6 +178,7 @@ export function loadConfig(configPath) {
                 session,
                 session_options: sessionOptions,
                 permissions,
+                permissionsDeclared,
                 identity: r.identity ?? name,
                 model: r.model ?? defaults.model,
                 max_tokens: r.max_tokens ?? defaults.max_tokens,
@@ -142,6 +186,17 @@ export function loadConfig(configPath) {
                 isolation,
                 monitor,
             });
+            // Forbidden-path enforcement (5.2): a mount that would breach the policy
+            // is a configuration error, caught by `config` rather than at launch.
+            if (isolation !== undefined) {
+                const role = roles[roles.length - 1];
+                try {
+                    resolveIsolation(isolation, isolationContextFor(role));
+                }
+                catch (e) {
+                    throw new ConfigError(`${file}: role '${name}' ${e.message}`);
+                }
+            }
         }
     }
     return { roles, vars, defaults, files, startStaggerMs };
@@ -228,8 +283,9 @@ function resolveStartStaggerMs(raw, base) {
 }
 /**
  * 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
+ * result, and fill code-constant defaults (design §2). `monitor.mode` selects
+ * fleet-owned or native-harness monitoring; absent everywhere ⇒ fleet. The old
+ * `enabled` boolean remains a compatibility alias. 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.
  */
@@ -239,18 +295,35 @@ export function resolveMonitorConfig(defMonitor, roleMonitor, labels = {}) {
         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 def = (defMonitor ?? {});
+    const own = (roleMonitor ?? {});
+    const defProblems = validateMonitorConfig(def);
+    if (defProblems.length)
+        throw new ConfigError(`${labels.base ?? 'config'}: defaults.${defProblems.join('; defaults.')}`);
+    const ownProblems = validateMonitorConfig(own);
+    if (ownProblems.length)
+        throw new ConfigError(`${where}${ownProblems.join('; ')}`);
     const merged = {
-        ...(defMonitor ?? {}),
-        ...(roleMonitor ?? {}),
+        ...def,
+        ...own,
     };
-    const problems = validateMonitorConfig(merged);
-    if (problems.length)
-        throw new ConfigError(`${where}${problems.join('; ')}`);
+    const selected = own.mode !== undefined
+        ? own.mode
+        : own.enabled !== undefined
+            ? (own.enabled ? 'fleet' : 'native')
+            : def.mode !== undefined
+                ? def.mode
+                : def.enabled !== undefined
+                    ? (def.enabled ? 'fleet' : 'native')
+                    : 'fleet';
+    const mode = selected;
     return {
-        enabled: merged.enabled ?? true,
+        mode,
+        enabled: mode === 'fleet',
         wake_sources: merged.wake_sources ?? [...DEFAULT_WAKE_SOURCES],
         batch_ms: merged.batch_ms ?? MONITOR_DEFAULT_BATCH_MS,
         inject: merged.inject ?? 'notification',
+        interrupt: merged.interrupt ?? false,
         turn_fail_threshold: merged.turn_fail_threshold ?? MONITOR_DEFAULT_TURN_FAIL_THRESHOLD,
     };
 }

package/dist/creation.d.ts

@@ -0,0 +1,179 @@
+import { type LockDeps } from './atomic-file.js';
+import { type FetchLike } from './monitor.js';
+export type ReservationKind = 'role' | 'identity';
+export interface Reservation {
+    kind: ReservationKind;
+    name: string;
+}
+export declare class CreationConflictError extends Error {
+    constructor(message: string);
+}
+/**
+ * Artifacts a transaction created, newest last. Rollback walks this in reverse,
+ * and may only delete what THIS transaction made — an object that already
+ * existed is never touched.
+ */
+export interface JournalEntry {
+    stage: string;
+    undo(): void | Promise<void>;
+}
+export interface CreationDeps {
+    lock?: LockDeps;
+    log?(line: string): void;
+    /** Reserve the ours identity name. Injectable so tests need no daemon. */
+    identityRegistry?: IdentityRegistry;
+    /** Verify/create the ours identity. Injectable so tests need no daemon. */
+    identityProvisioner?: IdentityProvisioner;
+}
+/**
+ * The contract the ours daemon must satisfy for identity names to be reserved
+ * atomically across ALL of its clients, not just across fleet processes.
+ *
+ * `check-then-create` is not atomic across processes, which is the whole point:
+ * two spawns can both observe a free identity name and both create it. The
+ * daemon is the only component that sees every client, so only the daemon can
+ * make the reservation authoritative.
+ */
+export interface IdentityRegistry {
+    /** Claim `name`. Returns false if it is already taken or reserved. */
+    reserve(name: string): Promise<boolean>;
+    /** Give the claim back (rollback). Must be safe to call on an unheld name. */
+    release(name: string): Promise<void>;
+}
+/**
+ * Host-local identity reservation: atomic across every ours-fleet process on
+ * this host, because it is taken under the same host-wide creation lock as the
+ * role name.
+ *
+ * It is NOT atomic against other clients of the same ours daemon — another tool
+ * creating the identity between our reservation and our creation would still
+ * win. Closing that needs a reserve/commit/release operation in the daemon
+ * itself; see the release notes.
+ */
+export declare const hostLocalIdentityRegistry: IdentityRegistry;
+export interface CreationTransaction {
+    /** Record an artifact this transaction created, with how to undo it. */
+    record(entry: JournalEntry): void;
+    /** Stages recorded so far, in order. */
+    readonly stages: string[];
+}
+/**
+ * Run `body` inside a creation transaction.
+ *
+ * Under one host-wide lock: both names are reserved, then `body` builds the
+ * role. If anything throws, every recorded stage is undone in reverse order and
+ * both reservations are released, so the names can be reused immediately. On
+ * success the reservations are released too — the role's own config and state
+ * are the durable record from then on.
+ *
+ * Rollback errors are collected and reported, never allowed to hide the failure
+ * that caused the rollback.
+ */
+export declare function withCreationTransaction<T>(names: {
+    role: string;
+    identity: string;
+}, body: (tx: CreationTransaction) => Promise<T>, deps?: CreationDeps): Promise<T>;
+/** Forget reservations left behind by a process that died mid-transaction. */
+export declare function clearStaleReservations(olderThanMs?: number, now?: number): number;
+/**
+ * Identity provisioning (7.3). The fleet must know — before the harness starts
+ * — whether the role's identity exists, and create it when it does not.
+ *
+ * `exists()` is answerable today: the daemon's authenticated `/identities`
+ * endpoint is already used by doctor. `create()` is NOT: `ours-mcp` exposes only
+ * `create-root`, and role identities are minted through the MCP `create_identity`
+ * tool inside an agent session. So creation is a seam, injected by whoever can
+ * satisfy it, and its absence is reported rather than papered over.
+ */
+export interface IdentityProvisioner {
+    /** Does this identity exist? `unknown` when the daemon could not be asked. */
+    exists(name: string): Promise<boolean | 'unknown'>;
+    /** Create it, publishing bio/persona through the same path. Absent = cannot. */
+    create?(name: string, profile: {
+        bio?: string;
+        persona?: string;
+    }): Promise<void>;
+    /**
+     * Undo a `create` during rollback. Only ever called for an identity THIS
+     * transaction created; absent means "cannot", and the orphan is reported.
+     */
+    remove?(name: string): Promise<void>;
+}
+export type IdentityGuarantee = {
+    state: 'verified';
+    detail: string;
+} | {
+    state: 'created';
+    detail: string;
+} | {
+    state: 'unverified';
+    detail: string;
+};
+/**
+ * Establish the identity before the role's service is enabled.
+ *
+ * Returns what was actually GUARANTEED, so the generated briefing can say
+ * something true instead of asserting a "predefined" identity nobody checked —
+ * the failure a real agent hit on its first boot, having been told to bind an
+ * identity that did not exist.
+ */
+export declare function ensureIdentity(name: string, profile: {
+    bio?: string;
+    persona?: string;
+}, provisioner: IdentityProvisioner | undefined, log?: (line: string) => void): Promise<IdentityGuarantee>;
+/**
+ * Ask the running ours daemon whether an identity exists, over the same
+ * authenticated endpoint doctor already probes. Answers `unknown` rather than
+ * guessing when the daemon cannot be reached — an unreachable daemon is not
+ * evidence that the identity is missing.
+ *
+ * It deliberately has no `create()`: role identities are minted through the MCP
+ * `create_identity` tool, and inventing a daemon endpoint we cannot test is the
+ * failure mode this release exists to stop.
+ */
+export declare function daemonIdentityProvisioner(env?: NodeJS.ProcessEnv, fetchImpl?: FetchLike): IdentityProvisioner;
+/** Atomically write a role's fleet.d file, journalling it for rollback. */
+export declare function writeRoleFile(tx: CreationTransaction, file: string, contents: string): void;
+/** Where a setting's effective value came from. */
+export type ProvenanceSource = 'cli' | 'fleet-default' | 'built-in';
+export interface ProvenanceEntry {
+    value: unknown;
+    source: ProvenanceSource;
+}
+export interface CreationProvenance {
+    version: 1;
+    /** The command that created the role, without its arguments. */
+    command: string;
+    fleetVersion: string;
+    createdAt: string;
+    lifetime: 'permanent' | 'temporary';
+    role: string;
+    /** Effective settings, each tagged with where its value came from. */
+    settings: Record<string, ProvenanceEntry>;
+}
+export declare const CREATION_PROVENANCE_FILE = "creation.json";
+/**
+ * Record HOW a role was created, so nobody has to remember.
+ *
+ * Six months on, "why does this role have `approval: allow`?" is unanswerable:
+ * the resolved config shows the value but not whether an operator typed it, a
+ * fleet default supplied it, or it fell through to a built-in. Those have very
+ * different implications for whether it is safe to change.
+ *
+ * Deliberately excluded: `env`, `bio`, `persona`, and `harness_options`. The
+ * first two can carry credentials, and this file exists to be read — it must
+ * never become a place secrets accumulate.
+ */
+export declare function buildProvenance(o: {
+    role: string;
+    lifetime: 'permanent' | 'temporary';
+    fleetVersion: string;
+    now?: Date;
+    settings: Record<string, ProvenanceEntry>;
+}): CreationProvenance;
+/** Write the provenance record atomically, before the role is started. */
+export declare function writeProvenance(stateDir: string, p: CreationProvenance): void;
+/** One concise line per non-built-in setting, for the post-creation summary. */
+export declare function formatProvenance(p: CreationProvenance): string[];
+/** Classify one setting: an explicit CLI value, a fleet default, or built-in. */
+export declare function provenanceOf(cliValue: unknown, fleetDefault: unknown, builtIn?: unknown): ProvenanceEntry;