@ours.network/fleet 0.9.4 → 0.9.7

package/dist/docs.js

@@ -0,0 +1,309 @@
+/**
+ * Stable, AI-friendly CLI and configuration reference.
+ *
+ * Keep this concise enough to place directly in an agent context. Unlike
+ * Commander's per-command help, this describes how the pieces compose.
+ */
+export const AI_DOCS = `# ours-fleet reference
+
+ours-fleet runs persistent or temporary, identity-bound AI roles. A role selects
+a harness independently from its session backend:
+
+- harness: \`claude-code\` or \`codex\`
+- session: \`tmux\` (default) or \`acp\`
+- lifetime: permanent (supervised, restartable) or \`spawn --temp\`
+
+## Discover and validate
+
+\`\`\`sh
+ours-fleet docs                         # this complete reference (\`man\` is an alias)
+ours-fleet help <command>               # exact flags for one command
+ours-fleet config [-c FILE]             # validate and print the merged plan; no changes
+ours-fleet doctor [-c FILE] [--harness codex|claude-code]
+\`\`\`
+
+Default configuration is \`~/fleet.yaml\` plus sorted \`~/fleet.d/*.yaml\` role
+drop-ins. An explicit \`-c FILE\` replaces \`~/fleet.yaml\`; fleet.d still adds
+roles. Validate with \`config\` and \`doctor\` before starting or restarting.
+
+## Lifecycle and console commands
+
+\`\`\`sh
+ours-fleet init
+ours-fleet up|down [Name...]
+ours-fleet restart [Name...]            # preserve/resume harness context
+ours-fleet force-restart [Name...]      # fresh context; briefing is reloaded
+ours-fleet ls
+ours-fleet status|peek|attach|logs Name
+ours-fleet logs -f Name
+ours-fleet send Name "prompt"
+ours-fleet send Name --key Enter        # tmux only
+ours-fleet rm Name
+\`\`\`
+
+\`peek\`, \`attach\`, and text \`send\` work with tmux and ACP. ACP attachment
+also accepts \`/permit <permission-id> <option-id>\`, \`/interrupt\`, and
+\`/detach\`. Raw \`--key\` input is tmux-only.
+
+## Spawn
+
+\`\`\`sh
+ours-fleet spawn [--temp] Name \\
+  --harness codex|claude-code --session tmux|acp \\
+  --mission "one line" --cwd /absolute/path --identity Identity \\
+  --coordinator Coordinator --model MODEL \\
+  --approval ask|allow|deny \\
+  --filesystem read-only|workspace|unrestricted \\
+  --unattended deny|wait \\
+  --bio-file /path/bio.md --persona-file /path/persona.md
+\`\`\`
+
+Permanent spawn writes \`~/fleet.d/Name.yaml\` and starts a supervised role.
+\`--temp\` writes ephemeral state, starts a detached supervisor, and removes the
+role after exit/reboot. Both lifetimes support \`--session acp\`.
+
+Codex-specific spawn flags: \`--sandbox\`, \`--permission-mode\`, \`--launcher\`,
+\`--profile\`, \`--search\`, repeatable \`--codex-config key=value\`, repeatable
+\`--add-dir\`, and \`--monitor\`. Run \`ours-fleet help spawn\` for exact values.
+
+## fleet.yaml
+
+\`\`\`yaml
+vars:
+  work_root: /home/me/work
+start_stagger_ms: 0
+defaults:
+  harness: codex
+  session: acp
+  model: gpt-model-id
+  permissions:
+    approval: ask
+    filesystem: workspace
+    unattended: deny
+  monitor:
+    enabled: true
+roles:
+  Coordinator:
+    harness: codex
+    session: acp
+    identity: Coordinator
+    cwd: \${work_root}/project
+    mission: Coordinate work and delegate implementation.
+    model: gpt-model-id
+    permissions:
+      approval: ask
+      filesystem: workspace
+      unattended: deny
+    session_options:                    # advanced overrides; normally omit
+      # acp:
+      #   command: [/custom/codex-acp, --flag]
+      tmux:
+        boot_grace_ms: 10000
+    monitor:
+      enabled: true
+      wake_sources: [message_received, file_received, local_contact_request, pending_message]
+      batch_ms: 2000
+      inject: notification
+      turn_fail_threshold: 3
+    harness_options:
+      launcher: auto
+      sandbox: workspace-write
+      approval: on-request
+      search: false
+      profile: fleet
+      add_dirs: [/data/shared]
+      config:
+        model_reasoning_effort: high
+    bio: Public role card and when peers should engage it.
+    persona: Local operating contract, boundaries, and escalation policy.
+    briefing_file: /absolute/custom-briefing.md
+    coordinator: AnotherCoordinator
+    env:
+      KEY: value
+    oversee:
+      - { role: Worker, interval: 5m }
+\`\`\`
+
+Role values override defaults. \`\${name}\` substitutes entries from \`vars\`.
+Other role fields include \`max_tokens\`, \`autocompact_pct\`, and \`isolation\`.
+Use README.md for the complete isolation policy and resource-cap schema.
+
+## Permissions
+
+Prefer the harness-neutral \`permissions\` block:
+
+- \`approval: ask|allow|deny\`: whether actions may request or receive approval
+- \`filesystem: read-only|workspace|unrestricted\`: filesystem intent
+- \`unattended: deny|wait\`: what ACP does when no console can answer a request
+
+The backend translates this common intent. Harness-native settings in
+\`harness_options\` take precedence where supplied. Do not choose
+\`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\`.
+
+Codex \`harness_options\`: \`launcher\` (auto, ours-codex, codex), \`sandbox\`
+(read-only, workspace-write, danger-full-access), \`approval\` or
+\`permission_mode\` (untrusted, on-request, never), \`profile\`, \`search\`,
+\`config\`, \`add_dirs\`, and \`monitor\`.
+
+## ACP adapters
+
+The maintained \`@agentclientprotocol/codex-acp\` and
+\`@agentclientprotocol/claude-agent-acp\` runtimes are bundled automatically as
+optional ours-fleet dependencies. The supervisor resolves their executable
+entrypoints internally, so default ACP roles do not depend on global PATH.
+The maintained Claude adapter requires Node 22; tmux and Codex ACP continue to
+work on the ours-fleet core minimum of Node 20.
+
+Override an adapter only when necessary with \`session_options.acp.command\`
+(string or argv list). If optional dependencies were deliberately omitted,
+ours-fleet falls back to a compatible globally installed \`codex-acp\` or
+\`claude-agent-acp\`. \`ours-fleet doctor -c FILE\` verifies the resolved adapter.
+
+## Reliable mail wake
+
+The supervisor monitor is enabled by default. It consumes body-free daemon
+events and advances its durable cursor only after delivery is accepted. ACP uses
+a structured \`session/prompt\`; tmux uses verified console injection. Message
+bodies are released only when the role calls the ours \`get_messages\` tool.
+
+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,9 +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 { agentDir, home, deriveXdgRuntimeDir } from './paths.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 { deriveXdgRuntimeDir } from './paths.js';
 import { resolveIsolation } from './isolation/policy.js';
 import { makeBubblewrapBackend } from './isolation/bubblewrap.js';
 import { authResolutionHint, resolveEndpoint, } from './monitor.js';
@@ -43,11 +45,24 @@ 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',
-    });
+    // 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({
+            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,
@@ -80,11 +95,49 @@ 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
     // `strict` is a hard failure.
-    const roles = loadConfigSafe(opts.configPath);
     const bw = await makeBubblewrapBackend(exec).available();
     checks.push({
         name: 'isolation: bubblewrap', ok: true,
@@ -95,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}`,
@@ -157,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();
@@ -169,13 +229,55 @@ 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 bundled = configured == null
+            ? role.harness === 'codex'
+                ? resolveBundledAcpAgent('@agentclientprotocol/codex-acp', 'codex-acp', 'codex-acp')
+                : role.harness === 'claude-code'
+                    ? resolveBundledAcpAgent('@agentclientprotocol/claude-agent-acp', 'claude-agent-acp', 'claude-agent-acp')
+                    : undefined
+            : undefined;
+        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;
+        }
+        if (bundled?.bundled) {
+            checks.push({
+                name: `acp: ${role.name}`, ok: true,
+                detail: `${command} bundled with ours-fleet`,
+            });
+            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) {
+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/acp-agent.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resolve an ACP agent shipped as an ours-fleet dependency. Running the JS
+ * entrypoint through this process's Node avoids depending on npm exposing a
+ * transitive dependency's bin on the user's global PATH.
+ */
+export interface AcpAgentResolution {
+    argv: string[];
+    bundled: boolean;
+}
+export declare function resolveBundledAcpAgent(packageName: string, binName: string, fallbackCommand: string): AcpAgentResolution;
+export declare function bundledAcpAgent(packageName: string, binName: string, fallbackCommand: string): string[];

package/dist/harness/acp-agent.js

@@ -0,0 +1,27 @@
+import { createRequire } from 'node:module';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+const require = createRequire(import.meta.url);
+export function resolveBundledAcpAgent(packageName, binName, fallbackCommand) {
+    try {
+        const manifestPath = require.resolve(`${packageName}/package.json`);
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        const relative = typeof manifest.bin === 'string'
+            ? manifest.bin
+            : manifest.bin?.[binName];
+        if (!relative)
+            return { argv: [fallbackCommand], bundled: false };
+        const entrypoint = resolve(dirname(manifestPath), relative);
+        if (!existsSync(entrypoint))
+            return { argv: [fallbackCommand], bundled: false };
+        return { argv: [process.execPath, entrypoint], bundled: true };
+    }
+    catch {
+        // Supports development installs that intentionally omit optional
+        // dependencies and existing hosts with a globally installed adapter.
+        return { argv: [fallbackCommand], bundled: false };
+    }
+}
+export function bundledAcpAgent(packageName, binName, fallbackCommand) {
+    return resolveBundledAcpAgent(packageName, binName, fallbackCommand).argv;
+}

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;