ruvnet-brain 4.5.4 → 4.5.6

package/scripts/model-terminal-gateway.mjs

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+// Per-launch Unix WebSocket adapter for the native subscription TUI. No daemon lifecycle ownership.
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import http from 'node:http';
+import { Duplex, PassThrough, Writable } from 'node:stream';
+import { EventEmitter } from 'node:events';
+import { StringDecoder } from 'node:string_decoder';
+import { spawn } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+import { connectNativeGateway, decideNativeTurn, nativeGatewayLaunch } from './model-routing-gateway.mjs';
+import { subscriptionEnvironment, assertSubscriptionAuth } from './model-router-dispatch.mjs';
+
+export const MAX_TERMINAL_BYTES = 64 * 1024 * 1024;
+const REFUSED = 'Native terminal routing unavailable; request was not sent.';
+const COMMANDS = new Set(['agents', 'exec', 'e', 'review', 'login', 'logout', 'mcp', 'plugin', 'app-server',
+  'remote-control', 'app', 'completion', 'update', 'doctor', 'sandbox', 'debug', 'apply', 'a', 'resume',
+  'queue', 'archive', 'delete', 'migrate-rollouts', 'unarchive', 'fork', 'cloud', 'exec-server', 'features', 'help']);
+const ADMIN = new Set(['login', 'logout', 'mcp', 'plugin', 'completion', 'update', 'doctor', 'features', 'help']);
+const VALUES = new Set(['-c', '--config', '--enable', '--disable', '-i', '--image', '-m', '--model',
+  '-p', '--profile', '-s', '--sandbox', '-C', '--cd', '--add-dir', '-a', '--ask-for-approval']);
+
+/** Short Unix roots avoid long environment-provided temp paths; Windows has no qualified transport. */
+export function terminalTempRoot(platform = process.platform) {
+  if (!['darwin', 'linux'].includes(platform)) throw new Error('Native Unix terminal routing requires macOS or Linux');
+  return platform === 'darwin' ? '/private/tmp' : '/tmp';
+}
+
+/** Keep native arguments verbatim; only proved interactive paths may enter the routed transport. */
+export function classifyTerminalArguments(args = []) {
+  if (args.some((arg) => /^--(?:remote(?:-auth-token-env)?|no-daemon)(?:=|$)/.test(arg))) {
+    throw new Error('Explicit remote or no-daemon transport conflicts with terminal routing');
+  }
+  let first;
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === '--') return 'interactive'; // Native '--' ends subcommand parsing: following words are prompts.
+    if (VALUES.has(arg)) { index++; continue; }
+    if (arg.startsWith('-')) continue;
+    first = arg; break;
+  }
+  if (ADMIN.has(first) || (!first && args.some((arg) => ['--help', '-h', '--version', '-V'].includes(arg)))) return 'admin';
+  if (COMMANDS.has(first) && !['resume', 'fork'].includes(first)) {
+    throw new Error(`Native command ${first} has no proved terminal routing transport`);
+  }
+  return 'interactive';
+}
+
+/** Reject symlinks and foreign/group-accessible endpoints, including their containing directory. */
+export function validateUpstreamSocket(socketPath, { uid = process.getuid?.() } = {}) {
+  if (!path.isAbsolute(socketPath || '') || uid == null) throw new Error('Owned absolute Unix socket required');
+  const normalized = path.normalize(socketPath);
+  let current = normalized;
+  while (true) {
+    const entry = fs.lstatSync(current);
+    if (entry.isSymbolicLink()) throw new Error('Symlink in upstream socket path refused');
+    if (current === normalized && (!entry.isSocket() || entry.uid !== uid || (entry.mode & 0o077))) {
+      throw new Error('Upstream must be an owned private Unix socket');
+    }
+    if (current === path.dirname(normalized) && (!entry.isDirectory() || entry.uid !== uid || (entry.mode & 0o077))) {
+      throw new Error('Upstream socket directory must be owned and private');
+    }
+    if (current === path.dirname(current)) break;
+    current = path.dirname(current);
+  }
+  return normalized;
+}
+
+function jsonPacket(text) {
+  const packet = JSON.parse(text);
+  if (!packet || typeof packet !== 'object' || Array.isArray(packet)
+    || !(typeof packet.method === 'string' || (Object.hasOwn(packet, 'id')
+      && (Object.hasOwn(packet, 'result') || Object.hasOwn(packet, 'error'))))) throw new Error(REFUSED);
+  if (Object.hasOwn(packet, 'id') && !(typeof packet.id === 'string' || Number.isSafeInteger(packet.id))) throw new Error(REFUSED);
+  return packet;
+}
+
+/** Official proxy is a byte tunnel: perform the daemon's /rpc WebSocket handshake over its stdio. */
+export async function connectProxyWebSocket(proxy, { startupMs = 10000, maxBytes = MAX_TERMINAL_BYTES } = {}) {
+  const { WebSocket } = await import('ws');
+  const tunnel = Duplex.from({ readable: proxy.stdout, writable: proxy.stdin });
+  // createConnection always returns the owned tunnel; even the placeholder endpoint is Unix-only.
+  const ws = new WebSocket('ws+unix:///native-proxy:/rpc', { createConnection: () => tunnel,
+    perMessageDeflate: false, maxPayload: maxBytes, handshakeTimeout: startupMs, followRedirects: false });
+  const child = new EventEmitter(); child.on('error', () => {});
+  child.stdout = new PassThrough({ highWaterMark: 65536 }); child.stderr = proxy.stderr;
+  child.exitCode = null; child.signalCode = null;
+  let closed = false, ready = false, buffer = '';
+  const decoder = new StringDecoder('utf8');
+  const fail = () => { if (!closed) { child.emit('error', new Error(REFUSED)); child.kill('SIGTERM'); } };
+  child.kill = (signal) => {
+    if (closed && signal !== 'SIGKILL') return;
+    if (!closed) { closed = true; ws.terminate(); tunnel.destroy(); }
+    const sent = proxy.kill(signal);
+    if (signal !== 'SIGKILL') {
+      const killer = setTimeout(() => { if (proxy.exitCode == null && proxy.signalCode == null) proxy.kill('SIGKILL'); }, 1000);
+      killer.unref(); proxy.once('exit', () => clearTimeout(killer));
+    } child.exitCode = proxy.exitCode; child.signalCode = proxy.signalCode;
+    return sent;
+  };
+  child.stdin = new Writable({ highWaterMark: 65536, write(chunk, _encoding, callback) {
+    try {
+      buffer += decoder.write(chunk); if (Buffer.byteLength(buffer) > maxBytes) throw new Error(REFUSED);
+      const lines = buffer.split('\n'); buffer = lines.pop(); let index = 0;
+      const send = () => {
+        if (index === lines.length) { callback(); return; }
+        const line = lines[index++]; jsonPacket(line);
+        if (closed || ws.readyState !== WebSocket.OPEN || ws.bufferedAmount + Buffer.byteLength(line) > maxBytes) throw new Error(REFUSED);
+        ws.send(line, { binary: false }, (error) => {
+          if (error) { callback(error); fail(); return; }
+          try { send(); } catch (error) { callback(error); fail(); }
+        });
+      }; send();
+    } catch (error) { callback(error); fail(); }
+  } });
+  child.stdin.on('error', fail); child.stdout.on('error', fail);
+  ws.on('message', (bytes, binary) => {
+    try {
+      if (binary || bytes.length > maxBytes || child.stdout.writableLength + bytes.length + 1 > maxBytes) throw new Error(REFUSED);
+      const line = new TextDecoder('utf-8', { fatal: true }).decode(bytes); jsonPacket(line);
+      if (!child.stdout.write(line + '\n')) ws.pause();
+    } catch { fail(); }
+  });
+  child.stdout.on('drain', () => { if (!closed) ws.resume(); });
+  proxy.once('error', (error) => child.emit('error', error));
+  proxy.once('exit', (code, signal) => {
+    child.exitCode = code; child.signalCode = signal; child.emit('exit', code, signal);
+    if (!closed) { closed = true; ws.terminate(); tunnel.destroy(); }
+  });
+  ws.on('error', () => { if (ready) fail(); });
+  ws.once('close', () => { if (ready && !closed) fail(); });
+  try {
+    await new Promise((resolve, reject) => {
+      const rejectProxy = () => reject(new Error(REFUSED));
+      proxy.once('exit', rejectProxy); proxy.once('error', rejectProxy);
+      ws.once('error', rejectProxy); ws.once('close', rejectProxy);
+      ws.once('open', () => { proxy.removeListener('exit', rejectProxy); proxy.removeListener('error', rejectProxy);
+        ws.removeListener('error', rejectProxy); ws.removeListener('close', rejectProxy); ready = true; resolve(); });
+    });
+  } catch (error) { child.kill('SIGTERM'); throw error; }
+  return child;
+}
+
+/** Real HTTP/WebSocket framing over one private Unix socket, converted to native JSONL streams. */
+export async function createTerminalTransport({ child, diagnostics = process.stderr, gatewayOptions = {},
+  tempRoot, maxBytes = MAX_TERMINAL_BYTES, startupMs = 10000, onFailure = () => {} } = {}) {
+  const defaultTempRoot = terminalTempRoot();
+  const { WebSocketServer, WebSocket } = await import('ws');
+  if (!child?.stdin || !child?.stdout) throw new Error('Native proxy child required');
+  if (!(maxBytes > 0 && maxBytes <= MAX_TERMINAL_BYTES)) throw new Error('Invalid transport byte bound');
+  const directory = fs.mkdtempSync(path.join(fs.realpathSync(tempRoot ?? defaultTempRoot), 'crt-'));
+  fs.chmodSync(directory, 0o700);
+  const socketPath = path.join(directory, 'r.sock');
+  if (Buffer.byteLength(socketPath) > 100) { fs.rmSync(directory, { recursive: true }); throw new Error('Unix socket path too long'); }
+  const server = http.createServer((_request, response) => { response.writeHead(403); response.end(); });
+  const wss = new WebSocketServer({ noServer: true, maxPayload: maxBytes, perMessageDeflate: false });
+  const input = new PassThrough({ highWaterMark: 65536 });
+  let client, claimed = false, gateway, closed = false, outputBuffer = '', failed = false;
+  const decoder = new StringDecoder('utf8'), initializations = new Set();
+  let resolveConnected, resolveReady;
+  const connected = new Promise((resolve) => { resolveConnected = resolve; });
+  const ready = new Promise((resolve) => { resolveReady = resolve; });
+  const close = () => {
+    if (closed) return;
+    closed = true; clearTimeout(timer); gateway?.close(); input.destroy(); output.destroy();
+    client?.terminate(); wss.close(); server.close();
+    // This is the only child and filesystem tree owned by this launch.
+    child.kill?.('SIGTERM');
+    const killer = setTimeout(() => { if (child.exitCode == null && child.signalCode == null) child.kill?.('SIGKILL'); }, 1000);
+    killer.unref(); child.once?.('exit', () => clearTimeout(killer));
+    fs.rmSync(directory, { recursive: true, force: true }); resolveConnected(false); resolveReady(false);
+  };
+  const fail = () => {
+    if (closed) return;
+    failed = true; diagnostics.write(`[native-terminal-routing] ${REFUSED}\n`); close(); onFailure();
+  };
+  const output = new Writable({ highWaterMark: 65536, write(chunk, _encoding, callback) {
+    try {
+      outputBuffer += decoder.write(chunk);
+      if (Buffer.byteLength(outputBuffer) > maxBytes) throw new Error(REFUSED);
+      const lines = outputBuffer.split('\n'); outputBuffer = lines.pop();
+      let index = 0;
+      const send = () => {
+        if (index >= lines.length) { callback(); return; }
+        const line = lines[index++], packet = jsonPacket(line);
+        if (initializations.has(packet.id)) {
+          if (packet.error) throw new Error(REFUSED);
+          initializations.delete(packet.id); clearTimeout(timer); resolveReady(true);
+        }
+        if (closed || client?.readyState !== WebSocket.OPEN || client.bufferedAmount + Buffer.byteLength(line) > maxBytes) throw new Error(REFUSED);
+        client.send(line, { binary: false }, (error) => {
+          if (error) { callback(error); fail(); return; }
+          try { send(); } catch (error) { callback(error); fail(); }
+        });
+      };
+      send();
+    } catch (error) { callback(error); fail(); }
+  } });
+  output.on('error', fail); input.on('error', fail);
+  const timer = setTimeout(fail, startupMs);
+  server.on('error', fail); wss.on('error', fail);
+  server.on('upgrade', (request, socket, head) => {
+    // Refuse a second client for this launch, including reconnect after disconnect.
+    if (closed || claimed || request.url !== '/rpc' || request.headers.origin) {
+      socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n'); return;
+    }
+    claimed = true;
+    wss.handleUpgrade(request, socket, head, (ws) => wss.emit('connection', ws));
+  });
+  wss.on('connection', (ws) => {
+    client = ws;
+    gateway = connectNativeGateway({ ...gatewayOptions, harness: 'codex', child, input, output, diagnostics });
+    ws.on('message', (bytes, binary) => {
+      try {
+        if (binary || bytes.length > maxBytes || closed) throw new Error(REFUSED);
+        const line = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+        const packet = jsonPacket(line);
+        if (packet.method === 'initialize' && Object.hasOwn(packet, 'id')) initializations.add(packet.id);
+        // Shared daemon ownership never crosses this per-client boundary.
+        if (['shutdown', 'exit'].includes(packet.method)) {
+          if (Object.hasOwn(packet, 'id')) ws.send(JSON.stringify({ id: packet.id, error: { code: -32001, message: 'Shared daemon shutdown refused' } }));
+          return;
+        }
+        if (gateway.spoolState().queuedBytes + input.writableLength + Buffer.byteLength(line) + 1 > maxBytes) throw new Error(REFUSED);
+        if (!input.write(JSON.stringify(packet) + '\n')) ws.pause();
+      } catch { fail(); }
+    });
+    input.on('drain', () => { if (!closed) ws.resume(); });
+    ws.once('close', close); ws.on('error', fail); resolveConnected(true);
+  });
+  child.once('error', fail); child.once('exit', fail);
+  child.stdin.on('error', fail); child.stdout.on('error', fail);
+  try {
+    await new Promise((resolve, reject) => {
+      server.once('error', reject); server.listen(socketPath, () => { server.removeListener('error', reject); resolve(); });
+    });
+    if (closed) throw new Error(REFUSED);
+    fs.chmodSync(socketPath, 0o600);
+  } catch (error) { close(); throw error; }
+  return { socketPath, directory, remote: `unix://${socketPath}`, connected, ready, close,
+    failed: () => failed, gateway: () => gateway };
+}
+
+export function parseTerminalInvocation(argv, env = process.env) {
+  const args = [...argv]; let realBinary = env.MODEL_ROUTER_REAL_CODEX, upstreamSocket;
+  while (args.length && args[0] !== '--') {
+    const flag = args.shift();
+    if (!['--real-binary', '--upstream-socket'].includes(flag) || !args.length) throw new Error('Explicit terminal gateway options required');
+    if (flag === '--real-binary') realBinary = args.shift(); else upstreamSocket = args.shift();
+  }
+  if (args[0] === '--') args.shift();
+  return { realBinary, upstreamSocket, args, env };
+}
+
+export async function runTerminalGateway({ realBinary, upstreamSocket, args = [], env = process.env,
+  spawnNative = spawn, adaptProxy = connectProxyWebSocket, gatewayOptions = {}, startupMs = 10000, tempRoot,
+  signalSource = process, diagnostics = process.stderr } = {}) {
+  if (!path.isAbsolute(realBinary || '')) throw new Error('Explicit absolute native executable required');
+  const binary = fs.realpathSync(realBinary), clean = subscriptionEnvironment(env);
+  if (env.MODEL_ROUTER_TERMINAL_ACTIVE || env.MODEL_ROUTER_GATEWAY_ACTIVE) throw new Error('Terminal routing recursion refused');
+  const mode = classifyTerminalArguments(args);
+  if (mode === 'admin') {
+    const child = spawnNative(binary, args, { env: clean, shell: false, stdio: 'inherit' });
+    return await exitOf(child);
+  }
+  const defaultTempRoot = terminalTempRoot();
+  tempRoot ??= defaultTempRoot;
+  // Reuse the established provider/config guards; this does not spawn app-server.
+  const normalized = nativeGatewayLaunch({ harness: 'codex', realBinary: binary, args: ['app-server', ...args], env: clean });
+  // Native global options precede the original subcommand/prompt, including a literal '--'.
+  const standardOverrides = normalized.args.slice(args.length + 1);
+  const socketPath = validateUpstreamSocket(upstreamSocket || path.join(clean.CODEX_HOME || path.join(os.homedir(), '.codex'), 'app-server-control', 'app-server-control.sock'));
+  const auth = () => assertSubscriptionAuth('codex', { env: clean }); auth();
+  clean.MODEL_ROUTER_TERMINAL_ACTIVE = '1';
+  const proxy = spawnNative(binary, ['app-server', 'proxy', '--sock', socketPath], { env: clean, shell: false, stdio: ['pipe', 'pipe', 'pipe'] });
+  let tui, transport, forcedFailure = false;
+  const handlers = new Map();
+  try {
+    const backend = await adaptProxy(proxy, { startupMs });
+    transport = await createTerminalTransport({ child: backend, diagnostics, startupMs, tempRoot,
+      onFailure: () => { forcedFailure = true; tui?.kill('SIGTERM'); },
+      gatewayOptions: { ...gatewayOptions, checkAuth: auth,
+        decide: gatewayOptions.decide || ((prompt, harness, metadata) => decideNativeTurn(prompt, harness, { env: clean, ...metadata })) } });
+    if (transport.failed()) throw new Error(REFUSED);
+    tui = spawnNative(binary, ['--remote', transport.remote, ...standardOverrides, ...args], { env: clean, shell: false, stdio: 'inherit' });
+    for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+      const handler = () => { transport.close(); tui.kill(signal); };
+      handlers.set(signal, handler); signalSource.on(signal, handler);
+    }
+    const result = await exitOf(tui);
+    return forcedFailure ? { code: 1, signal: null } : result;
+  } finally {
+    handlers.forEach((handler, signal) => signalSource.removeListener(signal, handler));
+    if (transport) transport.close(); else proxy.kill('SIGTERM');
+  }
+}
+
+function exitOf(child) {
+  return new Promise((resolve, reject) => {
+    child.once('error', reject); child.once('exit', (code, signal) => resolve({ code, signal }));
+  });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runTerminalGateway(parseTerminalInvocation(process.argv.slice(2))).then(({ code, signal }) => {
+    if (signal) { process.removeAllListeners(signal); process.kill(process.pid, signal); }
+    else process.exitCode = code ?? 1;
+  }).catch((error) => { process.stderr.write(`[native-terminal-routing] ${error.message}\n`); process.exitCode = 1; });
+}

package/scripts/model-terminal-launchers.mjs

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+// Explicit per-user terminal integration. Native binaries and authentication remain user owned.
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { spawn, execFileSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { classifyTerminalArguments, validateUpstreamSocket, terminalTempRoot } from './model-terminal-gateway.mjs';
+import { nativeGatewayLaunch } from './model-routing-gateway.mjs';
+import { subscriptionEnvironment, assertSubscriptionAuth } from './model-router-dispatch.mjs';
+
+const SELF = fileURLToPath(import.meta.url);
+const MARKER = '# Managed RuvNet Brain terminal launcher';
+const START = '# >>> RuvNet Brain terminal routing >>>';
+const END = '# <<< RuvNet Brain terminal routing <<<';
+const quote = (v) => `'${String(v).replaceAll("'", "'\\''")}'`;
+const digest = (v) => crypto.createHash('sha256').update(v).digest('hex');
+
+function regular(file, { privateFile = false } = {}) {
+  if (!path.isAbsolute(file || '')) throw new Error('Absolute file path required');
+  const stat = fs.lstatSync(file);
+  const ownerAllowed = stat.uid === process.getuid?.() || (!privateFile && stat.uid === 0);
+  if (!stat.isFile() || stat.isSymbolicLink() || !ownerAllowed ||
+      (privateFile && (stat.mode & 0o077))) throw new Error(`Owned regular file required: ${file}`);
+  return fs.realpathSync(file);
+}
+function executable(file) {
+  const result = regular(fs.realpathSync(file)); fs.accessSync(result, fs.constants.X_OK); return result;
+}
+function atomic(file, content, mode = 0o600) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  if (fs.existsSync(file)) regular(file);
+  const temp = `${file}.${crypto.randomUUID()}.tmp`;
+  try {
+    const fd = fs.openSync(temp, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, mode);
+    try { fs.writeFileSync(fd, content); fs.fchmodSync(fd, mode); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+    fs.renameSync(temp, file);
+  } finally { fs.rmSync(temp, { force: true }); }
+}
+function backup(file) {
+  if (!fs.existsSync(file)) return null;
+  const bytes = fs.readFileSync(regular(file)); const target = `${file}.${digest(bytes)}.original`;
+  if (fs.existsSync(target)) {
+    if (digest(fs.readFileSync(regular(target))) !== digest(bytes)) throw new Error('Backup digest mismatch');
+  } else fs.writeFileSync(target, bytes, { flag: 'wx', mode: 0o400 });
+  return target;
+}
+
+/** Follow only the native daemon's known user-owned locator, then validate the actual private endpoint. */
+export function resolveTerminalUpstream({ codexHome = path.join(os.homedir(), '.codex'), uid = process.getuid?.(),
+  daemonRoot = terminalTempRoot() } = {}) {
+  if (!path.isAbsolute(codexHome) || !path.isAbsolute(daemonRoot) || uid == null) throw new Error('Absolute owned socket locator required');
+  const home = fs.realpathSync(codexHome);
+  const directory = path.join(home, 'app-server-control');
+  const d = fs.lstatSync(directory);
+  if (!d.isDirectory() || d.isSymbolicLink() || d.uid !== uid || (d.mode & 0o022)) throw new Error('Native socket locator directory is not owned and protected');
+  const locator = path.join(directory, 'app-server-control.sock');
+  const s = fs.lstatSync(locator);
+  if (!s.isSymbolicLink()) return validateUpstreamSocket(locator, { uid });
+  if (s.uid !== uid) throw new Error('Native socket locator is foreign');
+  const actual = fs.realpathSync(locator);
+  const expected = path.join(fs.realpathSync(daemonRoot), `codex-daemon-${uid}`);
+  if (path.dirname(actual) !== expected || !/^[a-f0-9]{64}$/.test(path.basename(actual))) throw new Error('Native socket locator escaped the known daemon endpoint');
+  return validateUpstreamSocket(actual, { uid });
+}
+
+function unmanagedShellNames(text) {
+  return ['codex', 'claude'].filter((name) => new RegExp(`(?:^|\\n)\\s*(?:alias\\s+${name}\\s*=|(?:function\\s+)?${name}\\s*\\(\\s*\\)|function\\s+${name}\\s*(?:\\{|\\n))`).test(text));
+}
+export function terminalShellPlan(text, sourcePath, launchers) {
+  const starts = text.split(START).length - 1, ends = text.split(END).length - 1;
+  if (starts !== ends || starts > 1) throw new Error('Malformed managed terminal shell block');
+  const block = starts ? text.slice(text.indexOf(START), text.indexOf(END) + END.length) : null;
+  const outside = block ? text.replace(block, '') : text;
+  const conflicts = unmanagedShellNames(outside);
+  const lines = [MARKER];
+  for (const name of ['codex', 'claude']) {
+    if (launchers[name] && !conflicts.includes(name)) lines.push(`function ${name}() { ${quote(launchers[name])} "$@"; }`);
+  }
+  const managed = `${START}\nsource ${quote(sourcePath)}\n${END}`;
+  return { conflicts, source: lines.join('\n') + '\n', zshrc: block ? text.replace(block, managed) : `${text}${text && !text.endsWith('\n') ? '\n' : ''}${managed}\n` };
+}
+
+/** Runtime is supplied by the snapshot installer; this module does not rebuild or mutate it. */
+export function installTerminalLaunchers({ home = os.homedir(), nodeBinary = process.execPath, runtimeRoot,
+  runtimeDigest, realCodex = path.join(home, '.local/bin/codex'), realClaude, apply = false, manageZsh = true } = {}) {
+  if (!['darwin', 'linux'].includes(process.platform)) throw new Error('Terminal launchers require macOS or Linux');
+  if (!path.isAbsolute(home) || !path.isAbsolute(runtimeRoot || '') || !/^[a-f0-9]{64}$/.test(runtimeDigest || '')) throw new Error('Absolute home and identified runtime required');
+  const runner = regular(path.join(runtimeRoot, 'scripts/model-terminal-launchers.mjs'));
+  const config = { schemaVersion: 1, managedBy: 'ruvnet-brain-terminal-launchers', runtimeDigest, runtimeRoot: fs.realpathSync(runtimeRoot), nodeBinary: executable(nodeBinary),
+    runner, realCodex: executable(realCodex), gatewayPath: regular(path.join(runtimeRoot, 'scripts/model-terminal-gateway.mjs')) };
+  if (realClaude) {
+    config.realClaude = executable(realClaude);
+    config.claudeHelperPath = regular(path.join(runtimeRoot, 'scripts/claude-terminal-mod.mjs'));
+    config.enginePath = regular(path.join(runtimeRoot, 'scripts/model-router-engine.mjs'));
+  }
+  const configPath = path.join(home, '.cache/ruvnet-brain/model-routing/terminal-launcher-config.json');
+  if (fs.existsSync(configPath) && JSON.parse(fs.readFileSync(regular(configPath), 'utf8')).managedBy !== config.managedBy) throw new Error('Preserving unmanaged terminal configuration');
+  const launchers = { codex: path.join(home, '.local/bin/ruvnet-brain-codex-terminal') };
+  if (realClaude) launchers.claude = path.join(home, '.local/bin/ruvnet-brain-claude-terminal');
+  const contents = Object.fromEntries(Object.entries(launchers).map(([host, file]) => [file,
+    `#!/bin/sh\n${MARKER}\nexec ${quote(config.nodeBinary)} ${quote(runner)} --launch ${quote(host)} --config ${quote(configPath)} -- "$@"\n`]));
+  const shellSource = path.join(home, '.config/ruvnet-brain/terminal-routing.zsh');
+  const zshrc = path.join(home, '.zshrc');
+  const shell = terminalShellPlan(fs.existsSync(zshrc) ? fs.readFileSync(regular(zshrc), 'utf8') : '', shellSource, launchers);
+  for (const file of [...Object.keys(contents), shellSource]) {
+    if (fs.existsSync(file) && !fs.readFileSync(regular(file), 'utf8').includes(MARKER)) throw new Error(`Preserving unmanaged terminal integration: ${file}`);
+  }
+  for (const binary of [config.realCodex, config.realClaude].filter(Boolean)) {
+    if ([runner, ...Object.keys(contents)].includes(binary)) throw new Error('Native terminal launcher recursion refused');
+  }
+  const receipt = { apply, launchers, configPath, config, shellSource, shellConflicts: shell.conflicts, backups: [],
+    claudeEnforcementScope: realClaude ? 'Startup hook activation guard; continuing native worker enforcement requires separate proof' : null };
+  if (!apply) return receipt;
+  for (const file of [configPath, ...Object.keys(contents), ...(manageZsh ? [shellSource, zshrc] : [])]) {
+    const original = backup(file); if (original) receipt.backups.push(original);
+  }
+  atomic(configPath, JSON.stringify(config, null, 2) + '\n');
+  for (const [file, content] of Object.entries(contents)) atomic(file, content, 0o755);
+  if (manageZsh) { atomic(shellSource, shell.source); atomic(zshrc, shell.zshrc, fs.existsSync(zshrc) ? fs.statSync(zshrc).mode & 0o777 : 0o600); }
+  return receipt;
+}
+
+/** Supported native start is idempotent; never stop, restart, update or own the shared daemon. */
+export function ensureTerminalDaemon(binary, env = process.env, { exec = execFileSync } = {}) {
+  try {
+    exec(binary, ['app-server', 'daemon', 'start'], { env: subscriptionEnvironment(env), timeout: 10000,
+      stdio: 'ignore', shell: false, maxBuffer: 65536 });
+  } catch { throw new Error('Native Codex daemon start unavailable; terminal launch blocked'); }
+}
+export function terminalInvocation({ host, args = [], config, env = process.env, daemonExec = execFileSync }) {
+  if (config.schemaVersion !== 1 || env.RNB_TERMINAL_LAUNCH_ACTIVE) throw new Error('Invalid or recursive terminal launch');
+  const binary = executable(host === 'codex' ? config.realCodex : config.realClaude);
+  if (host !== 'codex') throw new Error('Use guarded native Claude launch');
+  const mode = classifyTerminalArguments(args);
+  if (mode === 'admin') return { command: binary, args: [...args], routed: false };
+  // Validate provider/transport overrides before native daemon startup has any side effect.
+  nativeGatewayLaunch({ harness: 'codex', realBinary: binary, args: ['app-server', ...args], env: subscriptionEnvironment(env) });
+  ensureTerminalDaemon(binary, env, { exec: daemonExec });
+  const upstream = resolveTerminalUpstream({ codexHome: env.CODEX_HOME || path.join(os.homedir(), '.codex') });
+  return { command: executable(config.nodeBinary), args: [regular(config.gatewayPath), '--real-binary', binary, '--upstream-socket', upstream, '--', ...args], routed: true };
+}
+
+export function verifyNativeWorkerAncestry(workerPid, nativePid, { uid = process.getuid?.() } = {}) {
+  if (![workerPid, nativePid, uid].every(Number.isSafeInteger) || workerPid <= 0 || nativePid <= 0) return false;
+  let current = workerPid;
+  for (let depth = 0; depth < 12; depth++) {
+    let result;
+    try { result = execFileSync('/bin/ps', ['-o', 'uid=,ppid=', '-p', String(current)], { encoding: 'utf8', timeout: 1000, stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return false; }
+    const match = /^(\d+)\s+(\d+)$/.exec(result);
+    if (!match || Number(match[1]) !== uid) return false;
+    if (current === nativePid) return true;
+    const parent = Number(match[2]); if (parent <= 1 || parent === current) return false;
+    current = parent;
+  }
+  return false;
+}
+export function validateClaudeReadiness(file, { nonce, pluginDir, modDigest, pid, startedAt, now = Date.now() }) {
+  const receipt = JSON.parse(fs.readFileSync(regular(file, { privateFile: true }), 'utf8'));
+  const observed = Date.parse(receipt.observedAt);
+  if (receipt.schemaVersion !== 1 || receipt.nonce !== nonce || receipt.pluginRoot !== fs.realpathSync(pluginDir) ||
+      receipt.modDigest !== modDigest || !verifyNativeWorkerAncestry(receipt.pid, pid) || receipt.status !== 'ready' ||
+      !/^2\.1\.\d+$/.test(receipt.nativeVersion || '') || Number(receipt.nativeVersion.split('.')[2]) < 287 ||
+      typeof receipt.sessionId !== 'string' || !receipt.sessionId || !Number.isFinite(observed) ||
+      observed < startedAt || observed > now || now - observed > 10000) throw new Error('Native Claude hook activation receipt invalid');
+  return receipt;
+}
+function exitOf(child) {
+  return new Promise((resolve, reject) => { child.once('error', reject); child.once('exit', (code, signal) => resolve({ code, signal })); });
+}
+function forwardSignals(child, source) {
+  const handlers = new Map(['SIGINT', 'SIGTERM', 'SIGHUP'].map((signal) => [signal, () => child.kill(signal)]));
+  handlers.forEach((handler, signal) => source.on(signal, handler));
+  return () => handlers.forEach((handler, signal) => source.removeListener(signal, handler));
+}
+
+export function validateClaudeTerminalSettings({ env = process.env, cwd = process.cwd(), home = os.homedir() } = {}) {
+  for (const key of ['CLAUDE_CODE_SAFE_MODE', 'CLAUDE_CODE_SIMPLE', 'CLAUDE_CODE_DISABLE_HOOKS', 'DISABLE_CLAUDE_CODE_MODS']) {
+    if (env[key] && !['0', 'false'].includes(env[key])) throw new Error('Claude environment disables native routing hooks');
+  }
+  const files = new Set([path.join(env.CLAUDE_CONFIG_DIR || path.join(home, '.claude'), 'settings.json'),
+    process.platform === 'darwin' ? '/Library/Application Support/ClaudeCode/managed-settings.json' : '/etc/claude-code/managed-settings.json']);
+  let directory = path.resolve(cwd);
+  while (true) {
+    for (const name of ['settings.json', 'settings.local.json']) files.add(path.join(directory, '.claude', name));
+    if (directory === path.dirname(directory)) break;
+    directory = path.dirname(directory);
+  }
+  const billing = /^(?:OPENAI_API_KEY|OPENAI_BASE_URL|ANTHROPIC_API_KEY|ANTHROPIC_AUTH_TOKEN|ANTHROPIC_BASE_URL|ANTHROPIC_CUSTOM_HEADERS|CLAUDE_CODE_USE_BEDROCK|CLAUDE_CODE_USE_VERTEX|CLAUDE_CODE_USE_FOUNDRY|CODEX_API_KEY|CLAUDE_CODE_SAFE_MODE|CLAUDE_CODE_SIMPLE|CLAUDE_CODE_DISABLE_HOOKS|DISABLE_CLAUDE_CODE_MODS)$/;
+  const unsafe = (value) => value && typeof value === 'object' && Object.entries(value).some(([key, entry]) => {
+    if (key === 'env') return !entry || typeof entry !== 'object' || Array.isArray(entry) || Object.keys(entry).some((name) => billing.test(name));
+    // The user's native modelSettings are ordinary model-keyed effort settings; the mod selects each turn.
+    if (key === 'modelSettings') return !entry || typeof entry !== 'object' || Array.isArray(entry) || Object.entries(entry).some(([model, settings]) =>
+      !/^claude-[a-z0-9][a-z0-9.-]*$/.test(model) || !settings || typeof settings !== 'object' || Array.isArray(settings) ||
+      Object.entries(settings).some(([name, level]) => name !== 'effortLevel' || !['low', 'medium', 'high', 'xhigh', 'max'].includes(level)));
+    return /^(?:apiKeyHelper|api_?key|base_?url|auth_?token|customHeaders|modelProvider|model_providers|alwaysThinkingEnabled|maxEffortLevel)$/i.test(key) ||
+      key === 'fastMode' && entry !== false || unsafe(entry);
+  });
+  for (const file of files) {
+    if (!fs.existsSync(file)) continue;
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('Claude settings must be regular files');
+    let settings;
+    try { settings = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { throw new Error('Claude settings unavailable or malformed'); }
+    if (!settings || typeof settings !== 'object' || Array.isArray(settings) || unsafe(settings)) throw new Error('Claude settings conflict with native subscription routing');
+  }
+}
+export function validateClaudeTerminalArguments(args) {
+  const flags = new Set(['--continue', '-c', '--resume', '-r', '--fork-session', '--no-session-persistence',
+    '--verbose', '--dangerously-skip-permissions', '--allow-dangerously-skip-permissions']);
+  const values = new Set(['--permission-mode', '--session-id', '--add-dir']);
+  const commands = new Set(['agents', 'remote-control', 'setup-token', 'serve', 'web', 'bridge', 'completion',
+    'attach', 'auto-mode', 'gateway', 'import', 'logs', 'purge', 'respawn', 'rm', 'stop', 'kill', 'ultrareview']);
+  const options = [], prompts = [];
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === '--') { prompts.push(...args.slice(index + 1)); break; }
+    if (values.has(arg)) { if (!args[++index] || args[index].startsWith('-')) throw new Error('Claude terminal flag requires a value'); options.push(arg, args[index]); continue; }
+    if (arg.startsWith('-') && !flags.has(arg) || commands.has(arg)) throw new Error('Claude terminal arguments conflict with guarded native routing');
+    if (flags.has(arg)) {
+      options.push(arg);
+      if (['--resume', '-r'].includes(arg) && args[index + 1] && !args[index + 1].startsWith('-')) options.push(args[++index]);
+    } else prompts.push(arg);
+  }
+  return { options, prompts };
+}
+
+/** Native plugin startup only: an unloaded/crashed native worker may skip subsequent hooks. */
+export async function runClaudeTerminal({ config, args = [], env = process.env, startupMs = 10000,
+  tempRoot = os.tmpdir(), cwd = process.cwd(), signalSource = process, diagnostics = process.stderr } = {}) {
+  if (env.RNB_TERMINAL_LAUNCH_ACTIVE) throw new Error('Native terminal launcher recursion refused');
+  if (!Number.isFinite(startupMs) || startupMs <= 0 || startupMs > 60000) throw new Error('Bounded native hook startup deadline required');
+  const binary = executable(config.realClaude), clean = subscriptionEnvironment(env);
+  const information = new Set(['--help', '-h', '--version', '-v']);
+  const ownerPermissionFlags = new Set(['--dangerously-skip-permissions', '--allow-dangerously-skip-permissions']);
+  const administrative = args.some((arg) => information.has(arg)) &&
+    args.every((arg) => information.has(arg) || ownerPermissionFlags.has(arg)) ||
+    ['auth', 'mcp', 'plugin', 'plugins', 'update', 'upgrade', 'doctor', 'install'].includes(args[0]);
+  if (administrative) {
+    const child = spawn(binary, args, { env: clean, cwd, stdio: 'inherit', shell: false });
+    const unforward = forwardSignals(child, signalSource);
+    try { return await exitOf(child); } finally { unforward(); }
+  }
+  const parsed = validateClaudeTerminalArguments(args);
+  validateClaudeTerminalSettings({ env: clean, cwd });
+  assertSubscriptionAuth('claude-code', { env: clean, probe: (_name, probeArgs, options) => execFileSync(binary, probeArgs, { ...options, cwd }) });
+  const { prepareClaudeTerminalMod } = await import(pathToFileURL(regular(config.claudeHelperPath)).href);
+  const directory = fs.mkdtempSync(path.join(fs.realpathSync(tempRoot), 'rnb-claude-')); fs.chmodSync(directory, 0o700);
+  let child, unforward = () => {}, timer, killer;
+  try {
+    const prepared = prepareClaudeTerminalMod({ destination: path.join(directory, 'plugin'), nodePath: executable(config.nodeBinary),
+      helperPath: regular(config.claudeHelperPath), enginePath: regular(config.enginePath) });
+    const receiptPath = path.join(directory, 'ready.json'), nonce = crypto.randomBytes(32).toString('hex'), startedAt = Date.now();
+    Object.assign(clean, { RNB_TERMINAL_LAUNCH_ACTIVE: '1', RNB_CLAUDE_MOD_NONCE: nonce, RNB_CLAUDE_MOD_RECEIPT: receiptPath });
+    child = spawn(binary, [...parsed.options, '--plugin-dir', prepared.pluginDir, '--', ...parsed.prompts], { env: clean, cwd, stdio: 'inherit', shell: false });
+    const exited = exitOf(child); unforward = forwardSignals(child, signalSource);
+    let failure, readiness;
+    const guard = new Promise((resolve) => {
+      const check = () => {
+        try {
+          if (fs.existsSync(receiptPath)) { readiness = validateClaudeReadiness(receiptPath, { nonce, ...prepared, pid: child.pid, startedAt }); resolve(); return; }
+          if (Date.now() - startedAt >= startupMs) throw new Error('Native Claude hook activation was not acknowledged');
+          timer = setTimeout(check, 25);
+        } catch (error) { failure = error; resolve(); }
+      }; check();
+    });
+    const early = await Promise.race([guard.then(() => null), exited]);
+    if (early && !readiness) throw new Error('Native Claude exited before hook activation');
+    if (failure) {
+      child.kill('SIGTERM'); killer = setTimeout(() => child.kill('SIGKILL'), 1000);
+      await exited; throw failure;
+    }
+    diagnostics.write('[native-terminal-routing] Claude startup hooks acknowledged; continuing worker enforcement is not established by this receipt.\n');
+    return { ...(early || await exited), readinessReceipt: readiness };
+  } finally {
+    clearTimeout(timer); clearTimeout(killer); unforward();
+    if (child && child.exitCode == null && child.signalCode == null) child.kill('SIGTERM');
+    fs.rmSync(directory, { recursive: true, force: true });
+  }
+}
+
+export async function runTerminalLauncher({ host, args, config, env = process.env, signalSource = process } = {}) {
+  if (host === 'claude') return runClaudeTerminal({ config, args, env, signalSource });
+  if (host !== 'codex') throw new Error('Unsupported terminal host');
+  const invocation = terminalInvocation({ host, args, config, env });
+  const child = spawn(invocation.command, invocation.args, { env: { ...subscriptionEnvironment(env), RNB_TERMINAL_LAUNCH_ACTIVE: '1' }, stdio: 'inherit', shell: false });
+  const unforward = forwardSignals(child, signalSource);
+  try { return await exitOf(child); } finally { unforward(); }
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === SELF) {
+  const argv = process.argv.slice(2);
+  Promise.resolve().then(() => {
+    if (argv[0] !== '--launch' || argv[2] !== '--config' || argv[4] !== '--') throw new Error('Explicit host/config terminal launcher required');
+    const config = JSON.parse(fs.readFileSync(regular(argv[3], { privateFile: true }), 'utf8'));
+    return runTerminalLauncher({ host: argv[1], args: argv.slice(5), config });
+  }).then(({ code, signal }) => {
+    if (signal) process.kill(process.pid, signal); else process.exitCode = code ?? 1;
+  }).catch((error) => { process.stderr.write(`[native-terminal-routing] ${error.message}\n`); process.exitCode = 1; });
+}