@ours.network/fleet 0.18.0-nightly.6 → 0.18.1

package/dist/harness/claude-code.js

@@ -6,8 +6,98 @@ 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', 'effort'];
+const OPTION_KEYS = [
+    'plugins', 'mem_palace', 'mem_palace_midsession_autosave', 'permission_mode', 'effort',
+    'mcp_servers', 'mcp_servers_only',
+];
 const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
+/** `.mcp.json` server types. Absent means stdio, as the file format has it. */
+const MCP_SERVER_TYPES = ['stdio', 'http', 'sse'];
+/** A role that names its own ACP command runs a process fleet did not choose. */
+const customAcpCommand = (role) => role.session === 'acp' && role.session_options?.acp?.command != null;
+/**
+ * Does this server set include the ours connector?
+ *
+ * Load-bearing, and the reason it is a check rather than a doc line:
+ * `mcp_servers_only` maps to `--strict-mcp-config`, which ignores EVERY other MCP
+ * configuration — project `.mcp.json`, user settings, and **plugins**. On a
+ * normal install the ours connector arrives as a plugin
+ * (`~/.claude/plugins/.../plugin.json` declares `ours`), so a role that turns
+ * strict mode on without re-declaring it loses `send_message` and `get_messages`
+ * and cannot report that it has: a mute agent looks exactly like a quiet one.
+ *
+ * Matched on the command line rather than the server's NAME, because the name is
+ * the operator's to choose and would make this trivially satisfiable by writing
+ * `ours:` above the wrong command.
+ */
+const declaresOursConnector = (servers) => Object.values(servers).some(s => [s.command ?? '', ...(s.args ?? [])].some(part => /(^|[/\\])ours-mcp($|\s)|@ours\.network[/\\]mcp/.test(part)));
+/** Shape-check `harness_options.mcp_servers` against `.mcp.json`'s own rules. */
+function validateMcpServers(servers) {
+    if (servers == null)
+        return [];
+    const at = (k = '') => ({ path: `harness_options.mcp_servers${k}` });
+    if (typeof servers !== 'object' || Array.isArray(servers))
+        return [{ ...at(), message: 'must be a map of server name to server definition' }];
+    const entries = Object.entries(servers);
+    if (!entries.length)
+        return [{ ...at(), message: 'must declare at least one server, or be omitted' }];
+    const errors = [];
+    for (const [name, raw] of entries) {
+        const p = `.${name}`;
+        if (!/^[A-Za-z0-9_-]+$/.test(name)) {
+            errors.push({ ...at(p), message: 'server name must be [A-Za-z0-9_-]' });
+            continue;
+        }
+        if (raw == null || typeof raw !== 'object' || Array.isArray(raw)) {
+            errors.push({ ...at(p), message: 'must be a map' });
+            continue;
+        }
+        const s = raw;
+        if (s.type != null && !MCP_SERVER_TYPES.includes(s.type))
+            errors.push({ ...at(`${p}.type`), message: `must be one of: ${MCP_SERVER_TYPES.join(', ')}` });
+        const remote = s.type === 'http' || s.type === 'sse';
+        if (remote) {
+            if (typeof s.url !== 'string' || !s.url.trim())
+                errors.push({ ...at(`${p}.url`), message: `must be a non-empty URL for a ${s.type} server` });
+            if (s.command != null)
+                errors.push({ ...at(`${p}.command`), message: `must not be set for a ${s.type} server` });
+        }
+        else {
+            if (typeof s.command !== 'string' || !s.command.trim())
+                errors.push({ ...at(`${p}.command`), message: 'must be a non-empty command for a stdio server' });
+            if (s.args != null && (!Array.isArray(s.args) || s.args.some(a => typeof a !== 'string')))
+                errors.push({ ...at(`${p}.args`), message: 'must be an array of strings' });
+            if (s.url != null)
+                errors.push({ ...at(`${p}.url`), message: 'must not be set for a stdio server' });
+        }
+        for (const key of ['env', 'headers']) {
+            const v = s[key];
+            if (v == null)
+                continue;
+            if (typeof v !== 'object' || Array.isArray(v)
+                || Object.values(v).some(x => typeof x !== 'string'))
+                errors.push({ ...at(`${p}.${key}`), message: 'must be a map of string to string' });
+        }
+    }
+    return errors;
+}
+/** `harness_options.mcp_servers` in ACP's `session/new` array shape. */
+function acpMcpServersFor(servers) {
+    if (!servers)
+        return [];
+    // `env` and `headers` are REQUIRED arrays in the protocol, so they are always
+    // sent — empty when the role declared none.
+    const pairs = (r) => Object.entries(r ?? {}).map(([name, value]) => ({ name, value }));
+    return Object.entries(servers).map(([name, s]) => {
+        if (s.type === 'http' || s.type === 'sse')
+            return { name, type: s.type, url: s.url, headers: pairs(s.headers) };
+        // Stdio carries NO `type` field: ACP's stdio variant is the one without it,
+        // and the bundled agent keys on exactly that (claude-agent-acp
+        // acp-agent.js:4058, `!("type" in server)`), so sending `type: 'stdio'`
+        // would drop the server on the floor.
+        return { name, command: s.command, args: s.args ?? [], env: pairs(s.env) };
+    });
+}
 /** Claude Code's accepted --permission-mode values. */
 const PERMISSION_MODES = ['default', 'acceptEdits', 'plan', 'dontAsk', 'bypassPermissions'];
 /**
@@ -127,11 +217,8 @@ export async function pretrust(dir, deps = {}) {
  * it must be the Monitor TOOL, not a background Bash task (which never wakes the
  * agent on output → an armed-looking but deaf monitor).
  */
-const shellQuote = (value) => `'${value.replace(/'/g, `'"'"'`)}'`;
-const watchCommand = (id) => 'ours api watch-notifications --input '
-    + shellQuote(JSON.stringify({ identity: id, since: 'tip' })) + ' --json';
 const armMonitor = (id) => 'arm a **persistent Monitor** (the Monitor TOOL — NOT a background Bash command; a ' +
-    `background Bash task never wakes you on output) running \`${watchCommand(id)}\` ` +
+    `background Bash task never wakes you on output) running \`ours-mcp watch "${id}"\` ` +
     'so inbound ours mail wakes you';
 export function makeClaudeCodeAdapter(exec = realExec) {
     return {
@@ -149,7 +236,7 @@ export function makeClaudeCodeAdapter(exec = realExec) {
                     }],
             };
         },
-        validateOptions(opts) {
+        validateOptions(opts, role) {
             if (opts == null)
                 return [];
             if (typeof opts !== 'object' || Array.isArray(opts))
@@ -157,9 +244,44 @@ export function makeClaudeCodeAdapter(exec = realExec) {
             const errors = Object.keys(opts)
                 .filter(k => !OPTION_KEYS.includes(k))
                 .map(k => ({ path: `harness_options.${k}`, message: `unknown option; allowed: ${OPTION_KEYS.join(', ')}` }));
-            const effort = opts.effort;
+            const o = opts;
+            const effort = o.effort;
             if (effort != null && !EFFORT_LEVELS.includes(effort))
                 errors.push({ path: 'harness_options.effort', message: `must be one of: ${EFFORT_LEVELS.join(', ')}` });
+            if (o.mcp_servers_only != null && typeof o.mcp_servers_only !== 'boolean')
+                errors.push({ path: 'harness_options.mcp_servers_only', message: 'must be a boolean' });
+            errors.push(...validateMcpServers(o.mcp_servers));
+            if (o.mcp_servers_only === true && !o.mcp_servers)
+                errors.push({
+                    path: 'harness_options.mcp_servers_only',
+                    message: 'requires harness_options.mcp_servers; on its own it would leave the role with no MCP servers at all',
+                });
+            // The muteness gate. Only when the declared set is otherwise well-formed —
+            // a shape error already told the operator to look here.
+            if (o.mcp_servers_only === true && o.mcp_servers && errors.length === 0
+                && !declaresOursConnector(o.mcp_servers))
+                errors.push({
+                    path: 'harness_options.mcp_servers',
+                    message: 'mcp_servers_only ignores every other MCP configuration, INCLUDING plugins — and the ours '
+                        + 'connector is normally a plugin, so this role would have no send_message or get_messages and no way '
+                        + 'to report that. Declare it explicitly, e.g. ours: { command: ours-mcp, args: [proxy] }',
+                });
+            // Session-aware refusals. Both options reach an ACP session through the
+            // bundled agent's `_meta` vocabulary, so a role that launches a DIFFERENT
+            // ACP agent cannot be promised either one. Refuse rather than send it and
+            // hope: silently dropping the config is the defect being fixed here.
+            if (role && customAcpCommand(role)) {
+                for (const key of ['plugins', 'mcp_servers', 'mcp_servers_only']) {
+                    if (o[key] == null)
+                        continue;
+                    errors.push({
+                        path: `harness_options.${key}`,
+                        message: 'cannot be honoured with session_options.acp.command: it is delivered through the bundled '
+                            + 'Claude ACP agent\'s _meta vocabulary, which another agent has no reason to read. Drop the '
+                            + 'custom ACP command, or drop this option',
+                    });
+                }
+            }
             return errors;
         },
         async prepareSession(role, dirs) {
@@ -178,6 +300,15 @@ export function makeClaudeCodeAdapter(exec = realExec) {
                 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: String(autocompactPct(role)),
                 MEMPALACE_HOOKS_AUTO_SAVE: 'false',
                 MEMPALACE_MIDSESSION_AUTOSAVE: o.mem_palace_midsession_autosave ? 'true' : 'false',
+                // The role's identity, for the ours connector to bind at startup instead of
+                // the briefing telling the MODEL to call choose_identity. Both launches
+                // return `prep.env`, so this one line covers tmux and ACP alike.
+                //
+                // The bind the connector performs is PLAIN and fail-closed: it can never
+                // evict a live session, and a role whose identity does not exist yet simply
+                // boots unbound and falls through to the briefing's create-if-missing step.
+                // Nothing here may ever grow a force flag.
+                OURS_BIND_IDENTITY: role.identity,
             };
             if (!memPalace)
                 env.MEMPALACE_DISABLED = 'true';
@@ -188,12 +319,29 @@ export function makeClaudeCodeAdapter(exec = realExec) {
             if (role.isolation)
                 mkdirSync(harnessRuntimeDir(dirs.stateDir, 'claude'), { recursive: true });
             const argv = [];
+            let settingsOverlay;
             if (Object.keys(enabledPlugins).length) {
-                const overlay = join(dirs.stateDir, '.settings-overlay.json');
-                writeFileSync(overlay, JSON.stringify({ enabledPlugins }, null, 2));
-                argv.push('--settings', overlay);
+                settingsOverlay = join(dirs.stateDir, '.settings-overlay.json');
+                writeFileSync(settingsOverlay, JSON.stringify({ enabledPlugins }, null, 2));
+                argv.push('--settings', settingsOverlay);
             }
-            return { argv, env };
+            // `harness_options.mcp_servers` — the tmux delivery. `--mcp-config` ADDS the
+            // file's servers; `--strict-mcp-config` is what makes the set exclusive, and
+            // it is opt-in per role because it drops everything else the user has,
+            // plugins included (see `declaresOursConnector`).
+            let mcpConfigFile;
+            if (o.mcp_servers) {
+                mcpConfigFile = join(dirs.stateDir, '.mcp-config.json');
+                writeFileSync(mcpConfigFile, JSON.stringify({ mcpServers: o.mcp_servers }, null, 2), { mode: 0o600 });
+                argv.push('--mcp-config', mcpConfigFile);
+                if (o.mcp_servers_only === true)
+                    argv.push('--strict-mcp-config');
+            }
+            return {
+                argv, env,
+                ...(settingsOverlay ? { settingsOverlay } : {}),
+                ...(mcpConfigFile ? { mcpConfigFile } : {}),
+            };
         },
         buildLaunch(role, mode, s, prep) {
             const stateDir = roleStateDir(role);
@@ -223,6 +371,46 @@ export function makeClaudeCodeAdapter(exec = realExec) {
         acpPermissionModeId(role) {
             return permissionMode(role);
         },
+        /**
+         * Deliver, over ACP, the two things the tmux launch delivers as flags.
+         *
+         * `buildAcpLaunch` builds its own argv and cannot carry `prep.argv`: the
+         * process it launches is the ACP agent, not `claude`, and it takes none of
+         * claude's flags. That is why `harness_options.plugins` did nothing at all on
+         * an ACP role — the overlay was written and then dropped, and the mem-palace
+         * toggle rode `prep.env` and survived, so the failure was silent AND
+         * selective.
+         *
+         * `_meta.claudeCode.options` is the bundled agent's own passthrough into the
+         * Claude Agent SDK (@agentclientprotocol/claude-agent-acp, acp-agent.js:4092
+         * → the `options` object at :4144). `settings` takes the same overlay path
+         * `--settings` takes; `strictMcpConfig` is the SDK's spelling of
+         * `--strict-mcp-config`. Both are spread BEFORE the fields the agent forces,
+         * so neither is overwritten.
+         *
+         * ⚠ RETURNS NOTHING FOR A ROLE THAT NAMES ITS OWN ACP COMMAND. That process
+         * is not the bundled agent and has no reason to read this vocabulary; sending
+         * it anyway would be the silent drop again, one level down. `validateOptions`
+         * refuses those roles instead.
+         */
+        acpSessionMeta(role, prep) {
+            if (customAcpCommand(role))
+                return undefined;
+            const options = {};
+            if (prep.settingsOverlay)
+                options.settings = prep.settingsOverlay;
+            if (role.harness_options?.mcp_servers_only === true)
+                options.strictMcpConfig = true;
+            return Object.keys(options).length ? { claudeCode: { options } } : undefined;
+        },
+        /**
+         * The declared servers, in ACP's array shape. Sent on `session/new` and on
+         * resume/load, because the SDK builds its server set once per session and a
+         * resumed session that dropped them would quietly lose its tools.
+         */
+        acpMcpServers(role) {
+            return acpMcpServersFor(role.harness_options?.mcp_servers);
+        },
         isolationPaths(_role, _dirs) {
             const claudeHome = join(home(), '.claude');
             return {
@@ -285,6 +473,7 @@ export function makeClaudeCodeAdapter(exec = realExec) {
             currentIdentityTool: 'current_identity',
             sendTool: 'send_message',
             getMessagesTool: 'get_messages',
+            watchCommand: id => `ours-mcp watch "${id}"`,
             monitorInstruction: id => {
                 const m = armMonitor(id);
                 return `${m.charAt(0).toUpperCase()}${m.slice(1)}.`;

package/dist/harness/codex.d.ts

@@ -1,10 +1,13 @@
 import { type Exec } from '../exec.js';
-import type { HarnessAdapter, UnattendedCapability } from './types.js';
+import type { AcpLaunch, HarnessAdapter, UnattendedCapability } from './types.js';
+import { type AcpAgentResolution } from './acp-agent.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[];
+/** Bind launch argv and metadata provenance to one already-completed resolution. */
+export declare function codexAcpLaunchForResolution(resolution: AcpAgentResolution): Pick<AcpLaunch, 'argv' | 'permissionMetadataSource'>;
 export declare function makeCodexAdapter(exec?: Exec): HarnessAdapter;
 export declare const codexAdapter: HarnessAdapter;

package/dist/harness/codex.js

@@ -5,7 +5,7 @@ import { agentDir, home } from '../paths.js';
 import { realExec } from '../exec.js';
 import { registerAdapter } from './registry.js';
 import { harnessRuntimeDir } from '../isolation/policy.js';
-import { bundledAcpAgent, resolveBundledAcpAgent } from './acp-agent.js';
+import { resolveBundledAcpAgent, } from './acp-agent.js';
 const OPTION_KEYS = [
     'launcher', 'sandbox', 'approval', 'permission_mode', 'search', 'profile', 'config', 'add_dirs',
     'monitor',
@@ -51,9 +51,7 @@ function sandboxMode(role) {
         throw new Error(`invalid harness_options.sandbox "${s}"; allowed: ${SANDBOX_MODES.join(', ')}`);
     return s;
 }
-/** codex-acp exposes the same sandbox postures as named ACP agent modes. */
-function acpAgentMode(role) {
-    const sandbox = sandboxMode(role);
+function modeForSandbox(sandbox) {
     if (sandbox === 'read-only')
         return 'read-only';
     if (sandbox === 'workspace-write')
@@ -62,6 +60,26 @@ function acpAgentMode(role) {
         return 'agent-full-access';
     return undefined;
 }
+/**
+ * Resolve the coupled Codex ACP mode.
+ *
+ * The portable approval contract owns the default mode selection: `allow`
+ * means the adapter's fully non-interactive yolo preset and `auto` means its
+ * ordinary agent preset. This intentionally means that Codex ACP cannot retain
+ * an independent neutral filesystem posture for those two modes. An explicit
+ * native sandbox remains authoritative and selects its corresponding preset.
+ */
+function acpAgentMode(role) {
+    const explicitSandbox = role.harness_options?.sandbox;
+    if (explicitSandbox != null)
+        return modeForSandbox(sandboxMode(role));
+    if (role.permissions?.approval === 'allow')
+        return 'agent-full-access';
+    if (role.permissions?.approval === 'auto')
+        return 'agent';
+    const sandbox = sandboxMode(role);
+    return modeForSandbox(sandbox);
+}
 function acpModePermissions(mode) {
     if (mode === 'read-only')
         return { approval: 'on-request', sandbox: 'read-only' };
@@ -69,6 +87,10 @@ function acpModePermissions(mode) {
         return { approval: 'never', sandbox: 'danger-full-access' };
     return { approval: 'on-request', sandbox: 'workspace-write' };
 }
+/** The sandbox Codex will actually receive from the selected coupled ACP mode. */
+function acpRuntimeSandbox(role) {
+    return acpModePermissions(acpAgentMode(role)).sandbox;
+}
 function fleetModeForApproval(nativeMode) {
     if (nativeMode === 'never')
         return 'allow';
@@ -102,6 +124,18 @@ function launcherMode(role) {
 function bundledCodexAcp() {
     return resolveBundledAcpAgent(CODEX_ACP_PACKAGE, 'codex-acp', 'codex-acp');
 }
+/** Bind launch argv and metadata provenance to one already-completed resolution. */
+export function codexAcpLaunchForResolution(resolution) {
+    const permissionMetadataSource = resolution.bundled
+        && resolution.version === BUNDLED_CODEX_ACP_VERSION
+        && resolution.manifestPath !== undefined
+        ? 'codex-acp'
+        : undefined;
+    return {
+        argv: [...resolution.argv],
+        ...(permissionMetadataSource ? { permissionMetadataSource } : {}),
+    };
+}
 function canOverrideBundledAcpApproval() {
     const resolution = bundledCodexAcp();
     return resolution.bundled && resolution.version === BUNDLED_CODEX_ACP_VERSION
@@ -147,7 +181,7 @@ function codexAcpEnvironment(role, dirs) {
     return {
         CODEX_PATH: command,
         [CODEX_PROXY_APPROVAL_ENV]: approvalPolicy(role) ?? 'on-request',
-        [CODEX_PROXY_SANDBOX_ENV]: sandboxMode(role) ?? 'workspace-write',
+        [CODEX_PROXY_SANDBOX_ENV]: acpRuntimeSandbox(role),
         [CODEX_PROXY_MANIFEST_ENV]: resolution.manifestPath,
         ...(process.env.CODEX_PATH ? { [CODEX_PROXY_REAL_PATH_ENV]: process.env.CODEX_PATH } : {}),
     };
@@ -285,7 +319,16 @@ export function makeCodexAdapter(exec = realExec) {
             if (requested === 'ours-codex' && !hasOursCodex)
                 throw new Error('harness_options.launcher is ours-codex, but ours-codex is not on PATH; install @ours.network/codex or use launcher: auto');
             const command = requested === 'codex' ? 'codex' : hasOursCodex ? 'ours-codex' : 'codex';
-            return { argv: [], env: codexAcpEnvironment(role, dirs), command };
+            return {
+                argv: [],
+                // OURS_BIND_IDENTITY is the connector's startup bind seed — see the note in
+                // claude-code.ts's prepareSession. It belongs on EVERY harness that runs a
+                // role with an ours identity, not just claude-code: a seed that works on one
+                // harness and silently does nothing on the other is the same class of defect
+                // as a config key that only works on one session type.
+                env: { OURS_BIND_IDENTITY: role.identity, ...codexAcpEnvironment(role, dirs) },
+                command,
+            };
         },
         buildLaunch(role, mode, _s, prep) {
             const stateDir = roleStateDir(role);
@@ -299,17 +342,30 @@ export function makeCodexAdapter(exec = realExec) {
         },
         buildAcpLaunch(role, prep) {
             const configured = role.session_options?.acp?.command;
+            // Resolve once: both argv and permission-metadata provenance must describe
+            // the same artifact. A bare PATH fallback is launchable for compatibility,
+            // but is never authenticated for protected-MCP auto-approval.
+            const resolved = configured == null
+                ? codexAcpLaunchForResolution(bundledCodexAcp())
+                : undefined;
             const argv = Array.isArray(configured)
                 ? [...configured]
                 : typeof configured === 'string'
                     ? ['sh', '-c', configured]
-                    : bundledAcpAgent(CODEX_ACP_PACKAGE, 'codex-acp', 'codex-acp');
+                    : resolved.argv;
             const initialMode = acpAgentMode(role);
             return {
                 argv,
                 env: initialMode ? { ...prep.env, INITIAL_AGENT_MODE: initialMode } : prep.env,
+                ...(resolved?.permissionMetadataSource
+                    ? { permissionMetadataSource: resolved.permissionMetadataSource } : {}),
             };
         },
+        // INITIAL_AGENT_MODE covers session/new in codex-acp; session/set_mode
+        // keeps resumed/loaded sessions and live status on the identical mode.
+        acpPermissionModeId(role) {
+            return acpAgentMode(role);
+        },
         isolationPaths(role, _dirs) {
             const codexHome = join(home(), '.codex');
             const profile = role.harness_options?.profile;
@@ -362,7 +418,9 @@ export function makeCodexAdapter(exec = realExec) {
                 const mode = acpAgentMode(role) ?? 'agent';
                 const configured = role.session_options?.acp?.command;
                 const overrideAvailable = configured == null && canOverrideBundledAcpApproval();
-                const actual = overrideAvailable ? { approval, sandbox } : acpModePermissions(mode);
+                const actual = overrideAvailable
+                    ? { approval, sandbox: acpRuntimeSandbox(role) }
+                    : acpModePermissions(mode);
                 const exact = actual.approval === approval && actual.sandbox === sandbox;
                 return {
                     ...translated,
@@ -372,10 +430,9 @@ export function makeCodexAdapter(exec = realExec) {
                             ? `custom ACP command cannot be verified against approval=${approval} sandbox=${sandbox}; `
                                 + `its '${mode}' mode is conservatively treated as approval=${actual.approval} `
                                 + `sandbox=${actual.sandbox}`
-                            : `codex-acp mode '${mode}' actually uses approval=${actual.approval} `
-                                + `sandbox=${actual.sandbox}, and the bundled ${BUNDLED_CODEX_ACP_VERSION} `
-                                + `app-server override is unavailable; this does not exactly represent `
-                                + `approval=${approval} sandbox=${sandbox}`],
+                            : `Codex ACP mode '${mode}' couples approval and filesystem as `
+                                + `approval=${actual.approval} sandbox=${actual.sandbox}; this does not exactly `
+                                + `represent approval=${approval} sandbox=${sandbox}`],
                     capabilities: codexCapabilities(actual.approval, actual.sandbox),
                 };
             }
@@ -411,6 +468,7 @@ export function makeCodexAdapter(exec = realExec) {
             currentIdentityTool: 'current_identity',
             sendTool: 'send_message',
             getMessagesTool: 'get_messages',
+            watchCommand: id => `ours-mcp watch "${id}"`,
             monitorInstruction: (id, configuredRole) => {
                 const consented = configuredRole?.harness_options?.monitor === true;
                 const consent = consented

package/dist/harness/types.d.ts

@@ -1,3 +1,4 @@
+import type { McpServer } from '@agentclientprotocol/sdk';
 import type { CommonPermissions, FleetPermissionMode, ResolvedRole } from '../config.js';
 export interface PrereqCheck {
     name: string;
@@ -21,14 +22,39 @@ export interface SessionPrep {
     env: Record<string, string>;
     /** Optional launcher selected after runtime prerequisite probing. */
     command?: string;
+    /**
+     * The settings overlay prepareSession wrote, if it wrote one.
+     *
+     * The tmux launch delivers this as `--settings <path>` in `argv`; an ACP agent
+     * takes no flags, so it needs the PATH rather than the flag. Recorded here so
+     * the two deliveries read one value instead of each re-deriving the filename.
+     */
+    settingsOverlay?: string;
+    /**
+     * The MCP config file prepareSession wrote for `harness_options.mcp_servers`,
+     * if the role declared any. Same reason as `settingsOverlay`: the tmux launch
+     * passes the file, the ACP launch has to send the servers themselves.
+     */
+    mcpConfigFile?: string;
 }
+/**
+ * One MCP server as ACP's `session/new` declares it.
+ *
+ * ⚠ THE PROTOCOL'S OWN TYPE, DELIBERATELY NOT A LOCAL RESTATEMENT. `mcpServers`
+ * goes onto the wire unchanged, so a hand-written near-copy would compile while
+ * being subtly wrong — `env` and `headers` are REQUIRED arrays, and the stdio
+ * variant is the one with no `type` field at all. Aliasing it also keeps
+ * `session/new`'s response type inferable, which a structural stand-in silently
+ * broke (every field of the result degraded to `unknown`).
+ */
+export type AcpMcpServer = McpServer;
 export interface Launch {
     argv: string[];
     env: Record<string, string>;
 }
-export interface AcpLaunch {
-    argv: string[];
-    env: Record<string, string>;
+export interface AcpLaunch extends Launch {
+    /** Metadata vocabulary authenticated by the exact ACP artifact in argv. */
+    permissionMetadataSource?: 'codex-acp';
 }
 /**
  * The result of expressing neutral `permissions:` in a harness's own terms.
@@ -67,6 +93,7 @@ export interface BriefingVocab {
     currentIdentityTool: string;
     sendTool: string;
     getMessagesTool: string;
+    watchCommand(identity: string): string;
     monitorInstruction(identity: string, role?: ResolvedRole): string;
     /** Wake-source wording for a role whose monitor is supervisor-owned (monitor.mode=fleet). */
     supervisedWakeNote(identity: string, role?: ResolvedRole): string;
@@ -95,7 +122,13 @@ export interface HarnessAdapter {
     id: string;
     supportsResume: boolean;
     checkPrereqs(): Promise<PrereqReport>;
-    validateOptions(opts: unknown): ValidationError[];
+    /**
+     * `role` is the SESSION-AWARE half: some harness options can only be honoured
+     * on some session types, and an option that is silently dropped is worse than
+     * one that is refused. Optional so an adapter that has nothing session-specific
+     * to say keeps its one-argument implementation.
+     */
+    validateOptions(opts: unknown, role?: ResolvedRole): 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;
@@ -105,6 +138,23 @@ export interface HarnessAdapter {
      * agent's default. Omit for a harness whose ACP agent has no modes.
      */
     acpPermissionModeId?(role: ResolvedRole): string | undefined;
+    /**
+     * The MCP servers this role declares, for the `mcpServers` array of ACP's
+     * `session/new` / `resume` / `load`. Empty (or omitted) leaves the agent's own
+     * configuration alone, which is what fleet has always sent.
+     */
+    acpMcpServers?(role: ResolvedRole): AcpMcpServer[];
+    /**
+     * Agent-specific `_meta` for `session/new` — how a capability the CLI takes as
+     * a flag reaches an ACP agent that accepts no flags.
+     *
+     * ⚠ THIS IS A PER-AGENT VOCABULARY, NOT PROTOCOL. `_meta` is free-form in ACP,
+     * so what an adapter puts here is only honoured by the agent it was written
+     * for. An adapter must therefore return nothing for an ACP command it did not
+     * choose, and the options that depend on it must be refused at validation for
+     * such a role rather than sent and silently ignored.
+     */
+    acpSessionMeta?(role: ResolvedRole, prep: SessionPrep): Record<string, unknown> | undefined;
     /** Effective portable policy and harness-native approval mode after native overrides win. */
     effectivePermissionMode?(role: ResolvedRole): {
         fleetMode: FleetPermissionMode;

package/dist/loops/manager.d.ts

@@ -68,8 +68,32 @@ export declare class ScheduledLoopManager implements ScheduledLoopManagerHandle
     private armAbandon;
     private finish;
     private advance;
+    /**
+     * Coalesce a backlog into one skip. The counters alone say how many
+     * occurrences were lost but never when or for how long, so the window is
+     * recorded too and carried on the state until a run is actually told about it
+     * — a dropped pass has to stay visible to the next one, not just to whoever
+     * was reading the log at the time.
+     */
     private skipMissed;
-    private skipRestartMisses;
+    /**
+     * Restart is not, by itself, a reason to lose an occurrence a running manager
+     * would still have run. `poll` tolerates lateness up to one full interval and
+     * runs the tick late; this path used to drop anything already due however
+     * recently, so a role restarted seconds after its own tick came due lost it
+     * outright. For an oversight role that is precisely the pass which would have
+     * recorded why it restarted, so the failure erased its own witness.
+     *
+     * The tolerance is the only thing shared with `poll`. A backlog at least one
+     * interval deep is still coalesced into a single skip and never replayed —
+     * after a long outage exactly one occurrence survives, and `schedule` then
+     * arms it through the ordinary path rather than firing a burst here.
+     *
+     * Running the survivor late cannot outpace the configured cadence: `advance`
+     * moves the cursor by exactly one `intervalMs` per occurrence from the nominal
+     * time, so a loop that keeps restarting still runs at most once per interval.
+     */
+    private skipRestartBacklog;
     /**
      * A run the store could not record is dropped, not retried: the cursor has
      * already moved, so this can never become a busy loop, and the outage is
@@ -86,5 +110,10 @@ export declare class ScheduledLoopManager implements ScheduledLoopManagerHandle
      * until the process was restarted.
      */
     private recover;
+    /**
+     * The envelope is the only channel a scheduled pass has for learning about
+     * the passes that did not happen. A gap stated here is what lets an oversight
+     * role report its own outage instead of resuming as if nothing was missed.
+     */
     private envelope;
 }