@link-assistant/hive-mind 2.13.4 → 2.14.0

package/src/isolation-runner.lib.mjs

@@ -26,6 +26,9 @@ import { acquireFormalAiSidecarForTask, attachFormalAiTaskContainer, releaseForm
 // importing this runner and creating a cycle. Re-exported here because callers
 // and tests have always reached them through the isolation runner. See #2154.
 import { getDockerIsolationImage } from './hive-mind-image.lib.mjs';
+import { buildRouterGitConfigEntries, buildRouterTaskEnv, getRouterSuppressedCredentialPaths, hasUseRouterFlag, isRouterEnabled, resolveRouterBaseUrl, resolveRouterGitHubRouting } from './router-isolation.lib.mjs';
+import { acquireRouterForTask, attachRouterTaskContainer, registerFormalAiWithRouter, releaseRouterForTask } from './router-task-isolation.lib.mjs';
+import { buildGitConfigEnv, GIT_PUSH_GUARD_CONTAINER_DIR, GIT_PUSH_GUARD_ESCAPE_ENV, hasForcePushOptIn, installGitPushGuard } from './git-push-guard.lib.mjs';
 export { getDockerIsolationImage, resolveDockerIsolationImageTag } from './hive-mind-image.lib.mjs';
 let commandStreamDollarPromise = null;
 async function getCommandStreamDollar() {
@@ -47,6 +50,10 @@ async function getCommandStreamDollar() {
 }
 // Re-export the shared status predicates so existing callers that reach them via the isolation-runner module (e.g. session-monitor's `runner.isExecutingSessionStatus`) keep working. The canonical definitions live in session-status.lib.mjs so the killed/terminated/oom vocabulary stays consistent everywhere (issue #1927).
 export { isExecutingSessionStatus, isTerminalSessionStatus, isKilledSessionStatus } from './session-status.lib.mjs';
+// Issue #2175: the `$` output parsers live in their own module to keep this file
+// under the 1350-line warning threshold. Re-exported so importers are unaffected.
+import { isUnknownDockerExitCode, parseSessionExitFooter, parseSessionListOutput, parseSessionStatusOutput, parseStartCommandExecutionUuid, readSessionExitFromLog, shouldFallbackToScreenStatus } from './isolation-runner.parsers.lib.mjs';
+export { isUnknownDockerExitCode, parseSessionExitFooter, parseSessionListOutput, parseSessionStatusOutput, parseStartCommandExecutionUuid, readSessionExitFromLog, shouldFallbackToScreenStatus };
 // Valid isolation backends
 const VALID_ISOLATION_BACKENDS = ['screen', 'tmux', 'docker'];
 const DOCKER_CONTAINER_HOME = '/home/box';
@@ -59,17 +66,6 @@ const DOCKER_ISOLATION_SHELL = 'sh';
 const DOCKER_ISOLATION_LOW_DISK_GIB = 40;
 // Docker-only start gate used to capture the container writable-layer baseline before the task command begins cloning or generating files. The parent releases the gate immediately after `docker inspect --size`; the fallback keeps the task from hanging forever if the parent exits at the wrong time.
 const DOCKER_START_GATE_WAIT_TENTHS = 300;
-// Sentinel start-command's detached docker logger records when it cannot capture the container's real exit code. A terminal `$ --status` carrying this value is ambiguous — the container may still be running — so we cross-check it against a live `docker inspect` before concluding the session finished. See #1939. The upstream emission of this premature sentinel was fixed in start-command 0.29.1 (link-foundation/start#136), which the Hive Mind images now pin; this cross-check is retained as defense-in-depth so an older `$` on an operator's PATH cannot resurrect the bug.
-const DOCKER_UNKNOWN_EXIT_CODE = -1;
-function normalizeProcessIds(value) {
-  if (!value || typeof value !== 'object') return {};
-  const out = {};
-  for (const [key, raw] of Object.entries(value)) {
-    const number = Number(raw);
-    if (Number.isInteger(number) && number > 0) out[key] = number;
-  }
-  return out;
-}
 function normalizeTool(tool) {
   return String(tool || 'claude')
     .trim()
@@ -121,21 +117,31 @@ export function resolveHostDockerSock({ env = process.env } = {}) {
  * commit. See issue #1939. Tool credentials are deliberately scoped: Codex
  * sessions do not receive Claude files and Claude sessions do not receive Codex
  * files.
+ *
+ * Issue #2164 (EXPERIMENTAL): with `useRouter` the vendor credential mounts are
+ * withheld entirely, so the task never holds the subscription — it reaches the
+ * `hive-mind-router` sidecar with its own scoped token instead. Git identity is
+ * still mounted, because it carries no secret and `solve` aborts without it
+ * (issue #1939). The gh config is only withheld when `ghRouted` says gh has
+ * somewhere else to go; otherwise the task would lose GitHub access entirely.
  */
-export function getDockerIsolationAuthMounts({ tool = 'claude', env = process.env, homeDir = os.homedir(), existsSync = fs.existsSync } = {}) {
+export function getDockerIsolationAuthMounts({ tool = 'claude', env = process.env, homeDir = os.homedir(), existsSync = fs.existsSync, useRouter = false, ghRouted = false } = {}) {
   const mounts = [];
   const normalizedTool = normalizeTool(tool);
-  maybeAddMount(mounts, env.GH_CONFIG_DIR || path.join(homeDir, '.config', 'gh'), path.join(DOCKER_CONTAINER_HOME, '.config', 'gh'), existsSync);
+  const suppressed = useRouter ? new Set(getRouterSuppressedCredentialPaths({ tool: normalizedTool, ghRouted })) : new Set();
+  if (!suppressed.has('.config/gh')) {
+    maybeAddMount(mounts, env.GH_CONFIG_DIR || path.join(homeDir, '.config', 'gh'), path.join(DOCKER_CONTAINER_HOME, '.config', 'gh'), existsSync);
+  }
   // Git identity (tool-agnostic, required for commits). Honor the same env vars git itself reads for an alternate global config location (GIT_CONFIG_GLOBAL) and the XDG base dir, falling back to the conventional `~/.gitconfig` and `~/.config/git`. Missing host paths are skipped, so a container image that already bakes a git identity is left untouched. See issue #1939.
   maybeAddMount(mounts, env.GIT_CONFIG_GLOBAL || path.join(homeDir, '.gitconfig'), path.join(DOCKER_CONTAINER_HOME, '.gitconfig'), existsSync);
   maybeAddMount(mounts, env.XDG_CONFIG_HOME ? path.join(env.XDG_CONFIG_HOME, 'git') : path.join(homeDir, '.config', 'git'), path.join(DOCKER_CONTAINER_HOME, '.config', 'git'), existsSync);
   if (normalizedTool === 'codex') {
-    maybeAddMount(mounts, path.join(homeDir, '.codex'), path.join(DOCKER_CONTAINER_HOME, '.codex'), existsSync);
+    if (!suppressed.has('.codex')) maybeAddMount(mounts, path.join(homeDir, '.codex'), path.join(DOCKER_CONTAINER_HOME, '.codex'), existsSync);
     // Issue #2074: Codex also discovers persistent user Agent Skills from ~/.agents/skills. Propagate that standard location alongside .codex so direct and Docker-isolated solver sessions expose the same capabilities.
-    maybeAddMount(mounts, path.join(homeDir, '.agents'), path.join(DOCKER_CONTAINER_HOME, '.agents'), existsSync);
+    if (!suppressed.has('.agents')) maybeAddMount(mounts, path.join(homeDir, '.agents'), path.join(DOCKER_CONTAINER_HOME, '.agents'), existsSync);
   } else if (normalizedTool === 'claude') {
-    maybeAddMount(mounts, path.join(homeDir, '.claude'), path.join(DOCKER_CONTAINER_HOME, '.claude'), existsSync);
-    maybeAddMount(mounts, path.join(homeDir, '.claude.json'), path.join(DOCKER_CONTAINER_HOME, '.claude.json'), existsSync);
+    if (!suppressed.has('.claude')) maybeAddMount(mounts, path.join(homeDir, '.claude'), path.join(DOCKER_CONTAINER_HOME, '.claude'), existsSync);
+    if (!suppressed.has('.claude.json')) maybeAddMount(mounts, path.join(homeDir, '.claude.json'), path.join(DOCKER_CONTAINER_HOME, '.claude.json'), existsSync);
   }
   return mounts;
 }
@@ -198,7 +204,18 @@ export async function resolveFormalAiIsolationEnv(env = process.env, { lookup =
  * reused instead of re-downloaded — no `--pull` plumbing required (issue #1879).
  */
 export function buildDockerIsolationStartArgs(command, args = [], options = {}) {
-  const { sessionId, tool = 'claude', env = process.env, homeDir = os.homedir(), existsSync = fs.existsSync } = options;
+  const { sessionId, tool = 'claude', env = process.env, homeDir = os.homedir(), existsSync = fs.existsSync, useRouter = false, routerToken = null, installGuard = installGitPushGuard } = options;
+  // Issue #2164 (EXPERIMENTAL): router isolation replaces the credential mounts
+  // with a scoped token pointing at the `hive-mind-router` sidecar. It only
+  // engages when a token was actually issued; without one the task would have
+  // neither credentials nor a route, so we fail open to the default mounts
+  // rather than launching an agent that cannot reach any model.
+  const routerActive = isRouterEnabled({ useRouter, env }) && Boolean(routerToken);
+  const routerEndpoint = routerActive ? resolveRouterBaseUrl({ env }) : { baseUrl: null, external: false };
+  const routerBaseUrl = routerEndpoint.baseUrl;
+  const routerGitHub = routerActive ? resolveRouterGitHubRouting({ env, external: Boolean(routerEndpoint.external) }) : { mode: 'off', ghHost: null };
+  const routerEnv = routerActive && routerBaseUrl ? buildRouterTaskEnv({ tool, baseUrl: routerBaseUrl, token: routerToken, githubMode: routerGitHub.mode, ghHost: routerGitHub.ghHost, homeDir: DOCKER_CONTAINER_HOME }) : {};
+  const routerWired = Object.keys(routerEnv).length > 0;
   const image = getDockerIsolationImage({ env });
   const startArgs = ['--isolated', 'docker', '--image', image];
   if (shouldRunPrivilegedDockerIsolation(image, env)) {
@@ -212,8 +229,33 @@ export function buildDockerIsolationStartArgs(command, args = [], options = {})
   if (env.HIVE_MIND_FORMAL_AI_BASE_URL) {
     startArgs.push('-e', `HIVE_MIND_FORMAL_AI_BASE_URL=${env.HIVE_MIND_FORMAL_AI_BASE_URL}`);
   }
-  for (const mount of getDockerIsolationAuthMounts({ tool, env, homeDir, existsSync })) {
-    startArgs.push('--volume', `${mount.source}:${mount.target}`);
+  for (const [name, value] of Object.entries(routerEnv)) {
+    startArgs.push('-e', `${name}=${value}`);
+  }
+  const mounts = getDockerIsolationAuthMounts({ tool, env, homeDir, existsSync, useRouter: routerWired, ghRouted: routerWired && routerGitHub.mode !== 'off' });
+  // Issue #2164 (R13): a routed task also loses the ability to destroy remote
+  // history by accident. The hook lives on the host and is mounted read-only, so
+  // the task cannot edit the rule it is being held to; git is pointed at it with
+  // GIT_CONFIG_* rather than `git config --global`, because the container's
+  // ~/.gitconfig is the operator's own file. This is one layer of three (see
+  // git-push-guard.lib.mjs) and `--no-verify` still gets past it.
+  if (routerWired) {
+    // One `GIT_CONFIG_COUNT` covers both the hook and the router's git
+    // transport: git shares the counter across all of them, so they have to be
+    // built together or the second would silently replace the first.
+    const gitConfigEntries = buildRouterGitConfigEntries({ baseUrl: routerBaseUrl, token: routerToken, githubMode: routerGitHub.mode });
+    const guard = installGuard({ env, homeDir });
+    if (guard.installed) {
+      mounts.push({ source: guard.dir, target: GIT_PUSH_GUARD_CONTAINER_DIR, readOnly: true });
+      gitConfigEntries.unshift(['core.hooksPath', GIT_PUSH_GUARD_CONTAINER_DIR]);
+      if (hasForcePushOptIn(args)) startArgs.push('-e', `${GIT_PUSH_GUARD_ESCAPE_ENV}=1`);
+    }
+    for (const [name, value] of Object.entries(buildGitConfigEnv(gitConfigEntries))) {
+      startArgs.push('-e', `${name}=${value}`);
+    }
+  }
+  for (const mount of mounts) {
+    startArgs.push('--volume', `${mount.source}:${mount.target}${mount.readOnly ? ':ro' : ''}`);
   }
   const taskCommand = buildShellCommand(command, args);
   startArgs.push('--detached', '--session', sessionId, '--', buildDockerStartGatedCommand(taskCommand, sessionId));
@@ -269,233 +311,6 @@ async function runStartCommand(binPath, startCommandArgs) {
 export function generateSessionId() {
   return crypto.randomUUID();
 }
-const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-/**
- * Extract start-command's own execution UUID from a launch banner.
- *
- * Issue #2154: an isolated task has two UUIDs. Hive Mind generates the session
- * name and passes it as `--session` (it also becomes the container name);
- * start-command mints a separate execution UUID and prints it as the `session`
- * field of its launch banner:
- *
- * ```
- * │ session   edc7b051-e12f-4f7b-b677-c885f3208407
- * │ container 0a3627ef-f1f1-4801-a073-3678b9453db7
- * ```
- *
- * `$ --list` shows the execution UUID, while Telegram and the logs showed the
- * session UUID, so the two views could not be joined — which is why three
- * refused tasks and two healthy ones looked equally unaccounted for. Returning
- * it lets the caller record both.
- *
- * Only a well-formed UUID is returned; a banner we do not recognise yields
- * null rather than a guess, because a wrong correlation is worse than none.
- *
- * @param {string} output - Raw stdout from the detached `$` launch
- * @returns {string|null}
- */
-export function parseStartCommandExecutionUuid(output) {
-  const raw = (output || '').trim();
-  if (!raw) return null;
-  try {
-    const parsed = JSON.parse(raw);
-    const data = Array.isArray(parsed) ? parsed[0] : parsed;
-    const uuid = data?.uuid || data?.session || null;
-    if (typeof uuid === 'string' && UUID_PATTERN.test(uuid.trim())) return uuid.trim();
-  } catch {
-    // Human-readable banner — fall through.
-  }
-  // The banner is box-drawn (`│ session   <uuid>`); tolerate the prefix, an
-  // ASCII `|`, or no prefix at all.
-  const match = raw.match(/^[\s│|]*session\s+([^\s]+)\s*$/im);
-  const candidate = match?.[1]?.trim();
-  return candidate && UUID_PATTERN.test(candidate) ? candidate : null;
-}
-/**
- * Parse output from `$ --status <session>`.
- *
- * start-command versions used in the wild may return JSON when
- * `--output-format json` is supported, or human-readable key/value text.
- * Keep the parser tolerant so completion monitoring survives either format.
- *
- * @param {string} output - Raw stdout from `$ --status`
- * @returns {{exists: boolean, uuid: string|null, status: string|null, exitCode: number|null, startTime: string|null, endTime: string|null, currentTime: string|null, logPath: string|null, command: string|null, isolation: string|null, workingDirectory: string|null, sessionName: string|null, processIds: Object, raw: string}}
- */
-export function parseSessionStatusOutput(output) {
-  const raw = (output || '').trim();
-  if (!raw) {
-    return { exists: false, uuid: null, status: null, exitCode: null, startTime: null, endTime: null, currentTime: null, logPath: null, command: null, isolation: null, workingDirectory: null, sessionName: null, processIds: {}, oomKilled: null, raw: '' };
-  }
-  const normalizeBooleanField = value => {
-    if (typeof value === 'boolean') return value;
-    if (value === null || value === undefined) return null;
-    const normalized = String(value).trim().toLowerCase();
-    if (['true', '1', 'yes'].includes(normalized)) return true;
-    if (['false', '0', 'no'].includes(normalized)) return false;
-    return null;
-  };
-  try {
-    const parsed = JSON.parse(raw);
-    const data = Array.isArray(parsed) ? parsed[0] : parsed;
-    // start-command (link-foundation/start) reports the isolation backend at `options.isolated` in both JSON and links-notation output. Older hypothetical layouts used `options.isolation` or a top-level `isolation` field — keep accepting all three so we are tolerant of future renames. See https://github.com/link-assistant/hive-mind/issues/1700.
-    const isolationCandidate = (typeof data?.isolation === 'string' && data.isolation) || (typeof data?.options?.isolated === 'string' && data.options.isolated) || (typeof data?.options?.isolation === 'string' && data.options.isolation) || null;
-    const topPid = Number(data?.pid);
-    const processIds = normalizeProcessIds(data?.processIds);
-    if (Number.isInteger(topPid) && topPid > 0 && processIds.pid == null) processIds.pid = topPid;
-    return {
-      exists: true,
-      uuid: data?.uuid || null,
-      status: typeof data?.status === 'string' ? data.status.toLowerCase() : null,
-      exitCode: data?.exitCode !== undefined && data?.exitCode !== null ? Number(data.exitCode) : null,
-      startTime: data?.startTime || null,
-      endTime: data?.endTime || null,
-      currentTime: data?.currentTime || null,
-      logPath: data?.logPath || null,
-      command: data?.command || null,
-      isolation: isolationCandidate ? isolationCandidate.toLowerCase() : null,
-      workingDirectory: data?.workingDirectory || null,
-      sessionName: data?.sessionName || data?.options?.sessionName || null,
-      processIds,
-      oomKilled: normalizeBooleanField(data?.oomKilled ?? data?.OOMKilled ?? data?.options?.oomKilled ?? data?.state?.oomKilled ?? data?.State?.OOMKilled),
-      raw,
-    };
-  } catch {
-    // Fall through to text parsing.
-  }
-  const firstLine =
-    raw
-      .split('\n')
-      .find(line => line.trim() && !line.includes(' '))
-      ?.trim() || null;
-  const readField = name => {
-    const match = raw.match(new RegExp(`^\\s*${name}\\s+"?([^"\\n]+)"?\\s*$`, 'mi'));
-    return match ? match[1].trim() : null;
-  };
-  const readBooleanField = name => normalizeBooleanField(readField(name));
-  const status = readField('status')?.toLowerCase() || null;
-  const exitCodeText = readField('exitCode');
-  // `start-command` links-notation output nests the isolation backend under `options` as `isolated <backend>` (not `isolation`). The leading indent varies by depth, but `readField` is anchored with `^\s*` which already matches indented lines. Older code only looked for `isolation`, which
-  // returned null for every real session and made /log + /terminal_watch
-  // reject screen/tmux/docker sessions. See issue #1700.
-  const isolationText = readField('isolated') || readField('isolation');
-  const processIds = {};
-  for (const name of ['pid', 'wrapperPid', 'childPid', 'processPid', 'commandPid']) {
-    const value = readField(name);
-    const number = Number(value);
-    if (Number.isInteger(number) && number > 0) processIds[name] = number;
-  }
-  return {
-    exists: Boolean(status || firstLine),
-    uuid: readField('uuid') || firstLine,
-    status,
-    exitCode: exitCodeText !== null ? Number(exitCodeText) : null,
-    startTime: readField('startTime'),
-    endTime: readField('endTime'),
-    currentTime: readField('currentTime'),
-    logPath: readField('logPath'),
-    command: readField('command'),
-    isolation: isolationText?.toLowerCase() || null,
-    workingDirectory: readField('workingDirectory'),
-    sessionName: readField('sessionName'),
-    processIds,
-    oomKilled: readBooleanField('oomKilled'),
-    raw,
-  };
-}
-/**
- * Decide whether a detached-docker exit code is "unknown" (not a real result).
- *
- * start-command's detached docker logger writes the exit-code footer only after
- * `docker logs -f` returns, capturing the real code via `docker inspect`. When
- * it cannot capture one it records the sentinel `-1`. A `$ --status` that
- * reports a terminal status ("executed") while still carrying that sentinel — or
- * no exit code at all — is therefore ambiguous: the container may actually still
- * be running. Callers treat such a status as provisional and cross-check the
- * live container before declaring the session finished. See issue #1939.
- *
- * @param {number|null|undefined} exitCode
- * @returns {boolean} True when the exit code carries no real result.
- */
-export function isUnknownDockerExitCode(exitCode) {
-  return exitCode === null || exitCode === undefined || Number(exitCode) === DOCKER_UNKNOWN_EXIT_CODE;
-}
-export function shouldFallbackToScreenStatus(statusResult) {
-  return !statusResult?.exists || !statusResult?.status;
-}
-/**
- * Parse the footer start-command appends to every execution log when the wrapped
- * command exits. The footer is authoritative about the terminal exit code even
- * when `$ --status` is wrong: start-command writes it from the command's own
- * `close`/`exited` handler, so its presence proves the command terminated.
- *
- * Footer shape (see start-command spawn-helpers.js):
- *
- *     ==================================================
- *     Finished: 2026-06-14 19:10:49.822
- *     Exit Code: 137
- *
- * Issue #1927: start-command's `enrichDetachedStatus` can flip a completed
- * `executed/137` record back to `executing` (nulling the exit code) when a
- * lingering shell keeps the screen session alive — so `$ --status` reports
- * `executing` forever and the bot never notices the kill. Reading this footer
- * lets hive-mind detect the real terminal exit regardless of that flip.
- *
- * @param {string} text - Log text (typically the tail of the log file)
- * @returns {{finished: boolean, exitCode: number|null, endTime: string|null}}
- */
-export function parseSessionExitFooter(text) {
-  if (!text) return { finished: false, exitCode: null, endTime: null };
-  // Match the LAST footer block in the text (a re-run could append more than
-  // one). Anchor on the `=` separator so command output that merely prints
-  // "Exit Code: N" mid-stream is not mistaken for the footer.
-  const re = /={10,}\s*\r?\nFinished:\s*([^\r\n]+)\r?\nExit Code:\s*(-?\d+)/g;
-  let match;
-  let last = null;
-  while ((match = re.exec(text)) !== null) last = match;
-  if (!last) return { finished: false, exitCode: null, endTime: null };
-  return { finished: true, exitCode: Number(last[2]), endTime: last[1].trim() };
-}
-/**
- * Read the terminal exit code from the tail of a start-command execution log.
- *
- * Only the last `tailBytes` of the file are read (the footer lives at the end),
- * so this is cheap even for multi-megabyte logs. Never throws — a missing or
- * unreadable log yields `{ finished: false }`.
- *
- * @param {string} logPath
- * @param {Object} [options]
- * @param {Object} [options.fsImpl=fs] - Injectable fs (for tests)
- * @param {number} [options.tailBytes=16384] - How many trailing bytes to scan
- * @param {boolean} [options.verbose]
- * @returns {{finished: boolean, exitCode: number|null, endTime: string|null}}
- */
-export function readSessionExitFromLog(logPath, options = {}) {
-  const { fsImpl = fs, tailBytes = 16384, verbose = false } = options;
-  if (!logPath) return { finished: false, exitCode: null, endTime: null };
-  try {
-    const { size } = fsImpl.statSync(logPath);
-    if (!size) return { finished: false, exitCode: null, endTime: null };
-    const start = Math.max(0, size - tailBytes);
-    const length = size - start;
-    const buffer = Buffer.alloc(length);
-    const fd = fsImpl.openSync(logPath, 'r');
-    try {
-      fsImpl.readSync(fd, buffer, 0, length, start);
-    } finally {
-      fsImpl.closeSync(fd);
-    }
-    const result = parseSessionExitFooter(buffer.toString('utf8'));
-    if (verbose && result.finished) {
-      console.log(`[VERBOSE] isolation-runner: log footer for ${logPath} reports exit ${result.exitCode} (finished ${result.endTime})`);
-    }
-    return result;
-  } catch (error) {
-    if (verbose) {
-      console.log(`[VERBOSE] isolation-runner: could not read exit footer from ${logPath}: ${error.message}`);
-    }
-    return { finished: false, exitCode: null, endTime: null };
-  }
-}
 /**
  * Find the `$` CLI binary path
  * @returns {Promise<string|null>} Path to `$` binary or null
@@ -588,6 +403,25 @@ export async function executeWithIsolation(command, args, options = {}) {
   const hostEnv = options.env || process.env;
   const { sidecar, error: sidecarError } = await acquireFormalAiSidecarForTask({ backend, args, model: options.model ?? null, tool: options.tool ?? null, sessionId, env: hostEnv, verbose });
   if (sidecarError) return failLaunch(sidecarError);
+  // Issue #2164 (EXPERIMENTAL): --use-router replaces the task's credential
+  // mounts with a token scoped to it alone. Like the Formal AI lease this is
+  // taken before the container exists, because the token is part of the
+  // environment the container is created with — and like it, it fails closed.
+  const { router, error: routerError } = await acquireRouterForTask({ backend, useRouter: options.useRouter === true || hasUseRouterFlag(args), model: options.model ?? null, tool: options.tool ?? 'claude', githubRepo: options.githubRepo ?? null, sessionId, env: hostEnv, verbose });
+  if (routerError) {
+    await releaseFormalAiSidecarForTask({ sidecar, sessionId, env: hostEnv, verbose });
+    return failLaunch(routerError);
+  }
+  // R11: when both sidecars are up, the router is taught to serve `formal-ai`
+  // itself, so that model is mediated and audited like every other one. Done
+  // before the container is created because the provider has to exist by the
+  // time the task issues its first request.
+  const formalAiRoutingError = await registerFormalAiWithRouter({ router, sidecar, verbose });
+  if (formalAiRoutingError) {
+    await releaseRouterForTask({ router, sessionId, env: hostEnv, verbose });
+    await releaseFormalAiSidecarForTask({ sidecar, sessionId, env: hostEnv, verbose });
+    return failLaunch(formalAiRoutingError);
+  }
   const taskEnv = sidecar ? { ...hostEnv, HIVE_MIND_FORMAL_AI_BASE_URL: sidecar.baseUrl } : hostEnv;
   const effectiveOptions =
     backend === 'docker'
@@ -596,7 +430,7 @@ export async function executeWithIsolation(command, args, options = {}) {
           env: await resolveFormalAiIsolationEnv(taskEnv),
         }
       : options;
-  const startCommandArgs = buildStartCommandArgs(command, args, { ...effectiveOptions, sessionId });
+  const startCommandArgs = buildStartCommandArgs(command, args, { ...effectiveOptions, sessionId, useRouter: Boolean(router), routerToken: router?.token ?? null });
   if (verbose) {
     console.log(`[VERBOSE] isolation-runner: ${[binPath, ...startCommandArgs].map(shellQuote).join(' ')}`);
     if (backend === 'docker') {
@@ -620,6 +454,7 @@ export async function executeWithIsolation(command, args, options = {}) {
   }
   let containerFilesystemStartBytes = null;
   let formalAiAttachError = null;
+  let routerAttachError = null;
   if (result.success && backend === 'docker') {
     try {
       containerFilesystemStartBytes = await getDockerContainerWritableLayerSize(sessionId, verbose);
@@ -632,10 +467,17 @@ export async function executeWithIsolation(command, args, options = {}) {
       // start sequence, and doing it here keeps the attach fail-closed on any
       // installed version instead of silently one-network on older parsers.
       formalAiAttachError = await attachFormalAiTaskContainer({ sidecar, sessionId, verbose });
+      routerAttachError = await attachRouterTaskContainer({ router, sessionId, env: hostEnv, verbose });
     } finally {
       await releaseDockerContainerStartGate(sessionId, verbose);
     }
   }
+  if (router && (!result.success || formalAiAttachError || routerAttachError)) {
+    // Fail closed for the same reason the acquire does: a task that cannot
+    // reach the router must not be left running with no route to a model.
+    if (routerAttachError) await removeDockerContainer(sessionId, verbose);
+    await releaseRouterForTask({ router, sessionId, env: hostEnv, verbose });
+  }
   if (sidecar && (!result.success || formalAiAttachError)) {
     // Fail closed: without the internal network the task cannot reach Formal
     // AI, and issue #2146 forbids falling back to another model.
@@ -645,6 +487,10 @@ export async function executeWithIsolation(command, args, options = {}) {
       return failLaunch(`Formal AI task container could not be attached to the internal Formal AI network, so the task was stopped instead of falling back to another model (issue #2146): ${formalAiAttachError}`, { output: result.output });
     }
   }
+  if (routerAttachError) {
+    if (sidecar) await releaseFormalAiSidecarForTask({ sidecar, sessionId, env: hostEnv, verbose });
+    return failLaunch(`The task container could not be joined to the router (internal network, CA trust or api.github.com interception), so it was stopped rather than run without a route to any model (issue #2164): ${routerAttachError}`, { output: result.output });
+  }
   // Issue #1939: capture the freshly-launched docker session's reported status
   // and the live container state together, so the next iteration has the data to
   // diagnose a premature "executed/-1" status (problem #1) or a surprise image
@@ -700,45 +546,6 @@ export async function querySessionStatus(sessionId, verbose = false) {
     return { exists: false, uuid: null, status: null, exitCode: null, startTime: null, endTime: null, currentTime: null, logPath: null, command: null, isolation: null, workingDirectory: null, sessionName: null, processIds: {}, raw: '' };
   }
 }
-/**
- * Parse output from `$ --list --output-format json`.
- *
- * start-command may return a top-level array, or an object with an
- * `executions`/`sessions` array. Each entry is normalized to the same shape used
- * by {@link parseSessionStatusOutput} (uuid/status/exitCode/command/isolation/…).
- * Tolerant of unknown layouts — anything unparseable yields an empty list.
- *
- * @param {string} output - Raw stdout from `$ --list`
- * @returns {Array<{uuid: string|null, status: string|null, exitCode: number|null, startTime: string|null, endTime: string|null, command: string|null, isolation: string|null, workingDirectory: string|null, sessionName: string|null}>}
- */
-export function parseSessionListOutput(output) {
-  const raw = (output || '').trim();
-  if (!raw) return [];
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    return [];
-  }
-  const records = Array.isArray(parsed) ? parsed : Array.isArray(parsed?.executions) ? parsed.executions : Array.isArray(parsed?.sessions) ? parsed.sessions : parsed && typeof parsed === 'object' ? [parsed] : [];
-  return records
-    .map(data => {
-      if (!data || typeof data !== 'object') return null;
-      const isolationCandidate = (typeof data.isolation === 'string' && data.isolation) || (typeof data.options?.isolated === 'string' && data.options.isolated) || (typeof data.options?.isolation === 'string' && data.options.isolation) || null;
-      return {
-        uuid: data.uuid || data.session || data.sessionId || null,
-        status: typeof data.status === 'string' ? data.status.toLowerCase() : null,
-        exitCode: data.exitCode !== undefined && data.exitCode !== null ? Number(data.exitCode) : null,
-        startTime: data.startTime || null,
-        endTime: data.endTime || null,
-        command: data.command || null,
-        isolation: isolationCandidate ? isolationCandidate.toLowerCase() : null,
-        workingDirectory: data.workingDirectory || null,
-        sessionName: data.sessionName || data.options?.sessionName || null,
-      };
-    })
-    .filter(Boolean);
-}
 /**
  * List all executions known to start-command via `$ --list --output-format json`.
  *