@ours.network/fleet 0.9.5 → 0.9.7

package/README.md

@@ -253,6 +253,107 @@ role's `harness_options`, so a fleet can set common Codex permission/profile def
 and override individual keys per role. `monitor` merges the same way — a role block
 overrides `defaults.monitor` key-by-key.
 
+### Never-prompt failure
+
+An unattended role has no console, so a permission request has nobody to answer
+it and is refused **inside the harness** — no prompt, no error, no log line. The
+agent does less than its briefing told it to, reports success, and nothing
+distinguishes that from having done the work. It is caused by a permission mode
+that suppresses the prompt without granting the action (Claude `dontAsk`), or by
+`unattended: deny`.
+
+Automatic decisions are now recorded rather than invisible. Every permission
+decided without a human is written to
+`~/.ours-fleet/agents/<Name>/.session-events.jsonl` with the decision, whether
+policy or a person made it, which policy produced it, the reason, and the option
+chosen — and `ours-fleet peek`/`attach` render them. Automatic denial always
+asks for a one-shot rejection, never a standing one, so one unattended refusal
+cannot disable a tool for the rest of the session. A role that can auto-deny
+says so once at startup.
+
+To catch this **before** a role runs, see the capability floor below —
+`ours-fleet doctor` fails an under-permissioned unattended role rather than
+letting it discover the problem silently.
+
+### The unattended capability floor
+
+A fleet role runs with no console attached, so a permission request has nobody
+to answer it and is refused inside the harness — silently. The agent then does
+less than its briefing told it to and reports no error at all.
+
+`ours-fleet config` and `ours-fleet doctor` therefore resolve each role's
+neutral `permissions:` through its harness adapter and check what the resulting
+native settings actually grant, against a fixed floor:
+
+| capability | what the role must be able to do |
+| --- | --- |
+| `read-state` | read its briefing, `ROUTINES.md`, and `WORKLOG.md` |
+| `write-state` | append its `WORKLOG.md` and its own state files |
+| `messaging` | bind its identity, send and receive ours mail |
+| `monitor` | arm and observe its mail monitor |
+| `workspace-edit` | edit and test files in its working directory |
+| `status-commands` | run the inspection commands its briefing prescribes |
+
+`doctor` reports this per role as `unattended floor: <Role>`. A role configured
+`unattended: deny` that cannot meet the floor **fails** doctor — it would deny
+those requests with nobody to see it. With `unattended: wait` it **warns**,
+since a human can still attach a console and answer.
+
+**Security meaning.** `approval: allow` maps to Claude's `bypassPermissions`,
+the mode that actually permits the actions the role was authorized to take.
+`dontAsk` suppresses only the *prompt*, not the denial, which is why an
+`allow` role previously ran unable to do its job. Nothing but an explicit
+`allow` is elevated: `ask` keeps Claude's default mode and `deny` maps to
+`plan`. `allow` is a real grant — give it deliberately, and keep per-role
+[`isolation:`](#agent-isolation) as the outer boundary, which no permission
+mode can cross.
+
+### Isolation at creation time
+
+```sh
+ours-fleet spawn Sec --isolation-file policy.yaml
+ours-fleet spawn --temp Scout --isolation-file policy.yaml
+```
+
+`--isolation-file` supplies the role's sandbox policy when it is created, so its
+**first** launch is already confined. Without it a role gains `isolation:` only when
+you edit `fleet.yaml` and run `up`, and everything before that ran unsandboxed.
+
+The file contains exactly the [`isolation:` mapping](#agent-isolation) — the same schema,
+validated by the same code, so it cannot mean something different from the identical block
+in `fleet.yaml`:
+
+```yaml
+network: deny
+fs:
+  read: [/opt/reference]
+resources:
+  mem: 2G
+```
+
+An invalid file is rejected before anything is created — no config, no state directory, no
+identity reservation.
+
+### Sandboxed credentials and configuration
+
+A sandboxed role gets a **per-role writable harness home** under its own state directory
+(`<state>/harness/<harness>/`), so its sessions, history and caches are its own and are
+invisible to every other role. The **shared** credentials, global instructions and
+configuration are layered back read-only:
+
+| Harness | Read-only (shared) | Per-role writable |
+| --- | --- | --- |
+| `claude-code` | `~/.claude.json`, `~/.claude/CLAUDE.md`, `settings.json`, `plugins/` | everything else under `~/.claude` |
+| `codex` | `~/.codex/auth.json`, `config.toml`, `AGENTS.md`, `plugins/`, `~/.agents` | everything else under `~/.codex` |
+
+An agent can read the credentials it needs and cannot rewrite them, cannot edit the
+instructions every role shares, and cannot alter a peer's configuration. Claude pre-trust
+stays a host-side step performed by the fleet.
+
+The forbidden-path list is enforced, not advisory: a role that asks for `~/.ssh`, the ours
+key store, a sibling's state directory — or a parent directory that would expose one, or a
+symlink to one — is refused by `ours-fleet config` before it can launch.
+
 ### Start staggering
 
 `start_stagger_ms` (top-level, host-wide, default `0`) spaces out agent **launches**

package/dist/atomic-file.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Cross-process file protection: a lock, and a replace that cannot leave a
+ * partial file behind.
+ *
+ * Shared state written with plain `readFileSync` → mutate → `writeFileSync` has
+ * two failure modes that only appear under concurrency, which is exactly the
+ * condition a fleet creates: two starts interleave and one silently discards
+ * the other's entry, or a crash mid-write truncates the last good file.
+ */
+export interface LockDeps {
+    now?(): number;
+    sleep?(ms: number): Promise<void>;
+}
+/**
+ * Run `fn` holding a cross-process lock. `mkdir` is atomic on every platform we
+ * support, so the directory's existence IS the lock; the timestamp inside lets a
+ * crashed holder's lock be broken rather than deadlocking the fleet forever.
+ * Same strategy as the runner's launch gate, factored out so both use one.
+ *
+ * The lock is always released, including when `fn` throws.
+ */
+export declare function withFileLock<T>(lockPath: string, fn: () => T | Promise<T>, deps?: LockDeps, staleMs?: number): Promise<T>;
+/**
+ * Replace a file's contents atomically: write a temp file in the SAME directory
+ * (so the rename cannot cross a filesystem boundary), fsync it, then rename over
+ * the target. A reader either sees the old file or the new one — never a
+ * half-written one — and an interrupted write leaves the previous contents
+ * intact.
+ */
+export declare function replaceFileAtomically(path: string, contents: string, mode?: number): void;

package/dist/atomic-file.js

@@ -0,0 +1,86 @@
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, writeSync, } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+const DEFAULT_STALE_MS = 10_000;
+const POLL_MS = 25;
+/**
+ * Run `fn` holding a cross-process lock. `mkdir` is atomic on every platform we
+ * support, so the directory's existence IS the lock; the timestamp inside lets a
+ * crashed holder's lock be broken rather than deadlocking the fleet forever.
+ * Same strategy as the runner's launch gate, factored out so both use one.
+ *
+ * The lock is always released, including when `fn` throws.
+ */
+export async function withFileLock(lockPath, fn, deps = {}, staleMs = DEFAULT_STALE_MS) {
+    const now = deps.now ?? (() => Date.now());
+    const sleep = deps.sleep ?? ((ms) => new Promise(r => { setTimeout(r, ms); }));
+    const stampPath = join(lockPath, 'ts');
+    mkdirSync(dirname(lockPath), { recursive: true });
+    for (let waited = 0;;) {
+        try {
+            mkdirSync(lockPath);
+            writeFileSync(stampPath, String(now()));
+            break;
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+            let held = null;
+            try {
+                const n = parseInt(readFileSync(stampPath, 'utf8').trim(), 10);
+                held = Number.isFinite(n) ? n : null;
+            }
+            catch { /* holder died between mkdir and stamp */ }
+            if ((held !== null && now() - held > staleMs) || waited > staleMs * 2) {
+                rmSync(lockPath, { recursive: true, force: true }); // break a dead holder's lock
+                continue;
+            }
+            await sleep(POLL_MS);
+            waited += POLL_MS;
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        rmSync(lockPath, { recursive: true, force: true });
+    }
+}
+/**
+ * Replace a file's contents atomically: write a temp file in the SAME directory
+ * (so the rename cannot cross a filesystem boundary), fsync it, then rename over
+ * the target. A reader either sees the old file or the new one — never a
+ * half-written one — and an interrupted write leaves the previous contents
+ * intact.
+ */
+export function replaceFileAtomically(path, contents, mode = 0o600) {
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+    const fd = openSync(tmp, 'w', mode);
+    try {
+        writeSync(fd, contents);
+        fsyncSync(fd); // the bytes are on disk before anything points at them
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        renameSync(tmp, path);
+    }
+    catch (e) {
+        rmSync(tmp, { force: true });
+        throw e;
+    }
+    // Best-effort: make the rename itself durable. Not supported everywhere.
+    try {
+        const dirFd = openSync(dir, 'r');
+        try {
+            fsyncSync(dirFd);
+        }
+        finally {
+            closeSync(dirFd);
+        }
+    }
+    catch { /* platform does not allow fsync on a directory */ }
+}

package/dist/briefing.d.ts

@@ -6,6 +6,12 @@ export interface BriefingOpts {
     routinesPath: string;
     /** Curated body (from briefing_file) replacing the narrative sections. */
     briefingBody?: string;
+    /**
+     * What spawn actually established about the role's ours identity (7.3).
+     * Defaults to `unverified`, because a briefing generated without that
+     * knowledge must not claim one.
+     */
+    identityGuarantee?: 'verified' | 'created' | 'unverified';
 }
 /** Render a role's briefing.md: narrative (or curated body) + mechanical boot steps. */
 export declare function generateBriefing(role: ResolvedRole, v: BriefingVocab, opts: BriefingOpts): string;

package/dist/briefing.js

@@ -1,4 +1,5 @@
 import { userInfo } from 'node:os';
+import { oversightTaxonomyLines } from './session/control.js';
 /** Render a role's briefing.md: narrative (or curated body) + mechanical boot steps. */
 export function generateBriefing(role, v, opts) {
     const L = [];
@@ -22,10 +23,25 @@ export function generateBriefing(role, v, opts) {
     }
     L.push('', '## Do these NOW, in order');
     L.push(`1. ${v.launchNote(role.name)}`);
-    L.push(`2. BIND your predefined ours identity: call the **${v.bindTool}** tool with`);
-    L.push(`   name "${id}" force=true (search the deferred tool registry first if needed).`);
-    L.push(`   - If no such identity exists yet, call **${v.createTool}** name "${id}" once`);
-    L.push('     to mint it, then you are bound. Re-binding your OWN identity is always allowed.');
+    // What this says depends on what spawn actually VERIFIED (7.3). Asserting a
+    // "predefined" identity that nobody checked is how an agent ends up improvising
+    // its own infrastructure on first boot.
+    const guarantee = opts.identityGuarantee ?? 'unverified';
+    if (guarantee === 'unverified') {
+        L.push(`2. BIND your ours identity: call the **${v.bindTool}** tool with`);
+        L.push(`   name "${id}" force=true (search the deferred tool registry first if needed).`);
+        L.push(`   - This identity was NOT verified when your role was created, so it may not exist.`);
+        L.push(`     If binding reports no such identity, call **${v.createTool}** name "${id}" once`);
+        L.push('     to mint it, then you are bound. Re-binding your OWN identity is always allowed.');
+    }
+    else {
+        L.push(`2. BIND your ours identity: call the **${v.bindTool}** tool with`);
+        L.push(`   name "${id}" force=true (search the deferred tool registry first if needed).`);
+        L.push(`   - It was ${guarantee === 'created' ? 'created' : 'verified to exist'} when your role`);
+        L.push('     was created, so binding should succeed. If it unexpectedly reports no such');
+        L.push(`     identity, call **${v.createTool}** name "${id}" once and report the discrepancy —`);
+        L.push('     something removed it after your role was created.');
+    }
     L.push(`3. RECONCILE your profile (idempotent): call **${v.currentIdentityTool}** and read your`);
     L.push('   current bio and persona, so you only write below when they actually differ.');
     L.push(`4. PUBLISH your public **bio** via **${v.setBioTool}**`);
@@ -50,7 +66,10 @@ export function generateBriefing(role, v, opts) {
         L.push(`7. Await messages. When the monitor wakes you (or the owner requests a manual check),`);
         L.push(`   call **${v.getMessagesTool}**, act on them,`);
         L.push(`   and reply with ${v.sendTool}. No coordinator is configured — the owner drives you`);
-        L.push(`   via \`tmux attach -t ${role.name}\` or by messaging "${id}".`);
+        // NOT `tmux attach -t <name>`: each role's pane lives on its own tmux
+        // socket (#32), so a bare attach finds no server. `ours-fleet attach`
+        // addresses the right one.
+        L.push(`   via \`ours-fleet attach ${role.name}\` or by messaging "${id}".`);
     }
     if (role.oversee?.length) {
         L.push('', '## Oversight assignments');
@@ -58,13 +77,24 @@ export function generateBriefing(role, v, opts) {
         for (const o of role.oversee)
             L.push(`- **${o.role}** — check every ${o.interval}`);
         L.push('');
-        L.push('Procedure (see also the oversee-agents skill if available): on each tick, run');
+        L.push('Procedure (see also the oversee-agents skill if available). On each tick, for each ward');
+        L.push('run BOTH — they answer different questions:');
         for (const o of role.oversee)
-            L.push(`\`ours-fleet peek ${o.role}\``);
-        L.push('and judge the console: stuck on a prompt/menu/trust dialog → answer it directly with');
-        L.push('`ours-fleet send <Name> "<text>"` (or `--key <K>` for raw keys); crashed to a shell →');
-        L.push('investigate and restart; idle with work assigned → nudge; healthy → do nothing.');
-        L.push('Escalate over ours messaging only when you cannot resolve it yourself.');
+            L.push(`\`ours-fleet status ${o.role}\` then \`ours-fleet peek ${o.role}\``);
+        L.push('');
+        L.push('**One console command is not a liveness verdict.** A `peek` or `send` that fails tells');
+        L.push('you what happened to YOUR REQUEST, and only one of its outcomes says the agent is gone.');
+        L.push('Read the result you actually got:');
+        L.push('');
+        L.push(...oversightTaxonomyLines());
+        L.push('');
+        L.push('Never translate any other failure into "dead". A busy agent, an unanswered control');
+        L.push('plane and a confirmed stop look identical if you only look at one command.');
+        L.push('');
+        L.push('Then judge the console content: stuck on a prompt/menu/trust dialog → answer it directly');
+        L.push('with `ours-fleet send <Name> "<text>"` (or `--key <K>` for raw keys); idle with work');
+        L.push('assigned → nudge; actively working → do nothing, and do not mistake a long turn for a');
+        L.push('stall. Escalate over ours messaging only when you cannot resolve it yourself.');
     }
     L.push('', '## Durable log');
     L.push(`Append important commands / decisions / results to \`${opts.worklogPath}\` as you go —`);

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,18 @@ 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(`    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 +155,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 +201,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 +221,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 +265,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 +297,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 +341,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 {
@@ -332,6 +394,7 @@ cOpt(program.command('spawn <name>').description('spawn a new agent (permanent b
     .option('--monitor', 'explicitly consent to arm this Codex role\'s ours mail monitor')
     .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 +406,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 +417,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 +450,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;
@@ -69,6 +69,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,6 +90,13 @@ 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;