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

package/README.md

@@ -54,8 +54,8 @@ 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, 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
+[Mail monitor](#mail-monitor)). Set `monitor.mode: native` when the harness
+should own mail wake instead. On crash the supervisor relaunches it and the
 harness resumes the same session.
 
 The state dir contract:
@@ -124,6 +124,8 @@ ours-fleet spawn --temp Scout --mission "one-off research"   # gone on exit/rebo
 ours-fleet spawn Coder --harness codex --model gpt-5.4 \
   --session acp --approval ask --filesystem workspace \
   --profile fleet --search --monitor --coordinator FleetCoordinator
+# Note: --monitor is legacy consent for Codex's native monitor. Choose the
+# wake owner separately in fleet.yaml with monitor.mode: fleet|native.
 ```
 
 Permanent spawns are written to `~/fleet.d/<Name>.yaml` — your hand-written
@@ -191,8 +193,8 @@ defaults:
     unattended: deny                    # deny | wait
   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
+  monitor:
+    mode: fleet                         # fleet (default) | native
 roles:
   Name:                                 # [A-Za-z0-9_-]+
     harness: claude-code
@@ -203,9 +205,9 @@ roles:
     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`
+    monitor:
+      mode: fleet                       # fleet = ours-fleet supervisor; native = harness monitor
+      interrupt: false                  # true cancels active work before every configured wake
       wake_sources:                     # which daemon events wake the console (default:
         - message_received              #   message_received, file_received,
         - file_received                 #   local_contact_request, pending_message)
@@ -253,6 +255,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**
@@ -273,21 +376,33 @@ their boots ~4 s apart instead of firing all seven at once.
 
 ### 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
+With `monitor.mode: fleet` (the default), the **ours-fleet supervisor** delivers
+a role's mail wakes: the per-role runner long-polls the ours daemon's notification API and
 submits a single `[fleet-monitor] N new messages from … — run get_messages` prompt
-through the selected backend. ACP uses structured `session/prompt`; tmux uses
-verified console input. It primes the notification cursor *before* the session launches
+through the selected backend. ACP uses live steering when its adapter supports it
+and falls back to structured `session/prompt`; tmux uses verified console input.
+Set `monitor.interrupt: true` on roles where every configured wake should cancel
+the active turn before the notification is delivered. This is intentionally
+content-blind: the supervisor cannot inspect encrypted message bodies, so all
+events selected by `wake_sources` receive the same interrupt policy.
+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`. Injection is held while the pane shows a modal dialog,
 so an injected wake can never answer a trust/permission prompt; if the dialog is
 still up after 2 minutes the monitor gives up on that wake and records
 `degraded: modal wedge …` instead of waiting silently forever (the mail stays
-queued and its cursor is not committed until a later delivery is accepted). 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
+queued and its cursor is not committed until a later delivery is accepted). The
+agent's briefing tells it **not** to arm a native harness Monitor.
+
+With `monitor.mode: native`, ours-fleet does not start its supervisor monitor;
+the generated briefing instead instructs the harness to arm its own wake
+mechanism (`ours-mcp watch` for Claude Code, or the Codex
+`arm_monitor`/`foreground_monitor` flow). The old `monitor.enabled: true|false`
+form remains accepted as a compatibility alias for `fleet|native`, respectively,
+but new configuration should use `mode`.
+
+`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`.
 
@@ -315,10 +430,11 @@ A role with `harness: codex` resolves its launcher at every supervised start:
 3. `launcher: ours-codex` makes the enhanced launcher mandatory and fails clearly if
    it is missing; `launcher: codex` explicitly selects standard mode.
 
-Monitoring remains consent-first. By default the generated briefing asks in the role's
-console before calling `arm_monitor`. Set `harness_options.monitor: true` (or pass
-`ours-fleet spawn --monitor`) to record explicit persistent consent for that role, including
-supervised restarts. In the standard-Codex fallback, the agent separately surfaces the
+Native Codex monitoring remains consent-first. By default the generated briefing asks in
+the role's console before calling `arm_monitor`. Set `harness_options.monitor: true` (or
+pass the legacy `ours-fleet spawn --monitor` flag) to record explicit persistent consent
+for the harness-native monitor, including supervised restarts. This does not choose the
+wake owner; use `monitor.mode: fleet|native` for that. In the standard-Codex fallback, the agent separately surfaces the
 `ours-codex` recommendation before asking to enter `foreground_monitor`. It never backgrounds
 `ours-mcp watch`, because a detached watch cannot wake a Codex turn. The foreground
 wait is re-entered after each handled message; `ours-codex` instead wakes the idle
@@ -335,7 +451,7 @@ defaults:
     profile: fleet                 # $CODEX_HOME/fleet.config.toml
     sandbox: workspace-write
     approval: on-request
-    monitor: true                  # explicit consent for unattended mail wake
+    monitor: true                  # consent for Codex's native monitor; not the wake-owner selector
     search: true
     add_dirs: [/data/shared]
     config:
@@ -348,7 +464,8 @@ roles:
 ```
 
 Equivalent one-off/permanent spawn controls include `--model`, `--permission-mode`,
-`--sandbox`, `--profile`, `--launcher`, `--search`, `--monitor`, repeatable
+`--sandbox`, `--profile`, `--launcher`, `--search`, legacy `--monitor` (native
+Codex monitor consent), repeatable
 `--codex-config key=value`, and repeatable `--add-dir`. Use `env.OURS_PORT`/`env.OURS_CONFIG` for a
 role-specific ours daemon, or configure the host default in `~/.ours/config.json`.
 

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}**`);
@@ -34,9 +50,9 @@ 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.`);
-    // When the supervisor owns the monitor (monitor.enabled), the agent must NOT arm
+    // When the supervisor owns the monitor (monitor.mode=fleet), the agent must NOT arm
     // its own in-session watch — wakes are injected as [fleet-monitor] lines (design §5).
-    const wakeNote = role.monitor?.enabled
+    const wakeNote = role.monitor?.mode === 'fleet'
         ? v.supervisedWakeNote(id, role)
         : v.monitorInstruction(id, role);
     L.push(`6. ${wakeNote}`);
@@ -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 —`);