@ours.network/fleet 0.9.3 → 0.9.5

package/README.md

@@ -8,8 +8,8 @@ harnesses — from one declarative file.**
 An AI coding agent in a terminal dies when you close the laptop. `ours-fleet`
 turns such sessions into **roles**: long-lived agents that
 
-- **live in a detached tmux console** you can attach to, peek at, or type into at
-  any time,
+- **run through a selectable session backend** — existing detached tmux consoles
+  or structured ACP sessions — which you can attach to, peek at, or prompt,
 - are **supervised** — systemd (Linux) or launchd (macOS) restarts them on crash
   and brings them back after a reboot,
 - **resume their context** across restarts (when the harness supports it),
@@ -44,7 +44,8 @@ roles:
 ~/fleet.yaml + ~/fleet.d/*.yaml           your declaration
         │  ours-fleet up
         ▼
- briefing.md per role  ──►  tmux session  ──►  harness CLI (claude …)
+briefing.md per role  ──►  tmux session  ──►  harness CLI (claude …)
+                       └─►  ACP client   ──►  ACP agent (codex-acp …)
         ▲                        │
  systemd --user / launchd ───────┘   restart on crash, start at boot/login
 ```
@@ -65,13 +66,16 @@ The state dir contract:
 | `WORKLOG.md` | the agent | seeded empty, agent-appended; survives restarts |
 | `ROUTINES.md` | operator / agent | **optional** recurring-work instructions; re-read at the start of every wake, hot-editable **without a restart**; absence means "no routines" |
 | `.identity`, `.cwd`, `.session-id`, `.booted`, `.exit-status`, `.config-path` | supervisor | dot-marker state — session resume and boot bookkeeping |
+| `.monitor-state.json`, `.monitor-status` | supervisor monitor | atomic body-free cursor/pending state and health |
+| `.session-events.jsonl`, `.control.sock`, `.control-token` | ACP backend | bounded typed console projection and private attachment control |
 
 ## Prerequisites
 
 | What | Why | Install |
 |---|---|---|
 | Node ≥ 20 | runs `ours-fleet` itself | nodejs.org, `apt`, or `brew` |
-| tmux | every role's console | `apt install tmux` / `brew install tmux` |
+| tmux | roles using `session: tmux` (the default) | `apt install tmux` / `brew install tmux` |
+| Node ≥ 22 | Claude roles using `session: acp` | required by the maintained Claude ACP adapter |
 | a harness CLI, logged in | the agent itself | e.g. Claude Code (`claude`) or Codex CLI (`codex`) |
 | `ours-mcp` daemon | identity + agent-to-agent messaging | `npm i -g @ours.network/mcp && ours-mcp start` |
 
@@ -87,6 +91,12 @@ ours-fleet init      # units/dirs/linger for this user
 ours-fleet doctor    # verifies everything above, with actionable messages
 ```
 
+The maintained Codex and Claude ACP adapters install as optional dependencies of
+`ours-fleet` and are resolved internally; users do not install adapter commands
+or add them to `PATH`. An explicit `session_options.acp.command` remains
+available for custom adapters. On Node 20–21, tmux and Codex ACP remain
+available, while maintained Claude ACP requires upgrading to Node 22.
+
 Each OS user manages their own fleet — to host roles under a sandboxed account,
 become that account and repeat.
 
@@ -112,28 +122,18 @@ ours-fleet spawn --temp Scout --mission "one-off research"   # gone on exit/rebo
 
 # Codex role: ours-codex is preferred automatically; plain codex is the fallback
 ours-fleet spawn Coder --harness codex --model gpt-5.4 \
-  --permission-mode on-request --sandbox workspace-write \
+  --session acp --approval ask --filesystem workspace \
   --profile fleet --search --monitor --coordinator FleetCoordinator
 ```
 
 Permanent spawns are written to `~/fleet.d/<Name>.yaml` — your hand-written
 `~/fleet.yaml` is **never** machine-edited. `ours-fleet rm <Name>` unspawns.
 
-From inside Claude Code: install the `ours-fleet` plugin (ships in this repo under
-`integrations/claude-code`) and say **"spawn ours agent …"** — the agent asks
-temp-vs-permanent, co-drafts the bio and persona with you, spawns, and arms
-oversight.
-
-From inside Codex, install the native fleet plugin:
-
-```sh
-npm i -g @ours.network/fleet-codex
-ours-fleet-codex-install
-```
-
-Start a new Codex session and say **"spawn an ours agent …"**. The bundled skill
-walks through lifetime, model, sandbox, approval policy, profile, launcher, and
-mail-monitor consent, then verifies the real tmux session and offers oversight.
+From inside Claude Code, Codex, or Hermes with the core `ours` plugin installed,
+say **"spawn an ours agent …"**. The core skill checks for `ours-fleet`, installs
+and initializes it when absent, then consults `ours-fleet docs` for the exact
+version-matched workflow. The older fleet-specific harness packages remain
+published for compatibility but are no longer required or installed by default.
 
 ## Oversight ("keep an eye")
 
@@ -161,11 +161,12 @@ roles:
 ## Command reference
 
 ```
+ours-fleet docs | man                 AI-friendly complete reference
 ours-fleet up|down|restart|force-restart [-c FILE] [Name...]
 ours-fleet config [-c FILE]         validate + print merged plan
 ours-fleet ls | attach | peek | logs [-f] | status <Name>
 ours-fleet send <Name> "text" | --key <K>
-ours-fleet spawn [--temp] <Name> [--harness --mission --model --permission-mode ...]
+ours-fleet spawn [--temp] <Name> [--harness --session --mission --model --approval ...]
 ours-fleet rm <Name>
 ours-fleet doctor [--harness H]
 ours-fleet init
@@ -183,6 +184,11 @@ vars: { work_root: /home/me/work }      # ${var} substitution anywhere below
 start_stagger_ms: 0                     # delay between agent LAUNCHES (host-wide, ms); 0 = no stagger
 defaults:
   harness: claude-code                  # for roles that don't set one
+  session: tmux                         # tmux (default) | acp
+  permissions:                         # common intent, translated by each harness/backend
+    approval: ask                       # ask | allow | deny
+    filesystem: workspace               # read-only | workspace | unrestricted
+    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)
@@ -190,6 +196,10 @@ defaults:
 roles:
   Name:                                 # [A-Za-z0-9_-]+
     harness: claude-code
+    session: acp                         # one flag selects ACP; omit for tmux
+    session_options:
+      acp:
+        command: claude-agent-acp        # optional advanced override
     identity: "Display Name"            # ours identity to bind (default: Name)
     cwd: ${work_root}/repo              # where the harness process runs
     coordinator: FleetCoordinator       # announce target on boot
@@ -236,7 +246,9 @@ roles:
 
 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
+never deletes an identity. `session` is independent of `harness`, so changing a
+role from tmux to ACP does not change its identity, mission, monitor, or permission
+contract. `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. `monitor` merges the same way — a role block
 overrides `defaults.monitor` key-by-key.
@@ -263,24 +275,34 @@ their boots ~4 s apart instead of firing all seven at once.
 
 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
+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
 (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
+`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
 inline) is on the roadmap and needs two new ours-mcp daemon endpoints; today all
 roles deliver `notification` lines and drain via `get_messages`.
 
+ACP stdio remains private to the persistent runner. `send`, `peek`, and the basic
+ACP `attach` console use a private, authenticated per-role control socket with
+typed replayable events. This is also the stable extension boundary for a richer
+console later; no terminal UI is part of the monitor or session backend.
+
 ## Codex roles
 
-Install Codex, the native ours plugin, and the fleet skills once on the fleet host:
+Install Codex, the native ours plugin, and the fleet CLI once on the fleet host:
 
 ```sh
-npm i -g @ours.network/fleet-codex
-ours-fleet-codex-install
+npm i -g @ours.network/fleet
+ours-fleet init
 ours-fleet doctor --harness codex
 ```
 
@@ -382,7 +404,7 @@ cleanly as long as each role has its own `cwd` (the common case); two roles
 sharing an identical `cwd` could have their resumes cross — give them distinct
 working directories if that matters. MCP and monitor wiring is provided by
 [`@ours.network/codex`](https://github.com/adapt-toolkit/ours-mcp/tree/main/packages/codex);
-the native spawn/oversight skills are provided by `@ours.network/fleet-codex`.
+the core ours skill discovers fleet behavior through `ours-fleet docs`.
 `ours-fleet doctor --harness codex` verifies the CLI, ours plugin, and enhanced launcher/fallback.
 
 ## Learn more

package/dist/cli.js

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 import { spawn as spawnChild } from 'node:child_process';
-import { mkdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync } from 'node:fs';
 import { realpathSync } from 'node:fs';
+import { join as joinPath } from 'node:path';
+import { createInterface } from 'node:readline';
 import { Command } from 'commander';
 import { VERSION } from './version.js';
-import { agentsRoot, tmpRoot, logsRoot, deriveXdgRuntimeDir } from './paths.js';
+import { agentDir, agentsRoot, tmpRoot, logsRoot, deriveXdgRuntimeDir } from './paths.js';
 import { loadConfig } from './config.js';
 import { Tmux } from './tmux.js';
 import { pickBackend } from './supervisor/index.js';
@@ -12,6 +14,8 @@ import { up, down, restartRoles, rmRole } from './ops.js';
 import { runOnce, runTemp } from './runner.js';
 import { spawnPermanent, spawnTemp } from './spawn.js';
 import { doctor } from './doctor.js';
+import { AI_DOCS } from './docs.js';
+import { controlRequest, controlSocketPath, followControl, } from './session/control.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
@@ -36,10 +40,48 @@ const passthrough = (cmd, args) => new Promise(resolve => {
 });
 const program = new Command()
     .name('ours-fleet')
-    .description('Fleet of persistent, identity-bound AI agents — harness-agnostic, tmux + systemd/launchd.')
+    .description('Fleet of persistent, identity-bound AI agents — selectable harness and tmux/ACP sessions.')
     .version(VERSION);
 const cOpt = (cmd) => cmd.option('-c, --configuration <file>', 'config file (default: ~/fleet.yaml + ~/fleet.d/)');
 const collect = (value, previous) => [...previous, value];
+program.command('docs')
+    .alias('man')
+    .description('print the complete AI-friendly command and configuration reference')
+    .action(() => { process.stdout.write(AI_DOCS); });
+function acpStateDir(name) {
+    const permanent = agentDir(name);
+    if (existsSync(controlSocketPath(permanent)))
+        return permanent;
+    const temp = agentDir(name, true);
+    if (existsSync(controlSocketPath(temp)))
+        return temp;
+    return undefined;
+}
+function renderSessionEvent(event) {
+    switch (event.kind) {
+        case 'agent_text':
+            process.stdout.write(event.text ?? '');
+            break;
+        case 'thought': break;
+        case 'tool_call':
+        case 'tool_update':
+            console.log(`\n[${event.kind}] ${event.title ?? event.toolCallId ?? ''} ${event.status ?? ''}`.trimEnd());
+            break;
+        case 'permission':
+            console.log(`\n[permission ${event.permissionId}] ${event.title ?? ''}`);
+            for (const option of event.options ?? [])
+                console.log(`  ${option.optionId}: ${option.name} (${option.kind})`);
+            console.log('  respond: /permit <permission-id> <option-id>');
+            break;
+        case 'turn_stop':
+            console.log(`\n[turn stopped: ${event.stopReason ?? 'unknown'}]`);
+            break;
+        case 'error':
+            console.error(`\n[error] ${event.text ?? ''}`);
+            break;
+        case 'state': break;
+    }
+}
 function parseCodexConfig(values) {
     if (!values?.length)
         return undefined;
@@ -67,6 +109,7 @@ cOpt(program.command('config').description('validate + print the merged plan (no
         for (const r of cfg.roles) {
             console.log(`\n● ${r.name}`);
             console.log(`    harness:     ${r.harness}`);
+            console.log(`    session:     ${r.session}`);
             console.log(`    identity:    ${r.identity}`);
             console.log(`    source:      ${r.sourceFile}`);
             if (r.cwd)
@@ -133,14 +176,81 @@ cOpt(program.command('force-restart [names...]').description('re-sync + bounce F
         die(e);
     }
 });
-program.command('ls').description('list running tmux consoles')
-    .action(async () => { console.log(await new Tmux().list() || '(none)'); });
+program.command('ls').description('list running fleet sessions')
+    .action(async () => {
+    const tmux = await new Tmux().list();
+    const acp = [];
+    for (const root of [agentsRoot(), tmpRoot()]) {
+        if (!existsSync(root))
+            continue;
+        for (const name of readdirSync(root)) {
+            const stateDir = joinPath(root, name);
+            if (!existsSync(controlSocketPath(stateDir)))
+                continue;
+            try {
+                const response = await controlRequest(stateDir, { command: 'status' }, 2_000);
+                if (response.ok && response.result?.alive)
+                    acp.push(`${name}: acp`);
+            }
+            catch { /* ignore stale sockets */ }
+        }
+    }
+    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) => process.exit(await passthrough('tmux', ['attach', '-t', name])));
+    .action(async (name) => {
+    const stateDir = acpStateDir(name);
+    if (!stateDir)
+        process.exit(await passthrough('tmux', ['attach', '-t', name]));
+    try {
+        const { socket, send } = await followControl(stateDir, message => {
+            if ('event' in message)
+                renderSessionEvent(message.event);
+            const result = message.result;
+            for (const event of result?.events ?? [])
+                renderSessionEvent(event);
+            if (message.ok === false)
+                console.error(`[control] ${String(message.error ?? 'request failed')}`);
+        });
+        console.log(`[attached to ${name} via ACP; type a prompt, /permit …, /interrupt, or /detach]`);
+        const input = createInterface({ input: process.stdin });
+        input.on('line', line => {
+            if (line === '/detach') {
+                input.close();
+                socket.end();
+                return;
+            }
+            if (line === '/interrupt') {
+                send({ command: 'interrupt' });
+                return;
+            }
+            const permit = line.match(/^\/permit\s+(\S+)\s+(\S+)$/);
+            if (permit) {
+                send({ command: 'respond_permission', permissionId: permit[1], optionId: permit[2] });
+                return;
+            }
+            if (line.trim())
+                send({ command: 'submit_prompt', text: line });
+        });
+        await new Promise(resolve => socket.once('close', resolve));
+    }
+    catch (e) {
+        die(e);
+    }
+});
 program.command('peek <name> [lines]').description('pane snapshot without attaching')
     .action(async (name, lines) => {
     try {
-        console.log(await new Tmux().capture(name, lines ? Number(lines) : 40));
+        const stateDir = acpStateDir(name);
+        if (stateDir) {
+            const response = await controlRequest(stateDir, { command: 'follow', since: 0 });
+            const events = response.result?.events ?? [];
+            for (const event of events.slice(-(lines ? Number(lines) : 40)))
+                renderSessionEvent(event);
+        }
+        else {
+            console.log(await new Tmux().capture(name, lines ? Number(lines) : 40));
+        }
     }
     catch {
         die(`'${name}' is not running; try: ours-fleet status ${name}`);
@@ -150,11 +260,20 @@ program.command('send <name> [text...]').description("type into the agent's cons
     .option('--key <key>', 'send a raw key instead (Escape, Up, C-c, ...)')
     .action(async (name, text, opts) => {
     try {
-        const tmux = new Tmux();
-        if (opts.key)
-            await tmux.sendKey(name, opts.key);
+        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');
+            const response = await controlRequest(stateDir, { command: 'submit_prompt', text: text.join(' ') });
+            if (!response.ok)
+                throw new Error(response.error ?? 'prompt rejected');
+        }
+        else if (opts.key)
+            await new Tmux().sendKey(name, opts.key);
         else if (text?.length)
-            await tmux.sendText(name, text.join(' '));
+            await new Tmux().sendText(name, text.join(' '));
         else
             die('nothing to send: give text or --key');
     }
@@ -168,7 +287,20 @@ program.command('logs <name>').description('show the role log').option('-f, --fo
     process.exit(await passthrough(cmd, args));
 });
 program.command('status <name>').description('unit/agent state')
-    .action(async (name) => { console.log(await pickBackend().status(name)); });
+    .action(async (name) => {
+    console.log(await pickBackend().status(name));
+    const stateDir = acpStateDir(name);
+    if (stateDir) {
+        try {
+            const response = await controlRequest(stateDir, { command: 'status' }, 2_000);
+            if (response.ok)
+                console.log(`session: ${JSON.stringify(response.result)}`);
+        }
+        catch {
+            console.log('session: acp control unavailable');
+        }
+    }
+});
 cOpt(program.command('rm <name>').description('stop + delete state dir (+ its fleet.d file if spawned)'))
     .action(async (name, opts) => {
     try {
@@ -179,14 +311,18 @@ cOpt(program.command('rm <name>').description('stop + delete state dir (+ its fl
     }
 });
 cOpt(program.command('spawn <name>').description('spawn a new agent (permanent by default)'))
-    .option('--temp', 'temporary: plain tmux, auto-cleaned, gone on reboot')
+    .option('--temp', 'temporary: detached supervisor, auto-cleaned, gone on reboot')
     .option('--harness <id>', 'harness adapter (default: defaults.harness)')
+    .option('--session <backend>', 'session backend: tmux|acp (default: defaults.session or tmux)')
     .option('--mission <text>', 'one-line mission')
     .option('--identity <name>', 'ours identity to bind (default: role name)')
     .option('--cwd <dir>', 'working directory')
     .option('--coordinator <name>', 'announce target')
     .option('--model <id>', 'model id to launch on (e.g. claude-fable-5); default: launcher default')
     .option('--permission-mode <mode>', 'harness permission mode (Codex: untrusted|on-request|never; Claude: native values)')
+    .option('--approval <mode>', 'common approval intent: ask|allow|deny')
+    .option('--filesystem <mode>', 'common filesystem intent: read-only|workspace|unrestricted')
+    .option('--unattended <mode>', 'permission behavior without a console: deny|wait')
     .option('--sandbox <mode>', 'Codex sandbox: read-only|workspace-write|danger-full-access')
     .option('--profile <name>', 'Codex profile file name ($CODEX_HOME/<name>.config.toml)')
     .option('--launcher <mode>', 'Codex launcher: auto|ours-codex|codex (default: auto)')
@@ -199,10 +335,12 @@ cOpt(program.command('spawn <name>').description('spawn a new agent (permanent b
     .action(async (name, opts) => {
     try {
         const o = {
-            name, temp: opts.temp, harness: opts.harness, mission: opts.mission,
+            name, temp: opts.temp, harness: opts.harness, session: opts.session, mission: opts.mission,
             identity: opts.identity, cwd: opts.cwd, coordinator: opts.coordinator,
             model: opts.model,
-            permissionMode: opts.permissionMode, sandbox: opts.sandbox, profile: opts.profile,
+            permissionMode: opts.permissionMode, approval: opts.approval,
+            filesystem: opts.filesystem, unattended: opts.unattended,
+            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,

package/dist/config.d.ts

@@ -7,6 +7,24 @@ 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 SessionBackendId = 'tmux' | 'acp';
+export type ApprovalMode = 'ask' | 'allow' | 'deny';
+export type FilesystemMode = 'read-only' | 'workspace' | 'unrestricted';
+export type UnattendedMode = 'deny' | 'wait';
+export interface CommonPermissions {
+    approval: ApprovalMode;
+    filesystem: FilesystemMode;
+    unattended: UnattendedMode;
+}
+export interface SessionOptions {
+    acp?: {
+        /** ACP agent command and arguments. Defaults are supplied by the harness adapter. */
+        command?: string | string[];
+    };
+    tmux?: {
+        boot_grace_ms?: number;
+    };
+}
 /** Resolved per-role supervisor-monitor config (see DESIGN-external-monitor §2). */
 export interface MonitorConfig {
     enabled: boolean;
@@ -27,6 +45,9 @@ export declare const DEFAULT_WAKE_SOURCES: NotifyEventType[];
 export declare function validateMonitorConfig(raw: unknown): string[];
 export interface RoleConfig {
     harness?: string;
+    session?: SessionBackendId;
+    session_options?: SessionOptions;
+    permissions?: Partial<CommonPermissions>;
     identity?: string;
     cwd?: string;
     coordinator?: string;
@@ -46,6 +67,8 @@ export interface RoleConfig {
 export interface ResolvedRole extends RoleConfig {
     name: string;
     harness: string;
+    session: SessionBackendId;
+    permissions: CommonPermissions;
     identity: string;
     sourceFile: string;
     monitor: MonitorConfig;
@@ -62,6 +85,7 @@ 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;
+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`

package/dist/config.js

@@ -51,7 +51,7 @@ export class ConfigError extends Error {
 }
 const NAME_RE = /^[A-Za-z0-9_-]+$/;
 const ROLE_KEYS = [
-    'harness', 'identity', 'cwd', 'coordinator', 'mission', 'persona', 'bio',
+    'harness', 'session', 'session_options', 'permissions', 'identity', 'cwd', 'coordinator', 'mission', 'persona', 'bio',
     'briefing_file', 'model', 'max_tokens', 'autocompact_pct', 'env', 'oversee', 'harness_options',
     'isolation', 'monitor',
 ];
@@ -107,6 +107,9 @@ export function loadConfig(configPath) {
             if (bad.length)
                 throw new ConfigError(`${file}: role '${name}' has unknown key(s) ${bad.join(', ')}; allowed: ${ROLE_KEYS.join(', ')}`);
             const isolation = r.isolation ?? defaults.isolation;
+            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 defaultHarnessOptions = defaults.harness_options;
             if (defaultHarnessOptions !== undefined
                 && (typeof defaultHarnessOptions !== 'object' || defaultHarnessOptions === null
@@ -129,6 +132,9 @@ export function loadConfig(configPath) {
                 name,
                 sourceFile: file,
                 harness: r.harness ?? defaults.harness ?? 'claude-code',
+                session,
+                session_options: sessionOptions,
+                permissions,
                 identity: r.identity ?? name,
                 model: r.model ?? defaults.model,
                 max_tokens: r.max_tokens ?? defaults.max_tokens,
@@ -140,6 +146,78 @@ export function loadConfig(configPath) {
     }
     return { roles, vars, defaults, files, startStaggerMs };
 }
+function resolveSession(raw, file, name) {
+    const value = raw ?? 'tmux';
+    if (value !== 'tmux' && value !== 'acp')
+        throw new ConfigError(`${file}: role '${name}' session: must be one of: tmux, acp`);
+    return value;
+}
+function resolveSessionOptions(defaults, role, session, file, name) {
+    if (defaults !== undefined && !isPlainObject(defaults))
+        throw new ConfigError(`${file}: defaults.session_options must be a map`);
+    if (role !== undefined && !isPlainObject(role))
+        throw new ConfigError(`${file}: role '${name}' session_options must be a map`);
+    const merged = {
+        ...(defaults ?? {}),
+        ...(role ?? {}),
+        acp: {
+            ...((defaults?.acp) ?? {}),
+            ...(role?.acp ?? {}),
+        },
+        tmux: {
+            ...((defaults?.tmux) ?? {}),
+            ...(role?.tmux ?? {}),
+        },
+    };
+    const bad = Object.keys(merged).filter(k => k !== 'acp' && k !== 'tmux');
+    if (bad.length)
+        throw new ConfigError(`${file}: role '${name}' session_options: unknown key(s) ${bad.join(', ')}`);
+    if (!isPlainObject(merged.acp) || !isPlainObject(merged.tmux))
+        throw new ConfigError(`${file}: role '${name}' session_options.${session} must be a map`);
+    const acpBad = Object.keys(merged.acp).filter(k => k !== 'command');
+    const tmuxBad = Object.keys(merged.tmux).filter(k => k !== 'boot_grace_ms');
+    if (acpBad.length)
+        throw new ConfigError(`${file}: role '${name}' session_options.acp: unknown key(s) ${acpBad.join(', ')}`);
+    if (tmuxBad.length)
+        throw new ConfigError(`${file}: role '${name}' session_options.tmux: unknown key(s) ${tmuxBad.join(', ')}`);
+    const command = merged.acp.command;
+    if (command !== undefined
+        && !(typeof command === 'string' && command.trim())
+        && !(Array.isArray(command) && command.length > 0
+            && command.every(v => typeof v === 'string' && v.length > 0)))
+        throw new ConfigError(`${file}: role '${name}' session_options.acp.command must be a non-empty string or string list`);
+    const grace = merged.tmux.boot_grace_ms;
+    if (grace !== undefined
+        && (typeof grace !== 'number' || !Number.isFinite(grace) || grace < 0))
+        throw new ConfigError(`${file}: role '${name}' session_options.tmux.boot_grace_ms must be a non-negative number`);
+    return Object.keys(merged.acp).length || Object.keys(merged.tmux).length ? merged : undefined;
+}
+export function resolvePermissions(defaults, role, file = 'config', name = 'role') {
+    if (defaults !== undefined && !isPlainObject(defaults))
+        throw new ConfigError(`${file}: defaults.permissions must be a map`);
+    if (role !== undefined && !isPlainObject(role))
+        throw new ConfigError(`${file}: role '${name}' permissions must be a map`);
+    const merged = {
+        ...(defaults ?? {}),
+        ...(role ?? {}),
+    };
+    const allowed = ['approval', 'filesystem', 'unattended'];
+    const bad = Object.keys(merged).filter(k => !allowed.includes(k));
+    if (bad.length)
+        throw new ConfigError(`${file}: role '${name}' permissions: unknown key(s) ${bad.join(', ')}`);
+    if (merged.approval !== undefined && !['ask', 'allow', 'deny'].includes(merged.approval))
+        throw new ConfigError(`${file}: role '${name}' permissions.approval must be one of: ask, allow, deny`);
+    if (merged.filesystem !== undefined
+        && !['read-only', 'workspace', 'unrestricted'].includes(merged.filesystem))
+        throw new ConfigError(`${file}: role '${name}' permissions.filesystem must be one of: read-only, workspace, unrestricted`);
+    if (merged.unattended !== undefined && !['deny', 'wait'].includes(merged.unattended))
+        throw new ConfigError(`${file}: role '${name}' permissions.unattended must be one of: deny, wait`);
+    return {
+        approval: merged.approval ?? 'ask',
+        filesystem: merged.filesystem ?? 'workspace',
+        unattended: merged.unattended ?? 'deny',
+    };
+}
 /** Validate the top-level `start_stagger_ms` (supervisor launch spacing); default 0. */
 function resolveStartStaggerMs(raw, base) {
     if (raw === undefined || raw === null)

package/dist/docs.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Stable, AI-friendly CLI and configuration reference.
+ *
+ * Keep this concise enough to place directly in an agent context. Unlike
+ * Commander's per-command help, this describes how the pieces compose.
+ */
+export declare const AI_DOCS = "# ours-fleet reference\n\nours-fleet runs persistent or temporary, identity-bound AI roles. A role selects\na harness independently from its session backend:\n\n- harness: `claude-code` or `codex`\n- session: `tmux` (default) or `acp`\n- lifetime: permanent (supervised, restartable) or `spawn --temp`\n\n## Discover and validate\n\n```sh\nours-fleet docs                         # this complete reference (`man` is an alias)\nours-fleet help <command>               # exact flags for one command\nours-fleet config [-c FILE]             # validate and print the merged plan; no changes\nours-fleet doctor [-c FILE] [--harness codex|claude-code]\n```\n\nDefault configuration is `~/fleet.yaml` plus sorted `~/fleet.d/*.yaml` role\ndrop-ins. An explicit `-c FILE` replaces `~/fleet.yaml`; fleet.d still adds\nroles. Validate with `config` and `doctor` before starting or restarting.\n\n## Lifecycle and console commands\n\n```sh\nours-fleet init\nours-fleet up|down [Name...]\nours-fleet restart [Name...]            # preserve/resume harness context\nours-fleet force-restart [Name...]      # fresh context; briefing is reloaded\nours-fleet ls\nours-fleet status|peek|attach|logs Name\nours-fleet logs -f Name\nours-fleet send Name \"prompt\"\nours-fleet send Name --key Enter        # tmux only\nours-fleet rm Name\n```\n\n`peek`, `attach`, and text `send` work with tmux and ACP. ACP attachment\nalso accepts `/permit <permission-id> <option-id>`, `/interrupt`, and\n`/detach`. Raw `--key` input is tmux-only.\n\n## Spawn\n\n```sh\nours-fleet spawn [--temp] Name \\\n  --harness codex|claude-code --session tmux|acp \\\n  --mission \"one line\" --cwd /absolute/path --identity Identity \\\n  --coordinator Coordinator --model MODEL \\\n  --approval ask|allow|deny \\\n  --filesystem read-only|workspace|unrestricted \\\n  --unattended deny|wait \\\n  --bio-file /path/bio.md --persona-file /path/persona.md\n```\n\nPermanent spawn writes `~/fleet.d/Name.yaml` and starts a supervised role.\n`--temp` writes ephemeral state, starts a detached supervisor, and removes the\nrole after exit/reboot. Both lifetimes support `--session acp`.\n\nCodex-specific spawn flags: `--sandbox`, `--permission-mode`, `--launcher`,\n`--profile`, `--search`, repeatable `--codex-config key=value`, repeatable\n`--add-dir`, and `--monitor`. Run `ours-fleet help spawn` for exact values.\n\n## fleet.yaml\n\n```yaml\nvars:\n  work_root: /home/me/work\nstart_stagger_ms: 0\ndefaults:\n  harness: codex\n  session: acp\n  model: gpt-model-id\n  permissions:\n    approval: ask\n    filesystem: workspace\n    unattended: deny\n  monitor:\n    enabled: true\nroles:\n  Coordinator:\n    harness: codex\n    session: acp\n    identity: Coordinator\n    cwd: ${work_root}/project\n    mission: Coordinate work and delegate implementation.\n    model: gpt-model-id\n    permissions:\n      approval: ask\n      filesystem: workspace\n      unattended: deny\n    session_options:                    # advanced overrides; normally omit\n      # acp:\n      #   command: [/custom/codex-acp, --flag]\n      tmux:\n        boot_grace_ms: 10000\n    monitor:\n      enabled: true\n      wake_sources: [message_received, file_received, local_contact_request, pending_message]\n      batch_ms: 2000\n      inject: notification\n      turn_fail_threshold: 3\n    harness_options:\n      launcher: auto\n      sandbox: workspace-write\n      approval: on-request\n      search: false\n      profile: fleet\n      add_dirs: [/data/shared]\n      config:\n        model_reasoning_effort: high\n    bio: Public role card and when peers should engage it.\n    persona: Local operating contract, boundaries, and escalation policy.\n    briefing_file: /absolute/custom-briefing.md\n    coordinator: AnotherCoordinator\n    env:\n      KEY: value\n    oversee:\n      - { role: Worker, interval: 5m }\n```\n\nRole values override defaults. `${name}` substitutes entries from `vars`.\nOther role fields include `max_tokens`, `autocompact_pct`, and `isolation`.\nUse README.md for the complete isolation policy and resource-cap schema.\n\n## Permissions\n\nPrefer the harness-neutral `permissions` block:\n\n- `approval: ask|allow|deny`: whether actions may request or receive approval\n- `filesystem: read-only|workspace|unrestricted`: filesystem intent\n- `unattended: deny|wait`: what ACP does when no console can answer a request\n\nThe backend translates this common intent. Harness-native settings in\n`harness_options` take precedence where supplied. Do not choose\n`allow`/`unrestricted`, Codex `never`/`danger-full-access`, or Claude\n`bypassPermissions` without explicit authorization.\n\nClaude `harness_options`: `permission_mode` (default, acceptEdits, plan,\ndontAsk, bypassPermissions), `plugins`, `mem_palace`, and\n`mem_palace_midsession_autosave`.\n\nCodex `harness_options`: `launcher` (auto, ours-codex, codex), `sandbox`\n(read-only, workspace-write, danger-full-access), `approval` or\n`permission_mode` (untrusted, on-request, never), `profile`, `search`,\n`config`, `add_dirs`, and `monitor`.\n\n## ACP adapters\n\nThe maintained `@agentclientprotocol/codex-acp` and\n`@agentclientprotocol/claude-agent-acp` runtimes are bundled automatically as\noptional ours-fleet dependencies. The supervisor resolves their executable\nentrypoints internally, so default ACP roles do not depend on global PATH.\nThe maintained Claude adapter requires Node 22; tmux and Codex ACP continue to\nwork on the ours-fleet core minimum of Node 20.\n\nOverride an adapter only when necessary with `session_options.acp.command`\n(string or argv list). If optional dependencies were deliberately omitted,\nours-fleet falls back to a compatible globally installed `codex-acp` or\n`claude-agent-acp`. `ours-fleet doctor -c FILE` verifies the resolved adapter.\n\n## Reliable mail wake\n\nThe supervisor monitor is enabled by default. It consumes body-free daemon\nevents and advances its durable cursor only after delivery is accepted. ACP uses\na structured `session/prompt`; tmux uses verified console injection. Message\nbodies are released only when the role calls the ours `get_messages` tool.\n\nSet `monitor.enabled: false` only to retain legacy in-session monitoring.\nInspect `ours-fleet status Name`, `peek Name`, role logs, and\n`~/.ours-fleet/agents/Name/.monitor-status` when diagnosing delivery.\n";