@ours.network/fleet 0.9.4 → 0.9.7

package/dist/harness/claude-code.js

@@ -1,16 +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)
-        return undefined;
+        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;
@@ -27,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
@@ -73,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 ?? {}) };
@@ -88,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');
@@ -108,6 +198,48 @@ export function makeClaudeCodeAdapter(exec = realExec) {
                     this.vocabulary.restartPrompt(role.identity, join(stateDir, 'WORKLOG.md'), role)];
             return { argv, env: prep.env };
         },
+        buildAcpLaunch(role, prep) {
+            const configured = role.session_options?.acp?.command;
+            const argv = Array.isArray(configured)
+                ? [...configured]
+                : typeof configured === 'string'
+                    ? ['sh', '-c', configured]
+                    : 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 = 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: {
             bindTool: 'choose_identity',
             createTool: 'create_identity',

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,10 @@
+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',
     'monitor',
@@ -11,11 +14,32 @@ 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;
-    if (s == null)
+    if (s == null) {
+        const filesystem = role.permissions?.filesystem;
+        if (filesystem === 'read-only')
+            return 'read-only';
+        if (filesystem === 'unrestricted')
+            return 'danger-full-access';
+        if (filesystem === 'workspace')
+            return 'workspace-write';
         return undefined;
+    }
     if (!SANDBOX_MODES.includes(s))
         throw new Error(`invalid harness_options.sandbox "${s}"; allowed: ${SANDBOX_MODES.join(', ')}`);
     return s;
@@ -24,8 +48,14 @@ function sandboxMode(role) {
 function approvalPolicy(role) {
     const o = role.harness_options;
     const a = o?.approval ?? o?.permission_mode;
-    if (a == null)
+    if (a == null) {
+        const approval = role.permissions?.approval;
+        if (approval === 'allow')
+            return 'never';
+        if (approval === 'ask' || approval === 'deny')
+            return 'on-request';
         return undefined;
+    }
     if (!APPROVAL_POLICIES.includes(a))
         throw new Error(`invalid harness_options.approval "${a}"; allowed: ${APPROVAL_POLICIES.join(', ')}`);
     return a;
@@ -155,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)
@@ -173,6 +208,56 @@ export function makeCodexAdapter(exec = realExec) {
                     this.vocabulary.restartPrompt(role.identity, join(stateDir, 'WORKLOG.md'), role)];
             return { argv, env: prep.env };
         },
+        buildAcpLaunch(role, prep) {
+            const configured = role.session_options?.acp?.command;
+            const argv = Array.isArray(configured)
+                ? [...configured]
+                : typeof configured === 'string'
+                    ? ['sh', '-c', configured]
+                    : 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 {
+                supported: true,
+                native: { approval, sandbox },
+                exact: true,
+                warnings: [],
+                capabilities: codexCapabilities(approval, sandbox),
+            };
+        },
         vocabulary: {
             bindTool: 'choose_identity',
             createTool: 'create_identity',

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[];

package/dist/harness/registry.js

@@ -1,5 +1,14 @@
 const adapters = new Map();
 export function registerAdapter(a) {
+    // Enforced here rather than left to the type system: an adapter that silently
+    // omits the capability is how the neutral-permission warnings ended up with no
+    // caller and no reader.
+    if (typeof a.translatePermissions !== 'function')
+        throw new Error(`harness adapter '${a.id}' must implement translatePermissions(): either translate ` +
+            `neutral permissions or return { supported: false, reason }`);
+    if (typeof a.nativePermissionOverrides !== 'function')
+        throw new Error(`harness adapter '${a.id}' must implement nativePermissionOverrides(): report the ` +
+            `native permission settings a role states in harness_options, or {}`);
     adapters.set(a.id, a);
 }
 export function getAdapter(id) {
@@ -11,3 +20,13 @@ export function getAdapter(id) {
 export function knownAdapters() {
     return [...adapters.keys()];
 }
+/**
+ * The adapters ours-fleet ships. Tests register extras, so "everything in the
+ * registry" is not the same question — this is the set doctor falls back to
+ * when a broken configuration names no harness at all.
+ */
+const PRODUCTION_ADAPTERS = ['claude-code', 'codex'];
+/** Production adapters actually registered in this process. */
+export function productionAdapters() {
+    return PRODUCTION_ADAPTERS.filter(id => adapters.has(id));
+}

package/dist/harness/types.d.ts

@@ -1,4 +1,4 @@
-import type { ResolvedRole } from '../config.js';
+import type { CommonPermissions, ResolvedRole } from '../config.js';
 export interface PrereqCheck {
     name: string;
     ok: boolean;
@@ -26,6 +26,36 @@ export interface Launch {
     argv: string[];
     env: Record<string, string>;
 }
+export interface AcpLaunch {
+    argv: string[];
+    env: Record<string, string>;
+}
+/**
+ * The result of expressing neutral `permissions:` in a harness's own terms.
+ *
+ * `supported: false` is a first-class answer, not an absence. The previous
+ * shape made `translatePermissions` optional, so an adapter that simply never
+ * implemented it was indistinguishable from one that had nothing to say — and
+ * the warnings the implementations DID produce had no caller at all.
+ */
+/**
+ * What an unattended agent must actually be able to DO to run its own briefing.
+ * A role that cannot meet this floor does not fail loudly — it silently does
+ * less than it was asked to, because the denial happens inside the harness with
+ * nobody to see it.
+ */
+export type UnattendedCapability = 'read-state' | 'write-state' | 'messaging' | 'monitor' | 'workspace-edit' | 'status-commands';
+export type PermissionTranslation = {
+    supported: true;
+    native: Record<string, unknown>;
+    exact: boolean;
+    warnings: string[];
+    /** What the native settings above actually permit, unattended. */
+    capabilities: UnattendedCapability[];
+} | {
+    supported: false;
+    reason: string;
+};
 /** Harness-correct wording/tool names used to generate briefing.md. */
 export interface BriefingVocab {
     bindTool: string;
@@ -42,6 +72,16 @@ export interface BriefingVocab {
     launchNote(name: string): string;
     restartPrompt(identity: string, worklogPath: string, role?: ResolvedRole): string;
 }
+/**
+ * How a harness's host state splits for sandboxing (5.1). `home` is the
+ * directory the CLI treats as its own and whose RUNTIME state must be per-role;
+ * `shared` are the credential, instruction and configuration paths that stay
+ * shared and become read-only inside the sandbox.
+ */
+export interface HarnessIsolationPaths {
+    home?: string;
+    shared: string[];
+}
 export interface ExitPolicy {
     cleanExitIsFresh: boolean;
     fastFailSecs: number;
@@ -57,6 +97,24 @@ export interface HarnessAdapter {
     validateOptions(opts: unknown): ValidationError[];
     prepareSession(role: ResolvedRole, dirs: RoleDirs): Promise<SessionPrep>;
     buildLaunch(role: ResolvedRole, mode: 'fresh' | 'resume', s: SessionState, prep: SessionPrep): Launch;
+    buildAcpLaunch?(role: ResolvedRole, prep: SessionPrep): AcpLaunch;
+    /**
+     * REQUIRED. Every adapter must either translate neutral permissions or
+     * explicitly declare that it cannot. Enforced at registration.
+     */
+    translatePermissions(permissions: CommonPermissions): PermissionTranslation;
+    /**
+     * The permission settings this role states NATIVELY in `harness_options`,
+     * keyed the same way `translatePermissions().native` is, so the two can be
+     * compared directly. Only keys the operator actually wrote appear.
+     */
+    nativePermissionOverrides(options: unknown): Record<string, unknown>;
+    /**
+     * Host paths this harness needs inside a sandbox, split into a per-role
+     * writable home and shared read-only credentials/config (5.1). Omit for a
+     * harness with no host state of its own.
+     */
+    isolationPaths?(role: ResolvedRole, dirs: RoleDirs): HarnessIsolationPaths;
     vocabulary: BriefingVocab;
     exitPolicy: ExitPolicy;
 }

package/dist/index.d.ts

@@ -1,6 +1,9 @@
-export { loadConfig, findRole, ConfigError } from './config.js';
-export type { FleetConfig, ResolvedRole, RoleConfig, OverseeEntry } from './config.js';
-export type { HarnessAdapter, BriefingVocab, ExitPolicy, PrereqReport, PrereqCheck, SessionPrep, SessionState, Launch, RoleDirs, ValidationError, } from './harness/types.js';
+export { loadConfig, findRole, resolvePermissions, ConfigError } from './config.js';
+export type { FleetConfig, ResolvedRole, RoleConfig, OverseeEntry, SessionBackendId, CommonPermissions, SessionOptions, } from './config.js';
+export type { HarnessAdapter, BriefingVocab, ExitPolicy, PrereqReport, PrereqCheck, SessionPrep, SessionState, Launch, AcpLaunch, PermissionTranslation, RoleDirs, ValidationError, } from './harness/types.js';
+export type { SessionHandle, SessionSnapshot, SessionEvent, TurnResult, } from './session/types.js';
+export { AcpSession } from './session/acp.js';
+export { TmuxSession } from './session/tmux.js';
 export { registerAdapter, getAdapter, knownAdapters } from './harness/registry.js';
 export { claudeCodeAdapter, makeClaudeCodeAdapter } from './harness/claude-code.js';
 export { codexAdapter, makeCodexAdapter } from './harness/codex.js';

package/dist/index.js

@@ -1,4 +1,6 @@
-export { loadConfig, findRole, ConfigError } from './config.js';
+export { loadConfig, findRole, resolvePermissions, ConfigError } from './config.js';
+export { AcpSession } from './session/acp.js';
+export { TmuxSession } from './session/tmux.js';
 export { registerAdapter, getAdapter, knownAdapters } from './harness/registry.js';
 export { claudeCodeAdapter, makeClaudeCodeAdapter } from './harness/claude-code.js';
 export { codexAdapter, makeCodexAdapter } from './harness/codex.js';

package/dist/isolation/bubblewrap.js

@@ -8,7 +8,13 @@ import { realExec } from '../exec.js';
 export function unsharesNet(network) {
     return network === 'deny';
 }
-/** Build the `bwrap … -- <argv>` sandbox launcher argv. Pure — no I/O. */
+/**
+ * Build the `bwrap … -- <argv>` sandbox launcher argv. Pure — no I/O.
+ *
+ * Consumes an ALREADY-ENFORCED mount set: `resolveIsolation` has refused
+ * anything that breaches the forbidden-path list, so no forbidden path can
+ * reach this argv. This function must never add a mount of its own.
+ */
 function wrap(argv, policy, ctx) {
     const out = [
         'bwrap',

package/dist/isolation/policy.d.ts

@@ -1,17 +1,46 @@
 import { type IsolationConfig, type ResolvedIsolation, type WrapContext } from './types.js';
+/** A mount that the forbidden-path policy refuses. Raised before any launch. */
+export declare class IsolationPolicyError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolve a path to its canonical form, following symlinks as far as the
+ * filesystem allows and normalising the rest. Without this, `~/link-to-ssh`
+ * and `/home/u/.ssh` are different strings for the same directory, and a
+ * string comparison against the forbidden list is trivially side-stepped.
+ */
+export declare function canonicalPath(p: string): string;
+/**
+ * How a canonical mount path collides with a canonical forbidden path.
+ *
+ * `parent` matters as much as the other two: binding `$HOME` does not name
+ * `~/.ssh`, but it exposes it just as completely.
+ */
+export declare function mountConflict(mount: string, forbidden: string): 'exact' | 'descendant' | 'parent' | null;
 /**
  * Validate a raw `isolation:` block. Returns a list of human-readable problems
  * (empty ⇒ valid). Pure; callable from config.ts like adapter.validateOptions.
  */
 export declare function validateIsolationConfig(raw: unknown): string[];
+/**
+ * Where a role's per-role harness runtime state lives (5.1). Under the agent's
+ * own state directory, so it is covered by the state dir's existing lifecycle
+ * and by the forbidden-path exception, and is never shared with a peer.
+ */
+export declare const harnessRuntimeDir: (stateDir: string, harnessId: string) => string;
 /**
  * Resolve a raw (already validated) isolation block against runtime context into
- * a defaults-filled, backend-agnostic policy. Pure — no I/O, no probing.
+ * a defaults-filled, backend-agnostic policy, and REFUSE any mount that would
+ * breach the forbidden-path list.
+ *
+ * The mount model is an allowlist: only the durable set (state dir, cwd, harness
+ * config, declared fs/secrets) plus read-only system dirs are exposed. The
+ * forbidden list — the ours key store, sibling agent state dirs, ~/.ssh, ~/.aws
+ * — is now enforced on top of that, so a role cannot ask its way back in.
  *
- * The mount model is an allowlist: only the durable set (state dir, cwd, Claude
- * config, declared fs/secrets) plus read-only system dirs are exposed; everything
- * else on the host — the ours key store, sibling agent state dirs, ~/.ssh, ~/.aws —
- * is simply never mounted, and thus absent inside the sandbox (§5.2).
+ * Not pure: canonicalising a path reads the filesystem, because symlink aliases
+ * are one of the ways a forbidden path gets requested. Throws
+ * `IsolationPolicyError`; callers surface it against the role.
  */
 export declare function resolveIsolation(cfg: IsolationConfig, ctx: WrapContext): ResolvedIsolation;
 export type { IsolationConfig };