@ours.network/fleet 0.9.5 → 0.9.7

package/dist/docs.js

@@ -141,6 +141,89 @@ The backend translates this common intent. Harness-native settings in
 \`allow\`/\`unrestricted\`, Codex \`never\`/\`danger-full-access\`, or Claude
 \`bypassPermissions\` without explicit authorization.
 
+### Creation-time isolation
+
+\`ours-fleet spawn --isolation-file <path>\` supplies a role's sandbox policy at
+creation, so the FIRST launch is already confined — a role that only gains
+\`isolation:\` on a later \`up\` ran unsandboxed until then.
+
+The file holds exactly the \`isolation:\` mapping documented above and nothing
+else — the same schema, validated by the same code, so a policy written here
+cannot mean something different from the identical block in fleet.yaml:
+
+\`\`\`yaml
+network: deny
+fs:
+  read: [/opt/reference]
+resources:
+  mem: 2G
+\`\`\`
+
+Invalid files are rejected before anything is created: no config, no state
+directory, no identity reservation. Works for both permanent and \`--temp\` roles.
+
+### Never-prompt failure
+
+The failure this section exists to prevent leaves no error message anywhere.
+
+An unattended role has no console. When the harness needs a permission decision
+there is nobody to ask, so the request is refused INSIDE the harness — no
+prompt, no error, no log line. The agent simply does less than its briefing told
+it to, reports success, and nothing distinguishes that from having done the
+work. Two settings produce it:
+
+1. a permission mode that suppresses the prompt without granting the action
+   (Claude \`dontAsk\`, which is why neutral \`allow\` maps to
+   \`bypassPermissions\` instead); and
+2. \`unattended: deny\`, which refuses every request that reaches it.
+
+**Automatic decisions are now recorded.** Every permission request decided
+without a human emits a completed event into
+\`~/.ours-fleet/agents/<Name>/.session-events.jsonl\` carrying the decision,
+whether policy or a person made it, the policy that produced it
+(\`permissions.unattended=deny\` vs \`permissions.approval=deny\`/\`=allow\`),
+the reason, and the option selected. \`ours-fleet peek\` and \`attach\` render
+them. Automatic denial asks for a one-shot rejection, never a standing one, so a
+single unattended refusal cannot disable a tool for the rest of the session.
+
+A role that can auto-deny logs one line at startup saying so.
+
+To detect an under-permissioned role BEFORE it runs, use the capability floor
+below: \`ours-fleet doctor\` fails such a role rather than letting it discover
+the problem silently at work.
+
+### The unattended capability floor
+
+An unattended role has no console, so a permission request cannot be answered —
+it is refused, silently, inside the harness. The agent then does less than it
+was told to and reports no error. To make that visible before launch,
+\`ours-fleet config\` and \`ours-fleet doctor\` resolve each role's neutral
+permissions through its harness and check the result against a fixed floor:
+
+- \`read-state\` — read its briefing, ROUTINES.md, and WORKLOG.md
+- \`write-state\` — append its WORKLOG and its own state files
+- \`messaging\` — bind its identity, send and receive ours mail
+- \`monitor\` — arm and observe its mail monitor
+- \`workspace-edit\` — edit and test files in its working directory
+- \`status-commands\` — run the inspection commands its briefing prescribes
+
+\`doctor\` reports this per role as \`unattended floor: <Role>\`. A role with
+\`unattended: deny\` that cannot meet the floor FAILS doctor, because it will
+deny those requests with nobody to see it; with \`unattended: wait\` it warns,
+because a human can still attach and answer.
+
+Security meaning: \`approval: allow\` maps to Claude's \`bypassPermissions\`,
+which genuinely permits the actions the role was authorized to take —
+\`dontAsk\` only suppresses the prompt while still refusing the action. Nothing
+other than an explicit \`allow\` is elevated: \`ask\` stays on Claude's default
+mode and \`deny\` maps to \`plan\`. \`allow\` is therefore a real grant and
+requires explicit authorization; per-role \`isolation:\` remains the outer
+boundary that a permission mode cannot cross.
+
+See also: \`spawn --approval/--filesystem/--unattended\` set this intent at
+creation, and \`ours-fleet config\` prints each role's neutral settings, their
+native translation, and any warning — the same text \`doctor\` reports.
+
 Claude \`harness_options\`: \`permission_mode\` (default, acceptEdits, plan,
 dontAsk, bypassPermissions), \`plugins\`, \`mem_palace\`, and
 \`mem_palace_midsession_autosave\`.
@@ -175,3 +258,52 @@ Set \`monitor.enabled: false\` only to retain legacy in-session monitoring.
 Inspect \`ours-fleet status Name\`, \`peek Name\`, role logs, and
 \`~/.ours-fleet/agents/Name/.monitor-status\` when diagnosing delivery.
 `;
+/**
+ * What every shipped spawn-skill variant must say, and must not say (7.1).
+ *
+ * The skills are separate markdown files in two published plugins, written for
+ * two different harnesses, so they cannot literally be one file. This is the
+ * source of truth they are all written from, and a test holds each variant to
+ * it — including the CLI reference above, so a skill and \`ours-fleet docs\`
+ * cannot name different permission settings.
+ *
+ * \`forbidden\` is the more important half. The old skills prescribed
+ * \`--approval ask --filesystem workspace --unattended deny\` as a blanket
+ * default while also telling the agent to stop at a failed doctor check — and
+ * that combination is exactly what \`doctor\` FAILS, because \`ask\` grants an
+ * unattended role nothing but \`read-state\` and \`deny\` makes the shortfall
+ * fatal. Following the skill produced a role the CLI then refused.
+ */
+export const SPAWN_SKILL_CONTRACT = {
+    /** Substrings every variant must contain (whitespace-normalised). */
+    required: [
+        // The installed reference is authoritative and must actually be read.
+        'ours-fleet docs',
+        'ours-fleet doctor',
+        // Trap 1: a mode that suppresses the prompt without granting the action.
+        'dontAsk',
+        'bypassPermissions',
+        // Trap 2: the floor, and the command that reports it before launch.
+        'unattended capability floor',
+        'unattended floor:',
+        // The only intent that clears the floor, and the honest alternative.
+        '--approval allow',
+        '--unattended wait',
+        // Creation-time isolation (6.3) — the one new operator input this release adds.
+        '--isolation-file',
+    ],
+    /**
+     * Substrings no variant may contain. Deliberately short: the real guard is
+     * the acceptance test, which runs every spawn command a variant prints
+     * through the same analysis `doctor` uses and fails if doctor would fail it.
+     * This list only pins the specific claim that was wrong.
+     */
+    forbidden: [
+        // The contradictory blanket default both variants used to prescribe.
+        // `ask` grants an unattended role only `read-state`, and `deny` makes the
+        // shortfall a doctor FAILURE — so the skill told you to build a role the
+        // CLI then refused, in the same breath as telling you to trust doctor.
+        '--approval ask --filesystem workspace --unattended deny',
+        '[TODO:',
+    ],
+};

package/dist/doctor.js

@@ -1,10 +1,11 @@
 import { userInfo } from 'node:os';
 import { readFileSync } from 'node:fs';
 import { realExec } from './exec.js';
-import { loadConfig } from './config.js';
-import { getAdapter } from './harness/registry.js';
+import { isolationContextFor, loadConfig } from './config.js';
+import { getAdapter, productionAdapters } from './harness/registry.js';
+import { analyzeFleetPermissions, formatNative } from './permissions.js';
 import { resolveBundledAcpAgent } from './harness/acp-agent.js';
-import { agentDir, home, deriveXdgRuntimeDir } from './paths.js';
+import { deriveXdgRuntimeDir } from './paths.js';
 import { resolveIsolation } from './isolation/policy.js';
 import { makeBubblewrapBackend } from './isolation/bubblewrap.js';
 import { authResolutionHint, resolveEndpoint, } from './monitor.js';
@@ -44,7 +45,17 @@ 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 roles = loadConfigSafe(opts.configPath);
+    // The configuration is a checked prerequisite in its own right. A config the
+    // `config` command rejects must fail here too, with the same cause — while the
+    // host checks below still run, because they are what the operator needs next.
+    const loaded = loadConfigResult(opts.configPath);
+    const roles = loaded.ok ? loaded.roles : [];
+    checks.push(loaded.ok
+        ? { name: 'config', ok: true, detail: loaded.files.join(' + ') || '(none — no fleet.yaml or fleet.d)' }
+        : { name: 'config', ok: false, detail: loaded.error });
+    checks.push(loaded.ok
+        ? { name: 'roles', ok: true, detail: `${roles.length} configured` }
+        : { name: 'roles', ok: false, detail: 'unknown — the configuration did not load' });
     if (roles.length === 0 || roles.some(role => (role.session ?? 'tmux') === 'tmux')) {
         const tmux = await exec('tmux', ['-V']);
         checks.push({
@@ -84,6 +95,45 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
                 : `no XDG_RUNTIME_DIR and /run/user/<uid> missing — systemctl --user cannot reach the user manager; enable linger: sudo loginctl enable-linger ${user}`,
         });
     }
+    // Per-role permission translation (2.3). Rendered from the same analysis the
+    // `config` command prints, so the two commands cannot disagree.
+    for (const analysis of analyzeFleetPermissions(roles)) {
+        if (!analysis.supported) {
+            checks.push({
+                name: `permissions: ${analysis.role}`, ok: false,
+                detail: analysis.warnings.join('; '),
+            });
+            continue;
+        }
+        const p = analysis.permissions;
+        const summary = `approval=${p.approval} filesystem=${p.filesystem} unattended=${p.unattended}`
+            + ` -> ${formatNative(analysis.native)}`;
+        checks.push({
+            name: `permissions: ${analysis.role}`, ok: true,
+            detail: analysis.warnings.length
+                ? `${summary} — ${analysis.warnings.join('; ')}`
+                : `${summary} (exact)`,
+        });
+        // A role that states its permission intent twice, in two disagreeing places
+        // (2.4). Quiet when there is a single source of intent.
+        for (const conflict of analysis.conflicts ?? [])
+            checks.push({
+                name: `permission conflict: ${analysis.role}`, ok: true, detail: conflict.warning,
+            });
+        // The floor is checked BEFORE start (2.1): an under-permissioned unattended
+        // role never reports its own failure, because the denial happens inside the
+        // harness with nobody attached to see it.
+        const floor = analysis.floor;
+        checks.push({
+            name: `unattended floor: ${analysis.role}`,
+            ok: floor.meets || analysis.floorSeverity !== 'fail',
+            detail: floor.meets
+                ? `grants ${analysis.capabilities.join(', ')}`
+                : `MISSING ${floor.missing.join(', ')} — with unattended=${p.unattended} these requests will `
+                    + `${p.unattended === 'deny' ? 'be denied silently' : 'block the turn'}; `
+                    + `grants only ${analysis.capabilities.join(', ') || '(nothing)'}`,
+        });
+    }
     // Isolation reporting (AC-9). Backend availability is advisory — isolation is
     // 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
@@ -98,13 +148,15 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
     if (platform === 'linux')
         checks.push({ name: 'isolation: cgroup delegation', ok: true, detail: cgroupDelegationDetail() });
     for (const r of roles.filter(r => r.isolation)) {
-        const stateDir = agentDir(r.name);
-        const policy = resolveIsolation(r.isolation, {
-            stateDir, runCwd: r.cwd ?? stateDir, home: home(), harness: r.harness,
-            additionalWriteDirs: r.harness === 'codex'
-                ? (r.harness_options?.add_dirs ?? [])
-                : [],
-        });
+        // A refused mount is a launch-blocking policy error (5.2), not a warning.
+        let policy;
+        try {
+            policy = resolveIsolation(r.isolation, isolationContextFor(r));
+        }
+        catch (e) {
+            checks.push({ name: `isolation: ${r.name}`, ok: false, detail: e.message });
+            continue;
+        }
         const caps = [
             policy.resources.mem && `mem=${policy.resources.mem}`,
             policy.resources.cpu && `cpu=${policy.resources.cpu}`,
@@ -160,9 +212,14 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
         }
         checks.push({ name: checkName, ok, detail });
     }
+    // A broken config resolves no roles and therefore no harnesses. Without a
+    // fallback the AI CLI prerequisites would simply vanish from the report at
+    // exactly the moment the operator is trying to work out what is wrong.
     const harnesses = opts.harness
         ? [opts.harness]
-        : [...new Set(roles.map(r => r.harness))];
+        : loaded.ok
+            ? [...new Set(roles.map(r => r.harness))]
+            : productionAdapters();
     for (const h of harnesses) {
         try {
             const rep = await getAdapter(h).checkPrereqs();
@@ -215,11 +272,12 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
     }
     return { ok: checks.every(c => c.ok), checks };
 }
-function loadConfigSafe(configPath) {
+function loadConfigResult(configPath) {
     try {
-        return loadConfig(configPath).roles;
+        const cfg = loadConfig(configPath);
+        return { ok: true, roles: cfg.roles, files: cfg.files };
     }
-    catch {
-        return [];
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
     }
 }

package/dist/harness/claude-code.d.ts

@@ -1,8 +1,44 @@
 import { type Exec } from '../exec.js';
 import type { ResolvedRole } from '../config.js';
-import type { HarnessAdapter } from './types.js';
+import type { HarnessAdapter, UnattendedCapability } from './types.js';
+import { type LockDeps } from '../atomic-file.js';
+/**
+ * Neutral approval → native Claude mode. The ONE definition, shared by launch
+ * and by translation so the two can never disagree about what a role will run
+ * with.
+ *
+ * `allow` maps to `bypassPermissions`, not `dontAsk`. `dontAsk` suppresses the
+ * PROMPT, not the denial: an unattended role configured with the operator's
+ * explicit `approval: allow` was silently refused the actions it was told to
+ * take, with no prompt and no error to show for it. Only an explicit `allow`
+ * gets this; `ask` and `deny` are never elevated.
+ */
+export declare function nativePermissionMode(approval: ResolvedRole['permissions']['approval']): string | undefined;
+/**
+ * What an unattended role can actually do under a native mode. Derived from the
+ * NATIVE mode, so an operator's explicit `harness_options.permission_mode`
+ * override is judged on what it really grants.
+ */
+export declare function claudeCapabilities(mode: string | undefined, filesystem: ResolvedRole['permissions']['filesystem']): UnattendedCapability[];
 export declare function autocompactPct(role: ResolvedRole): number;
-/** Pre-trust a dir in ~/.claude.json so the first launch never blocks on the trust dialog. */
-export declare function pretrust(dir: string): void;
+/**
+ * Pre-trust a dir in ~/.claude.json so the first launch never blocks on the
+ * trust dialog.
+ *
+ * `~/.claude.json` is SHARED by every role and by the operator's own Claude
+ * Code. The previous read-modify-write held nothing while it worked, so two
+ * roles starting together interleaved and one silently lost its trust entry —
+ * and that role then blocked on the dialog it was supposed to be spared,
+ * unattended, with nobody to answer it. A crash mid-write truncated the file
+ * for everyone.
+ *
+ * Now: take a cross-process lock, re-read inside it, merge ONLY this project's
+ * entry so unrelated operator state survives untouched, and replace the file
+ * atomically. Never fatal — a role that cannot be pre-trusted still launches.
+ */
+export declare function pretrust(dir: string, deps?: {
+    log?(line: string): void;
+    lock?: LockDeps;
+}): Promise<void>;
 export declare function makeClaudeCodeAdapter(exec?: Exec): HarnessAdapter;
 export declare const claudeCodeAdapter: HarnessAdapter;

package/dist/harness/claude-code.js

@@ -1,22 +1,55 @@
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { home } from '../paths.js';
 import { realExec } from '../exec.js';
 import { registerAdapter } from './registry.js';
+import { replaceFileAtomically, withFileLock } from '../atomic-file.js';
+import { harnessRuntimeDir } from '../isolation/policy.js';
 import { bundledAcpAgent } from './acp-agent.js';
 const OPTION_KEYS = ['plugins', 'mem_palace', 'mem_palace_midsession_autosave', 'permission_mode'];
 /** Claude Code's accepted --permission-mode values. */
 const PERMISSION_MODES = ['default', 'acceptEdits', 'plan', 'dontAsk', 'bypassPermissions'];
+/**
+ * Neutral approval → native Claude mode. The ONE definition, shared by launch
+ * and by translation so the two can never disagree about what a role will run
+ * with.
+ *
+ * `allow` maps to `bypassPermissions`, not `dontAsk`. `dontAsk` suppresses the
+ * PROMPT, not the denial: an unattended role configured with the operator's
+ * explicit `approval: allow` was silently refused the actions it was told to
+ * take, with no prompt and no error to show for it. Only an explicit `allow`
+ * gets this; `ask` and `deny` are never elevated.
+ */
+export function nativePermissionMode(approval) {
+    switch (approval) {
+        case 'allow': return 'bypassPermissions';
+        case 'deny': return 'plan';
+        default: return undefined; // 'ask' → Claude's own default
+    }
+}
+/**
+ * What an unattended role can actually do under a native mode. Derived from the
+ * NATIVE mode, so an operator's explicit `harness_options.permission_mode`
+ * override is judged on what it really grants.
+ */
+export function claudeCapabilities(mode, filesystem) {
+    // `plan` may not act at all; `default` and `acceptEdits` still stop to ask,
+    // and with no console attached that request is refused rather than answered.
+    if (mode !== 'bypassPermissions' && mode !== 'dontAsk')
+        return ['read-state'];
+    // `dontAsk` reaches the tools but is refused the actions behind them.
+    if (mode === 'dontAsk')
+        return ['read-state', 'status-commands'];
+    const caps = ['read-state', 'messaging', 'monitor', 'status-commands'];
+    if (filesystem !== 'read-only')
+        caps.push('write-state', 'workspace-edit');
+    return caps;
+}
 /** 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 (role.permissions?.approval === 'allow')
-            return 'dontAsk';
-        if (role.permissions?.approval === 'deny')
-            return 'plan';
-        return undefined;
-    }
+    if (pm == null)
+        return nativePermissionMode(role.permissions?.approval);
     if (!PERMISSION_MODES.includes(pm))
         throw new Error(`invalid harness_options.permission_mode "${pm}"; allowed: ${PERMISSION_MODES.join(', ')}`);
     return pm;
@@ -33,16 +66,58 @@ export function autocompactPct(role) {
         return 50;
     return Math.max(1, Math.min(100, pct));
 }
-/** Pre-trust a dir in ~/.claude.json so the first launch never blocks on the trust dialog. */
-export function pretrust(dir) {
+/**
+ * Pre-trust a dir in ~/.claude.json so the first launch never blocks on the
+ * trust dialog.
+ *
+ * `~/.claude.json` is SHARED by every role and by the operator's own Claude
+ * Code. The previous read-modify-write held nothing while it worked, so two
+ * roles starting together interleaved and one silently lost its trust entry —
+ * and that role then blocked on the dialog it was supposed to be spared,
+ * unattended, with nobody to answer it. A crash mid-write truncated the file
+ * for everyone.
+ *
+ * Now: take a cross-process lock, re-read inside it, merge ONLY this project's
+ * entry so unrelated operator state survives untouched, and replace the file
+ * atomically. Never fatal — a role that cannot be pre-trusted still launches.
+ */
+export async function pretrust(dir, deps = {}) {
     const p = join(home(), '.claude.json');
-    const d = existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : {};
-    const projects = (d.projects ??= {});
-    const e = (projects[dir] ??= {});
-    e.hasTrustDialogAccepted = true;
-    e.hasCompletedProjectOnboarding = true;
-    e.projectOnboardingSeenCount = Math.max(e.projectOnboardingSeenCount ?? 0, 1);
-    writeFileSync(p, JSON.stringify(d, null, 2));
+    const log = deps.log ?? (() => { });
+    try {
+        await withFileLock(`${p}.lock`, () => {
+            let doc;
+            if (!existsSync(p))
+                doc = {};
+            else {
+                const raw = readFileSync(p, 'utf8');
+                try {
+                    doc = JSON.parse(raw);
+                }
+                catch (e) {
+                    // Someone else's file, and it is already broken. Overwriting it would
+                    // destroy operator state we cannot read; refusing to launch would take
+                    // the role down for a file it does not own.
+                    log(`pretrust: ${p} is not valid JSON (${e.message}) — skipping pre-trust; `
+                        + `the role may block on Claude's trust dialog until the file is repaired`);
+                    return;
+                }
+                if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) {
+                    log(`pretrust: ${p} does not contain a JSON object — skipping pre-trust`);
+                    return;
+                }
+            }
+            const projects = (doc.projects ??= {});
+            const e = (projects[dir] ??= {});
+            e.hasTrustDialogAccepted = true;
+            e.hasCompletedProjectOnboarding = true;
+            e.projectOnboardingSeenCount = Math.max(e.projectOnboardingSeenCount ?? 0, 1);
+            replaceFileAtomically(p, JSON.stringify(doc, null, 2));
+        }, deps.lock);
+    }
+    catch (e) {
+        log(`pretrust: could not update ${p} (${e.message}) — continuing without pre-trust`);
+    }
 }
 /**
  * Shared Monitor-arming mandate (issue #16). Single-sourced so the briefing and
@@ -79,9 +154,12 @@ export function makeClaudeCodeAdapter(exec = realExec) {
                 .map(k => ({ path: `harness_options.${k}`, message: `unknown option; allowed: ${OPTION_KEYS.join(', ')}` }));
         },
         async prepareSession(role, dirs) {
-            pretrust(dirs.stateDir);
+            // Pre-trust stays a HOST-side step: inside the sandbox ~/.claude.json is
+            // read-only, and it is the fleet's job to trust the role's dirs, not the
+            // agent's (5.1, 6.1).
+            await pretrust(dirs.stateDir);
             if (dirs.runCwd && dirs.runCwd !== dirs.stateDir)
-                pretrust(dirs.runCwd);
+                await pretrust(dirs.runCwd);
             const o = (role.harness_options ?? {});
             const memPalace = o.mem_palace !== false;
             const enabledPlugins = { ...(o.plugins ?? {}) };
@@ -94,6 +172,12 @@ export function makeClaudeCodeAdapter(exec = realExec) {
             };
             if (!memPalace)
                 env.MEMPALACE_DISABLED = 'true';
+            // Per-role harness runtime home (5.1). Created before sandbox entry so the
+            // bind has something to mount; harmless for un-isolated roles.
+            // Only a role that declares `isolation:` gets a sandbox, and only a
+            // sandbox needs this directory to exist before entry.
+            if (role.isolation)
+                mkdirSync(harnessRuntimeDir(dirs.stateDir, 'claude'), { recursive: true });
             const argv = [];
             if (Object.keys(enabledPlugins).length) {
                 const overlay = join(dirs.stateDir, '.settings-overlay.json');
@@ -123,19 +207,37 @@ export function makeClaudeCodeAdapter(exec = realExec) {
                     : bundledAcpAgent('@agentclientprotocol/claude-agent-acp', 'claude-agent-acp', 'claude-agent-acp');
             return { argv, env: prep.env };
         },
+        isolationPaths(_role, _dirs) {
+            const claudeHome = join(home(), '.claude');
+            return {
+                home: claudeHome,
+                // Credentials and project trust (~/.claude.json), the global
+                // instructions every role shares, and the shared settings. Everything
+                // else under ~/.claude — sessions, projects, caches, history — is
+                // runtime state and belongs to the role, not to the fleet.
+                shared: [
+                    join(home(), '.claude.json'),
+                    join(claudeHome, 'CLAUDE.md'),
+                    join(claudeHome, 'settings.json'),
+                    join(claudeHome, 'plugins'),
+                ],
+            };
+        },
+        nativePermissionOverrides(options) {
+            const pm = options?.permission_mode;
+            return pm == null ? {} : { permission_mode: pm };
+        },
         translatePermissions(permissions) {
-            const native = permissions.approval === 'allow'
-                ? 'dontAsk'
-                : permissions.approval === 'deny'
-                    ? 'plan'
-                    : 'default';
+            const native = nativePermissionMode(permissions.approval) ?? 'default';
             const exact = permissions.filesystem === 'workspace' && permissions.approval === 'ask';
             return {
+                supported: true,
                 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',
                 ],
+                capabilities: claudeCapabilities(native, permissions.filesystem),
             };
         },
         vocabulary: {

package/dist/harness/codex.d.ts

@@ -1,4 +1,10 @@
 import { type Exec } from '../exec.js';
-import type { HarnessAdapter } from './types.js';
+import type { HarnessAdapter, UnattendedCapability } from './types.js';
+/**
+ * What an unattended role can actually do under Codex's native settings.
+ * `on-request` and `untrusted` stop to ask, and with no console attached that
+ * request is refused rather than answered — so the role can only read.
+ */
+export declare function codexCapabilities(approval: string, sandbox: string): UnattendedCapability[];
 export declare function makeCodexAdapter(exec?: Exec): HarnessAdapter;
 export declare const codexAdapter: HarnessAdapter;

package/dist/harness/codex.js

@@ -1,7 +1,9 @@
+import { mkdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { agentDir } from '../paths.js';
+import { agentDir, home } from '../paths.js';
 import { realExec } from '../exec.js';
 import { registerAdapter } from './registry.js';
+import { harnessRuntimeDir } from '../isolation/policy.js';
 import { bundledAcpAgent } from './acp-agent.js';
 const OPTION_KEYS = [
     'launcher', 'sandbox', 'approval', 'permission_mode', 'search', 'profile', 'config', 'add_dirs',
@@ -12,6 +14,19 @@ const LAUNCHERS = ['auto', 'ours-codex', 'codex'];
 const SANDBOX_MODES = ['read-only', 'workspace-write', 'danger-full-access'];
 /** Codex CLI's accepted `--ask-for-approval` values. */
 const APPROVAL_POLICIES = ['untrusted', 'on-request', 'never'];
+/**
+ * What an unattended role can actually do under Codex's native settings.
+ * `on-request` and `untrusted` stop to ask, and with no console attached that
+ * request is refused rather than answered — so the role can only read.
+ */
+export function codexCapabilities(approval, sandbox) {
+    if (approval !== 'never')
+        return ['read-state'];
+    const caps = ['read-state', 'messaging', 'monitor', 'status-commands'];
+    if (sandbox !== 'read-only')
+        caps.push('write-state', 'workspace-edit');
+    return caps;
+}
 /** Resolve & validate the per-role sandbox mode, throwing on an unknown value. */
 function sandboxMode(role) {
     const s = role.harness_options?.sandbox;
@@ -170,7 +185,12 @@ export function makeCodexAdapter(exec = realExec) {
             }
             return errs;
         },
-        async prepareSession(role, _dirs) {
+        async prepareSession(role, dirs) {
+            // Per-role harness runtime home (5.1); harmless for un-isolated roles.
+            // Only a role that declares `isolation:` gets a sandbox, and only a
+            // sandbox needs this directory to exist before entry.
+            if (role.isolation)
+                mkdirSync(harnessRuntimeDir(dirs.stateDir, 'codex'), { recursive: true });
             const requested = launcherMode(role);
             const hasOursCodex = await commandAvailable('ours-codex', exec);
             if (requested === 'ours-codex' && !hasOursCodex)
@@ -197,18 +217,45 @@ export function makeCodexAdapter(exec = realExec) {
                     : bundledAcpAgent('@agentclientprotocol/codex-acp', 'codex-acp', 'codex-acp');
             return { argv, env: prep.env };
         },
+        isolationPaths(role, _dirs) {
+            const codexHome = join(home(), '.codex');
+            const profile = role.harness_options?.profile;
+            return {
+                home: codexHome,
+                // Credentials, shared config, shared instructions, and the role's own
+                // profile file if it names one. Sessions, history, caches and the local
+                // sqlite stores are runtime state and stay per-role.
+                shared: [
+                    join(codexHome, 'auth.json'),
+                    join(codexHome, 'config.toml'),
+                    join(codexHome, 'AGENTS.md'),
+                    join(codexHome, 'plugins'),
+                    ...(profile ? [join(codexHome, `${profile}.config.toml`)] : []),
+                    join(home(), '.agents'),
+                ],
+            };
+        },
+        nativePermissionOverrides(options) {
+            const o = options;
+            const approval = o?.approval ?? o?.permission_mode; // permission_mode is the alias
+            return {
+                ...(approval == null ? {} : { approval }),
+                ...(o?.sandbox == null ? {} : { sandbox: o.sandbox }),
+            };
+        },
         translatePermissions(permissions) {
+            const approval = permissions.approval === 'allow' ? 'never' : 'on-request';
+            const sandbox = permissions.filesystem === 'read-only'
+                ? 'read-only'
+                : permissions.filesystem === 'unrestricted'
+                    ? 'danger-full-access'
+                    : 'workspace-write';
             return {
-                native: {
-                    approval: permissions.approval === 'allow' ? 'never' : 'on-request',
-                    sandbox: permissions.filesystem === 'read-only'
-                        ? 'read-only'
-                        : permissions.filesystem === 'unrestricted'
-                            ? 'danger-full-access'
-                            : 'workspace-write',
-                },
+                supported: true,
+                native: { approval, sandbox },
                 exact: true,
                 warnings: [],
+                capabilities: codexCapabilities(approval, sandbox),
             };
         },
         vocabulary: {

package/dist/harness/registry.d.ts

@@ -2,3 +2,5 @@ import type { HarnessAdapter } from './types.js';
 export declare function registerAdapter(a: HarnessAdapter): void;
 export declare function getAdapter(id: string): HarnessAdapter;
 export declare function knownAdapters(): string[];
+/** Production adapters actually registered in this process. */
+export declare function productionAdapters(): string[];