@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/engine/cli.mjs

@@ -0,0 +1,1204 @@
+/**
+ * lib/engine/cli.mjs — `cohort run`, the engine's headless entry point.
+ *
+ *   cohort run -p "<prompt>" --output-format json --model cohort-agentic \
+ *     --session-id <id> --max-turns 20 --mcp-config .mcp.json --strict-mcp-config \
+ *     --permission-mode dontAsk --allowedTools "Read,Grep,mcp__cohort"
+ *
+ * Flags mirror the subset of the `claude --print` surface maestro's lanes use,
+ * so the runtime adapter (W1-E) can swap binaries by changing argv[0] and a
+ * handful of env names:
+ *
+ *   -p, --print [prompt]         headless (the only mode); the prompt may
+ *                                follow -p, be positional, or come on stdin
+ *   --output-format text|json    default text
+ *   --model <tier>               default $COHORT_LLM_MODEL or cohort-agentic
+ *   --session-id <id>            start a session with this id, or continue it when it exists
+ *                                and no live run holds it (one writer per session)
+ *   --resume <id>                continue an existing session
+ *   --max-turns <n>              default 50
+ *   --append-system-prompt <s>   appended to the system prompt
+ *   --system-prompt <s>          replaces the base system prompt
+ *   --tools <list>               built-in tools to expose ("" for none; default all)
+ *   --base-url <url>             default $COHORT_LLM_BASE_URL
+ *   --wire openai|anthropic      default $COHORT_LLM_WIRE or openai
+ *   --max-output-tokens <n>      per-turn output ceiling (default 16000)
+ *   --wall-clock-ms <n>          whole-run time limit (default 30 min)
+ *   --mcp-config <file|json>     MCP servers (repeatable)
+ *   --strict-mcp-config          only the --mcp-config servers
+ *   --permission-mode <mode>     default|acceptEdits|plan|dontAsk|bypassPermissions
+ *   --dangerously-skip-permissions   = --permission-mode bypassPermissions
+ *   --allowedTools <rules>       allow rules (repeatable; comma or space separated)
+ *   --disallowedTools <rules>    deny rules; a rule with no specifier also hides the tool
+ *   --settings <file|json>       a settings layer above local/project/user
+ *   --add-dir <dir>              an extra directory acceptEdits may write in (repeatable)
+ *   --plugin-dir <dir>           a plugin root whose skills and subagents load (repeatable)
+ *   --output-format stream-json  NDJSON events (output/stream-json.mjs)
+ *   --input-format stream-json   one turn per NDJSON user line on stdin, until EOF
+ *   --include-partial-messages   stream_event deltas (stream-json output only)
+ *   --verbose                    debug notes on stderr
+ *   --agents <json>              inline subagent definitions (agents/definitions.mjs)
+ *   --effort <level>             reasoning effort where the tier takes it (wire/effort.mjs)
+ *   --bare                       no user/project/local settings, hooks, instruction files,
+ *                                skills, subagents or project MCP servers; managed settings,
+ *                                --settings, --mcp-config, --plugin-dir and --agents still apply
+ *
+ * W3-G1 adds the per-run tools (tools/session.mjs: TodoWrite, subagents,
+ * background shells, NotebookEdit), subagent discovery and the agent runtime,
+ * per-tier usage aggregation into the result (`modelUsage`, `cohort.modelUsage`,
+ * `cohort.todos`, `cohort.agents`), and a turn loop so one session can take
+ * several stream-json prompts.
+ *
+ * `cohort auth status --json` (auth-status.mjs) proves the credential against
+ * GET /cohort/v1/quota for doctor and the setup probe.
+ *
+ * The gateway credential comes from the environment only — never a flag, so it
+ * never lands in a process listing: `$COHORT_LLM_TOKEN_HELPER` (a command
+ * re-run on a TTL and after a 401, wire/token-provider.mjs) or
+ * `$COHORT_LLM_TOKEN`.
+ *
+ * What a run assembles, in order: settings layers (permissions, hooks, plugin
+ * dirs) → MCP config → the session → instruction files and skills → MCP
+ * servers → tool list (built-ins, Skill, MCP; fully denied tools hidden) →
+ * SessionStart and UserPromptSubmit hooks → the loop, with every tool call
+ * passing the guard (permissions, in-process gates, PreToolUse hooks) and
+ * Stop hooks consulted before it ends. MCP servers are shut down however the
+ * run ends.
+ *
+ * `parseRunArgs` is pure; `runCli` is the edge and takes every effect as a
+ * dependency, so the end-to-end tests drive it in-process. The user-level
+ * layers (~/.claude/…) come from `deps.homedir`, else `env.HOME`; with neither
+ * there is no user layer.
+ *
+ * @module lib/engine/cli
+ */
+
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { runLoop, DEFAULTS } from "./loop.mjs";
+import { createModelCaller, isWireName } from "./wire/index.mjs";
+import { parseIdleTimeoutMs, idleTimeoutNote, formatStreamDiagnostic } from "./wire/stall.mjs";
+import { selectTools, createToolContext } from "./tools/index.mjs";
+import { openSession, appendMessage, appendResult, acquireSessionLock } from "./session/store.mjs";
+import { createTokenProvider } from "./wire/token-provider.mjs";
+import { runAuthStatus } from "./auth-status.mjs";
+import { buildResult, buildSetupErrorResult } from "./output/json.mjs";
+import { buildSystemPrompt } from "./prompt.mjs";
+import { evaluatePermission, isPermissionMode, isToolFullyDenied, splitRuleList, PERMISSION_MODES } from "./permissions.mjs";
+import { loadSettingsLayers, mergeSettings, defaultManagedSettingsPath, userConfigDir } from "./context/settings.mjs";
+import { loadInstructions, formatInstructions, defaultManagedInstructionsPath } from "./context/instructions.mjs";
+import { discoverSkills, formatSkillListing, createSkillTool } from "./skills/index.mjs";
+import { readMcpConfigArg, loadMcpLayers, resolveMcpServers, filterProjectServers } from "./mcp/config.mjs";
+import { startMcpServers } from "./mcp/index.mjs";
+import { createHookRunner, createDefaultGates, SEND_GATE_NAME } from "./hooks.mjs";
+import { createToolGuard } from "./guard.mjs";
+import { createPathResolver } from "./context/real-path.mjs";
+import { appendJsonl } from "../fs-atomic.mjs";
+// W3-G1: subagents, session tools, stream-json, --effort.
+import { parseAgentsJson, discoverAgents } from "./agents/definitions.mjs";
+import { createAgentRuntime, subagentPrompt, DEFAULT_MAX_AGENT_DEPTH } from "./agents/runtime.mjs";
+import { createWorkflowRuntime, workflowTimingFromEnv } from "./workflow/runtime.mjs";
+import { mergeNotificationSources } from "./workflow/notifications.mjs";
+import { createWorkflowTools } from "./tools/workflow.mjs";
+import { aggregateUsage } from "./agents/usage.mjs";
+import { createSessionToolkit, wantedSessionTools, SESSION_TOOL_NAMES } from "./tools/session.mjs";
+import { createTodoState, loadSessionTodos } from "./tools/todo.mjs";
+import { createStreamJsonWriter, observeQuota, parseInputLine } from "./output/stream-json.mjs";
+import { EFFORT_LEVELS, isEffortLevel, resolveEffort } from "./wire/effort.mjs";
+// W3-G2: context management, prompt caching, deferred tools, web tools, MCP resources, CF-21.
+import { createContextManager } from "./context/manager.mjs";
+import { resolveContextConfig } from "./context/budget.mjs";
+import { stableToolOrder, promptCacheKey } from "./context/cache.mjs";
+import { resumeHistory } from "./context/compaction.mjs";
+import { createLazyInstructions } from "./context/lazy-instructions.mjs";
+import { createStreamInput, parseStreamInputLine } from "./context/stream-input.mjs";
+import { isCoreCredentialEnvName, parseEnvNameList, parsePassthroughEnv, PROJECT_SCOPES, withheldByValue } from "./context/child-env.mjs";
+import { createDeferredTools, createToolSearchTool, shouldDeferTools, formatDeferredNote } from "./tools/toolsearch.mjs";
+import { createMcpResourceTools } from "./mcp/resources.mjs";
+import { transcriptMessage } from "./context/images.mjs";
+import { webToolsEnabled, WEB_TOOL_NAMES } from "./tools/web-switch.mjs";
+import { createPromptCacheKeyState, promptCacheKeyMode } from "./wire/prompt-cache.mjs";
+// W4-A1: background-shell completion notices (CF-50); `cohort session` plugs in through `deps.host`.
+import { createNotificationQueue, shellExitNotice } from "./session-runtime/notifications.mjs";
+// W4-E1: --max-budget-usd.
+import { parseBudgetUsd, createBudgetMeter } from "./budget.mjs";
+// W4-E2: slash commands and skills invoked from a prompt (rows 14, 34).
+import { discoverCommands, expandSlashCommand, resolveSlashCommand } from "./commands/index.mjs";
+import { resolveAgentModel } from "./agents/definitions.mjs";
+
+export const DEFAULT_MODEL = "cohort-agentic";
+export const DEFAULT_MAX_OUTPUT_TOKENS = 16_000;
+
+export const USAGE = `Usage: cohort run [-p] "<prompt>" [flags]
+       cohort auth status [--json] [--base-url <url>]   does the gateway credential work?
+
+Run the Cohort Engine headless: the prompt is worked to completion with the
+built-in tools, MCP tools and skills, and the answer is printed.
+
+Flags:
+  -p, --print [prompt]         Headless mode; the prompt may follow -p
+  --output-format text|json    Output format (default text)
+  --model <tier>               Model tier (default $COHORT_LLM_MODEL or ${DEFAULT_MODEL})
+  --session-id <id>            Start a session with this id, or continue it if it exists
+  --resume <id>                Continue an existing session
+  --max-turns <n>              Maximum model turns (default ${DEFAULTS.maxTurns})
+  --append-system-prompt <s>   Text appended to the system prompt
+  --system-prompt <s>          Replace the base system prompt
+  --tools <list>               Built-in tools to expose, comma-separated ("" for none)
+  --base-url <url>             Gateway URL (default $COHORT_LLM_BASE_URL)
+  --wire openai|anthropic      Gateway wire (default $COHORT_LLM_WIRE or openai)
+  --max-output-tokens <n>      Output tokens per turn (default ${DEFAULT_MAX_OUTPUT_TOKENS})
+  --wall-clock-ms <n>          Time limit for the whole run (default ${DEFAULTS.wallClockMs})
+  --mcp-config <file|json>     MCP servers to connect (repeatable)
+  --strict-mcp-config          Use only --mcp-config servers
+  --permission-mode <mode>     ${PERMISSION_MODES.join("|")}
+  --dangerously-skip-permissions  Same as --permission-mode bypassPermissions
+  --allowedTools <rules>       Allow rules, e.g. "Read,Bash(npm run test:*),mcp__cohort"
+  --disallowedTools <rules>    Deny rules
+  --settings <file|json>       Extra settings layer
+  --add-dir <dir>              Extra directory edits are accepted in (repeatable)
+  --plugin-dir <dir>           Plugin root to load skills and subagents from (repeatable)
+  --output-format stream-json  NDJSON events instead of one result
+  --input-format text|stream-json  stream-json (needs stream-json output): user turns as
+                               NDJSON on stdin, and {"type":"control","subtype":"compact"}
+  --include-partial-messages   With stream-json output: stream deltas
+  --verbose                    Print debug notes on stderr
+  --agents <json>              Subagent definitions: {"name":{"description","prompt","tools","model"}}
+  --effort <level>             ${EFFORT_LEVELS.join("|")}: reasoning effort where the tier takes it
+  --bare                       No user/project settings, hooks, instructions, skills, subagents or
+                               project MCP; managed policy, --settings and --mcp-config still apply
+  --max-budget-usd <usd>       Stop before the next model call once the run (subagents included) has
+                               spent this much, by the gateway's cost figures (error_max_budget_usd)
+
+Environment:
+  COHORT_LLM_TOKEN             Gateway credential (this or COHORT_LLM_TOKEN_HELPER)
+  COHORT_LLM_TOKEN_HELPER      Command printing a fresh credential; re-run on a TTL and after a 401
+  COHORT_LLM_TOKEN_TTL_MS      How long a helper credential is reused (default 600000)
+  COHORT_LLM_BASE_URL          Gateway URL
+  COHORT_ENGINE_SESSIONS_DIR   Where transcripts are kept (default ~/.cohort/engine/sessions)
+  COHORT_ENGINE_CONTEXT_WINDOW Context window (tokens) to plan against
+  COHORT_ENGINE_COMPACT_THRESHOLD  Compact at this share of the window (default 0.85)
+  COHORT_ENGINE_WEB_TOOLS      0 drops WebFetch and WebSearch from the default tools
+  COHORT_ENGINE_AUTO_COMPACT   0 turns automatic compaction off
+  COHORT_ENGINE_IMAGE_INPUT    1/0: send tool-result images to the model
+  COHORT_LLM_PROMPT_CACHE_KEY  1/0: send prompt_cache_key (default: when the gateway says so)
+  COHORT_LLM_STREAM_IDLE_TIMEOUT_MS  End a gateway stream that sends no event for this long (default 60000; 0 disables; clamped to 5000-120000)
+`;
+
+const VALUE_FLAGS = new Map([
+  ["--output-format", "outputFormat"],
+  ["--model", "model"],
+  ["--session-id", "sessionId"],
+  ["--resume", "resume"],
+  ["-r", "resume"],
+  ["--max-turns", "maxTurns"],
+  ["--append-system-prompt", "appendSystemPrompt"],
+  ["--system-prompt", "systemPrompt"],
+  ["--tools", "tools"],
+  ["--base-url", "baseUrl"],
+  ["--wire", "wire"],
+  ["--max-output-tokens", "maxTokens"],
+  ["--wall-clock-ms", "wallClockMs"],
+  ["--permission-mode", "permissionMode"],
+  ["--settings", "settings"],
+  ["--input-format", "inputFormat"],
+  ["--effort", "effort"],
+  ["--agents", "agents"],
+  // W4-E1 (row 24): a hard spend cap on the run, from the gateway's cost figures.
+  ["--max-budget-usd", "maxBudgetUsd"],
+]);
+/** Flags that may repeat; values accumulate in order. */
+const LIST_FLAGS = new Map([
+  ["--mcp-config", "mcpConfig"],
+  ["--allowedTools", "allowedTools"],
+  ["--allowed-tools", "allowedTools"],
+  ["--disallowedTools", "disallowedTools"],
+  ["--disallowed-tools", "disallowedTools"],
+  ["--add-dir", "addDirs"],
+  ["--plugin-dir", "pluginDirs"],
+]);
+const BOOL_FLAGS = new Map([
+  ["--strict-mcp-config", "strictMcpConfig"],
+  ["--dangerously-skip-permissions", "dangerouslySkipPermissions"],
+  ["--bare", "bare"],
+  ["--verbose", "verbose"],
+  ["--include-partial-messages", "includePartialMessages"],
+]);
+/**
+ * Every flag spelling `parseRunArgs` recognises, derived from the tables above
+ * (plus the print/help spellings it handles inline). The runtime adapter's
+ * drift test reads this instead of a hand-kept copy, so a flag the adapter
+ * emits for engine cohort that the parser does not know fails the build.
+ */
+export const RUN_FLAGS = Object.freeze([
+  "-p", "--print", "-h", "--help",
+  ...VALUE_FLAGS.keys(), ...LIST_FLAGS.keys(), ...BOOL_FLAGS.keys(),
+]);
+const INT_FLAGS = new Set(["maxTurns", "maxTokens", "wallClockMs"]);
+const RULE_LISTS = new Set(["allowedTools", "disallowedTools"]);
+
+/**
+ * @param {string[]} argv  arguments after `run` (a leading `run` is tolerated)
+ * @returns {{ ok:true, opts: Record<string, any> } | { ok:false, error:string }}
+ */
+export function parseRunArgs(argv) {
+  const args = [...argv];
+  if (args[0] === "run") args.shift();
+  /** @type {Record<string, any>} */
+  const opts = {
+    outputFormat: "text",
+    inputFormat: "text",
+    print: false,
+    help: false,
+    prompt: null,
+    tools: null,
+    mcpConfig: [],
+    allowedTools: [],
+    disallowedTools: [],
+    addDirs: [],
+    pluginDirs: [],
+    strictMcpConfig: false,
+    dangerouslySkipPermissions: false,
+    bare: false,
+    verbose: false,
+    includePartialMessages: false,
+  };
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    let a = args[i];
+    let inline = null;
+    if (a.startsWith("--") && a.includes("=")) {
+      inline = a.slice(a.indexOf("=") + 1);
+      a = a.slice(0, a.indexOf("="));
+    }
+    if (a === "-h" || a === "--help") {
+      opts.help = true;
+    } else if (a === "-p" || a === "--print") {
+      opts.print = true;
+      const next = args[i + 1];
+      if (next !== undefined && !next.startsWith("-")) {
+        opts.prompt = next;
+        i++;
+      }
+    } else if (BOOL_FLAGS.has(a)) {
+      opts[/** @type string */ (BOOL_FLAGS.get(a))] = true;
+    } else if (VALUE_FLAGS.has(a) || LIST_FLAGS.has(a)) {
+      const key = /** @type string */ (VALUE_FLAGS.get(a) ?? LIST_FLAGS.get(a));
+      const value = inline ?? args[++i];
+      if (value === undefined) return { ok: false, error: `${a} needs a value` };
+      if (INT_FLAGS.has(key)) {
+        const n = Number(value);
+        if (!Number.isInteger(n) || n < 1) return { ok: false, error: `${a} must be a positive integer, got "${value}"` };
+        opts[key] = n;
+      } else if (RULE_LISTS.has(key)) {
+        opts[key].push(...splitRuleList(value));
+      } else if (LIST_FLAGS.has(a)) {
+        opts[key].push(value);
+      } else {
+        opts[key] = value;
+      }
+    } else if (a === "--") {
+      positional.push(...args.slice(i + 1));
+      break;
+    } else if (a.startsWith("-") && a !== "-") {
+      return { ok: false, error: `unknown flag ${a}` };
+    } else {
+      positional.push(a);
+    }
+  }
+  if (opts.prompt === null && positional.length > 0) opts.prompt = positional.join(" ");
+  if (!["text", "json", "stream-json"].includes(opts.outputFormat)) {
+    return { ok: false, error: `--output-format must be text, json or stream-json` };
+  }
+  if (opts.inputFormat !== "text" && opts.inputFormat !== "stream-json") return { ok: false, error: "--input-format must be text or stream-json" };
+  if (opts.inputFormat === "stream-json" && opts.outputFormat !== "stream-json") return { ok: false, error: "--input-format stream-json needs --output-format stream-json" };
+  if (opts.includePartialMessages && opts.outputFormat !== "stream-json") return { ok: false, error: "--include-partial-messages needs --output-format stream-json" };
+  if (opts.effort !== undefined && !isEffortLevel(opts.effort)) return { ok: false, error: `--effort must be one of ${EFFORT_LEVELS.join(", ")}` };
+  if (opts.agents !== undefined) {
+    const parsedAgents = parseAgentsJson(opts.agents);
+    if (!parsedAgents.ok) return { ok: false, error: parsedAgents.error };
+    opts.agents = parsedAgents.agents;
+  } else {
+    opts.agents = [];
+  }
+  if (opts.maxBudgetUsd !== undefined) {
+    const b = parseBudgetUsd(opts.maxBudgetUsd);
+    if (!b.ok) return { ok: false, error: b.error };
+    opts.maxBudgetUsd = b.usd;
+    opts.maxBudgetMicros = b.micros;
+  }
+  if (opts.wire !== undefined && !isWireName(opts.wire)) return { ok: false, error: `--wire must be openai or anthropic` };
+  if (opts.sessionId && opts.resume && opts.sessionId !== opts.resume) {
+    return { ok: false, error: "--session-id and --resume name different sessions; pass one" };
+  }
+  if (opts.permissionMode !== undefined && !isPermissionMode(opts.permissionMode)) {
+    return { ok: false, error: `--permission-mode must be one of ${PERMISSION_MODES.join(", ")}` };
+  }
+  if (opts.dangerouslySkipPermissions && opts.permissionMode !== undefined && opts.permissionMode !== "bypassPermissions") {
+    return { ok: false, error: `--dangerously-skip-permissions conflicts with --permission-mode ${opts.permissionMode}` };
+  }
+  if (typeof opts.tools === "string") {
+    opts.tools = opts.tools.trim() === "" ? [] : opts.tools.split(/[,\s]+/).filter(Boolean);
+  }
+  return { ok: true, opts };
+}
+
+/**
+ * Did argv ask for JSON output? Read from the raw argv so it still answers when
+ * `parseRunArgs` refused some other flag.
+ * @param {string[]} argv
+ */
+export function wantsJson(argv) {
+  const structured = (/** @type {string|undefined} */ v) => v === "json" || v === "stream-json";
+  return argv.some((a, i) => (a.startsWith("--output-format=") && structured(a.slice("--output-format=".length))) || (a === "--output-format" && structured(argv[i + 1])));
+}
+
+/**
+ * @typedef {Object} CliFs
+ * @property {(p:string)=>string} readFile
+ * @property {(p:string)=>boolean} exists
+ * @property {(p:string)=>boolean} isFile
+ * @property {(p:string)=>boolean} isDir
+ * @property {(p:string)=>string[]} readdir
+ * @property {(p:string)=>string} realpath
+ */
+
+/** @type {CliFs} */
+export const NODE_FS = Object.freeze({
+  readFile: (p) => readFileSync(p, "utf8"),
+  exists: (p) => existsSync(p),
+  isFile: (p) => {
+    try {
+      return statSync(p).isFile();
+    } catch {
+      return false;
+    }
+  },
+  isDir: (p) => {
+    try {
+      return statSync(p).isDirectory();
+    } catch {
+      return false;
+    }
+  },
+  readdir: (p) => readdirSync(p),
+  realpath: (p) => realpathSync(p),
+});
+
+/**
+ * @typedef {Object} CliDeps
+ * @property {NodeJS.ProcessEnv} [env]
+ * @property {string} [cwd]
+ * @property {{ write: (s:string) => unknown }} [stdout]
+ * @property {{ write: (s:string) => unknown }} [stderr]
+ * @property {typeof fetch} [fetchImpl]         the gateway's fetch
+ * @property {typeof fetch} [mcpFetchImpl]      MCP streamable HTTP's fetch
+ * @property {() => number} [now]
+ * @property {() => string} [newId]
+ * @property {() => Promise<string>} [readStdin]
+ * @property {string|null} [homedir]            user layers (~/.claude); default env.HOME
+ * @property {string|null} [managedSettingsPath]
+ * @property {string|null} [managedInstructionsPath]
+ * @property {CliFs} [fs]
+ * @property {AbortSignal} [signal]
+ * @property {boolean} [useRipgrep]
+ * @property {(ms:number, s?:AbortSignal)=>Promise<void>} [sleep]
+ * @property {(command:string, o:{env:Record<string,string|undefined>}) => Promise<string>} [runTokenHelper]  runs COHORT_LLM_TOKEN_HELPER (tests)
+ * @property {number} [pid]  the session lock's holder pid (default process.pid; tests)
+ * @property {(pid:number) => boolean} [isProcessAlive]  whether a session lock's holder is alive (tests)
+ * @property {(pid:number) => string|null} [processStartTime]  a process's start time, for the session lock's pid-reuse check (tests)
+ * @property {AsyncIterable<Buffer|string> & {destroy?:()=>void}} [stdinStream]  --input-format stream-json source (bytes)
+ * @property {AsyncIterable<string>|Iterable<string>} [stdinLines]  --input-format stream-json source, one line per item (tests)
+ * @property {{allowHttp?:boolean, resolve?:Function, policy?:Function, cache?:any, now?:()=>number}} [web]  WebFetch network options (tests)
+ * @property {ReturnType<typeof import('./session-runtime/host.mjs').createSessionHost>} [host]
+ *           W4-A1 `cohort session`: its event queue, front-door tools, per-turn signals and approvals
+ */
+
+/**
+ * @param {string[]} argv
+ * @param {CliDeps} [deps]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runCli(argv, deps = {}) {
+  // `cli.mjs auth status --json`: does this process's gateway credential work (rows 1 and 25)?
+  if (argv[0] === "auth") return runAuthStatus(argv.slice(1), deps);
+  /** Inputs released however the run ends (stream-json stdin). @type {Array<{close:()=>void}>} */
+  const inputs = [];
+  try {
+    return await runCliBody(argv, deps, inputs);
+  } finally {
+    for (const i of inputs) i.close();
+  }
+}
+
+/** @param {string[]} argv @param {CliDeps} deps @param {Array<{close:()=>void}>} inputs */
+async function runCliBody(argv, deps, inputs) {
+  const env = deps.env ?? process.env;
+  const cwd = deps.cwd ?? process.cwd();
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const now = deps.now ?? Date.now;
+  const fs = deps.fs ?? NODE_FS;
+  const started = now();
+  const warn = (/** @type string */ line) => stderr.write(`cohort run: ${line}\n`);
+
+  const parsed = parseRunArgs(argv);
+  if (!parsed.ok) {
+    // A JSON caller parses stdout; it gets a result object even for a bad flag.
+    if (wantsJson(argv)) {
+      const wire = isWireName(env.COHORT_LLM_WIRE) ? env.COHORT_LLM_WIRE : "openai";
+      const r = buildSetupErrorResult({ sessionId: null, code: "invalid_arguments", message: parsed.error, durationMs: now() - started, wire });
+      stdout.write(JSON.stringify(r) + "\n");
+    } else {
+      stderr.write(`cohort run: ${parsed.error}\n\n${USAGE}`);
+    }
+    return 2;
+  }
+  const o = parsed.opts;
+  if (o.help) {
+    stdout.write(USAGE);
+    return 0;
+  }
+  const wire = o.wire ?? (isWireName(env.COHORT_LLM_WIRE) ? env.COHORT_LLM_WIRE : "openai");
+
+  /** @param {string} code @param {string} message @param {string|null} sessionId */
+  const setupFail = (code, message, sessionId = null) => {
+    if (o.outputFormat !== "text") {
+      const r = buildSetupErrorResult({ sessionId, code, message, durationMs: now() - started, wire });
+      stdout.write(JSON.stringify(r) + "\n");
+    } else {
+      stderr.write(`cohort run: ${message}\n`);
+    }
+    return 1;
+  };
+
+  const baseUrl = o.baseUrl ?? env.COHORT_LLM_BASE_URL;
+  if (!baseUrl) return setupFail("missing_base_url", "no gateway URL: pass --base-url or set COHORT_LLM_BASE_URL");
+  // The credential may outlive a seat token (a `cohort session` runs for days): a helper
+  // command re-mints it on a TTL and after a 401; a bare COHORT_LLM_TOKEN is used as given.
+  const tokenProvider = createTokenProvider({ env, now, ...(deps.runTokenHelper ? { runHelper: deps.runTokenHelper } : {}) });
+  if (!tokenProvider.ok) return setupFail(tokenProvider.error.code, tokenProvider.error.message);
+  const token = tokenProvider.token;
+
+  // --input-format stream-json: turns arrive as NDJSON on stdin (a -p prompt, if any, is the first).
+  const streamInputWanted = o.inputFormat === "stream-json";
+  let prompt = o.prompt;
+  if (streamInputWanted && prompt === "-") prompt = null;
+  if (!streamInputWanted && (prompt === null || prompt === "-") && deps.readStdin) prompt = (await deps.readStdin()).trim();
+  if (!prompt && !streamInputWanted) return setupFail("missing_prompt", "no prompt: pass it after -p, as an argument, or on stdin");
+
+  const wantSkill = o.tools == null || o.tools.includes("Skill");
+  const hostToolNames = deps.host?.toolNames ?? [];
+  const { tools: builtins, unknown } = selectTools(o.tools == null ? null : o.tools.filter((/** @type string */ n) => n !== "Skill" && !SESSION_TOOL_NAMES.includes(n) && !hostToolNames.includes(n)));
+  if (unknown.length > 0) return setupFail("unknown_tool", `unknown tool(s) in --tools: ${unknown.join(", ")}`);
+
+  // ── settings: permissions, hooks, plugin dirs ──────────────────────────────
+  const homedir = deps.homedir !== undefined ? deps.homedir : env.HOME || null;
+  const userDir = userConfigDir({ homedir, cwd, env });
+  const platform = os.platform();
+  const loadedSettings = loadSettingsLayers({
+    homedir,
+    cwd,
+    env,
+    managedPath: deps.managedSettingsPath !== undefined ? deps.managedSettingsPath : defaultManagedSettingsPath(platform),
+    cliSettings: o.settings ?? null,
+    readFile: fs.readFile,
+    exists: fs.exists,
+  });
+  // --bare: of the settings files, only managed policy and an explicit --settings apply.
+  const settingsLayers = o.bare ? loadedSettings.layers.filter((l) => l.scope === "managed" || l.scope === "cli") : loadedSettings.layers;
+  const settings = mergeSettings(settingsLayers, {
+    allowedTools: o.allowedTools,
+    disallowedTools: o.disallowedTools,
+    permissionMode: o.dangerouslySkipPermissions ? "bypassPermissions" : o.permissionMode ?? null,
+    cwd,
+  });
+  // A settings problem that could drop a deny rule or a hook stops the run.
+  const settingsErrors = [...(o.bare ? loadedSettings.errors.filter((e) => /^(managed settings|cli settings|--settings)/.test(e)) : loadedSettings.errors), ...settings.errors];
+  if (settingsErrors.length > 0) return setupFail("invalid_settings", `settings could not be applied: ${settingsErrors.join("; ")}`);
+  for (const w of settings.warnings) warn(w);
+  const mode = settings.mode;
+  if (!isPermissionMode(mode)) return setupFail("invalid_settings", `permissions.defaultMode "${mode}" is not one of ${PERMISSION_MODES.join(", ")}`);
+  if (mode === "bypassPermissions" && settings.disableBypassPermissionsMode) {
+    return setupFail("bypass_disabled", "bypassPermissions mode is disabled by settings (permissions.disableBypassPermissionsMode)");
+  }
+
+  // ── MCP configuration (parsed before a session is created) ─────────────────
+  const cliServers = [];
+  const mcpErrors = [];
+  for (const value of o.mcpConfig) {
+    const r = readMcpConfigArg(value, { cwd, readFile: fs.readFile, env });
+    cliServers.push(...r.servers);
+    mcpErrors.push(...r.errors);
+  }
+  if (mcpErrors.length > 0) return setupFail("invalid_mcp_config", mcpErrors.join("; "));
+  let mcpLayers = { user: [], project: [], local: [] };
+  /** Project servers left unstarted, reported in the result. */
+  const notStarted = [];
+  if (!(o.strictMcpConfig || o.bare)) {
+    const loaded = loadMcpLayers({ homedir, cwd, readFile: fs.readFile, exists: fs.exists, env });
+    for (const e of loaded.errors) warn(e);
+    // A repository's .mcp.json runs only what the user (or the organisation) approved.
+    const approved = filterProjectServers(loaded.layers.project, [loaded.approval, settings.mcpApproval]);
+    mcpLayers = { ...loaded.layers, project: approved.servers };
+    for (const s of approved.unapproved) {
+      warn(`MCP server "${s.name}" from ${s.source} was not started: project servers need approval (enabledMcpjsonServers or enableAllProjectMcpServers in ~/.claude/settings.json), or pass it with --mcp-config`);
+      notStarted.push({ name: s.name, source: s.source, transport: s.transport, status: "not_approved", tools: 0 });
+    }
+    for (const s of approved.disabled) notStarted.push({ name: s.name, source: s.source, transport: s.transport, status: "disabled", tools: 0 });
+  }
+  const servers = resolveMcpServers({ cli: cliServers, strict: o.strictMcpConfig || o.bare, ...mcpLayers });
+  const startedServers = new Set(servers.map((s) => s.name));
+
+  // ── session ────────────────────────────────────────────────────────────────
+  // CF-21: settings `model` is the default tier, below --model and COHORT_LLM_MODEL.
+  let settingsModel = settings.model;
+  if (settingsModel && !settingsModel.startsWith("cohort-")) {
+    warn(`settings model "${settingsModel}" is not a Cohort tier (cohort-…) and is ignored`);
+    settingsModel = null;
+  }
+  const model = o.model ?? env.COHORT_LLM_MODEL ?? settingsModel ?? DEFAULT_MODEL;
+  // CF-21: settings `env` reaches tool, hook and MCP child processes (each behind
+  // its own credential scrub) — never the engine's own gateway configuration.
+  /** @type {Record<string,string|undefined>} */
+  const childEnv = { ...env };
+  for (const [k, v] of Object.entries(settings.env)) {
+    if (isCoreCredentialEnvName(k)) warn(`settings env ${k} has a credential's name and is not applied`);
+    else childEnv[k] = v;
+  }
+  // CF-22: extended-shape secrets (GITHUB_TOKEN, *_SECRET, *_PASSWORD, …) a seat lets through to
+  // Bash, hooks and MCP children — from managed, --settings or user settings and the engine's own
+  // env, never from a repository's settings. Model, gateway and org credentials are never passed.
+  /** @type {Set<string>} */
+  const passthroughNames = new Set(parsePassthroughEnv(env.COHORT_ENGINE_ENV_PASSTHROUGH));
+  for (const layer of settingsLayers) {
+    const list = layer.settings?.cohort?.envPassthrough;
+    if (list === undefined) continue;
+    if (PROJECT_SCOPES.has(layer.scope)) {
+      warn(`${layer.scope} ${layer.path}: cohort.envPassthrough is honoured only in user, managed or --settings settings (ignored)`);
+      continue;
+    }
+    const parsed = parseEnvNameList(list);
+    if (!parsed.ok) warn(`${layer.scope} ${layer.path}: cohort.envPassthrough ${parsed.error} (ignored)`);
+    else for (const n of parsed.names) passthroughNames.add(n);
+  }
+  for (const n of passthroughNames) if (isCoreCredentialEnvName(n)) warn(`cohort.envPassthrough names ${n}, a model, gateway or org credential, which is never passed through`);
+  const envPassthrough = [...passthroughNames].filter((n) => !isCoreCredentialEnvName(n));
+  // CF-118: variables withheld for their VALUE alone (a URL with a password, a vendor token, a long
+  // random run) — reported once per run, by name and rule, never by value.
+  const byValue = withheldByValue(childEnv, { passthrough: envPassthrough });
+  if (byValue.length > 0) {
+    warn(`environment ${byValue.map((w) => `${w.name} (${w.kind})`).join(", ")} withheld from Bash, Monitor, hooks and MCP servers: the value looks like a credential (name it in user or managed cohort.envPassthrough, or a hook's or server's inheritEnv, to pass it)`);
+  }
+  const sessionsDir = env.COHORT_ENGINE_SESSIONS_DIR || path.join(deps.homedir ?? os.homedir(), ".cohort", "engine", "sessions");
+  const sessionId = o.resume ?? o.sessionId ?? (deps.newId ?? randomUUID)();
+  // One writer per session, for the whole run (conformance row 4). A caller-chosen --session-id
+  // that already exists is continued — maestro's dispatcher crash recovery and responder
+  // continuation re-spawn `--session-id <same id> <prompt>` — unless a live run holds it.
+  const lock = acquireSessionLock({ dir: sessionsDir, sessionId, ...(deps.pid != null ? { pid: deps.pid } : {}), ...(deps.isProcessAlive ? { isAlive: deps.isProcessAlive } : {}), ...(deps.processStartTime ? { processStartTime: deps.processStartTime } : {}), now });
+  /**
+   * W4-E integration: one process-identity probe for everything that records "which process holds
+   * this" — the session lock above, subagent task states and workflow journals. Injected (tests) or
+   * the defaults, which are all process-identity.mjs.
+   */
+  const processIdentityDeps = {
+    ...(deps.pid != null ? { pid: deps.pid } : {}),
+    ...(deps.isProcessAlive ? { isProcessAlive: deps.isProcessAlive } : {}),
+    ...(deps.processStartTime ? { processStartToken: deps.processStartTime } : {}),
+  };
+  if (!lock.ok) return setupFail(lock.error.code, lock.error.message, sessionId);
+  inputs.push({ close: lock.release });
+  const opened = openSession({
+    dir: sessionsDir,
+    sessionId,
+    mode: o.resume ? "resume" : o.sessionId ? "continue" : "new",
+    meta: { cwd, model, wire },
+    now,
+  });
+  if (!opened.ok) return setupFail(opened.error.code, opened.error.message, sessionId);
+  const session = opened.session;
+  // A continued --session-id is a resume in every way a run can see (todos, SessionStart source).
+  const resumed = Boolean(o.resume) || opened.session.continued === true;
+
+  // ── instructions and skills ────────────────────────────────────────────────
+  // --bare loads no instruction files, and only plugin skills and agents from explicit plugin dirs.
+  const instructions = o.bare ? null : loadInstructions({
+    cwd,
+    homedir,
+    userDir,
+    managedPath: deps.managedInstructionsPath !== undefined ? deps.managedInstructionsPath : defaultManagedInstructionsPath(platform),
+    readFile: fs.readFile,
+    isFile: fs.isFile,
+    realpath: fs.realpath,
+    readdir: fs.readdir,
+    isDir: fs.isDir,
+  });
+  for (const e of instructions?.errors ?? []) warn(`instructions: ${e}`);
+  // Subdirectory CLAUDE.md and path-scoped rules on first touch: one tracker per conversation (the run, each subagent).
+  const newLazyInstructions = () =>
+    instructions ? createLazyInstructions({ cwd, homedir, readFile: fs.readFile, isFile: fs.isFile, realpath: fs.realpath, loaded: instructions.files.map((f) => f.path), conditionalRules: instructions.conditionalRules }) : null;
+  const pluginDirs = [...settings.pluginDirs, ...o.pluginDirs.map((/** @type string */ d) => ({ dir: path.resolve(cwd, d), source: "--plugin-dir" }))];
+  const discovered = discoverSkills({ userDir: o.bare ? null : userDir, cwd, pluginDirs, fs });
+  for (const e of discovered.errors) warn(`skills: ${e}`);
+  const skills = wantSkill ? discovered.skills.filter((s) => !o.bare || s.source === "plugin") : [];
+  // W4-E2: `/name args` in a prompt — project and user command files, skills, plugin commands.
+  const slashSkills = discovered.skills.filter((s) => !o.bare || s.source === "plugin");
+  const discoveredCommands = discoverCommands({ userDir: o.bare ? null : userDir, cwd: o.bare ? null : cwd, pluginDirs, fs });
+  for (const e of discoveredCommands.errors) warn(`commands: ${e}`);
+  const agentDefs = discoverAgents({ cliAgents: o.agents, userDir, cwd, seatRoot: env.AGENT_ROOT || null, pluginDirs, bare: o.bare, fs });
+  for (const e of agentDefs.errors) warn(`agents: ${e}`);
+
+  // ── MCP servers: from here on they must be shut down ───────────────────────
+  const mcp = await startMcpServers(servers, { env: childEnv, envPassthrough, cwd, fetchImpl: deps.mcpFetchImpl, clientInfo: { name: "cohort-engine", version: packageVersion() } });
+  for (const e of mcp.errors) warn(e);
+  /** @type {ReturnType<typeof createSessionToolkit>|null} */
+  let kit = null;
+  /** @type {ReturnType<typeof createAgentRuntime>|null} */
+  let agentRuntime = null;
+  /** @type {ReturnType<typeof createWorkflowRuntime>|null} */
+  let workflows = null;
+  try {
+    // --output-format stream-json: every event goes through this writer.
+    const writer = o.outputFormat === "stream-json" ? createStreamJsonWriter({ write: (s) => stdout.write(s), sessionId: session.id, includePartialMessages: o.includePartialMessages, wire }) : null;
+    const mcpServerStatuses = () => [...mcp.statuses.map(({ error, ...s }) => (error ? { ...s, error } : s)), ...notStarted.filter((s) => !startedServers.has(s.name))];
+    const hidden = (/** @type {{name:string}} */ t) => isToolFullyDenied(t.name, settings.rules);
+    const context = resolveContextConfig({ tier: model, settings: settings.engine, env });
+    for (const w of context.warnings) warn(w);
+
+    const gates = createDefaultGates({ env, now, sessionId: session.id, cwd });
+    // CF-20: with the send gate in process, the seat's pre-send-audit.sh hook is
+    // skipped for the gated tools, so an allowed send is counted once.
+    const hooks = createHookRunner({ hooks: settings.hooks, sessionId: session.id, transcriptPath: session.path, cwd, permissionMode: mode, env: childEnv, envPassthrough, log: (l) => warn(`hook: ${l}`), sendGateInProcess: gates.list().includes(SEND_GATE_NAME) });
+    const additionalDirectories = [...settings.additionalDirectories, ...o.addDirs.map((/** @type string */ d) => path.resolve(cwd, d))];
+    const configDirs = env.CLAUDE_CONFIG_DIR ? [path.resolve(cwd, env.CLAUDE_CONFIG_DIR)] : [];
+    // CF-19: every permission decision follows symlinks to where a path really leads.
+    const resolvePath = deps.resolvePath ?? createPathResolver();
+    // One guard per run and per subagent, all from the same rules, gates and hooks.
+    // W4-A1: a subagent's asks carry its id, so a session approval ("always") is remembered per agent.
+    // W4-A2: a workflow child may run in its own directory (a git worktree).
+    const hostAsk = deps.host?.askPermission ?? null;
+    const guardFor = (/** @type string */ m, /** @type {string|null} */ agentId = null, /** @type {string|undefined} */ childCwd = undefined) =>
+      createToolGuard({ mode: m, rules: settings.rules, cwd: childCwd ?? cwd, homedir, additionalDirectories, configDirs, resolvePath, gates, hooks, ask: hostAsk && agentId ? (q) => hostAsk({ ...q, agentId }) : hostAsk });
+    const guard = guardFor(mode);
+
+    // ── model callers ─────────────────────────────────────────────────────────
+    const flag = (/** @type {string|undefined} */ v) => (/^(1|true|on|yes)$/i.test(String(v ?? "")) ? true : /^(0|false|off|no)$/i.test(String(v ?? "")) ? false : null);
+    const imageInput = flag(env.COHORT_ENGINE_IMAGE_INPUT) ?? settings.engine.imageInput ?? wire === "anthropic";
+    const gatewayHeaders = { "x-cohort-surface": "engine", "x-cohort-session-id": session.id };
+    // W4-E1 (row 24): one spend meter for the run, its subagents and its workflow children.
+    const budget = o.maxBudgetMicros !== undefined ? createBudgetMeter({ maxMicros: o.maxBudgetMicros }) : null;
+    // CF-156: a stalled stream ends on its own silence budget and says why on
+    // stderr. A stall or a mid-stream fault always reports — that is the
+    // evidence W13 did not have — while a merely slow stream reports only
+    // under --verbose, so an ordinary run stays quiet.
+    const idleTimeoutMs = parseIdleTimeoutMs(env.COHORT_LLM_STREAM_IDLE_TIMEOUT_MS);
+    // A budget that did not parse, or that had to be clamped into its band, is
+    // said out loud: both failures leave a guard that LOOKS armed.
+    const idleNote = idleTimeoutNote(env.COHORT_LLM_STREAM_IDLE_TIMEOUT_MS, idleTimeoutMs);
+    if (idleNote) warn(idleNote);
+    const onStreamDiagnostic = (/** @type {import('./wire/stall.mjs').StreamDiagnostic} */ d) => {
+      if (d.outcome !== "slow" || o.verbose) warn(formatStreamDiagnostic(d));
+    };
+    const modelBase = { wire, baseUrl, token, maxTokens: o.maxTokens ?? DEFAULT_MAX_OUTPUT_TOKENS, fetchImpl: deps.fetchImpl, now, sleep: deps.sleep, images: imageInput, idleTimeoutMs, onStreamDiagnostic };
+    // OpenAI wire: one prompt_cache_key state per project and tier, shared by every caller on that tier
+    // (the run, its subagents, the compaction summary), so the gateway's advertisement is seen once.
+    /** @type {Map<string, ReturnType<typeof createPromptCacheKeyState>>} */
+    const promptCaches = new Map();
+    const promptCacheFor = (/** @type string */ tier) => {
+      if (wire !== "openai") return null;
+      const key = promptCacheKey({ cwd, model: tier });
+      if (!promptCaches.has(key)) promptCaches.set(key, createPromptCacheKeyState({ key, mode: promptCacheKeyMode(env.COHORT_LLM_PROMPT_CACHE_KEY, settings.engine.promptCacheKey) }));
+      return promptCaches.get(key) ?? null;
+    };
+    // A model caller for a tier: --effort where the tier takes it, prompt caching, partial
+    // messages (`partial`) and quota events for stream-json.
+    const effortNoted = new Set();
+    const createCaller = (/** @type {{model:string, headers:Record<string,string>, parentToolUseId?:string|null, partial?:boolean, effort?:string|null}} */ { model: tier, headers, parentToolUseId = null, partial = true, effort: effortOverride = null }) => {
+      const effort = resolveEffort({ effort: effortOverride ?? o.effort ?? null, wire, tier });
+      if (effort.note && o.verbose && !effortNoted.has(tier)) {
+        effortNoted.add(tier);
+        warn(effort.note);
+      }
+      const caller = createModelCaller({ ...modelBase, model: tier, headers, reasoningEffort: effort.param, promptCache: promptCacheFor(tier), onFrame: partial ? writer?.partialFrames(parentToolUseId) : undefined });
+      return writer ? observeQuota(caller, (q) => writer.quota(q, parentToolUseId)) : caller;
+    };
+    // The tool context of a conversation (the run, or one subagent): the web tools'
+    // gateway and side-tier callers carry that conversation's attribution headers.
+    const toolContextFor = (/** @type {Record<string,string>} */ headers, /** @type {string|undefined} */ childCwd) => {
+      /** @type {Map<string, ReturnType<typeof createModelCaller>>} */
+      const tierCallers = new Map();
+      const models = {
+        /** A request on another tier through the same gateway (WebFetch uses cohort-fast). @param {{tier:string, system:string, messages:any[], maxTokens?:number, signal?:AbortSignal}} r */
+        call({ tier, system: sys, messages, maxTokens, signal }) {
+          // --max-budget-usd spent: no further model call, a tool's side call included (never billed).
+          if (budget?.exhausted()) return Promise.resolve({ ok: false, accepted: false, error: { kind: "budget", code: "max_budget_usd", status: 0, message: "the run's --max-budget-usd is spent" }, cohort: null, apiMs: 0 });
+          if (!tierCallers.has(tier)) tierCallers.set(tier, createModelCaller({ ...modelBase, headers, model: tier }));
+          return /** @type {ReturnType<typeof createModelCaller>} */ (tierCallers.get(tier))({ system: sys, messages, tools: [], signal, maxTokens });
+        },
+      };
+      return { ...createToolContext({ cwd: childCwd ?? cwd, env: childEnv, useRipgrep: deps.useRipgrep, envPassthrough }), gateway: { baseUrl, token, headers, fetchImpl: deps.fetchImpl }, models, web: deps.web };
+    };
+
+    // ── session tools: the task list, background shells, subagents ───────────
+    const todoState = createTodoState({
+      initial: resumed ? loadSessionTodos(session.path) : [],
+      onChange: (todos) => {
+        if (!appendJsonl(session.path, { type: "todos", sessionId: session.id, ts: new Date(now()).toISOString(), todos })) session.writeFailures++;
+        writer?.todos(todos);
+      },
+    });
+    // Events for the model between requests (CF-50): background shells that ended, and — in a
+    // session — monitor lines; background subagents' reports join as a source below.
+    const notices = deps.host?.notices ?? createNotificationQueue();
+    kit = createSessionToolkit({ cwd, env: childEnv, envPassthrough, spillDir: path.join(sessionsDir, "shells", session.id), todoState, onShellExit: (s) => notices.push(shellExitNotice(s)) });
+    const promptBase = { cwd, platform: `${os.platform()} ${os.release()}`, date: new Date(now()).toISOString().slice(0, 10), instructions: instructions ? formatInstructions(instructions) : null };
+    // Child refusals belong to the turn that started the child. One that arrives
+    // after that turn's result was written is emitted on its own (stream-json).
+    let turnNo = 0;
+    /** @type {Map<number, any[]>} */
+    const childDenials = new Map();
+    const reportedTurns = new Set();
+    const addChildDenials = (/** @type {any[]} */ ds, /** @type {{turn:number|null}} */ meta) => {
+      const t = meta?.turn ?? turnNo;
+      if (reportedTurns.has(t)) {
+        writer?.emit({ type: "system", subtype: "cohort_late_permission_denials", turn: t, permission_denials: ds, session_id: session.id });
+        return;
+      }
+      childDenials.set(t, [...(childDenials.get(t) ?? []), ...ds]);
+    };
+
+    /**
+     * A subagent's own context (W3 integration): the parent's ToolSearch is bound to
+     * the parent's deferred state, so a child whose MCP tools cross the deferral
+     * threshold gets its own; and a context manager on the child's tier, so a long
+     * child compacts (its summary on the child's caller, billed to the child).
+     * @param {{def:any, model:string, tools:any[], headers:Record<string,string>, parentToolUseId:string|null, onCompact:(m:any)=>void}} c
+     */
+    const prepareChild = ({ def, model: tier, tools: granted, headers, parentToolUseId, onCompact }) => {
+      const childContext = resolveContextConfig({ tier, settings: settings.engine, env }).config;
+      let childTools = granted.filter((t) => t.name !== "ToolSearch");
+      /** @type {ReturnType<typeof createDeferredTools>|null} */
+      let childDeferred = null;
+      if (!hidden({ name: "ToolSearch" }) && shouldDeferTools({ tools: childTools, contextWindow: childContext.contextWindow })) {
+        childDeferred = createDeferredTools({ tools: [] });
+        childTools = stableToolOrder([...childTools.filter((t) => !t.mcp), createToolSearchTool(childDeferred), ...childTools.filter((t) => t.mcp)]);
+        childDeferred.replace(childTools);
+      }
+      const childManager = createContextManager({
+        config: childContext,
+        cwd,
+        summarise: createCaller({ model: tier, headers, parentToolUseId, partial: false }),
+        tools: childTools,
+        deferred: childDeferred,
+        hooks,
+        lazy: newLazyInstructions(),
+        // Children use the MCP tool list as it was when they started; list changes are the run's to pick up.
+        mcp: null,
+        input: null,
+        onCompact: ({ message }) => onCompact(message),
+        log: (l) => warn(`subagent ${def.name}: ${l}`),
+      });
+      return { tools: childTools, sent: childDeferred ? childDeferred.active() : childTools, notes: childDeferred ? formatDeferredNote(childDeferred) : null, context: childManager };
+    };
+
+    // cohort.maxAgentDepth from managed, --settings or user settings: a repository cannot raise it.
+    const depthSetting = settingsLayers.filter((l) => l.scope !== "project" && l.scope !== "local").map((l) => Number(l.settings?.cohort?.maxAgentDepth)).find((n) => Number.isInteger(n) && n >= 1);
+    agentRuntime = createAgentRuntime({
+      agents: agentDefs.agents,
+      sessionId: session.id,
+      sessionsDir,
+      cwd,
+      wire,
+      parentModel: model,
+      parentMode: mode,
+      parentAgentId: session.id,
+      maxDepth: depthSetting ?? DEFAULT_MAX_AGENT_DEPTH,
+      createCaller,
+      createGuard: ({ mode: m, agentId, cwd: childCwd }) => guardFor(m, agentId ?? null, childCwd),
+      buildSystem: ({ def, toolNames, notes, cwd: childCwd }) => buildSystemPrompt({ ...promptBase, ...(childCwd ? { cwd: childCwd } : {}), toolNames, append: subagentPrompt(def), skills: toolNames.includes("Skill") ? formatSkillListing(skills) : null, notes: notes ?? null }),
+      createToolContext: ({ headers, cwd: childCwd }) => toolContextFor(headers, childCwd),
+      prepareChild,
+      hooks,
+      onMessage: (m, { parentToolUseId }) => writer?.message(m, parentToolUseId),
+      onDenials: addChildDenials,
+      currentTurn: () => turnNo,
+      checkSubagent: ({ toolName, input, mode: m }) => evaluatePermission({ toolName, input, readOnly: true, mode: m, rules: settings.rules, cwd, homedir, additionalDirectories, configDirs, resolvePath }),
+      log: (l) => warn(l),
+      maxTurns: o.maxTurns,
+      wallClockMs: o.wallClockMs,
+      budget,
+      now,
+      shells: kit.shells,
+      onNotify: () => notices.poke(),
+      // W4-E2: task states record the process; a continued session reads them back (row 23).
+      // W4-E integration: the same identity probe as the session lock (process-identity.mjs).
+      ...processIdentityDeps,
+    });
+    notices.addSource(agentRuntime.drainNotifications);
+    // W4-A2: workflow runs. Their agent() children are this run's subagents (same ceiling,
+    // headers, usage records), and each agent type passes the Task(<type>) rules.
+    const budgetTokens = Number(env.COHORT_ENGINE_WORKFLOW_BUDGET_TOKENS);
+    const runtimeForChildren = agentRuntime;
+    workflows = createWorkflowRuntime({
+      sessionId: session.id,
+      sessionsDir,
+      cwd,
+      agents: agentDefs.agents,
+      runChild: (p) => runtimeForChildren.runChild(p),
+      checkAgent: ({ agentType }) => evaluatePermission({ toolName: "Task", input: { subagent_type: agentType }, readOnly: true, mode, rules: settings.rules, cwd, homedir, additionalDirectories, configDirs, resolvePath }),
+      checkRead: ({ path: file }) => evaluatePermission({ toolName: "Read", input: { file_path: file }, readOnly: true, mode, rules: settings.rules, cwd, homedir, additionalDirectories, configDirs, resolvePath }),
+      now,
+      // Workflow journals judge a run's process with the same probe as task states and the session lock.
+      ...processIdentityDeps,
+      budgetTokens: Number.isInteger(budgetTokens) && budgetTokens > 0 ? budgetTokens : null,
+      // W4-E2 (CF-90): an optional time limit per run, and the busy-watchdog and budget-grace knobs.
+      ...workflowTimingFromEnv(env),
+      onNotify: () => notices.poke(),
+    });
+    // Workflow results reach the loop through the same event queue as background subagents' reports.
+    notices.addSource(workflows.drainNotifications);
+    // W4-E2: TaskOutput and TaskStop take workflow run ids too.
+    agentRuntime.setWorkflowRuns(workflows);
+
+    // ── the run's tools ───────────────────────────────────────────────────────
+    // Tool order is part of the cached prefix: built-ins (the session Bash in Bash's
+    // place), Skill, session tools, MCP resource tools, then MCP tools by name.
+    // The web tools leave the default set when switched off (an explicit --tools list keeps them).
+    const webOff = o.tools == null && !webToolsEnabled({ env: env.COHORT_ENGINE_WEB_TOOLS, setting: settings.engine.webTools });
+    const baseTools = [
+      ...kit.withSessionBash(builtins.filter((t) => !(webOff && WEB_TOOL_NAMES.includes(t.name)))),
+      ...(skills.length > 0 ? [createSkillTool(skills, fs)] : []),
+      ...kit.tools({ wanted: wantedSessionTools(o.tools), agentTools: agentRuntime.tools(), workflowTools: createWorkflowTools(workflows) }),
+      ...createMcpResourceTools(() => mcp.connections, { isServerDenied: (name) => isToolFullyDenied(`mcp__${name}`, settings.rules) }),
+      // W4-A1: ListAgents, SendMessage, ScheduleWakeup, Monitor. A Monitor command is also held to the Bash deny/ask rules.
+      ...(deps.host
+        ? deps.host
+            .tools({
+              session,
+              kit,
+              checkCommand: (command) => evaluatePermission({ toolName: "Bash", input: { command }, readOnly: false, mode: "bypassPermissions", rules: settings.rules, cwd, homedir, additionalDirectories, configDirs, resolvePath }),
+            })
+            .filter((t) => o.tools == null || o.tools.includes(t.name))
+        : []),
+    ].filter((t) => !hidden(t));
+    let tools = stableToolOrder([...baseTools, ...mcp.tools.filter((t) => !hidden(t))]);
+    /** @type {ReturnType<typeof createDeferredTools>|null} */
+    let deferred = null;
+    /** @type {any} */
+    let toolSearch = null;
+    if (!hidden({ name: "ToolSearch" }) && shouldDeferTools({ tools, contextWindow: context.config.contextWindow })) {
+      deferred = createDeferredTools({ tools: [] });
+      toolSearch = createToolSearchTool(deferred);
+    }
+    const composeTools = (/** @type any[] */ mcpTools) => stableToolOrder([...baseTools, ...(toolSearch ? [toolSearch] : []), ...mcpTools.filter((t) => !hidden(t))]);
+    if (deferred) {
+      tools = composeTools(mcp.tools);
+      deferred.replace(tools);
+    }
+
+    const system = buildSystemPrompt({
+      ...promptBase,
+      toolNames: (deferred ? deferred.active() : tools).map((t) => t.name),
+      systemPrompt: o.systemPrompt ?? null,
+      append: o.appendSystemPrompt ?? null,
+      skills: formatSkillListing(skills),
+      notes: deferred ? formatDeferredNote(deferred) : null,
+    });
+
+    const sessionStart = await hooks.sessionStart({ source: resumed ? "resume" : "startup" });
+    writer?.init({ model, tools: tools.map((t) => t.name), mcpServers: mcpServerStatuses(), permissionMode: mode, cwd, agents: agentDefs.agents.map((a) => a.name), wire });
+
+    // stream-json input: one reader for user turns and control messages. Invalid lines
+    // are reported as they are read; user text keeps the note on blocks it left out.
+    /** @type {ReturnType<typeof createStreamInput>|null} */
+    let streamInput = null;
+    if (streamInputWanted) {
+      const source = deps.stdinStream ?? (deps.stdinLines ? linesAsChunks(deps.stdinLines) : process.stdin);
+      streamInput = createStreamInput(source, {
+        parse: parseInputItem,
+        onInvalid: (e) => {
+          warn(`stream-json input: ${e}`);
+          writer?.emit({ type: "system", subtype: "cohort_input_error", error: e, session_id: session.id });
+        },
+      });
+      inputs.push(streamInput);
+    }
+
+    const callModel = createCaller({ model, headers: gatewayHeaders });
+    // One context manager for the session: its calibration, compaction history and
+    // loaded deferred tools carry from turn to turn. A control message is drained at
+    // a turn boundary only when it arrived before the next user message.
+    const manager = createContextManager({
+      config: context.config,
+      cwd,
+      summarise: createCaller({ model, headers: gatewayHeaders, partial: false }),
+      tools,
+      deferred,
+      hooks,
+      lazy: newLazyInstructions(),
+      mcp,
+      composeTools,
+      input: streamInput ? { drain: () => /** @type {NonNullable<typeof streamInput>} */ (streamInput).drainControls() } : null,
+      onCompact: ({ message }) => appendMessage(session, transcriptMessage(message), now),
+      log: (l) => warn(l),
+    });
+    // Front-door tools belong to the session, not to its subagents.
+    agentRuntime.setParentTools(() => manager.tools.filter((/** @type any */ t) => !t.sessionOnly));
+    const toolContext = toolContextFor(gatewayHeaders);
+    // A headless run waits for background subagents' reports and workflow results together (their
+    // drains are sources of `notices`, so each notification is taken exactly once).
+    const notifications = mergeNotificationSources([agentRuntime, workflows]);
+
+    // One turn per prompt: the -p prompt, then (stream-json input) each user line until EOF.
+    let pendingPrompt = prompt ? String(prompt) : null;
+    const nextTurn = async () => {
+      if (pendingPrompt !== null) {
+        const t = pendingPrompt;
+        pendingPrompt = null;
+        return t;
+      }
+      if (!streamInput) return null;
+      const u = await streamInput.nextUser();
+      return u.ok ? u.text : null;
+    };
+
+    /**
+     * W4-E2: a prompt that invokes a command or skill carries its instructions instead (hooks saw the
+     * prompt as typed). Before expanding, the rules are consulted: `SlashCommand(/<name>)` (typed name
+     * and canonical name; `SlashCommand(/kit:*)` for a plugin; a bare `SlashCommand` for all) and, for a
+     * skill, `Skill(<name>)`. A deny or ask rule (nobody can be asked mid-prompt) refuses it: the prompt
+     * passes on as written with a note, and its frontmatter `model` does not apply. An unknown name
+     * passes with a note.
+     * @param {string} typed
+     * @returns {{text:string, model:string|null, invoked:{kind:string, name:string, file:string|null}|null}}
+     */
+    const expandPrompt = (typed) => {
+      const resolved = resolveSlashCommand({ text: typed, commands: discoveredCommands.commands, skills: slashSkills });
+      if (resolved.kind === "none") return { text: typed, model: null, invoked: null };
+      if (resolved.kind !== "unknown") {
+        const canonical = resolved.kind === "skill" ? resolved.skill.name : resolved.command.name;
+        const judge = (/** @type string */ toolName, /** @type any */ input) => evaluatePermission({ toolName, input, readOnly: true, mode, rules: settings.rules, cwd, homedir, additionalDirectories, configDirs, resolvePath });
+        const verdicts = [...new Set([resolved.name, canonical])].map((n) => judge("SlashCommand", { command: `/${n}` }));
+        if (resolved.kind === "skill") verdicts.push(judge("Skill", { skill: canonical }));
+        const refused = verdicts.find((v) => v.behavior !== "allow");
+        if (refused) {
+          const what = resolved.kind === "skill" ? `the "${canonical}" skill` : `the /${canonical} command`;
+          warn(`/${resolved.name}: ${what.replace(/"/g, "")} is refused (${refused.reason})`);
+          return { text: `${typed}\n\n[Note: ${what} is not available in this session (${refused.reason}); the message above is passed on as written.]`, model: null, invoked: null };
+        }
+      }
+      const x = expandSlashCommand(resolved, fs, typed);
+      if (!x.ok) {
+        warn(x.error);
+        return { text: `${typed}\n\n[Note: ${x.error}]`, model: null, invoked: null };
+      }
+      if (resolved.kind === "unknown") warn(`/${resolved.name} is not a command or skill here; passed on as written`);
+      return x;
+    };
+
+    let history = resumeHistory(session.messages);
+    let first = true;
+    /** @type {any} */
+    let last = null;
+    for (let text = await nextTurn(); text !== null; text = await nextTurn()) {
+      const turnStarted = first ? started : now();
+      const submitted = await hooks.userPromptSubmit({ prompt: text });
+      const hookStop = (first ? sessionStart.stopReason : null) ?? submitted.stopReason;
+      if (submitted.blockReason || hookStop) {
+        const [code, message] = submitted.blockReason
+          ? ["prompt_blocked", `the prompt was blocked by a UserPromptSubmit hook: ${submitted.blockReason}`]
+          : ["hook_stopped", `a hook ended the run before it started: ${hookStop}`];
+        if (!streamInput) return setupFail(code, message, session.id);
+        last = buildSetupErrorResult({ sessionId: session.id, code, message, durationMs: now() - turnStarted, wire });
+        writer?.result(last);
+        if (hookStop) break;
+        continue;
+      }
+
+      /** @type {Array<{type:'text', text:string}>} */
+      const blocks = [];
+      if (first && sessionStart.additionalContext) blocks.push({ type: "text", text: `Context from the session start hooks:\n${sessionStart.additionalContext}` });
+      const slash = expandPrompt(text);
+      blocks.push({ type: "text", text: slash.text });
+      /** A command's `model` runs this turn on that model's tier. */
+      let turnCaller = callModel;
+      if (slash.model) {
+        const r = resolveAgentModel(slash.model, model);
+        if (r.note) warn(`/${slash.invoked?.name}: ${r.note}`);
+        if (r.model !== model) turnCaller = createCaller({ model: r.model, headers: gatewayHeaders });
+      }
+      if (submitted.additionalContext) blocks.push({ type: "text", text: `Context from the prompt hooks:\n${submitted.additionalContext}` });
+      const prompted = { role: "user", content: blocks };
+      first = false;
+
+      const denialsBefore = guard.denials.length;
+      const compactionsBefore = manager.stats().compactions.length;
+      turnNo++;
+      appendMessage(session, prompted, now);
+      const outcome = await runLoop({
+        callModel: turnCaller,
+        system,
+        messages: [...history, prompted],
+        tools: manager.tools,
+        toolContext,
+        maxTurns: o.maxTurns,
+        wallClockMs: o.wallClockMs,
+        // A session interrupts one turn at a time; its own shutdown is deps.signal.
+        signal: deps.host ? deps.host.turnSignal() : deps.signal,
+        now,
+        onMessage: (m) => {
+          appendMessage(session, transcriptMessage(m), now);
+          writer?.message(m);
+        },
+        guard,
+        onStop: ({ stopHookActive }) => hooks.stop({ stopHookActive }),
+        drainNotifications: notices.drain,
+        // A session's turn does not wait for background agents or workflows: their reports arrive as events.
+        awaitNotifications: deps.host ? undefined : notifications.awaitNotifications,
+        context: manager,
+        budget,
+      });
+      // A run that ended without waiting (interrupted, out of turns) stops its background agents and workflows; their usage still counts.
+      // A session keeps them across turns (stopped when it ends, in the finally below).
+      if (!deps.host) {
+        await workflows.stopAll();
+        await agentRuntime.stopAll();
+      }
+      // The loop's history, compacted where compaction ran: the next turn continues from it.
+      history = outcome.messages;
+
+      const children = agentRuntime.drainRecords();
+      const total = aggregateUsage({ tier: outcome.modelTier || model, usage: outcome.usage, costMicros: outcome.costMicros, requestIds: outcome.requestIds }, children);
+      const result = buildResult({
+        outcome: children.length > 0 ? { ...outcome, usage: total.usage, costMicros: total.costMicros, requestIds: total.requestIds } : outcome,
+        sessionId: session.id,
+        durationMs: now() - turnStarted,
+        wire,
+        session: { path: session.path, writeFailures: session.writeFailures, skipped: session.skipped },
+      });
+      result.permission_denials = [...guard.denials.slice(denialsBefore), ...(childDenials.get(turnNo) ?? [])];
+      childDenials.delete(turnNo);
+      reportedTurns.add(turnNo);
+      result.modelUsage = total.modelUsage;
+      result.cohort.permissionMode = mode;
+      result.cohort.mcpServers = mcpServerStatuses();
+      result.cohort.modelUsage = total.cohortModelUsage;
+      result.cohort.todos = todoState.todos;
+      result.cohort.agents = children.map((c) => ({ agentId: c.agentId, agentType: c.agentType, tier: c.tier, costMicros: c.costMicros, background: c.background, numTurns: c.numTurns, stop: c.stop }));
+      // Context stats for the session so far; `compactions` are this turn's.
+      const stats = manager.stats();
+      result.cohort.context = { ...stats, compactions: stats.compactions.slice(compactionsBefore) };
+      // --max-budget-usd: the cap and what the run has spent so far (subagents and workflows included).
+      if (budget) {
+        result.cohort.budget = budget.snapshot();
+        // CF-157: say it ONCE per run when the gateway priced nothing, so a cap
+        // that CANNOT bind is never read as a cap that merely was not reached.
+        const budgetNotice = budget.notice();
+        if (budgetNotice) warn(budgetNotice);
+      }
+      if (slash.invoked) result.cohort.slashCommand = slash.invoked;
+      appendResult(session, result, now);
+      last = result;
+
+      if (writer) writer.result(result);
+      else if (o.outputFormat === "json") stdout.write(JSON.stringify(result) + "\n");
+      else if (result.is_error) stderr.write(`cohort run: ${result.result}\n`);
+      else stdout.write(`${result.result}\n`);
+      if (deps.signal?.aborted) break;
+    }
+    if (streamInput && streamInput.pendingControls > 0) warn(`stream-json input: ${streamInput.pendingControls} control message(s) arrived after the last user message and were not applied`);
+    if (last === null) {
+      // stream-json input that ended before any user message: still one result.
+      last = buildSetupErrorResult({ sessionId: session.id, code: "no_input", message: "the stream-json input ended before any user message", durationMs: now() - started, wire });
+      writer?.result(last);
+    }
+    return last?.is_error ? 1 : 0;
+  } finally {
+    await workflows?.stopAll();
+    await agentRuntime?.stopAll();
+    await kit?.dispose();
+    await mcp.close();
+  }
+}
+
+/**
+ * One stream-json input line: control messages as context/stream-input.mjs reads
+ * them; a user message's text as output/stream-json.mjs reads it, which notes
+ * the content blocks it left out. Pure.
+ * @param {string} line
+ */
+function parseInputItem(line) {
+  const item = parseStreamInputLine(line);
+  if (item.kind !== "user") return item;
+  const turn = parseInputLine(line);
+  return turn && turn.ok ? { ...item, text: turn.text } : item;
+}
+
+/** Lines (tests' `stdinLines`) as newline-terminated chunks for the stream reader. @param {AsyncIterable<string>|Iterable<string>} lines */
+async function* linesAsChunks(lines) {
+  for await (const line of lines) yield `${line}\n`;
+}
+
+/** The package version, for the MCP clientInfo. */
+function packageVersion() {
+  try {
+    return JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version || "0";
+  } catch {
+    return "0";
+  }
+}
+
+/** Read all of stdin when it is not a terminal. */
+export async function readProcessStdin() {
+  if (process.stdin.isTTY) return "";
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/**
+ * The process edge: wires SIGINT/SIGTERM to an abort so an interrupted run
+ * still closes its transcript and prints a result.
+ * @param {string[]} argv
+ */
+export async function runFromProcess(argv) {
+  // W4-A1: `cli.mjs session …` is the long-lived front door (session-runtime/runner.mjs).
+  if (argv[0] === "session") return (await import("./session-runtime/runner.mjs")).runSessionFromProcess(argv.slice(1));
+  const controller = new AbortController();
+  const onSignal = () => controller.abort();
+  process.once("SIGINT", onSignal);
+  process.once("SIGTERM", onSignal);
+  try {
+    return await runCli(argv, { signal: controller.signal, readStdin: readProcessStdin });
+  } finally {
+    process.removeListener("SIGINT", onSignal);
+    process.removeListener("SIGTERM", onSignal);
+  }
+}
+
+/** Same realpath-resolved comparison bin/maestro.mjs uses (npm bins are symlinks). */
+function isEntrypoint() {
+  if (!process.argv[1]) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+  } catch {
+    return false; // argv[1] is not a real path (e.g. `node -e`): not the entrypoint
+  }
+}
+
+if (isEntrypoint()) {
+  // Not a top-level await: `session` imports modules that import this one, and a module
+  // still evaluating (held open by its own top-level await) would never finish loading.
+  runFromProcess(process.argv.slice(2)).then(
+    (code) => {
+      process.exitCode = code;
+    },
+    (e) => {
+      process.stderr.write(`${e instanceof Error ? (e.stack ?? e.message) : String(e)}\n`);
+      process.exitCode = 1;
+    },
+  );
+}