@ours.network/fleet 0.9.4 → 0.9.7

package/dist/cli.js

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

package/dist/config.d.ts

@@ -1,4 +1,4 @@
-import type { IsolationConfig } from './isolation/types.js';
+import type { IsolationConfig, WrapContext } from './isolation/types.js';
 export interface OverseeEntry {
     role: string;
     interval: string;
@@ -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,15 @@ export interface RoleConfig {
 export interface ResolvedRole extends RoleConfig {
     name: string;
     harness: string;
+    session: SessionBackendId;
+    permissions: CommonPermissions;
+    /**
+     * Whether `permissions:` was actually written by the operator (on the role or
+     * in defaults), as opposed to resolved from built-in defaults. A role that
+     * states its intent only once — neutrally OR natively — has nothing to
+     * contradict, and must not be warned at (2.4).
+     */
+    permissionsDeclared: boolean;
     identity: string;
     sourceFile: string;
     monitor: MonitorConfig;
@@ -60,8 +90,16 @@ export interface FleetConfig {
 }
 export declare class ConfigError extends Error {
 }
+/**
+ * The runtime facts the isolation resolver needs for a role. Single-sourced so
+ * config validation, doctor, and the runner all judge the SAME mount set — a
+ * policy checked against a different context than the one that launches is not
+ * a check at all.
+ */
+export declare function isolationContextFor(role: ResolvedRole): WrapContext;
 /** Load ~/fleet.yaml (or an explicit path) merged with ~/fleet.d/*.yaml drop-ins. */
 export declare function loadConfig(configPath?: string): FleetConfig;
+export declare function resolvePermissions(defaults: unknown, role: Partial<CommonPermissions> | undefined, file?: string, name?: string): CommonPermissions;
 /**
  * Merge `defaults.monitor` under the role's own `monitor:` key-by-key, validate the
  * result, and fill code-constant defaults (design §2). `defaults.monitor.enabled`

package/dist/config.js

@@ -1,8 +1,9 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { parse } from 'yaml';
-import { defaultConfigPath, fleetDDir } from './paths.js';
-import { validateIsolationConfig } from './isolation/policy.js';
+import { agentDir, defaultConfigPath, fleetDDir, home } from './paths.js';
+import { harnessRuntimeDir, resolveIsolation, validateIsolationConfig, } from './isolation/policy.js';
+import { getAdapter } from './harness/registry.js';
 /** The 8 content-free event types the ours daemon appends to notifications.log. */
 export const NOTIFY_EVENT_TYPES = [
     'message_received', 'file_received', 'sibling_contact_added', 'local_contact_request',
@@ -49,9 +50,40 @@ export function validateMonitorConfig(raw) {
 }
 export class ConfigError extends Error {
 }
+/**
+ * The runtime facts the isolation resolver needs for a role. Single-sourced so
+ * config validation, doctor, and the runner all judge the SAME mount set — a
+ * policy checked against a different context than the one that launches is not
+ * a check at all.
+ */
+export function isolationContextFor(role) {
+    const stateDir = agentDir(role.name, role.__temp === true);
+    const runCwd = role.cwd ?? stateDir;
+    // Ask the harness how its host state splits (5.1). An adapter that declares
+    // none keeps the historical whole-home mount.
+    let split;
+    try {
+        split = getAdapter(role.harness).isolationPaths?.(role, { stateDir, runCwd });
+    }
+    catch {
+        split = undefined;
+    }
+    return {
+        stateDir,
+        runCwd,
+        home: home(),
+        harness: role.harness,
+        additionalWriteDirs: role.harness === 'codex'
+            ? (role.harness_options?.add_dirs ?? [])
+            : [],
+        harnessHome: split?.home,
+        harnessRuntimeDir: split?.home ? harnessRuntimeDir(stateDir, role.harness) : undefined,
+        harnessSharedPaths: split?.shared,
+    };
+}
 const NAME_RE = /^[A-Za-z0-9_-]+$/;
 const ROLE_KEYS = [
-    'harness', '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 +139,10 @@ 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 permissionsDeclared = r.permissions !== undefined || defaults.permissions !== undefined;
             const defaultHarnessOptions = defaults.harness_options;
             if (defaultHarnessOptions !== undefined
                 && (typeof defaultHarnessOptions !== 'object' || defaultHarnessOptions === null
@@ -129,6 +165,10 @@ export function loadConfig(configPath) {
                 name,
                 sourceFile: file,
                 harness: r.harness ?? defaults.harness ?? 'claude-code',
+                session,
+                session_options: sessionOptions,
+                permissions,
+                permissionsDeclared,
                 identity: r.identity ?? name,
                 model: r.model ?? defaults.model,
                 max_tokens: r.max_tokens ?? defaults.max_tokens,
@@ -136,10 +176,93 @@ export function loadConfig(configPath) {
                 isolation,
                 monitor,
             });
+            // Forbidden-path enforcement (5.2): a mount that would breach the policy
+            // is a configuration error, caught by `config` rather than at launch.
+            if (isolation !== undefined) {
+                const role = roles[roles.length - 1];
+                try {
+                    resolveIsolation(isolation, isolationContextFor(role));
+                }
+                catch (e) {
+                    throw new ConfigError(`${file}: role '${name}' ${e.message}`);
+                }
+            }
         }
     }
     return { roles, vars, defaults, files, startStaggerMs };
 }
+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)