@ours.network/fleet 0.9.4 → 0.10.0-nightly.2

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` |
+| an ACP adapter | roles using `session: acp` | `codex-acp` or `claude-agent-acp` |
 | 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` |
 
@@ -112,7 +116,7 @@ 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
 ```
 
@@ -165,7 +169,7 @@ 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 +187,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 +199,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 +249,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,22 +278,27 @@ 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`. 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 — the agent drains it on the next wake or at SessionStart). The agent's
+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:

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,7 @@ 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 { 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
@@ -40,6 +43,40 @@ const program = new Command()
     .version(VERSION);
 const cOpt = (cmd) => cmd.option('-c, --configuration <file>', 'config file (default: ~/fleet.yaml + ~/fleet.d/)');
 const collect = (value, previous) => [...previous, value];
+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 +104,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 +171,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 +255,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 +282,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 {
@@ -181,12 +308,16 @@ 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('--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 +330,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/doctor.js

@@ -43,11 +43,14 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
         name: 'node', ok: major >= 20,
         detail: major >= 20 ? `v${process.versions.node}` : `v${process.versions.node} — need >= 20`,
     });
-    const tmux = await exec('tmux', ['-V']);
-    checks.push({
-        name: 'tmux', ok: tmux.code === 0,
-        detail: tmux.code === 0 ? tmux.stdout.trim() : 'not found — apt install tmux / brew install tmux',
-    });
+    const roles = loadConfigSafe(opts.configPath);
+    if (roles.length === 0 || roles.some(role => (role.session ?? 'tmux') === 'tmux')) {
+        const tmux = await exec('tmux', ['-V']);
+        checks.push({
+            name: 'tmux', ok: tmux.code === 0,
+            detail: tmux.code === 0 ? tmux.stdout.trim() : 'not found — apt install tmux / brew install tmux',
+        });
+    }
     const mcp = await exec('ours-mcp', ['--version']);
     checks.push({
         name: 'ours-mcp', ok: mcp.code === 0,
@@ -84,7 +87,6 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
     // opt-in per role (OQ-1), so a missing bwrap must not fail doctor for fleets that
     // don't use it. Only a role that DECLARES isolation and cannot get it under
     // `strict` is a hard failure.
-    const roles = loadConfigSafe(opts.configPath);
     const bw = await makeBubblewrapBackend(exec).available();
     checks.push({
         name: 'isolation: bubblewrap', ok: true,
@@ -169,6 +171,33 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
             checks.push({ name: h, ok: false, detail: e.message });
         }
     }
+    for (const role of roles.filter(role => role.session === 'acp')) {
+        const configured = role.session_options?.acp?.command;
+        const command = Array.isArray(configured)
+            ? configured[0]
+            : typeof configured === 'string'
+                ? configured.trim().split(/\s+/)[0]
+                : role.harness === 'codex'
+                    ? 'codex-acp'
+                    : role.harness === 'claude-code'
+                        ? 'claude-agent-acp'
+                        : '';
+        if (!command) {
+            checks.push({
+                name: `acp: ${role.name}`, ok: false,
+                detail: `harness '${role.harness}' has no default ACP agent; set session_options.acp.command`,
+            });
+            continue;
+        }
+        const result = await exec('sh', ['-c', 'command -v "$1" >/dev/null 2>&1', 'sh', command]);
+        checks.push({
+            name: `acp: ${role.name}`,
+            ok: result.code === 0,
+            detail: result.code === 0
+                ? `${command} available`
+                : `${command} not found or failed — install the ACP adapter or set session_options.acp.command`,
+        });
+    }
     return { ok: checks.every(c => c.ok), checks };
 }
 function loadConfigSafe(configPath) {

package/dist/harness/claude-code.js

@@ -9,8 +9,13 @@ const PERMISSION_MODES = ['default', 'acceptEdits', 'plan', 'dontAsk', 'bypassPe
 /** Resolve & validate the per-role permission mode, throwing on an unknown value. */
 function permissionMode(role) {
     const pm = role.harness_options?.permission_mode;
-    if (pm == null)
+    if (pm == null) {
+        if (role.permissions?.approval === 'allow')
+            return 'dontAsk';
+        if (role.permissions?.approval === 'deny')
+            return 'plan';
         return undefined;
+    }
     if (!PERMISSION_MODES.includes(pm))
         throw new Error(`invalid harness_options.permission_mode "${pm}"; allowed: ${PERMISSION_MODES.join(', ')}`);
     return pm;
@@ -108,6 +113,30 @@ export function makeClaudeCodeAdapter(exec = realExec) {
                     this.vocabulary.restartPrompt(role.identity, join(stateDir, 'WORKLOG.md'), role)];
             return { argv, env: prep.env };
         },
+        buildAcpLaunch(role, prep) {
+            const configured = role.session_options?.acp?.command;
+            const argv = Array.isArray(configured)
+                ? [...configured]
+                : typeof configured === 'string'
+                    ? ['sh', '-c', configured]
+                    : ['claude-agent-acp'];
+            return { argv, env: prep.env };
+        },
+        translatePermissions(permissions) {
+            const native = permissions.approval === 'allow'
+                ? 'dontAsk'
+                : permissions.approval === 'deny'
+                    ? 'plan'
+                    : 'default';
+            const exact = permissions.filesystem === 'workspace' && permissions.approval === 'ask';
+            return {
+                native: { permission_mode: native },
+                exact,
+                warnings: exact ? [] : [
+                    'Claude permission modes do not exactly represent independent approval and filesystem intent; fleet isolation remains the outer boundary',
+                ],
+            };
+        },
         vocabulary: {
             bindTool: 'choose_identity',
             createTool: 'create_identity',