synabun 2.0.10 → 2.1.0

package/neural-interface/lib/opencode-protocol.js

@@ -1,78 +1,210 @@
 // ─────────────────────────────────────────────────────────────────────────────
 // Which OpenCode SynaBun talks to, and how to know it is really there.
 //
-// OpenCode 1 and OpenCode 2 are different servers behind the same
-// `opencode serve`:
-//   • OpenCode 1 (`opencode --version` → "1.18.34"): its API at the root
-//     (/global/health, /session, /global/event, …), no password.
-//   • OpenCode 2 (→ "opencode v2.0.32"): its API under /api/*, HTTP Basic auth
-//     (user `opencode`) with a password set per launch (OPENCODE_PASSWORD,
-//     which OpenCode keeps out of its children's environment); every other
-//     path is its web app, an HTML page with status 200.
-// SynaBun reads the major version of the binary it is about to start (the CLI
-// resolver's cached `--version`, keyed by the file, so an upgrade in place is
-// read again), starts it the way that version wants, and calls a serve healthy
-// only when the right API answers JSON: an HTML page never passes.
+// SynaBun drives OpenCode 2 and nothing else (OpenCode 1 support was removed
+// on 2026-10-24). OpenCode 2 (`opencode --version` → "opencode v2.1.4") serves
+// its API under /api/*, behind HTTP Basic auth (user `opencode`) with a
+// password set per launch. Production serves generate it privately on stdout
+// (serveSpecFor passwordFrom 'stdout'); an environment password would remain
+// readable in the process and its shell's programs. The low-level 'env' mode
+// remains for explicit callers/fixtures. Every other path is its web app, an HTML page with
+// status 200. SynaBun reads the version of the binary it is about to start
+// (the CLI resolver's cached `--version`, keyed by the file, so an upgrade in
+// place is read again), refuses an OpenCode it does not drive with one
+// sentence that says what was found and how to get OpenCode 2, and calls a
+// serve healthy only when OpenCode 2's API answers JSON: an HTML page never
+// passes.
+//
+// OPENCODE_MIN_VERSION is the oldest OpenCode 2 SynaBun's OpenCode layer was
+// built and checked against (the recorded events of tests/fixtures/
+// opencode2-events.json, the plugin hook of the route gate and the browser
+// policy, the live smoke test). npm's `opencode-ai` package is still OpenCode
+// 1; OpenCode 2 comes from its own installer (https://opencode.ai/v2/install),
+// Homebrew (anomalyco/tap/opencode-v2) or WinGet (Anomaly.OpenCode).
 // ─────────────────────────────────────────────────────────────────────────────
 
 import { randomBytes } from 'node:crypto';
+import { request as httpRequest } from 'node:http';
 
-/** Protocols SynaBun speaks, by the OpenCode major version that serves them. */
-export const OPENCODE_PROTOCOLS = Object.freeze({ 1: 'opencode1', 2: 'opencode2' });
-export const OPENCODE2_USERNAME = 'opencode';
+export const OPENCODE_MIN_VERSION = '2.0.32';
+export const OPENCODE_USERNAME = 'opencode';
 
-/** "1.18.34", "opencode v2.0.32", "v1.19.3" → 1 / 2; null when no version can be read. */
-export function opencodeMajorOf(version) {
+/** "2.1.4", "opencode v2.1.4", "v1.19.3" → { major, minor, patch }; null when no version can be read. */
+export function opencodeVersionOf(version) {
   const match = String(version ?? '').match(/(\d+)\.(\d+)\.(\d+)/);
   if (!match) return null;
-  const major = Number(match[1]);
-  return Number.isFinite(major) ? major : null;
+  const [major, minor, patch] = match.slice(1, 4).map(Number);
+  return [major, minor, patch].every(Number.isFinite) ? { major, minor, patch } : null;
+}
+
+const MINIMUM = opencodeVersionOf(OPENCODE_MIN_VERSION);
+
+function olderThanMinimum(v) {
+  if (v.major !== MINIMUM.major) return v.major < MINIMUM.major;
+  if (v.minor !== MINIMUM.minor) return v.minor < MINIMUM.minor;
+  return v.patch < MINIMUM.patch;
 }
 
 /**
- * The protocol for a version string: `{ protocol: 1 | 2 | null, major,
- * version, supported, reason }`. OpenCode 0.x is the 1.x API's predecessor and
- * speaks it; a major SynaBun does not know is refused with a sentence, never
- * guessed at.
+ * The commands that install OpenCode 2 on a system, the first one first: OpenCode's own installer
+ * (https://opencode.ai/v2/install, the one `opencode upgrade` runs), its Homebrew tap, WinGet on Windows.
  */
-export function protocolForVersion(version) {
-  const major = opencodeMajorOf(version);
+export function opencodeInstallCommands(platform = process.platform) {
+  if (platform === 'win32') return ['winget install --id Anomaly.OpenCode --exact'];
+  if (platform === 'darwin') return ['brew install anomalyco/tap/opencode-v2', 'curl -fsSL https://opencode.ai/v2/install | bash'];
+  return ['curl -fsSL https://opencode.ai/v2/install | bash'];
+}
+
+/** How to get OpenCode 2 on a system, as words of a sentence ("run: …, or: …"). */
+export function opencodeInstallRoute(platform = process.platform) {
+  return opencodeInstallCommands(platform).map((command, index) => `${index ? 'or: ' : 'run: '}${command}`).join(', ');
+}
+
+/**
+ * Whether SynaBun drives the OpenCode of a version string: `{ supported,
+ * version, major, reason, code }`. `reason` is the one sentence a person reads
+ * when it does not: what was found (`path`, when known) and how to get OpenCode
+ * 2; `code` says which case it is ('unreadable' | 'opencode1' | 'newer' |
+ * 'outdated'), for a page that words it in its own language.
+ */
+export function opencodeSupportFor(version, { path = null, platform = process.platform } = {}) {
   const text = version ? String(version).trim() : '';
-  if (major == null) {
-    return { protocol: null, major: null, version: text || null, supported: false, reason: text ? `SynaBun cannot read the OpenCode version "${text}".` : 'SynaBun could not read the OpenCode version.' };
+  const parsed = opencodeVersionOf(text);
+  const where = path ? ` (${path})` : '';
+  // What every refusal but an outdated OpenCode 2's ends with: how to get OpenCode 2, or where to pick one.
+  const getOpencode2 = `install OpenCode 2 (${opencodeInstallRoute(platform)}), or choose an OpenCode 2 under Settings → Executable paths`;
+  if (!parsed) {
+    const found = text ? `SynaBun cannot read the OpenCode version "${text}"${where}` : `SynaBun could not read the version of the OpenCode it found${where}`;
+    return { supported: false, version: text || null, major: null, code: 'unreadable', reason: `${found}, and it needs OpenCode 2 (${OPENCODE_MIN_VERSION} or newer): ${getOpencode2}.` };
+  }
+  const { major } = parsed;
+  // The version as OpenCode prints it, without its name ("opencode v2.1.4" → "2.1.4", a prerelease kept whole).
+  const shown = text.replace(/^opencode\s+/i, '').replace(/^v(?=\d)/i, '') || `${parsed.major}.${parsed.minor}.${parsed.patch}`;
+  if (major <= 1) {
+    return { supported: false, version: text, major, code: 'opencode1', reason: `SynaBun works with OpenCode 2 only, and the OpenCode it found${where} is version ${shown}: install OpenCode 2 (${opencodeInstallRoute(platform)}; npm's opencode-ai package is still OpenCode 1), or choose an OpenCode 2 under Settings → Executable paths.` };
+  }
+  if (major >= 3) {
+    return { supported: false, version: text, major, code: 'newer', reason: `OpenCode ${shown}${where} is newer than SynaBun supports: SynaBun works with OpenCode 2 only, so ${getOpencode2}.` };
+  }
+  if (olderThanMinimum(parsed)) {
+    return { supported: false, version: text, major, code: 'outdated', reason: `SynaBun needs OpenCode ${OPENCODE_MIN_VERSION} or newer, and the OpenCode it found${where} is version ${shown}: update it (run: opencode upgrade).` };
   }
-  if (major <= 1) return { protocol: 1, major, version: text, supported: true, reason: null };
-  if (major === 2) return { protocol: 2, major, version: text, supported: true, reason: null };
-  return { protocol: null, major, version: text, supported: false, reason: `OpenCode ${major} (${text}) is newer than SynaBun supports: SynaBun works with OpenCode 1 and OpenCode 2.` };
+  return { supported: true, version: text, major, code: null, reason: null };
 }
 
-/** A fresh password for one OpenCode 2 launch. */
+/** A fresh password for one serve launch. */
 export function newServePassword() {
   return randomBytes(24).toString('base64url');
 }
 
-/** The Authorization header for an OpenCode 2 serve. */
-export function basicAuthHeader(password, username = OPENCODE2_USERNAME) {
+/** The Authorization header for a serve. */
+export function basicAuthHeader(password, username = OPENCODE_USERNAME) {
   return `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`;
 }
 
+/** The environment variables OpenCode 2 takes its serve password from (OPENCODE_PASSWORD first). */
+export const SERVE_PASSWORD_ENV = Object.freeze(['OPENCODE_PASSWORD', 'OPENCODE_SERVER_PASSWORD']);
+
 /**
- * The arguments and environment of `opencode serve` on `port` for a protocol.
- * OpenCode 1 keeps exactly what SynaBun always ran (`serve --port N`); OpenCode
- * 2 also gets its loopback host name and the launch's password (OPENCODE_PASSWORD;
- * any OPENCODE_SERVER_PASSWORD the environment carries is dropped, so the
- * password SynaBun holds is the one the serve checks). A version SynaBun could
- * not read (`protocol` null: a command line in Settings) starts like OpenCode
- * 2: OpenCode 1 ignores OPENCODE_PASSWORD and takes --hostname too, and the
- * health check then says which one answered.
+ * The arguments and environment of `opencode serve` on `port`: its loopback
+ * host name and the launch's password. `passwordFrom`:
+ *   'env'     (default) the password is OPENCODE_PASSWORD (any
+ *             OPENCODE_SERVER_PASSWORD the environment carries is dropped, so
+ *             the password SynaBun holds is the one the serve checks). OpenCode
+ *             2 keeps it in its own environment, so every program its shell
+ *             starts inherits it, and a process of the same user can read it
+ *             in the serve's start-up environment (ps eww).
+ *   'stdout'  no password variable at all: OpenCode 2 makes one up and prints
+ *             it once on its standard output ("server password <it>", after
+ *             "server listening on …"), which SynaBun reads
+ *             (servePasswordReader) and keeps out of its logs
+ *             (redactServeOutput). The password is in no environment: not the
+ *             serve's, not its shell's. `password` is null until it is read.
+ *             A launch through a login shell removes both variables after the
+ *             profile ran (`unset`, serveUnsetCommand), so a profile that
+ *             exports one cannot put it back.
  */
-export function serveSpecFor(protocol, port, { env = process.env, password = null } = {}) {
-  const args = ['serve', '--port', String(port)];
-  if (protocol === 1) return { args, env, password: null };
+export function serveSpecFor(port, { env = process.env, password = null, passwordFrom = 'env' } = {}) {
+  const args = ['serve', '--port', String(port), '--hostname', '127.0.0.1'];
+  const next = { ...env };
+  for (const key of SERVE_PASSWORD_ENV) delete next[key];
+  if (passwordFrom === 'stdout') return { args, env: next, password: null, passwordFrom: 'stdout' };
   const pass = password || newServePassword();
-  const next = { ...env, OPENCODE_PASSWORD: pass };
-  delete next.OPENCODE_SERVER_PASSWORD;
-  return { args: [...args, '--hostname', '127.0.0.1'], env: next, password: pass };
+  next.OPENCODE_PASSWORD = pass;
+  return { args, env: next, password: pass, passwordFrom: 'env' };
+}
+
+/** What a POSIX shell runs before `exec opencode serve` of a 'stdout' launch: the password variables gone. */
+export function serveUnsetCommand() {
+  return `unset ${SERVE_PASSWORD_ENV.join(' ')}`;
+}
+
+const SERVE_PASSWORD_LINE = /(?:^|\n)server password (\S+)[ \t]*\r?\n/;
+
+/**
+ * A reader of a 'stdout' serve's output: feed it each chunk of standard output; it answers the password once its
+ * line is complete ("server password <it>" and a line end), else null. Chunks may split the line anywhere.
+ */
+export function servePasswordReader() {
+  let buffered = '';
+  let found = null;
+  return (chunk) => {
+    if (found) return found;
+    buffered = `${buffered}${String(chunk ?? '')}`.slice(-4096);
+    const m = SERVE_PASSWORD_LINE.exec(buffered);
+    if (m) found = m[1];
+    return found;
+  };
+}
+
+/** Serve output with its password line taken out (what a log may hold). */
+export function redactServeOutput(text) {
+  return String(text ?? '').replace(/server password \S+/g, 'server password <hidden>');
+}
+
+/**
+ * A line-buffering redactor for either of a serve's output streams. redactServeOutput runs on whole lines only: a chunk of a
+ * stream may split the "server password <x>" line anywhere (the token across two reads), and redacting each chunk on
+ * its own would let a fragment of the password through to the log. Feed every chunk to `push`; it assembles complete
+ * lines, redacts each and hands it to `emit` (the trailing newline kept). Call `flush` once the stream ends to emit a
+ * last line that never got its newline. A partial line that grows past `maxLine` without a newline is redacted and
+ * emitted so the buffer cannot grow without bound (the password line is short and newline-terminated, so this cap is
+ * never reached mid-password).
+ */
+export function createServeLogRedactor(emit, { maxLine = 65536 } = {}) {
+  let buf = '';
+  const drain = (final) => {
+    let nl;
+    while ((nl = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, nl + 1);
+      buf = buf.slice(nl + 1);
+      emit(redactServeOutput(line));
+    }
+    if ((final || buf.length > maxLine) && buf) { emit(redactServeOutput(buf)); buf = ''; }
+  };
+  return {
+    push: (chunk) => { buf += String(chunk ?? ''); drain(false); },
+    flush: () => drain(true),
+  };
+}
+
+/**
+ * A serve's environment with a run's own settings on top: a string value is set, null (or undefined) removes the
+ * variable, anything else is ignored. `GIT_*: null` clears every inherited git variable BEFORE the explicit
+ * settings are applied, so SynaBun's own git safety settings survive. The marker never reaches the child.
+ * A new object; `env` is not changed. Also used for evaluation runtimes, whose whole process tree needs this policy.
+ */
+export function withServeEnv(env, extra) {
+  const next = { ...(env || {}) };
+  if (extra && typeof extra === 'object') {
+    if (extra['GIT_*'] === null) for (const key of Object.keys(next)) if (key.startsWith('GIT_')) delete next[key];
+    for (const [key, value] of Object.entries(extra)) {
+      if (key === 'GIT_*') continue;
+      if (typeof value === 'string') next[key] = value;
+      else if (value === null || value === undefined) delete next[key];
+    }
+  }
+  return next;
 }
 
 function isJsonResponse(res) {
@@ -85,89 +217,94 @@ async function readJson(res) {
 }
 
 /**
- * Is a real OpenCode API answering on `port`? `protocol` 1 asks
- * /global/health, 2 asks /api/info with `password`; `protocol` null asks both
- * (an unknown serve: which one is it?). Resolves
- * `{ ok, protocol, version, state, error }`, where `state` is
- *   'healthy'  the protocol's API answered JSON
- *   'locked'   an OpenCode 2 serve whose password SynaBun does not hold
- *   'mismatch' an OpenCode of the other major answered
- *   'html'     a web page (OpenCode 2's app, or anything else) — never healthy
- *   'down'     nothing answered
- *   'error'    something answered, but not an OpenCode API
+ * Is OpenCode 2's API answering on `port`? Asks /api/info with `password`.
+ * Resolves `{ ok, version, state, error }`, where `state` is
+ *   'healthy'     OpenCode 2's API answered JSON, from a version SynaBun drives
+ *   'unsupported' OpenCode's API answered, from a version SynaBun does not drive
+ *                 (`error` is opencodeSupportFor's sentence)
+ *   'locked'      an OpenCode 2 serve whose password SynaBun does not hold
+ *   'html'        a web page — never healthy
+ *   'down'        nothing answered
+ *   'error'       something answered, but not OpenCode 2's API
  * Never throws.
  */
-export async function checkOpencodeServer({ port, protocol = null, password = null, fetchImpl = globalThis.fetch, timeoutMs = 2000, host = '127.0.0.1' } = {}) {
-  const base = `http://${host}:${port}`;
-  const get = async (path, headers = {}) => {
-    try {
-      return await fetchImpl(`${base}${path}`, { headers: { accept: 'application/json', ...headers }, signal: AbortSignal.timeout(timeoutMs) });
-    } catch (error) {
-      return { failed: true, error };
-    }
-  };
-  const asV1 = async () => {
-    const res = await get('/global/health');
-    if (res.failed) return { ok: false, protocol: 1, version: null, state: 'down', error: String(res.error?.message || res.error) };
-    const { json, html } = await readJson(res);
-    if (res.ok && json && (json.healthy === true || typeof json.version === 'string')) {
-      return { ok: true, protocol: 1, version: typeof json.version === 'string' ? json.version : null, state: 'healthy', error: null };
-    }
-    return { ok: false, protocol: 1, version: null, state: html ? 'html' : 'error', error: html ? 'answered with a web page, not the OpenCode 1 API' : `GET /global/health answered ${res.status}` };
-  };
-  const asV2 = async () => {
-    const res = await get('/api/info', password ? { authorization: basicAuthHeader(password) } : {});
-    if (res.failed) return { ok: false, protocol: 2, version: null, state: 'down', error: String(res.error?.message || res.error) };
-    const { json, html } = await readJson(res);
-    if (res.ok && json && typeof json.version === 'string' && Array.isArray(json.urls)) {
-      return { ok: true, protocol: 2, version: json.version, state: 'healthy', error: null };
-    }
-    if (res.status === 401 && json && /unauthori[sz]ed/i.test(String(json._tag || json.name || ''))) {
-      return { ok: false, protocol: 2, version: null, state: 'locked', error: password ? 'the OpenCode 2 serve refused SynaBun\'s password' : 'an OpenCode 2 serve SynaBun did not start (it needs that serve\'s password)' };
-    }
-    return { ok: false, protocol: 2, version: null, state: html ? 'html' : 'error', error: html ? 'answered with a web page, not the OpenCode 2 API' : `GET /api/info answered ${res.status}` };
-  };
-
-  if (protocol === 1) {
-    const v1 = await asV1();
-    if (v1.ok || v1.state === 'down') return v1;
-    // A web page where OpenCode 1 was expected: is it an OpenCode 2?
-    const v2 = await asV2();
-    if (v2.ok || v2.state === 'locked') return { ...v2, ok: false, state: 'mismatch', error: 'an OpenCode 2 serve answered where SynaBun expected OpenCode 1' };
-    return v1;
+export async function checkOpencodeServer({ port, password = null, fetchImpl = globalThis.fetch, timeoutMs = 2000, host = '127.0.0.1' } = {}) {
+  let res;
+  try {
+    res = await fetchImpl(`http://${host}:${port}/api/info`, {
+      headers: { accept: 'application/json', ...(password ? { authorization: basicAuthHeader(password) } : {}) },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (error) {
+    return { ok: false, version: null, state: 'down', error: String(error?.message || error) };
   }
-  if (protocol === 2) {
-    const v2 = await asV2();
-    if (v2.ok || v2.state === 'down' || v2.state === 'locked') return v2;
-    const v1 = await asV1();
-    if (v1.ok) return { ...v1, ok: false, state: 'mismatch', error: 'an OpenCode 1 serve answered where SynaBun expected OpenCode 2' };
-    return v2;
+  const { json, html } = await readJson(res);
+  if (res.ok && json && typeof json.version === 'string' && Array.isArray(json.urls)) {
+    const support = opencodeSupportFor(json.version);
+    if (!support.supported) return { ok: false, version: json.version, state: 'unsupported', error: support.reason };
+    return { ok: true, version: json.version, state: 'healthy', error: null };
   }
-  const v1 = await asV1();
-  if (v1.ok || v1.state === 'down') return v1;
-  const v2 = await asV2();
-  return v2.ok || v2.state === 'locked' ? v2 : v1;
+  if (res.status === 401 && json && /unauthori[sz]ed/i.test(String(json._tag || json.name || ''))) {
+    return { ok: false, version: null, state: 'locked', error: password ? 'the OpenCode serve refused SynaBun\'s password' : 'an OpenCode serve SynaBun did not start (it needs that serve\'s password)' };
+  }
+  return { ok: false, version: null, state: html ? 'html' : 'error', error: html ? 'answered with a web page, not the OpenCode 2 API' : `GET /api/info answered ${res.status}` };
+}
+
+// An upgrade must be rejected before PTY/resource lookup, even for an Origin
+// that OpenCode permits. Never place a real credential in a URL or this probe.
+export function probeUnauthenticatedUpgrade({ port, timeoutMs = 2000 } = {}) {
+  return new Promise(resolve => {
+    const req = httpRequest({ hostname: '127.0.0.1', port,
+      path: '/api/pty/synabun-auth-probe/connect',
+      headers: { connection: 'Upgrade', upgrade: 'websocket', 'sec-websocket-version': '13',
+        'sec-websocket-key': randomBytes(16).toString('base64'), origin: 'http://localhost:1' },
+    });
+    req.on('response', res => { res.resume(); resolve(res.statusCode); });
+    req.on('upgrade', (_res, socket) => { socket.destroy(); resolve(101); });
+    req.on('error', () => resolve(null));
+    req.setTimeout(timeoutMs, () => { req.destroy(); resolve(null); });
+    req.end();
+  });
+}
+
+/** Readiness for private serves: valid client + denied anonymous HTTP AND WS.
+ * An unmanaged, passwordless API is never adopted. Errors contain no secrets.
+ */
+export async function checkPrivateOpencodeServer(options = {}) {
+  const check = await checkOpencodeServer(options);
+  if (!check.ok) return check;
+  const refused = () => ({ ok: false, version: check.version, state: 'unsecured',
+    error: 'OpenCode did not prove private HTTP and WebSocket authentication; it will not be used.' });
+  if (!options.password) return refused();
+  try {
+    const response = await (options.fetchImpl || globalThis.fetch)(`http://127.0.0.1:${options.port}/api/info`, {
+      headers: { accept: 'application/json' }, signal: AbortSignal.timeout(options.timeoutMs || 2000), redirect: 'error',
+    });
+    await response.body?.cancel();
+    if (response.status !== 401 || await probeUnauthenticatedUpgrade(options) !== 401) return refused();
+  } catch { return refused(); }
+  return check;
 }
 
 /**
  * The sentence a person reads when OpenCode cannot be used: what was found and
- * what to do. `check` is a checkOpencodeServer answer, `detected` a
- * protocolForVersion answer.
+ * what to do. `check` is a checkOpencodeServer answer, `detected` an
+ * opencodeSupportFor answer.
  */
 export function opencodeProblemText({ check = null, detected = null, port = null } = {}) {
   if (detected && !detected.supported) return detected.reason;
   if (!check || check.ok) return '';
   const where = port ? ` on port ${port}` : '';
   switch (check.state) {
+    case 'unsupported':
+      return check.error || `The OpenCode server${where} is a version SynaBun does not drive.`;
     case 'locked':
-      return `An OpenCode 2 server SynaBun did not start is already running${where}, and SynaBun does not have its password. Stop that server (or free the port) and start OpenCode again from SynaBun.`;
-    case 'mismatch':
-      return `The OpenCode server${where} is not the version SynaBun found on this computer (${check.error}). Stop it and start OpenCode again from SynaBun.`;
+      return `An OpenCode server SynaBun did not start is already running${where}, and SynaBun does not have its password. Stop that server (or free the port) and start OpenCode again from SynaBun.`;
     case 'html':
-      return `Something${where} answers with a web page instead of the OpenCode API (${check.error}).`;
+      return `Something${where} answers with a web page instead of the OpenCode 2 API (${check.error}).`;
     case 'down':
       return `OpenCode is not answering${where}.`;
     default:
-      return `OpenCode${where} did not answer as expected: ${check.error || 'unknown error'}.`;
+      return `OpenCode${where} did not answer as OpenCode 2: ${check.error || 'unknown error'}.`;
   }
 }

package/neural-interface/lib/opencode-runtime-config.js

@@ -1,35 +1,33 @@
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { mcpServersOf, normalizeMcpServers, parseJsonc, setMcpServer, withPlugin } from './opencode-config.js';
 
-/** The browser-policy plugin (assistant-brains/opencode-browser-policy.js) as a file URL a serve can load. */
-export const OPENCODE_BROWSER_POLICY_PLUGIN = pathToFileURL(resolve(dirname(fileURLToPath(import.meta.url)), 'assistant-brains', 'opencode-browser-policy.js')).href;
-/** Its OpenCode 2 form: a plugin folder, listed under `plugins` (OpenCode 1 ignores that key). */
-export const OPENCODE2_BROWSER_POLICY_PLUGIN = pathToFileURL(resolve(dirname(fileURLToPath(import.meta.url)), 'assistant-brains', 'opencode2-browser-policy')).href;
+/** The browser-policy plugin (assistant-brains/opencode2-browser-policy/, a plugin folder) as a file URL a serve can load. */
+export const OPENCODE_BROWSER_POLICY_PLUGIN = pathToFileURL(resolve(dirname(fileURLToPath(import.meta.url)), 'assistant-brains', 'opencode2-browser-policy')).href;
 
 /**
  * An Assistant task run's serve config gets SynaBun's browser policy as a
- * plugin (`cwd`: the run's project, for the scripts it reads), for OpenCode 1
- * (`plugin`) and OpenCode 2 (`plugins`). The user's own plugins stay; an
- * earlier entry of ours is replaced. Returns `config`.
+ * plugin (`cwd`: the run's project, for the scripts it reads; `roots`: the
+ * registered code projects its test runners may also run in, as the run
+ * starts), listed under `plugins`. The user's own plugins stay; an earlier
+ * entry of ours is replaced. Returns `config`.
  */
-export function withOpenCodeBrowserPolicy(config, { cwd = null } = {}) {
-  const options = cwd ? { cwd: String(cwd) } : {};
-  const plugins = (Array.isArray(config.plugin) ? config.plugin : []).filter((entry) => (Array.isArray(entry) ? entry[0] : entry) !== OPENCODE_BROWSER_POLICY_PLUGIN);
-  plugins.push([OPENCODE_BROWSER_POLICY_PLUGIN, options]);
-  config.plugin = plugins;
-  const plugins2 = (Array.isArray(config.plugins) ? config.plugins : []).filter((entry) => (entry && typeof entry === 'object' ? entry.package : entry) !== OPENCODE2_BROWSER_POLICY_PLUGIN);
-  plugins2.push({ package: OPENCODE2_BROWSER_POLICY_PLUGIN, options });
-  config.plugins = plugins2;
-  return config;
+export function withOpenCodeBrowserPolicy(config, { cwd = null, roots = [] } = {}) {
+  const list = (Array.isArray(roots) ? roots : []).filter((path) => typeof path === 'string' && path);
+  return withPlugin(config, OPENCODE_BROWSER_POLICY_PLUGIN, { ...(cwd ? { cwd: String(cwd) } : {}), ...(list.length ? { roots: list } : {}) });
 }
 
 /**
- * Build the SynaBun MCP entry used by managed OpenCode runtimes.
+ * Build the SynaBun MCP entry used by managed OpenCode runtimes, in OpenCode
+ * 2's shape (`mcp.servers.SynaBun`: type local, the command as an array, its
+ * `environment`).
  *
  * Managed sidepanels/automations must always use a local MCP child. Reusing a
  * user's remote entry would ignore process environment pins and collapse all
- * sessions onto the shared HTTP server. Preserve harmless local options, but
- * remove remote-only transport fields and canonicalize command/environment.
+ * sessions onto the shared HTTP server. Preserve harmless local options (its
+ * timeout, its working folder), but remove remote-only transport fields and a
+ * switch that turned it off, and canonicalize command/environment. SynaBun tools are always direct calls;
+ * OpenCode 2.1 otherwise hides them behind Code Mode (`execute`). Other servers keep their own settings.
  */
 export function buildManagedOpenCodeSynabunEntry(existing, {
   command,
@@ -45,7 +43,10 @@ export function buildManagedOpenCodeSynabunEntry(existing, {
     environment: _environment,
     env: _env,
     command: _command,
+    args: _args,
     type: _type,
+    enabled: _enabled,
+    disabled: _disabled,
     ...safeOptions
   } = source;
   const environment = {
@@ -57,9 +58,18 @@ export function buildManagedOpenCodeSynabunEntry(existing, {
   return {
     ...safeOptions,
     type: 'local',
-    command: Array.isArray(command) ? [...command] : command,
-    enabled: true,
+    codemode: false,
+    command: Array.isArray(command) ? [...command] : [command],
     environment,
-    env: { ...environment },
   };
 }
+
+/** Pin only SynaBun on the shared serve, preserving an inherited overlay and the owner's other servers. */
+export function buildSharedOpenCodeConfigOverlay(config, content) {
+  const overlay = normalizeMcpServers(parseJsonc(content || '{}'));
+  const synabun = mcpServersOf(config).SynaBun;
+  const inherited = mcpServersOf(overlay).SynaBun;
+  if (!synabun && !inherited) return content;
+  setMcpServer(overlay, 'SynaBun', { ...synabun, ...inherited, codemode: false });
+  return JSON.stringify(overlay);
+}