ruvnet-brain 4.5.11 → 4.5.13

package/scripts/model-routing-execution-adapters.mjs

@@ -0,0 +1,318 @@
+const assertModelRoutingText = async text => (await import('./model-routing-defence.mjs')).assertModelRoutingText(text);
+// Guarded native workers for Agentic Kit's existing execution runner.
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { runControlledClaudeTurn } from './claude-controlled-terminal.mjs';
+import { validateDispatchDecision, assertSubscriptionAuth, buildLaunch, subscriptionEnvironment } from './model-router-dispatch.mjs';
+import { subscriptionOnlyEnv } from './subscription-hosts.mjs';
+import { readCodexAllowance } from './native-subscription-usage.mjs';
+
+const digest = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+const blocked = reason => Object.assign(new Error(reason), { safetyBlocked: true });
+
+export function nativeWorkflowBinaries(home = os.homedir()) {
+  const config = JSON.parse(fs.readFileSync(path.join(home, '.cache/ruvnet-brain/model-routing/terminal-launcher-config.json'), 'utf8'));
+  return { claude: config.realClaude, codex: config.realCodex };
+}
+
+export function readCodexWorkerObservation(sessionId, { home = process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), now = Date.now(), expectedPriorTurns, evidencePath, allowHistory = false } = {}) {
+  if (!/^[a-f0-9-]{36}$/.test(sessionId || '')) throw blocked('Native worker session identity missing');
+  const matches = [];
+  const directories = [];
+  const base = path.join(home, 'sessions');
+  if (evidencePath) directories.push(path.dirname(evidencePath));
+  else if ((expectedPriorTurns !== undefined || allowHistory) && fs.existsSync(base)) {
+    for (const year of fs.readdirSync(base)) if (/^\d{4}$/.test(year))
+      for (const month of fs.readdirSync(path.join(base, year))) if (/^\d{2}$/.test(month))
+        for (const day of fs.readdirSync(path.join(base, year, month))) if (/^\d{2}$/.test(day)) directories.push(path.join(base, year, month, day));
+  } else for (const offset of [0, 86400000]) {
+    const date = new Date(now - offset).toISOString().slice(0, 10).split('-');
+    directories.push(path.join(home, 'sessions', ...date));
+  }
+  for (const directory of new Set(directories)) {
+    if (!fs.existsSync(directory)) continue;
+    for (const name of fs.readdirSync(directory)) {
+      if (!name.endsWith(`-${sessionId}.jsonl`)) continue;
+      const file = path.join(directory, name), stat = fs.lstatSync(file);
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 16 * 1024 * 1024) throw blocked('Unsafe native worker evidence file');
+      matches.push({ file, bytes: fs.readFileSync(file) });
+    }
+  }
+  if (matches.length !== 1) throw blocked('Exact native worker rollout unavailable or ambiguous');
+  const rows = matches[0].bytes.toString('utf8').trim().split('\n').map(line => JSON.parse(line));
+  const contexts = rows.filter(row => row.type === 'turn_context');
+  if (!contexts.length || !allowHistory && contexts.length !== (expectedPriorTurns === undefined ? 1 : expectedPriorTurns + 1)) throw blocked('Native worker has unexpected turn history');
+  const context = contexts.at(-1).payload;
+  return { model: context.model, effort: context.effort, cwd: context.cwd, sandbox: context.sandbox_policy, sessionId,
+    turnCount: contexts.length, evidence: { path: matches[0].file, sha256: digest(matches[0].bytes), type: 'native-turn-context' } };
+}
+
+/** Only the installed user-owned Brain search server is projected into isolated native workers. */
+export function codexBrainSearchArguments(env = process.env) {
+  const server = path.join(env.HOME || os.homedir(), '.claude', 'ruvnet-brain', 'mcp', 'server.mjs');
+  if (!fs.existsSync(server)) return [];
+  const stat = fs.lstatSync(server);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.uid !== process.getuid?.()) throw blocked('Installed Brain search server is not user-owned');
+  const table = `mcp_servers.ruvnet-brain={command=${JSON.stringify(process.execPath)},args=[${JSON.stringify(server)}],enabled_tools=["search_ruvnet"],startup_timeout_sec=30,tool_timeout_sec=90,env={RUVNET_HOOK_HOST="codex"}}`;
+  return ['-c', table];
+}
+
+const CLAUDE_WORKFLOW_SCHEMAS = {"planner":{"type":"object","properties":{"tasks":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9-]{0,79}$"},"instructions":{"type":"string","minLength":1},"dependsOn":{"type":"array","items":{"type":"string"}},"mode":{"type":"string","enum":["read","write"]},"worktree":{"type":"string"},"paths":{"type":"array","items":{"type":"string"}},"checkIds":{"type":"array","items":{"type":"string"}}},"required":["id","instructions","mode","checkIds"]}}},"required":["tasks"]},"worker":{"type":"object","properties":{"outcome":{"type":"string","minLength":1},"artifacts":{"type":"array","items":{}},"decisions":{"type":"array","items":{}},"risks":{"type":"array","items":{}}},"required":["outcome","artifacts","decisions","risks"]},"reviewer":{"type":"object","properties":{"passed":{"type":"boolean"},"artifactDigest":{"type":"string","pattern":"^[a-f0-9]{64}$"},"findings":{"type":"array","items":{}},"evidence":{"type":"array","items":{},"minItems":1}},"required":["passed","artifactDigest","findings","evidence"]}};
+const plainObject = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+export function claudeWorkflowResponse(role) {
+  const kind = role === 'developer' ? 'worker' : role;
+  if (!Object.hasOwn(CLAUDE_WORKFLOW_SCHEMAS, kind)) throw blocked('Unknown native Claude workflow role');
+  const schema = CLAUDE_WORKFLOW_SCHEMAS[kind];
+  if (!schema) throw blocked('Unknown native Claude workflow role');
+  const nonblank = value => typeof value === 'string' && value.trim().length > 0;
+  const strings = value => Array.isArray(value) && value.every(item => typeof item === 'string');
+  const validate = value => {
+    if (!plainObject(value)) return false;
+    if (kind === 'planner') return Array.isArray(value.tasks) && value.tasks.length > 0 && value.tasks.every(task =>
+      plainObject(task) && Object.keys(task).every(key => ['id', 'instructions', 'dependsOn', 'mode', 'worktree', 'paths', 'checkIds'].includes(key))
+      && /^[a-z][a-z0-9-]{0,79}$/.test(task.id || '') && nonblank(task.instructions) && ['read', 'write'].includes(task.mode)
+      && strings(task.checkIds) && (task.dependsOn === undefined || strings(task.dependsOn))
+      && (task.paths === undefined || strings(task.paths)) && (task.worktree === undefined || typeof task.worktree === 'string'));
+    if (kind === 'worker') return nonblank(value.outcome) && ['artifacts', 'decisions', 'risks'].every(key => Array.isArray(value[key]));
+    return typeof value.passed === 'boolean' && /^[a-f0-9]{64}$/.test(value.artifactDigest || '')
+      && Array.isArray(value.findings) && Array.isArray(value.evidence) && value.evidence.length > 0;
+  };
+  return { responseSchema: structuredClone(schema), validateStructuredOutput: validate };
+}
+
+export async function executeCodexWorkflowWorker({ binary, decision, prompt, cwd, readOnly, signal, timeoutMs,
+  env = process.env, sessionId, launch = spawn, observe = readCodexWorkerObservation, allowance = readCodexAllowance }) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || signal?.aborted) throw blocked('Native worker cancelled or deadline unavailable');
+  const limit = performance.now() + timeoutMs;
+  await assertModelRoutingText(prompt);
+  const clean = { ...subscriptionOnlyEnv(subscriptionEnvironment(env)), RNB_TERMINAL_LAUNCH_ACTIVE: '1' };
+  assertSubscriptionAuth('codex', { env: clean });
+  const quota = await allowance({ env: clean,
+    spawnHost: (_command, args, options) => launch(binary, args, options) });
+  if (quota.ordinaryUsageAllowed !== true) throw blocked('Native Codex included allowance not available');
+  if (performance.now() >= limit || signal?.aborted) throw blocked('Native worker deadline expired during readiness');
+  const spec = buildLaunch(decision, { cwd });
+  const evidenceHome = clean.CODEX_HOME || path.join(os.homedir(), '.codex');
+  const prior = sessionId ? observe(sessionId, { home: evidenceHome, expectedPriorTurns: undefined, allowHistory: true }) : null;
+  const args = sessionId ? ['exec', 'resume', '--ignore-user-config', '--skip-git-repo-check', '--json', '--model', decision.model,
+    '-c', `model_reasoning_effort=\"${decision.effort}\"`, '-c', 'model_provider=\"openai\"',
+    '-c', 'service_tier=\"default\"', '-c', `sandbox_mode=\"${readOnly ? 'read-only' : 'workspace-write'}\"`,
+    '-c', 'features.fast_mode=false', '-c', 'features.multi_agent=false', '-c', 'features.multi_agent_v2=false', sessionId, '-']
+    : [...spec.args.slice(0, -1), '--skip-git-repo-check', '--json', '--sandbox', readOnly ? 'read-only' : 'workspace-write',
+      '-c', 'features.multi_agent=false', '-c', 'features.multi_agent_v2=false', '-'];
+  args.splice(args.length - 1, 0, ...codexBrainSearchArguments(clean));
+  const result = await new Promise((resolve, reject) => {
+    const child = launch(binary, args, { cwd, env: clean, shell: false, stdio: ['pipe', 'pipe', 'pipe'] });
+    let stdout = '', stderr = '', finished = false, timer, killTimer, cancelled = false, cancelReason;
+    const finish = (error, value) => {
+      if (finished) return; finished = true; clearTimeout(timer); clearTimeout(killTimer);
+      signal?.removeEventListener('abort', cancel);
+      error ? reject(error) : resolve(value);
+    };
+    const safeKill = signalName => { try { child.kill(signalName); } catch { /* close remains required */ } };
+    const cancel = reason => {
+      if (finished || cancelled) return; cancelled = true; cancelReason = typeof reason === 'string' ? reason : 'Native worker cancelled';
+      safeKill('SIGTERM');
+      killTimer = setTimeout(() => { safeKill('SIGKILL');
+        child.stdin?.destroy(); child.stdout?.destroy(); child.stderr?.destroy(); child.unref?.();
+        finish(Object.assign(blocked('Native worker retirement not confirmed'), { retirementUnconfirmed: true })); }, 1000);
+    };
+    child.stdout.on('data', chunk => { if (cancelled) return; stdout += chunk; if (Buffer.byteLength(stdout) > 16 * 1024 * 1024) cancel('Native worker output exceeded bound'); });
+    child.stderr.on('data', chunk => { stderr = (stderr + chunk).slice(-8000); });
+    child.on('error', () => cancel('Native worker process error; retirement required'));
+    child.stdin.once('error', () => cancel('Native worker input delivery failed'));
+    child.once('close', (code, nativeSignal) => {
+      if (cancelled || signal?.aborted || nativeSignal) return finish(blocked('Native worker interrupted; effects require inspection'));
+      if (code !== 0) return finish(blocked(`Native worker failed (exit ${code}); inspect effects before retry`));
+      finish(null, { stdout, stderr });
+    });
+    signal?.addEventListener('abort', cancel, { once: true });
+    timer = setTimeout(() => cancel('Native worker deadline exceeded'), Math.max(1, limit - performance.now()));
+    if (signal?.aborted) cancel(); else child.stdin.end(prompt);
+  });
+  if (performance.now() >= limit || signal?.aborted) throw blocked('Native worker completed after its deadline');
+  const events = result.stdout.trim().split('\n').map(line => JSON.parse(line));
+  const thread = events.find(event => event.type === 'thread.started');
+  if (!events.some(event => event.type === 'turn.completed') || events.some(event => event.type === 'turn.failed' || event.type === 'error')) {
+    throw blocked('Native Codex turn did not complete successfully');
+  }
+  if (sessionId && thread?.thread_id !== sessionId) throw blocked('Native parent session changed');
+  const observation = observe(thread?.thread_id, sessionId ? { home: evidenceHome, expectedPriorTurns: prior.turnCount, evidencePath: prior.evidence.path } : { home: evidenceHome });
+  if (observation.model !== decision.model || observation.effort !== decision.effort || observation.cwd !== cwd
+    || (readOnly && observation.sandbox?.type !== 'read-only')) throw blocked('Native worker model, effort, directory or sandbox mismatch');
+  const messages = events.filter(event => event.type === 'item.completed' && event.item?.type === 'agent_message');
+  const answer = messages.at(-1)?.item?.text;
+  if (typeof answer !== 'string') throw blocked('Native final answer unavailable');
+  await assertModelRoutingText(answer);
+  if (performance.now() >= limit || signal?.aborted) throw blocked('Native worker exceeded deadline during output inspection');
+  return { ...observation, answer, completed: true, modelObserved: true, effortSettingsObserved: true, effortEvidence: 'native-turn-context', usage: events.find(event => event.type === 'turn.completed')?.usage ?? null };
+}
+
+/** Native Codex stays read-only. Only exact, preconditioned owner-authorized files are published here. */
+export function applyOwnedCodexEdits(worker, answer, { signal, deadline = Infinity } = {}) {
+  let report;
+  try { report = JSON.parse(answer); } catch { throw blocked('Codex write result must be bounded JSON edits'); }
+  if (!Array.isArray(report.edits) || !report.edits.length || report.edits.length > 32) throw blocked('Exact bounded edits required');
+  const root = fs.realpathSync(worker.ownership.worktree), targets = new Set(); let total = 0;
+  const live = () => { if (signal?.aborted || Date.now() >= deadline) throw blocked('Edit publication cancelled or expired'); };
+  const edits = report.edits.map(edit => {
+    live();
+    if (!edit || typeof edit.path !== 'string' || path.isAbsolute(edit.path) ||
+      edit.path.split(/[\\/]/).some(part => !part || part === '.' || part === '..') ||
+      !worker.ownership.paths.includes(edit.path) || typeof edit.content !== 'string') throw blocked('Edit escaped exact file ownership');
+    const file = path.join(root, edit.path); if (targets.has(file)) throw blocked('Duplicate edit'); targets.add(file);
+    total += Buffer.byteLength(edit.content); if (total > 4 * 1024 * 1024) throw blocked('Edit bytes exceeded bound');
+    for (let ancestor = file; ancestor !== root; ancestor = path.dirname(ancestor)) {
+      if (fs.existsSync(ancestor) && fs.lstatSync(ancestor).isSymbolicLink()) throw blocked('Symlink edit refused');
+    }
+    if (!fs.existsSync(path.dirname(file))) throw blocked('Edit parent must already exist');
+    const exists = fs.existsSync(file), stat = exists ? fs.lstatSync(file) : null;
+    if (stat && (!stat.isFile() || stat.nlink !== 1)) throw blocked('Nonregular or hardlinked edit refused');
+    if (exists ? edit.oldSha256 !== digest(fs.readFileSync(file)) : edit.oldSha256 !== null) throw blocked('Edit precondition changed');
+    return { ...edit, file, mode: stat?.mode & 0o777 || 0o600, exists };
+  });
+  const applied = [];
+  try {
+    for (const edit of edits) {
+      live();
+      if (edit.exists ? !fs.existsSync(edit.file) || digest(fs.readFileSync(edit.file)) !== edit.oldSha256 : fs.existsSync(edit.file)) throw blocked('Edit changed at publication');
+      const temporary = path.join(path.dirname(edit.file), `.rnb-edit-${crypto.randomUUID()}`);
+      try {
+        fs.writeFileSync(temporary, edit.content, { flag: 'wx', mode: edit.mode }); live();
+        if (edit.exists) {
+          if (fs.lstatSync(edit.file).isSymbolicLink() || digest(fs.readFileSync(edit.file)) !== edit.oldSha256) throw blocked('Edit changed before replacement');
+          // Single-writer ownership is required; external same-user writes are not an atomic CAS contract.
+          fs.renameSync(temporary, edit.file);
+        } else fs.linkSync(temporary, edit.file); // no-replace publication even if a destination races into existence
+        applied.push({ path: edit.file, digest: digest(fs.readFileSync(edit.file)) });
+      } finally { try { fs.unlinkSync(temporary); } catch (error) { if (error.code !== 'ENOENT') throw error; } }
+    }
+  } catch (error) {
+    throw Object.assign(blocked(`Edit publication blocked: ${error.message}; inspect actual applied files before retry`), { applied, uncertainEffects: applied.length > 0 });
+  }
+  return applied;
+}
+
+function ownedPermission(request, worker, nativeRequest) {
+  if (['Agent', 'Task'].includes(nativeRequest.tool_name)) return false;
+  if (['Read', 'Glob', 'Grep'].includes(nativeRequest.tool_name) || /__search_ruvnet$/.test(nativeRequest.tool_name)) return true;
+  if (worker.ownership?.mode !== 'write' || request.permissions?.write !== true) return false;
+  if (!['Write', 'Edit', 'MultiEdit'].includes(nativeRequest.tool_name)) return false;
+  const input = nativeRequest.input || {}, raw = input.file_path;
+  if (typeof raw !== 'string') return false;
+  const root = fs.realpathSync(worker.ownership.worktree), target = path.resolve(root, raw);
+  if (!target.startsWith(root + path.sep)) return false;
+  let ancestor = target;
+  while (!fs.existsSync(ancestor)) ancestor = path.dirname(ancestor);
+  if (fs.realpathSync(ancestor) !== ancestor) return false;
+  return worker.ownership.paths.some(relative => {
+    const allowed = path.resolve(root, relative);
+    return target === allowed || (relative.endsWith('/') && target.startsWith(allowed + path.sep));
+  });
+}
+
+export function createGuardedWorkflowAdapters({ request, budget, env = process.env,
+  binaries = nativeWorkflowBinaries(), executeNative, verifyDecision = validateDispatchDecision, captureObservation = () => {} }) {
+  const adapters = {};
+  for (const host of ['codex', 'claude']) {
+    adapters[host] = {
+      id: `brain-native-${host}`,
+      hostId: host,
+      readiness: async () => ({ ready: true }),
+      prepare: async ({ worker, signal, timeoutMs }) => {
+        const decision = worker.decision;
+        if (!decision || decision.harness !== (host === 'claude' ? 'claude-code' : host)
+          || decision.model !== worker.configuredModel) throw blocked('Worker allocation missing or inconsistent');
+        verifyDecision(decision);
+        const binary = binaries[host];
+        if (!path.isAbsolute(binary || '') || !fs.statSync(binary).isFile()) throw blocked('Native executable unavailable');
+        const cwd = fs.realpathSync(worker.ownership?.worktree || request.projectRoot || request.cwd);
+        if (worker.ownership?.mode === 'write' && (request.permissions?.write !== true || !worker.ownership.paths?.length)) {
+          throw blocked('Worker write authority unavailable');
+        }
+        if (!request.originalPrompt || typeof worker.prompt !== 'string') throw blocked('Original request context unavailable');
+        let original;
+        try { original = JSON.parse(worker.prompt).originalPrompt; } catch { /* AK appends its handoff below the canonical JSON. */ }
+        if (original !== request.originalPrompt && !worker.prompt.includes(request.originalPrompt)
+          && !worker.prompt.includes(JSON.stringify(request.originalPrompt))) throw blocked('Worker lost the original request');
+        for (const ref of request.contextRefs || []) {
+          if (digest(fs.readFileSync(ref.path)) !== ref.digest) throw blocked('Canonical context changed before launch');
+        }
+        const controller = new AbortController();
+        return { worker, decision, binary, cwd, controller, signal: signal ? AbortSignal.any([signal, controller.signal]) : controller.signal,
+          timeoutMs: Math.min(timeoutMs, budget.deadline - Date.now()), startedAt: new Date().toISOString(), finished: false };
+      },
+      launch: async state => {
+        try {
+          if (host === 'claude') state.timeoutMs = Math.floor(Math.min(state.timeoutMs, budget.deadline - Date.now()));
+          if (state.timeoutMs <= 0) throw blocked('Shared workflow deadline exhausted');
+          if (executeNative) state.observation = await executeNative({ ...state, prompt: state.worker.prompt + (state.worker.reviewContract ? '\n' + state.worker.reviewContract : ''), env });
+          else if (host === 'codex') {
+            const write = state.worker.ownership?.mode === 'write';
+            const contract = write ? '\nExecution contract: native execution is read-only. Return ONLY JSON with outcome, artifacts, decisions, risks, and edits:[{path,oldSha256,content}]. Read each existing file first and use its actual SHA256; new files use oldSha256:null. Paths must exactly match ownership.paths. Do not write files or run mutating commands.' : '';
+            state.observation = await executeCodexWorkflowWorker({ ...state, prompt: state.worker.prompt + contract + (state.worker.reviewContract ? '\n' + state.worker.reviewContract : ''), readOnly: true, env });
+            if (write) state.observation.appliedArtifacts = applyOwnedCodexEdits(state.worker, state.observation.answer, { signal: state.signal, deadline: budget.deadline });
+          }
+          else {
+            const receipts = [];
+            const turn = await runControlledClaudeTurn({ ...state, ...claudeWorkflowResponse(state.worker.role), prompt: state.worker.prompt + (state.worker.reviewContract ? '\n' + state.worker.reviewContract : ''), env,
+              decide: async () => state.decision, approve: async permission => ownedPermission(request, state.worker, permission),
+              receipt: value => receipts.push(value) });
+            if (turn.structuredOutput !== true || typeof turn.finalAnswer !== 'string' || !turn.finalAnswer.trim()) throw blocked('Native final answer unavailable');
+            state.observation = { model: turn.decision?.model, effort: turn.decision?.effort,
+              sessionId: turn.sessionId, completed: turn.modelObserved === true && turn.effortSettingsObserved === true, answer: turn.finalAnswer,
+              evidence: receipts, responseFormat: 'json-schema', nativeSchemaRetries: 'not-observed', effortEvidence: 'Native settings observed before and after; per-request effort not exposed' };
+          }
+          if (state.observation?.completed && state.observation.model === state.decision.model && state.observation.effort === state.decision.effort) {
+            captureObservation(state.worker, state.observation);
+          }
+        } catch (error) { state.error = error; if (error.retirementUnconfirmed) state.retirementUnconfirmed = true; }
+        finally { state.finished = true; }
+        return state;
+      },
+      observe: async state => state.observation,
+      interpret: (state, observation) => {
+        const valid = !state.error && observation?.completed === true && observation.model === state.decision.model && observation.effort === state.decision.effort;
+        state.observation = observation;
+        const endedAt = new Date().toISOString();
+        return { workerId: state.worker.id, activity: state.worker.activity, role: state.worker.role, host,
+          status: valid ? 'succeeded' : 'blocked', exitCategory: valid ? 'success' : 'protocol_error',
+          startedAt: state.startedAt, endedAt, durationMs: Math.max(0, Date.parse(endedAt) - Date.parse(state.startedAt)),
+          provider: valid ? state.decision.provider : null, providerProvenance: valid ? 'configured' : 'unknown',
+          configuredModel: state.decision.model, observedModel: valid ? observation.model : null,
+          configuredEffort: state.decision.effort, observedEffort: valid ? observation.effort : null,
+          effortEvidence: valid ? observation.effortEvidence || 'native-turn-context' : null,
+          sessionId: observation?.sessionId || null, transcriptRefs: observation?.evidence?.path ? [observation.evidence.path] : [],
+          failure: valid ? null : { reason: state.error?.message || 'Native model/effort/completion unverified' }, usage: observation?.usage || null,
+          ...(observation?.type === 'orphaned' || state.retirementUnconfirmed ? { status: 'blocked', exitCategory: 'orphaned' } : {}) };
+      },
+      summarize: state => {
+        try { return JSON.parse(state.observation.answer); } catch { throw blocked('Required native handoff is missing or malformed'); }
+      },
+      cancel: async state => { state?.controller.abort(); return { type: state?.finished ? 'cancelled' : 'orphaned' }; },
+      cleanup: async state => {
+        if (state && (!state.finished || state.retirementUnconfirmed)) throw blocked('Native worker cleanup is not confirmed');
+        return { cleaned: true };
+      },
+    };
+  }
+  return adapters;
+}
+
+export async function runObservedWorkflowWorker({ request, decision, prompt, ownership, role = 'worker',
+  id = `worker-${crypto.randomUUID()}`, env = process.env, signal, timeoutMs = 120000 }) {
+  const host = decision.harness === 'claude-code' ? 'claude' : decision.harness;
+  const adapters = createGuardedWorkflowAdapters({ request, env, budget: { deadline: request.deadline || Date.now() + timeoutMs } });
+  if (!adapters[host]) throw blocked('Native workflow host unavailable');
+  const worker = { id, host, activity: role === 'reviewer' ? 'review' : 'implementation', role, decision,
+    configuredModel: decision.model, configuredEffort: decision.effort, ownership, prompt };
+  const state = await adapters[host].prepare({ worker, signal, timeoutMs });
+  await adapters[host].launch(state);
+  const result = adapters[host].interpret(state, await adapters[host].observe(state));
+  await adapters[host].cleanup(state);
+  if (result.status !== 'succeeded') throw blocked(result.failure?.reason || 'Native worker completion unverified');
+  return { ...state.observation, result };
+}

package/scripts/model-routing-launchers.mjs

@@ -82,6 +82,7 @@ function backup(file) {
 export function runtimeSnapshot(sourceRoot) {
   const root = fs.realpathSync(sourceRoot); const files = new Map();
   const visit = (relative) => {
+    relative = relative.split(path.sep).join('/');
     if (files.has(relative)) return;
     const file = regular(path.join(root, relative));
     if (!file.startsWith(`${root}${path.sep}`)) throw new Error('Runtime dependency escaped source root');
@@ -112,6 +113,36 @@ export function runtimeSnapshot(sourceRoot) {
       files.set(`node_modules/ws/${relative}`, fs.readFileSync(file));
     }
   }
+  // Freeze the installed managed runner with this runtime; no global-version drift or download.
+  if (files.has('scripts/model-routing-controller.mjs')) {
+    const require = createRequire(path.join(root, 'package.json'));
+    const kitRoot = path.dirname(regular(require.resolve('@pacphi/agentic-kit/package.json')));
+    const manifest = JSON.parse(fs.readFileSync(path.join(kitRoot, 'package.json')));
+    if (manifest.name !== '@pacphi/agentic-kit') throw new Error('Unexpected managed runner identity');
+    const collect = relative => {
+      const absolute = path.join(kitRoot, relative), stat = fs.lstatSync(absolute);
+      if (stat.isSymbolicLink()) throw new Error('Managed runner dependency symlink refused');
+      if (stat.isDirectory()) {
+        for (const name of fs.readdirSync(absolute)) if (name !== 'node_modules') collect(path.join(relative, name));
+      } else if (stat.isFile()) files.set(`node_modules/@pacphi/agentic-kit/${relative.split(path.sep).join('/')}`, fs.readFileSync(absolute));
+      else throw new Error('Nonregular managed runner dependency');
+    };
+    collect('package.json'); collect('src');
+  }
+  if (files.has('scripts/model-routing-defence.mjs')) {
+    const defenceEntry = regular(fileURLToPath(import.meta.resolve('@claude-flow/aidefence')));
+    const defenceRoot = path.dirname(path.dirname(defenceEntry));
+    const manifest = JSON.parse(fs.readFileSync(path.join(defenceRoot, 'package.json')));
+    if (manifest.name !== '@claude-flow/aidefence') throw new Error('Unexpected local defence identity');
+    const collect = relative => {
+      const absolute = path.join(defenceRoot, relative), stat = fs.lstatSync(absolute);
+      if (stat.isSymbolicLink()) throw new Error('Defence dependency symlink refused');
+      if (stat.isDirectory()) { for (const name of fs.readdirSync(absolute)) collect(path.join(relative, name)); }
+      else if (stat.isFile()) files.set(`node_modules/@claude-flow/aidefence/${relative.split(path.sep).join('/')}`, fs.readFileSync(absolute));
+      else throw new Error('Nonregular defence dependency');
+    };
+    collect('package.json'); collect('dist');
+  }
   for (const name of fs.readdirSync(path.join(root, 'config/model-router'))) {
     if (/\.(?:json|mjs)$/.test(name)) visit(`config/model-router/${name}`);
   }

package/scripts/model-terminal-launchers.mjs

@@ -28,9 +28,17 @@ function regular(file, { privateFile = false } = {}) {
 function executable(file) {
   const result = regular(fs.realpathSync(file)); fs.accessSync(result, fs.constants.X_OK); return result;
 }
-function atomic(file, content, mode = 0o600) {
+function nativeExecutable(file) {
+  const result = executable(file), fd = fs.openSync(result, 'r');
+  const header = Buffer.alloc(512);
+  try {
+    if (header.subarray(0, fs.readSync(fd, header, 0, header.length, 0)).toString().includes(MARKER)) throw new Error('Native terminal launcher recursion refused');
+  } finally { fs.closeSync(fd); }
+  return result;
+}
+function atomic(file, content, mode = 0o600, replaceLink = false) {
   fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
-  if (fs.existsSync(file)) regular(file);
+  if (fs.existsSync(file) && !replaceLink) 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);
@@ -38,6 +46,27 @@ function atomic(file, content, mode = 0o600) {
     fs.renameSync(temp, file);
   } finally { fs.rmSync(temp, { force: true }); }
 }
+function canonicalEntry(file, binary, replace) {
+  let stat;
+  try { stat = fs.lstatSync(file); } catch (error) { if (error.code === 'ENOENT') return { file, symlink: false }; throw error; }
+  if (stat.uid !== process.getuid?.()) throw new Error(`Preserving foreign canonical terminal entry: ${file}`);
+  if (stat.isSymbolicLink()) {
+    if (fs.realpathSync(file) !== binary) throw new Error(`Preserving unrelated canonical terminal link: ${file}`);
+    return { file, symlink: true, link: fs.readlinkSync(file) };
+  }
+  regular(file);
+  if (fs.realpathSync(file) === binary) throw new Error('Separate native binary required before replacing canonical terminal entry');
+  if (!fs.readFileSync(file, 'utf8').includes(MARKER) && !replace) throw new Error(`Preserving unmanaged canonical terminal entry: ${file}`);
+  return { file, symlink: false };
+}
+function backupCanonical(entry) {
+  if (!entry.symlink) return backup(entry.file);
+  const target = `${entry.file}.${digest(entry.link)}.original`;
+  try { fs.symlinkSync(entry.link, target); } catch (error) {
+    if (error.code !== 'EEXIST' || !fs.lstatSync(target).isSymbolicLink() || fs.lstatSync(target).uid !== process.getuid?.() || fs.readlinkSync(target) !== entry.link) throw new Error('Canonical link backup mismatch');
+  }
+  return target;
+}
 function backup(file) {
   if (!fs.existsSync(file)) return null;
   const bytes = fs.readFileSync(regular(file)); const target = `${file}.${digest(bytes)}.original`;
@@ -84,40 +113,48 @@ export function terminalShellPlan(text, sourcePath, launchers) {
 
 /** 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 } = {}) {
+  runtimeDigest, realCodex, realClaude, apply = false, manageZsh = true,
+  replaceCanonicalEntries = [] } = {}) {
   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 configPath = path.join(home, '.cache/ruvnet-brain/model-routing/terminal-launcher-config.json');
+  const previous = fs.existsSync(configPath) ? JSON.parse(fs.readFileSync(regular(configPath), 'utf8')) : null;
+  if (previous && previous.managedBy !== 'ruvnet-brain-terminal-launchers') throw new Error('Preserving unmanaged terminal configuration');
+  realCodex ??= previous?.realCodex || path.join(home, '.local/bin/codex');
   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')) };
+    runner, realCodex: nativeExecutable(realCodex), gatewayPath: regular(path.join(runtimeRoot, 'scripts/model-terminal-gateway.mjs')) };
   if (realClaude) {
-    config.realClaude = executable(realClaude);
+    config.realClaude = nativeExecutable(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');
+  if (!Array.isArray(replaceCanonicalEntries) || replaceCanonicalEntries.some(host => !Object.hasOwn(launchers, host))) throw new Error('Explicit installed host names required for canonical entry migration');
+  const canonicalEntries = Object.fromEntries(Object.keys(launchers).map(host => [host, path.join(home, '.local/bin', host)]));
+  const canonical = Object.entries(canonicalEntries).map(([host, file]) => canonicalEntry(file, config[host === 'codex' ? 'realCodex' : 'realClaude'], replaceCanonicalEntries.includes(host)));
   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`]));
+  for (const [host, file] of Object.entries(canonicalEntries)) contents[file] = contents[launchers[host]];
   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]) {
+  for (const file of [...Object.values(launchers), 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: [],
+  const receipt = { apply, launchers, canonicalEntries, configPath, config, shellSource, shellConflicts: shell.conflicts, backups: [],
     claudeEnforcementScope: realClaude ? 'Controlled native prompt boundary; model observations and effective effort settings checked for each completed turn' : null };
   if (!apply) return receipt;
-  for (const file of [configPath, ...Object.keys(contents), ...(manageZsh ? [shellSource, zshrc] : [])]) {
+  for (const file of [configPath, ...Object.values(launchers), ...(manageZsh ? [shellSource, zshrc] : [])]) {
     const original = backup(file); if (original) receipt.backups.push(original);
   }
+  for (const entry of canonical) { const original = backupCanonical(entry); 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);
+  for (const [file, content] of Object.entries(contents)) atomic(file, content, 0o755, canonical.some(entry => entry.file === file && entry.symlink));
   if (manageZsh) { atomic(shellSource, shell.source); atomic(zshrc, shell.zshrc, fs.existsSync(zshrc) ? fs.statSync(zshrc).mode & 0o777 : 0o600); }
   return receipt;
 }
@@ -131,7 +168,7 @@ export function ensureTerminalDaemon(binary, env = process.env, { exec = execFil
 }
 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);
+  const binary = nativeExecutable(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 };
@@ -240,7 +277,7 @@ export async function runClaudeTerminal({ config, args = [], env = process.env,
   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 binary = nativeExecutable(config.realClaude), clean = subscriptionEnvironment(env);
   if (claudeAdministrativeArguments(args)) {
     const child = spawn(binary, args, { env: clean, cwd, stdio: 'inherit', shell: false });
     const unforward = forwardSignals(child, signalSource);
@@ -289,10 +326,17 @@ export async function runTerminalLauncher({ host, args = [], config, env = proce
     if (claudeAdministrativeArguments(args)) return runClaudeTerminal({ config, args, env, signalSource });
     if (env.RNB_TERMINAL_LAUNCH_ACTIVE) throw new Error('Native terminal launcher recursion refused');
     const { launchControlledClaudeTerminal } = await import('./claude-controlled-terminal.mjs');
-    await launchControlledClaudeTerminal({ binary: executable(config.realClaude), args, env, cwd: process.cwd() });
+    await launchControlledClaudeTerminal({ binary: nativeExecutable(config.realClaude), args, env, cwd: process.cwd() });
     return { code: 0, signal: null };
   }
   if (host !== 'codex') throw new Error('Unsupported terminal host');
+  const classification = classifyTerminalArguments(args);
+  if (classification === 'interactive') {
+    if (env.RNB_TERMINAL_LAUNCH_ACTIVE) throw new Error('Native terminal launcher recursion refused');
+    const { launchManagedCodexTerminal } = await import('./codex-managed-terminal.mjs');
+    await launchManagedCodexTerminal({ binary: nativeExecutable(config.realCodex), args, env, cwd: process.cwd() });
+    return { code: 0, signal: null };
+  }
   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);