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

package/dist/docs.js

@@ -27,11 +27,34 @@ 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.
 
+## Deterministic harness plugins
+
+Harness plugin channels are configured independently and default to \`stable\`:
+
+\`\`\`yaml
+harnesses:
+  codex: { plugin_channel: nightly }
+  claude-code: { plugin_channel: stable }
+\`\`\`
+
+\`ours-fleet plugins install [codex|claude-code...]\` resolves an npm dist-tag
+once only when no same-channel lock exists. \`plugins update\` explicitly resolves
+again. Both persist the exact semver under
+\`~/.ours-fleet/harness-plugins/<harness>/plugin-lock.json\`, generate a local
+marketplace whose npm source contains that exact version, and install from that
+marketplace. \`plugins status\` reports the configured channel, exact lock, and
+channel mismatches. Stable resolves \`latest\` once and pins it; nightly resolves
+\`nightly\` once and requires a \`-nightly.N\` prerelease. Starts, restarts, and
+reconciliation only re-materialize the marketplace from the lock: they never
+query a dist-tag, run an installer, or advance a version.
+An explicit nightly role refuses to launch until that harness has a nightly lock;
+a configured/locked channel mismatch also fails with the exact update command.
+
 The CLI never writes the base file: \`spawn\` writes \`~/fleet.d/Name.yaml\`. The
 web console does write it, as a whole document — its setup wizard and
 configuration editor may create, change or remove any top-level block, including
-\`vars:\`, \`defaults:\`, \`roles:\`, \`watchdogs:\` and \`loops:\`. Only the base
-file may hold \`defaults:\`, \`watchdogs:\` and \`loops:\`; a fleet.d drop-in may
+\`vars:\`, \`defaults:\`, \`harnesses:\`, \`roles:\`, \`watchdogs:\` and \`loops:\`. Only the base
+file may hold \`defaults:\`, \`harnesses:\`, \`watchdogs:\` and \`loops:\`; a fleet.d drop-in may
 declare \`roles:\` and nothing else. Unrecognised top-level keys are round-tripped
 untouched. Console edits are applied as surgical splices against the file's exact
 bytes, so an unchanged save is byte-identical and lines outside the edit keep their
@@ -270,6 +293,9 @@ roles:
       add_dirs: [/data/shared]
       config:
         model_reasoning_effort: high
+      mcp_servers:                       # claude-code: per-role MCP servers, additive by default
+        ours: { command: ours-mcp, args: [proxy] }
+      mcp_servers_only: false            # true = ONLY these; drops user/project/plugin servers
     bio: Public role card and when peers should engage it.
     persona: Local operating contract, boundaries, and escalation policy.
     briefing_file: /absolute/custom-briefing.md
@@ -314,6 +340,11 @@ 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.
 
+Supervised roles connect to the operator-configured ours daemon; they do not own its
+lifecycle. Fleet forces \`OURS_AUTOSTART=0\` in tmux and ACP child processes after role
+environment overlays. Start the shared daemon only through an explicit operator or
+installer/setup flow.
+
 ## Permissions
 
 Prefer the harness-neutral \`permissions\` block:
@@ -399,10 +430,14 @@ permissions through its harness and check the result against a fixed floor:
 deny those requests with nobody to see it; with \`unattended: wait\` it warns,
 because a human can still attach and answer.
 
-Security meaning: \`ask\` maps to Codex \`untrusted\` and Claude \`default\`;
-\`auto\` maps to Codex \`on-request\` and Claude \`acceptEdits\`; and
-\`approval: allow\` maps to Codex \`never\` and Claude \`bypassPermissions\`,
-which genuinely permits the actions the role was authorized to take —
+Security meaning: \`ask\` maps to Codex \`untrusted\` and Claude \`default\`.
+\`auto\` selects Codex ACP \`agent\` (\`on-request\` + \`workspace-write\`) and
+Claude \`acceptEdits\`. \`approval: allow\` selects Codex ACP's fully
+non-interactive yolo mode, reported as \`agent-full-access\` (\`never\` +
+\`danger-full-access\`), and Claude \`bypassPermissions\`. Codex tmux retains
+independent approval and sandbox flags: \`auto\` is \`on-request\`, \`allow\`
+is \`never\`, and \`filesystem\` still selects the sandbox. These modes genuinely
+permit the actions the role was authorized to take —
 \`dontAsk\` only suppresses the prompt while still refusing the action. Nothing
 other than an explicit \`allow\` becomes non-interactive. Legacy \`deny\` keeps
 its conservative Codex \`on-request\` / Claude \`plan\` translation. \`allow\` is therefore a real grant and
@@ -413,20 +448,45 @@ ACP carries agent-advertised session mode IDs and \`session/set_mode\`, but thos
 IDs are agent-specific and ACP defines no portable permission-policy capability.
 Fleet therefore uses the ACP primitive where an adapter exposes a matching mode
 and otherwise performs the harness translation above. The bundled Codex ACP
-adapter couples approval and sandboxing in its advertised mode IDs, so fleet
-keeps the selected sandbox preset and enforces the independently translated
-approval policy on the app-server turn request. For example, \`allow\` plus
-\`workspace\` is really \`approval=never sandbox=workspace-write\`; it is never
-widened to \`danger-full-access\`. The live session reports both its effective
-normalized mode and the ACP sandbox-preset ID.
+adapter couples approval and sandboxing in its advertised mode IDs. Neutral
+\`allow\` therefore selects \`agent-full-access\` and widens \`filesystem:
+workspace\` or \`read-only\` to \`danger-full-access\`; neutral \`auto\` selects
+\`agent\` and \`workspace-write\` even when the neutral filesystem value differs.
+An explicit \`harness_options.sandbox\` selects its corresponding ACP preset and
+still wins, as does an explicit native approval override. \`config\` and
+\`doctor\` report a coupled-mode mismatch as approximate. Use per-role
+\`isolation:\` as the outer boundary for an \`allow\` ACP role. The live session
+reports both its effective normalized mode and the exact native mode selected.
 
 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\`.
+dontAsk, bypassPermissions), \`plugins\`, \`mem_palace\`,
+\`mem_palace_midsession_autosave\`, \`mcp_servers\` and \`mcp_servers_only\`.
+
+\`mcp_servers\` declares MCP servers for the role, in \`.mcp.json\`'s own shape
+(a map of name to \`{ command, args, env }\`, or \`{ type: http|sse, url,
+headers }\`). By default they are ADDED to whatever the OS user running the role
+already has configured, on both session types: tmux passes \`--mcp-config\`, and
+ACP sends them in \`session/new\`.
+
+\`mcp_servers_only: true\` makes the declared set EXCLUSIVE — \`--strict-mcp-config\`
+on tmux, \`strictMcpConfig\` on ACP. It is all-or-nothing and it ignores every
+other MCP configuration: project \`.mcp.json\`, user settings, and **plugins**.
+The ours connector is normally installed as a plugin, so a strict role that does
+not re-declare it has no \`send_message\` and no \`get_messages\` — it cannot even
+report that it has gone mute. Fleet therefore refuses a strict role whose
+\`mcp_servers\` does not name the connector; declare it explicitly, e.g.
+\`ours: { command: ours-mcp, args: [proxy] }\`.
+
+Both options, and \`plugins\`, reach an ACP session through the bundled Claude ACP
+agent's \`_meta\` vocabulary. A role that sets \`session_options.acp.command\` runs
+an agent fleet did not choose and cannot be promised them, so that combination is
+refused at validation rather than accepted and dropped. This narrows a role's
+tool surface; it does not stop the harness deferring tool schemas, which is the
+harness's own decision.
 
 Codex \`harness_options\`: \`launcher\` (auto, ours-codex, codex), \`sandbox\`
 (read-only, workspace-write, danger-full-access), \`approval\` or
@@ -514,12 +574,11 @@ owner of that authenticated source wire instead of the latest conversation.
 Every other CID is rejected and warned about without reflecting its body. Fleet sends
 accepted/queued/progress/interrupted/failure notices and routes the ACP turn's
 final assistant text back to the authenticated sender with its source wire ID.
-For file replies, fleet injects a request-specific outbox path into the owner
-prompt. The agent copies completed artifacts there; fleet sends every regular
-file from the channel identity with the same source wire ID and removes the
-temporary outbox only after successful delivery. For proactive or in-turn agent
-attachments, the agent calls ours \`send_file\` to the channel identity and may
-pair it with a reply-linked caption; fleet, not the agent, chooses the owner.
+For file replies of every kind — a response artifact, a proactive note, or an
+in-turn attachment — the agent calls ours \`send_file\` to the channel identity
+and may pair it with a reply-linked caption; fleet, not the agent, chooses the
+owner. That is the only delivery route an agent is given: a tool call either
+delivers or reports an error, where a file written to disk does neither.
 Owner messages whose trimmed text starts with \`/\` are deterministic
 supervisor commands and never enter the model: \`/help\` (alias \`/commands\`),
 \`/status\`, \`/comments [status|on|off]\`, \`/interrupt\`, \`/clear\`,
@@ -552,18 +611,13 @@ their content signature must match the declared MIME, and symlinks or non-regula
 paths fail closed. Sanitized copies live only in a mode-0700 request directory as
 mode-0600 files and are removed after completion or bounded stale retention.
 
-Voice prompts include a bounded transcript only when typed daemon metadata reports success.
+Voice prompts include a bounded transcript only when ours-mcp reports success.
 Failure or unavailability is explicit and preserves the private audio path as the
-input for direct review. Run \`ours config show --json\` and inspect \`sttConfigured\` without
-revealing provider credentials.
-A mode-0600 message claim journal stores only wire ID, persistent-history
-sequence, and claim time. Fleet journals the exact body-free oldest-first slice
-before calling \`getMessages\` with that slice length, rejects a returned set
-mismatch, and loads a crash-recovered body only through \`getHistoryItem\`.
-The attachment crash journal contains only authenticated CID and wire routing
-data; it never stores captions, filenames, paths, transcript text, or bytes.
-Journaled read files resume through \`getFileInfo\` and \`fetchFile\`. A claimed
-agent caption is loaded from history and rejoined before the group is admitted. Fleet
+fallback. Run \`ours-mcp voice-status --json\` to inspect the host configuration.
+A mode-0600 crash journal contains only authenticated CID and wire routing data;
+it never stores captions, filenames, paths, transcript text, or bytes. Journaled
+post-retrieval files resume selectively through \`save_file\`. A deferred agent
+caption is replayed with its processed files before the group is admitted. Fleet
 resolves one authenticated owner route before retrieving bytes, admits every file
 before emitting the caption or any file, and sends every part to that same route.
 Unknown correlated routes remain queued without retrieval and receive one bounded
@@ -666,10 +720,38 @@ escape hatch.
 
 ## Bounded worklogs, auth proxy, and model recovery
 
-An optional \`worklog: { max_kb, keep_tail_kb, max_archives }\` policy rotates a
-stable snapshot at fleet-owned lifecycle points. Concurrent changes defer
-rotation. Archives remain beside WORKLOG.md with the same sensitive-state
-boundary; retention deletes only recognized fleet archive names.
+WORKLOG rotation is enabled by default with
+\`worklog: { max_kb: 1024, keep_tail_kb: 256, max_archives: 12 }\`. Maps may
+override individual values; \`worklog: false\` on a role or in defaults opts out.
+Fleet rotates only at that role's launch/resume lifecycle boundary. Concurrent
+changes defer rotation. The active file keeps a bounded UTF-8 tail and advances
+to a line boundary when a complete line fits. If one logical line alone exceeds
+the budget, its newest suffix remains and the rotation manifest records the
+mid-line start and omitted byte count. The complete prior inode receives a
+collision-safe UTC archive name, and
+\`.worklog-rotation.json\` records restart provenance. \`max_archives\` bounds
+recent archives beside WORKLOG.md; older complete archives move to
+\`WORKLOG.archives/\` without deletion. All archives share the role's sensitive
+state boundary. Fleet refuses a symlinked/non-regular live log or a symlinked
+cold-archive boundary before replacing the live path and best-effort removes a
+duplicate publication left by a detected failure while the original inode is
+still available. The manifest records SHA-256 digests for the archive and live
+bytes observed when it is written. These checks address ordinary path hazards,
+not intentional path mutation by a malicious concurrent process with the same
+Unix authority; that is outside the threat model and requires OS-level isolation.
+
+ACP tool diffs are bounded before entering web conversation events. Existing
+small before/after diffs are unchanged. Oversized whole-file snapshots are
+reduced to the actual changed region plus path, operation, original byte counts,
+digest, and omission metadata. Each retained side is a newest-content UTF-8 tail
+of at most 64 KiB, advanced to a line boundary when a complete line fits. An
+overlong single line keeps its newest suffix and explicitly records a mid-line
+start. Paths retain at most a 4 KiB suffix with byte count, digest, and omitted
+prefix metadata; the complete normalized update is capped at 320 KiB. A large
+append therefore retains current appended content, not the historical prefix.
+The live web-console transcript includes only the current runner generation and
+excludes adapter session/load replay. Replayed events remain durable with
+agent_replay provenance for diagnosis and recovery.
 
 \`auth_proxy: { kind: anthropic, base_url, required, health_url }\` is Claude-only
 and loopback-only. Fleet injects only ANTHROPIC_BASE_URL and doctor rejects

package/dist/doctor.d.ts

@@ -1,10 +1,7 @@
-import { type AttachOursClientOptions, type OursClient } from '@ours.network/sdk/client';
 import { type Exec } from './exec.js';
 import type { YamlMode } from './config-yaml.js';
 import { type FetchLike } from './monitor.js';
 import type { PrereqReport } from './harness/types.js';
-type DoctorDaemonClient = Pick<OursClient, 'version'>;
-type AttachDoctorDaemon = (options: AttachOursClientOptions) => Promise<DoctorDaemonClient>;
 /** Host-level + per-harness prerequisite report with actionable messages. */
 export declare function doctor(opts?: {
     harness?: string;
@@ -15,5 +12,4 @@ export declare function doctor(opts?: {
         path?: string;
         argv1?: string;
     };
-}, exec?: Exec, platform?: NodeJS.Platform, fetchImpl?: FetchLike, attachDaemon?: AttachDoctorDaemon): Promise<PrereqReport>;
-export {};
+}, exec?: Exec, platform?: NodeJS.Platform, fetchImpl?: FetchLike): Promise<PrereqReport>;

package/dist/doctor.js

@@ -1,6 +1,5 @@
 import { userInfo } from 'node:os';
 import { existsSync, readFileSync } from 'node:fs';
-import { attachOursClient, } from '@ours.network/sdk/client';
 import { realExec } from './exec.js';
 import { isolationContextFor, loadConfig } from './config.js';
 import { getAdapter, productionAdapters } from './harness/registry.js';
@@ -77,7 +76,7 @@ function installChecks(scan) {
     ];
 }
 /** Host-level + per-harness prerequisite report with actionable messages. */
-export async function doctor(opts = {}, exec = realExec, platform = process.platform, fetchImpl = (u, i) => globalThis.fetch(u, i), attachDaemon = attachOursClient) {
+export async function doctor(opts = {}, exec = realExec, platform = process.platform, fetchImpl = (u, i) => globalThis.fetch(u, i)) {
     const checks = [];
     // First: which artifact is producing this report. Everything below is only as
     // trustworthy as the answer, and a second install with the same semver and
@@ -113,22 +112,16 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
             detail: tmux.code === 0 ? tmux.stdout.trim() : 'not found — apt install tmux / brew install tmux',
         });
     }
-    try {
-        const client = await attachDaemon({
-            env: process.env,
-            leaseToken: `ours-fleet-doctor-${process.pid}`,
-            clientPid: process.pid,
-        });
-        const info = await client.version();
-        if (info.name !== 'ours' || typeof info.version !== 'string')
-            throw new Error('the selected endpoint did not return a valid ours daemon identity');
-        checks.push({ name: 'ours daemon', ok: true, detail: `running (${info.version})` });
-    }
-    catch (error) {
+    const mcp = await exec('ours-mcp', ['--version']);
+    checks.push({
+        name: 'ours-mcp', ok: mcp.code === 0,
+        detail: mcp.code === 0 ? mcp.stdout.trim() : 'not found — npm i -g @ours.network/mcp',
+    });
+    if (mcp.code === 0) {
+        const st = await exec('ours-mcp', ['status']);
         checks.push({
-            name: 'ours daemon', ok: false,
-            detail: `not reachable through the SDK — start it with: ours daemon start `
-                + `[${error?.message ?? String(error)}]`,
+            name: 'ours-mcp daemon', ok: st.code === 0,
+            detail: st.code === 0 ? 'running' : 'not running — start it with: ours-mcp start',
         });
     }
     if (platform === 'linux') {
@@ -295,7 +288,7 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
         }
         catch (e) {
             detail = `unreachable on :${endpoint.port} — monitored roles run degraded until it is up ` +
-                `(start it: ours daemon start) [${e?.message ?? e}]`;
+                `(start it: ours-mcp start) [${e?.message ?? e}]`;
         }
         checks.push({ name: checkName, ok, detail });
     }

package/dist/fleet-proxy.d.ts

@@ -12,6 +12,11 @@ export interface ManagedFleetSpawnResult {
     session: 'tmux' | 'acp';
     model?: string;
     monitor: Pick<MonitorConfig, 'mode' | 'interrupt'>;
+    /** Adapter-resolved portable policy and exact native runtime mode. */
+    permissionMode?: {
+        fleetMode: 'ask' | 'auto' | 'allow';
+        nativeMode: string;
+    };
     inherited: string[];
     creationActionId: string;
 }

package/dist/harness/acp-agent.js

@@ -1,18 +1,23 @@
 import { createRequire } from 'node:module';
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve, sep } 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'
+        const declaredEntrypoint = typeof manifest.bin === 'string'
             ? manifest.bin
             : manifest.bin?.[binName];
-        if (!relative)
+        if (!declaredEntrypoint)
             return { argv: [fallbackCommand], bundled: false };
-        const entrypoint = resolve(dirname(manifestPath), relative);
-        if (!existsSync(entrypoint))
+        const packageRoot = realpathSync(dirname(manifestPath));
+        const entrypoint = realpathSync(resolve(packageRoot, declaredEntrypoint));
+        const entrypointFromRoot = relative(packageRoot, entrypoint);
+        if (entrypointFromRoot === '..'
+            || entrypointFromRoot.startsWith(`..${sep}`)
+            || isAbsolute(entrypointFromRoot)
+            || !statSync(entrypoint).isFile())
             return { argv: [fallbackCommand], bundled: false };
         return {
             argv: [process.execPath, entrypoint], bundled: true, manifestPath,

package/dist/harness/claude-code.js

@@ -6,8 +6,99 @@ 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'];
+import { restoreLockedHarnessMarketplace } from '../harness-plugins.js';
+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 +218,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 +237,7 @@ export function makeClaudeCodeAdapter(exec = realExec) {
                     }],
             };
         },
-        validateOptions(opts) {
+        validateOptions(opts, role) {
             if (opts == null)
                 return [];
             if (typeof opts !== 'object' || Array.isArray(opts))
@@ -157,12 +245,50 @@ 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) {
+            // Re-materialize only from the persisted exact lock. Ordinary launches
+            // never resolve npm tags or run an installer.
+            restoreLockedHarnessMarketplace('claude-code', role.harnessPluginChannel);
             // 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).
@@ -178,6 +304,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 +323,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 +375,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 +477,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;