headlesscode 1.0.2

package/src/cli.ts

@@ -0,0 +1,1535 @@
+#!/usr/bin/env tsx
+/**
+ * headlesscode — Phase 1 headless CLI entry.
+ *
+ * Exit codes:
+ *   0  success
+ *   1  task failed / max iterations / bounded failure
+ *   2  usage or configuration error (bad args, missing API key)
+ */
+
+import * as fs from "node:fs"
+import * as path from "node:path"
+
+import { LocalMemoryStore } from "./memory/local.js"
+import type { MemoryStore } from "./memory/types.js"
+import { OpenRouterClient, parseReasoningEffort } from "./llm/openrouter.js"
+import { OllamaClient } from "./llm/ollama.js"
+import type { LlmClient } from "./engine/types.js"
+import { HeadlessSession } from "./engine/loop.js"
+import { chownWorktreeWorkspace } from "./dashboard/session-launch.js"
+import { isLocalExploreEnabled } from "./engine/local-explore.js"
+import { Logger } from "./engine/logger.js"
+import {
+	appendCodeIntelTools,
+	appendDescribeImageTool,
+	buildSystemPrompt,
+	loadCustomModes,
+	selectToolsForMode,
+} from "./engine/prompt.js"
+import { orchestrateMain } from "./orchestrator/cli.js"
+import { watchMain } from "./watcher/cli.js"
+import { checkpointsMain } from "./checkpoints/cli.js"
+import { dashboardMain } from "./dashboard/cli.js"
+import { trendMain } from "./dashboard/trend-cli.js"
+import { indexMain } from "./codesearch/cli.js"
+import { codemapMain } from "./codemap/cli.js"
+import { initMain } from "./init/cli.js"
+import { provisionMain, pushPrMain } from "./github/cli.js"
+import { decisionProxyMain } from "./decision-proxy/cli.js"
+import { migrateMain } from "./migrate/cli.js"
+import { projectsMain } from "./projects/cli.js"
+import { analyzeCliMain } from "./orchestrator/analyze-cli.js"
+import { costHistoryCliMain } from "./orchestrator/cost-history-cli.js"
+import { resolvePermissions, type PermissionsConfig } from "./permissions/config.js"
+import { resolveModelForMode, resolveReasoningEffortForMode } from "./config/mode-models.js"
+
+const VERSION = "0.1.0"
+
+interface CliOptions {
+	mode: string
+	task?: string
+	taskFile?: string
+	workspace?: string
+	/** Explicit session id override (set by the dashboard's session-launch endpoint). */
+	sessionId?: string
+	/** See HeadlessSessionConfig.requireArtifactPathPattern (loop.ts) — a research-harness primitive. */
+	requireArtifactPath?: string
+	/** See HeadlessSessionConfig.requireArtifactMinCitations (loop.ts). */
+	requireArtifactMinCitations?: number
+	/** See HeadlessSessionConfig.requireArtifactSections (loop.ts) — pipe-separated on the CLI. */
+	requireArtifactSections?: string[]
+	model?: string
+	maxIterations?: number
+	consecutiveErrorLimit?: number
+	/**
+	 * Recursive task decomposition (`new_task`): hard cap on how deep a single
+	 * root session may delegate (default DEFAULT_MAX_RECURSION_DEPTH = 2;
+	 * also $HEADLESSCODE_MAX_RECURSION_DEPTH). See src/engine/loop.ts.
+	 */
+	maxRecursionDepth?: number
+	/**
+	 * Recursive task decomposition (`new_task`): a child's default
+	 * maxIterations as a fraction of the parent's REMAINING iterations
+	 * (default DEFAULT_CHILD_ITERATION_FRACTION = 0.5; also
+	 * $HEADLESSCODE_CHILD_ITERATION_FRACTION). See src/engine/loop.ts.
+	 */
+	childIterationFraction?: number
+	/**
+	 * Hard cap on tokens the model may generate per LLM call (default
+	 * DEFAULT_MAX_TOKENS = 32768; also $HEADLESSCODE_MAX_TOKENS). See
+	 * src/engine/loop.ts.
+	 */
+	maxTokens?: number
+	/** Sliding-window history cap, in messages (also see DEFAULT_WINDOW_SIZE in engine/loop.ts). */
+	windowSize?: number
+	/**
+	 * Phase 3 context condensation: the model's real context window in
+	 * tokens (default: live OpenRouter lookup, else
+	 * DEFAULT_CONTEXT_WINDOW_TOKENS in src/engine/condense.ts).
+	 */
+	contextWindowTokens?: number
+	/**
+	 * Sampling temperature sent on every LLM call (default: 0 — fully
+	 * deterministic/greedy). Exposed 2026-08-27 while investigating whether
+	 * greedy decoding was a factor in local-model task failures — there was
+	 * previously no way to override this at all.
+	 */
+	temperature?: number
+	/**
+	 * Phase 3 context condensation: fraction of the context window at which
+	 * the oldest turns are condensed (default
+	 * DEFAULT_CONDENSE_THRESHOLD_FRACTION in src/engine/condense.ts).
+	 */
+	condenseThreshold?: number
+	/**
+	 * Async/background condensation: fraction of the context window at which
+	 * the condensation LLM call fires EARLY in the background (default
+	 * DEFAULT_CONDENSE_EARLY_FIRE_FRACTION in src/engine/condense.ts). Must be
+	 * below the hard `condenseThreshold`; when it isn't, the async path is off
+	 * and only the synchronous hard-threshold path runs.
+	 */
+	condenseEarlyFire?: number
+	/**
+	 * Phase 3 context condensation: model id for the condensation call
+	 * (default: the session model, or the `_condensation` key in
+	 * .headlesscode/mode-models.json).
+	 */
+	condenseModel?: string
+	/** Per-LLM-call abort timeout, ms (default: DEFAULT_LLM_TIMEOUT_MS in engine/loop.ts). */
+	llmTimeoutMs?: number
+	/**
+	 * Streaming-and-reasoning: opt-in SSE streaming (default OFF — the
+	 * blocking request path is unchanged). Also settable via
+	 * $HEADLESSCODE_STREAM ("1"/"true"/"yes"/"on").
+	 */
+	stream: boolean
+	/** Phase 6: per-session cost cap, USD (also $HEADLESSCODE_MAX_COST_USD). */
+	maxCostUsd?: number
+	/** Phase 6: per-session duration cap, ms (also $HEADLESSCODE_MAX_DURATION_MS). */
+	maxDurationMs?: number
+	logFile?: string
+	memoryDir?: string
+	noMemory: boolean
+	dryRun: boolean
+	version: boolean
+	help: boolean
+	/** Checkpoints on by default; --no-checkpoints opts out. */
+	noCheckpoints: boolean
+	checkpointDir?: string
+	/** Decision escalation timeout, ms (also $HEADLESSCODE_DECISION_TIMEOUT_MS). */
+	decisionTimeoutMs?: number
+	/** Pause/resume max duration, ms (also $HEADLESSCODE_MAX_PAUSE_MS). */
+	maxPauseMs?: number
+	/** Permissions: comma-separated command prefixes allowed to run (also $HEADLESSCODE_ALLOWED_COMMANDS). */
+	allowedCommands?: string
+	/** Permissions: comma-separated command prefixes never allowed (also $HEADLESSCODE_DENIED_COMMANDS). */
+	deniedCommands?: string
+	/** Permissions: comma-separated protected-file globs (also $HEADLESSCODE_PROTECTED_FILES). */
+	protectedFiles?: string
+	/** Permissions escape hatch: allow writes to protected files (default: false). */
+	allowProtectedWrites: boolean
+	/**
+	 * OPT-IN local exploration phase (default OFF): a bounded, read-only local
+	 * Ollama pass runs before the cloud model's first turn and folds its
+	 * findings into a labeled synthetic message. Also settable via
+	 * $HEADLESSCODE_LOCAL_EXPLORE. Experimental — see plans/local-explore-phase-experiment.md.
+	 */
+	localExplore: boolean
+	/**
+	 * switch_mode (plans/switch-mode-headless.md): opt-in auto-approval of
+	 * in-place mode switches — OFF by default because the approval gate is the
+	 * security boundary that keeps a restricted mode from silently granting
+	 * itself a broader mode's permissions. Also settable via
+	 * $HEADLESSCODE_AUTO_APPROVE_MODE_SWITCH.
+	 */
+	autoApproveModeSwitch: boolean
+	/** switch_mode: hard cap on total in-place mode switches per session (default 5). */
+	maxModeSwitches?: number
+}
+
+const USAGE = `headlesscode — headless coding-agent harness (Phase 1 engine)
+
+Usage:
+  headlesscode --task "<task text>" [options]
+  headlesscode --task-file <path> [options]
+  headlesscode --dry-run [options]          # build system prompt + validate config, no LLM call
+
+Subcommands:
+  headlesscode orchestrate --repo <path> --issue <n>... [--qa] [--deploy] [--dry-run]
+              Run a full parallel orchestration round
+              (split → spawn → review → QA → deploy gate). See
+              \`npx tsx src/cli.ts orchestrate --help\` for full options.
+  headlesscode orchestrate status --repo <path> [--wait] [--timeout-ms <n>] [--json]
+              Print a compact per-group status of a round, or block inside one
+              call until every group is terminal (--wait) — replaces
+              hand-rolled poll loops over the state file / harness.log. See
+              \`npx tsx src/cli.ts orchestrate status --help\` for full options.
+  headlesscode orchestrate stop --repo <path> --group <name> [--group <name> ...]
+              Stop a group's worker COMPLETELY (whole process tree via
+              scripts/stop-worker.sh — issue #20) and mark it needs-human. See
+              \`npx tsx src/cli.ts orchestrate stop --help\` for full options.
+  headlesscode watch --owner <o> --repo <r> --label <label> [--run-once]
+              Poll GitHub for labeled issues and fan out into orchestration
+              batches (idempotent). See
+              \`npx tsx src/cli.ts watch --help\` for full options.
+  headlesscode checkpoints --workspace <path> [list | restore <hash> | diff <hash>]
+              List/restore/diff shadow-git checkpoints for a workspace. See
+              \`npx tsx src/cli.ts checkpoints --help\` for full options.
+  headlesscode dashboard [--port 4390] [--repo <path>]
+              Serve a local cost/token dashboard with a live per-session
+              event feed and pause/resume control (Phase 3: no longer purely
+              read-only — see src/dashboard/server.ts). See
+              \`npx tsx src/cli.ts dashboard --help\` for full options.
+  headlesscode trend --repo <path> [--repo <path> ...] [--port 4460]
+              Serve a local, auto-refreshing page comparing multiple repos'
+              cost-efficiency trends side by side (wasted-session tracking,
+              cost/iteration vs. round-size correlation, rework rate). See
+              \`npx tsx src/cli.ts trend --help\` for full options.
+  headlesscode index --workspace <path> [--model <id>] [--embedding-backend <b>]
+              Build/refresh the codebase semantic-search index for a workspace
+              (used by the codebase_search tool). A separate, explicit step —
+              never auto-triggered mid-session. --embedding-backend picks
+              openrouter (default), ollama (local), or airunner (local
+              AIRunner server). See \`npx tsx src/cli.ts index --help\` for
+              full options.
+  headlesscode codemap --workspace <path> [--force] [--watch] [--interval-ms <n>]
+              Build/refresh a project's deterministic module/import map
+              (codemap.json/codemap.lock/codemap.html in the central project
+              store). No LLM anywhere in the pipeline; regeneration is
+              fingerprint-aware (an unchanged repo writes nothing). --watch
+              turns it into a long-running poll loop. See
+              \`npx tsx src/cli.ts codemap --help\` for full options.
+  headlesscode init --workspace <path> [--skip-index] [--skip-codemap]
+              Register a new project in one step: resolves the central data
+              dir, detects the stack(s) (drives per-session instruction
+              selection), ensures .gitignore excludes .headlesscode/, then
+              builds the codesearch index + codemap. See
+              \`npx tsx src/cli.ts init --help\` for full options.
+  headlesscode provision --installation-id <id> --owner <o> --repo <r> --target <dir>
+              Clone a GitHub repo the App installation can access into a local
+              dir (token stripped from the remote URL), ready as a
+              --workspace value. Also --list-repos <id>. See
+              \`npx tsx src/cli.ts provision --help\` for full options.
+  headlesscode push-pr --installation-id <id> --owner <o> --repo <r> \\
+              --local-dir <path> --branch <name> --title <title> --body <text> [--base <branch>]
+              Push a local branch to a GitHub repo with the App installation
+              token (token scrubbed from .git/config immediately), then open
+              a pull request from it — never to the repo's default branch,
+              never auto-merged. See
+              \`npx tsx src/cli.ts push-pr --help\` for full options.
+  headlesscode decision-proxy --workspace <path> [--task <text>] [--task-file <path>]
+              OPT-IN (HEADLESSCODE_DECISION_PROXY=1) LLM stand-in for the
+              human on ask_followup_question: watches <path> for
+              .harness.needs-decision and answers via .harness.decision-answer,
+              grounded in the session's ORIGINAL task text. Writes nothing
+              when uncertain/errored — the existing timeout fallback fires
+              as today. See \`npx tsx src/cli.ts decision-proxy --help\` for
+              full options.
+  headlesscode migrate [--workspace <path>]
+              One-time central-store migrations: moves global shared
+              instructions (~/.roo/) and the checkpoint store
+              (~/.headlesscode/checkpoints) into ~/.local/share/headlesscode/,
+              plus a workspace's legacy .headlesscode/ content (index,
+              mode-models.json, permissions.json) into the central project
+              store. Idempotent; each move is verified before the source is
+              removed. See \`npx tsx src/cli.ts migrate --help\`.
+  headlesscode projects list [--json] [--registered-only] [--stale] [--size]
+              Enumerate the central per-project store as a table (or JSON),
+              optionally filtered to registered/stale entries, with an
+              opt-in size column. See
+              \`npx tsx src/cli.ts projects list --help\` for full options.
+  headlesscode projects prune [--dry-run] [--yes] [--include-registered]
+              Reclaim orphaned store entries (missing paths that were never
+              registered, plus pre-registry no-project.json litter). Never
+              deletes a registered project without --include-registered; the
+              escape hatch for a deleted repo / unmounted drive. See
+              \`npx tsx src/cli.ts projects prune --help\` for full options.
+
+Options:
+  --mode <slug>              Mode to run in (built-in or from .roomodes). Default: code
+  --task <text>              The task description for the agent
+  --task-file <path>         Read the task from a file (relative to workspace)
+  --workspace <root>         Workspace root (default: $HEADLESSCODE_WORKSPACE_ROOT or cwd)
+  --session-id <id>          Explicit session id override (default: a fresh UUID).
+                             Used by the dashboard's session-launch endpoint so
+                             the browser can open the session's event view
+                             immediately; rarely needed from a terminal.
+  --model <id>               OpenRouter model id (default: $OPENROUTER_MODEL or deepseek/deepseek-v4-flash-0731)
+  --max-iterations <n>       Loop iteration cap (default: 250 — see DEFAULT_MAX_ITERATIONS
+                               in src/engine/loop.ts)
+  --max-recursion-depth <n>  Recursive task decomposition (new_task): hard cap
+                               on how deep one root session may delegate
+                               (default: 2 = root → child → grandchild; a
+                               deeper new_task call is refused as a normal
+                               tool error). Default:
+                               $HEADLESSCODE_MAX_RECURSION_DEPTH
+  --child-iteration-fraction <f>  Recursive task decomposition: a child's
+                               default maxIterations as a fraction of the
+                               parent's REMAINING iterations (default: 0.5,
+                               floor 3 — a child never exceeds what its parent
+                               has left). Default:
+                               $HEADLESSCODE_CHILD_ITERATION_FRACTION
+  --max-tokens <n>           Hard cap on tokens the model may generate per LLM
+                               call (default: 32768 — see DEFAULT_MAX_TOKENS in
+                               src/engine/loop.ts). Default: $HEADLESSCODE_MAX_TOKENS
+  --consecutive-error-limit <n>  Consecutive mistakes before giving up (default: 3,
+                               or 6 for the local code-mode backend — see cli.ts's
+                               DEFAULT_LOCAL_CONSECUTIVE_ERROR_LIMIT)
+  --window-size <n>          Sliding-window history cap, in messages, before the
+                             oldest are evicted (default: 300; see DEFAULT_WINDOW_SIZE
+                             in src/engine/loop.ts for why)
+  --temperature <f>          Sampling temperature, 0-2 (default: 0 — fully deterministic/
+                             greedy; every LLM call uses this, no per-role override)
+  --context-window <n>       Phase 3 context condensation: the model's real context
+                             window in tokens (default: live OpenRouter lookup, else
+                             128000, or 40960 for the local code-mode backend — see
+                             DEFAULT_LOCAL_CONTEXT_WINDOW_TOKENS in cli.ts and
+                             DEFAULT_CONTEXT_WINDOW_TOKENS in src/engine/condense.ts;
+                             override with $HEADLESSCODE_CODE_MODE_CONTEXT_WINDOW)
+  --condense-threshold <f>   Phase 3 context condensation: fraction of the context
+                             window at which the oldest turns are condensed into one
+                             summary (default: 0.75, or 0.92 for the local code-mode
+                             backend — see cli.ts's LOCAL_CONDENSE_THRESHOLD_FRACTION;
+                             must be between 0 and 1)
+  --condense-early-fire <f>  Async condensation: fraction of the context window at
+                             which the condensation LLM call fires EARLY, in the
+                             background against a snapshot, while the loop keeps
+                             running (default: 0.6, provisional; DISABLED for the
+                             local code-mode backend — a second concurrent call
+                             against a single locally-loaded model has no latency to
+                             hide and only adds GPU contention — must be below
+                             --condense-threshold or the async path is off)
+  --condense-model <id>      Phase 3 context condensation: model id for the
+                             condensation call (default: the session model, or the
+                             _condensation key in .headlesscode/mode-models.json)
+  --llm-timeout-ms <n>       Per-LLM-call abort timeout, ms (default: 300000 / 5 min
+                             — reasoning models can take a while on a heavy turn)
+  --log-file <path>          Also append structured logs to this file
+  --memory-dir <path>        Store project memory (facts + session summaries) under
+                             <path>. Enables Phase 3 memory. Default (when enabled):
+                             $HEADLESSCODE_MEMORY_DIR or <workspace>/.headlesscode/memory
+  --no-memory                Explicitly disable memory even if HEADLESSCODE_MEMORY_DIR is set
+  --max-cost-usd <n>         Phase 6: per-session cost cap in USD (decimal, e.g. 0.05).
+                             Default: $HEADLESSCODE_MAX_COST_USD; off when neither is set
+  --max-duration-ms <n>      Phase 6: per-session wall-clock cap in ms. Default:
+                             $HEADLESSCODE_MAX_DURATION_MS; off when neither is set.
+                             When a cap trips the session aborts with reason "budget"
+  --dry-run                  Build the system prompt, validate .roomodes/rules loading,
+                             then exit without calling the LLM (no API key needed)
+  --no-checkpoints           Disable shadow-git checkpoints (on by default; see
+                             \`headlesscode checkpoints --help\`). No effect for
+                             read-only sessions (reviewer/QA), which never checkpoint
+  --checkpoint-dir <path>    Shadow-git storage root override (default:
+                             ~/.headlesscode/checkpoints — MUST be outside the
+                             workspace; see docs/checkpoints.md)
+  --decision-timeout-ms <n>  How long ask_followup_question blocks waiting for
+                               a human/orchestrator answer before falling back
+                               to autonomous decision, ms (default 1800000 / 30
+                               min). Default: $HEADLESSCODE_DECISION_TIMEOUT_MS
+  --max-pause-ms <n>         Max duration a dashboard-initiated pause may hold
+                               the loop before it auto-resumes, ms (default
+                               7200000 / 2h — matches the orchestrator's stall
+                               guard). Default: $HEADLESSCODE_MAX_PAUSE_MS
+  --allowed-commands <list>  Comma-separated command prefixes the agent may run.
+                               Default: $HEADLESSCODE_ALLOWED_COMMANDS, else
+                               .headlesscode/permissions.json, else empty (=
+                               allow everything except --denied-commands)
+  --denied-commands <list>   Comma-separated command prefixes that are ALWAYS
+                               refused (deny wins over allow; dangerous shell
+                               substitutions are always blocked regardless).
+                               Default: $HEADLESSCODE_DENIED_COMMANDS, else
+                               .headlesscode/permissions.json, else empty
+  --protected-files <list>   Comma-separated glob patterns of files the agent may
+                               not write. Default: $HEADLESSCODE_PROTECTED_FILES,
+                               else .headlesscode/permissions.json, else
+                               ".env,.env.*,*.pem,*.key,id_rsa*"
+  --allow-protected-writes   Escape hatch: permit writes to protected files
+                               (default: OFF). Also settable via
+                               "allowProtectedWrites": true in
+                               .headlesscode/permissions.json
+  --stream                   Opt-in SSE streaming (streaming-and-reasoning):
+                              stream token/reasoning deltas and emit
+                              llm_stream_chunk events for live-typing view.
+                              Default: OFF (blocking requests unchanged).
+                              Also settable via $HEADLESSCODE_STREAM
+  --local-explore            OPT-IN local exploration phase (experimental,
+                               default OFF): run a bounded, strictly read-only
+                               local Ollama pass (qwen3.5:9b — read_file +
+                               list_files only) before the cloud model's first
+                               turn and fold its findings into the cloud
+                               context as a labeled synthetic message. Fails
+                               open to cloud-only on any local error. Also
+                               settable via $HEADLESSCODE_LOCAL_EXPLORE
+  --auto-approve-mode-switch switch_mode: auto-approve in-place mode switches
+                               WITHOUT escalating to a human/orchestrator.
+                               OFF by default — the approval gate is the
+                               security boundary that keeps a restricted mode
+                               (e.g. architect, read+md-only) from silently
+                               granting itself a broader mode's edit
+                               permissions. Also settable via
+                               $HEADLESSCODE_AUTO_APPROVE_MODE_SWITCH
+  --max-mode-switches <n>    switch_mode: hard cap on total in-place mode
+                               switches per session (default: 5 — see
+                               DEFAULT_MAX_MODE_SWITCHES in src/engine/loop.ts).
+                               Also settable via
+                               $HEADLESSCODE_MAX_MODE_SWITCHES
+  --version                  Print version and exit
+  --help                     Show this help and exit
+
+Environment:
+  HEADLESSCODE_OPENROUTER_API_KEY         Required (except --dry-run)
+  OPENROUTER_MODEL           Default model id
+  OPENROUTER_HTTP_REFERER    Optional HTTP-Referer header
+  OPENROUTER_APP_TITLE       Optional X-Title header
+  HEADLESSCODE_WORKSPACE_ROOT  Default workspace root
+  HEADLESSCODE_MEMORY_DIR    Default memory dir (memory enabled when set)
+  HEADLESSCODE_PROJECT       Project scope for memory (default: workspace basename)
+  HEADLESSCODE_ALLOWED_COMMANDS   Default --allowed-commands (comma-separated)
+  HEADLESSCODE_DENIED_COMMANDS    Default --denied-commands (comma-separated)
+  HEADLESSCODE_PROTECTED_FILES    Default --protected-files (comma-separated globs)
+  HEADLESSCODE_ALLOW_PROTECTED_WRITES  Allow protected-file writes ("1"/"true")
+  HEADLESSCODE_MAX_RECURSION_DEPTH    Default --max-recursion-depth (positive int)
+  HEADLESSCODE_CHILD_ITERATION_FRACTION  Default --child-iteration-fraction (0 < f <= 1)
+  HEADLESSCODE_MAX_TOKENS      Default --max-tokens (positive int)
+  HEADLESSCODE_STREAM          Opt-in SSE streaming ("1"/"true"/"yes"/"on")
+  HEADLESSCODE_LOCAL_EXPLORE   Opt-in local exploration phase ("1"/"true")
+  HEADLESSCODE_AUTO_APPROVE_MODE_SWITCH  Auto-approve switch_mode calls ("1"/"true"/"yes"/"on")
+  HEADLESSCODE_MAX_MODE_SWITCHES      switch_mode: hard cap on total in-place
+                               mode switches per session (positive int)
+  HEADLESSCODE_LOCAL_EXPLORE_MODEL    Local model (default qwen3.5:9b)
+  HEADLESSCODE_LOCAL_EXPLORE_MAX_ITERATIONS  Iteration cap (default 15)
+  HEADLESSCODE_LOCAL_EXPLORE_CONTEXT_TOKENS   Context-token budget (default 131072)
+  HEADLESSCODE_LOCAL_EXPLORE_TIMEOUT_MS       Per-call timeout ms (default 120000)
+  HEADLESSCODE_OLLAMA_URL      Ollama base URL (default http://localhost:11434)
+  HEADLESSCODE_DECISION_PROXY   Opt-in decision-proxy agent ("1"/"true") — an
+                                LLM stand-in for the human on
+                                ask_followup_question (headlesscode
+                                decision-proxy subcommand; see
+                                plans/decision-proxy-agent.md)
+`
+
+export function parseArgs(argv: string[]): { options: CliOptions; error?: string } {
+	const options: CliOptions = {
+		mode: "code",
+		noMemory: false,
+		dryRun: false,
+		version: false,
+		help: false,
+		noCheckpoints: false,
+		allowProtectedWrites: false,
+		stream: false,
+		localExplore: false,
+		autoApproveModeSwitch: false,
+	}
+
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i]
+		const eq = arg.indexOf("=")
+		const flag = eq === -1 ? arg : arg.slice(0, eq)
+		const inlineValue = eq === -1 ? undefined : arg.slice(eq + 1)
+		const next = (): string | undefined => {
+			if (inlineValue !== undefined) {
+				return inlineValue
+			}
+			const v = argv[i + 1]
+			if (v === undefined || v.startsWith("--")) {
+				return undefined
+			}
+			i++
+			return v
+		}
+
+		switch (flag) {
+			case "--mode":
+			case "--task":
+			case "--task-file":
+			case "--workspace":
+			case "--model":
+			case "--log-file":
+			case "--session-id":
+			case "--require-artifact-path":
+			case "--require-artifact-sections": {
+				const value = next()
+				if (value === undefined) {
+					return { options, error: `Missing value for ${flag}` }
+				}
+				switch (flag) {
+					case "--mode":
+						options.mode = value
+						break
+					case "--task":
+						options.task = value
+						break
+					case "--task-file":
+						options.taskFile = value
+						break
+					case "--workspace":
+						options.workspace = value
+						break
+					case "--model":
+						options.model = value
+						break
+					case "--log-file":
+						options.logFile = value
+						break
+					case "--session-id":
+						options.sessionId = value
+						break
+					case "--require-artifact-path":
+						options.requireArtifactPath = value
+						break
+					case "--require-artifact-sections":
+						options.requireArtifactSections = value
+							.split("|")
+							.map((s) => s.trim())
+							.filter(Boolean)
+						break
+				}
+				break
+			}
+			case "--max-iterations":
+			case "--consecutive-error-limit":
+			case "--window-size":
+			case "--context-window":
+			case "--llm-timeout-ms":
+			case "--max-recursion-depth":
+			case "--max-mode-switches":
+			case "--max-tokens":
+			case "--require-artifact-min-citations": {
+				const value = next()
+				const num = value === undefined ? Number.NaN : Number(value)
+				if (!Number.isInteger(num) || num <= 0) {
+					return { options, error: `${flag} requires a positive integer` }
+				}
+				if (flag === "--max-iterations") {
+					options.maxIterations = num
+				} else if (flag === "--consecutive-error-limit") {
+					options.consecutiveErrorLimit = num
+				} else if (flag === "--window-size") {
+					options.windowSize = num
+				} else if (flag === "--context-window") {
+					options.contextWindowTokens = num
+				} else if (flag === "--max-recursion-depth") {
+					options.maxRecursionDepth = num
+				} else if (flag === "--max-mode-switches") {
+					options.maxModeSwitches = num
+				} else if (flag === "--max-tokens") {
+					options.maxTokens = num
+				} else if (flag === "--require-artifact-min-citations") {
+					options.requireArtifactMinCitations = num
+				} else {
+					options.llmTimeoutMs = num
+				}
+				break
+			}
+			case "--child-iteration-fraction": {
+				const value = next()
+				const num = value === undefined ? Number.NaN : Number(value)
+				if (!Number.isFinite(num) || num <= 0 || num > 1) {
+					return { options, error: "--child-iteration-fraction requires a fraction between 0 and 1 (e.g. 0.5)" }
+				}
+				options.childIterationFraction = num
+				break
+			}
+			case "--temperature": {
+				const value = next()
+				const num = value === undefined ? Number.NaN : Number(value)
+				if (!Number.isFinite(num) || num < 0 || num > 2) {
+					return { options, error: "--temperature requires a number between 0 and 2 (e.g. 0.3)" }
+				}
+				options.temperature = num
+				break
+			}
+			case "--condense-threshold": {
+				const value = next()
+				const num = value === undefined ? Number.NaN : Number(value)
+				if (!Number.isFinite(num) || num <= 0 || num >= 1) {
+					return { options, error: "--condense-threshold requires a fraction between 0 and 1 (e.g. 0.75)" }
+				}
+				options.condenseThreshold = num
+				break
+			}
+			case "--condense-early-fire": {
+				const value = next()
+				const num = value === undefined ? Number.NaN : Number(value)
+				if (!Number.isFinite(num) || num <= 0 || num >= 1) {
+					return { options, error: "--condense-early-fire requires a fraction between 0 and 1 (e.g. 0.6)" }
+				}
+				options.condenseEarlyFire = num
+				break
+			}
+			case "--condense-model": {
+				const value = next()
+				if (value === undefined) {
+					return { options, error: "Missing value for --condense-model" }
+				}
+				options.condenseModel = value
+				break
+			}
+			case "--max-cost-usd": {
+				const value = next()
+				const num = value === undefined ? Number.NaN : Number(value)
+				if (!Number.isFinite(num) || num <= 0) {
+					return { options, error: "--max-cost-usd requires a positive number (USD, decimal allowed)" }
+				}
+				options.maxCostUsd = num
+				break
+			}
+			case "--max-duration-ms": {
+				const value = next()
+				const num = value === undefined ? Number.NaN : Number(value)
+				if (!Number.isInteger(num) || num <= 0) {
+					return { options, error: "--max-duration-ms requires a positive integer" }
+				}
+				options.maxDurationMs = num
+				break
+			}
+			case "--decision-timeout-ms": {
+				const value = next()
+				const num = value === undefined ? Number.NaN : Number(value)
+				if (!Number.isInteger(num) || num <= 0) {
+					return { options, error: "--decision-timeout-ms requires a positive integer" }
+				}
+				options.decisionTimeoutMs = num
+				break
+			}
+			case "--max-pause-ms": {
+				const value = next()
+				const num = value === undefined ? Number.NaN : Number(value)
+				if (!Number.isInteger(num) || num <= 0) {
+					return { options, error: "--max-pause-ms requires a positive integer" }
+				}
+				options.maxPauseMs = num
+				break
+			}
+			case "--memory-dir":
+			case "--allowed-commands":
+			case "--denied-commands":
+			case "--protected-files": {
+				const value = next()
+				if (value === undefined) {
+					return { options, error: `Missing value for ${flag}` }
+				}
+				switch (flag) {
+					case "--memory-dir":
+						options.memoryDir = value
+						break
+					case "--allowed-commands":
+						options.allowedCommands = value
+						break
+					case "--denied-commands":
+						options.deniedCommands = value
+						break
+					case "--protected-files":
+						options.protectedFiles = value
+						break
+				}
+				break
+			}
+			case "--allow-protected-writes":
+				options.allowProtectedWrites = true
+				break
+			case "--stream":
+				options.stream = true
+				break
+			case "--local-explore":
+				options.localExplore = true
+				break
+			case "--auto-approve-mode-switch":
+				options.autoApproveModeSwitch = true
+				break
+			case "--checkpoint-dir": {
+				const value = next()
+				if (value === undefined) {
+					return { options, error: "Missing value for --checkpoint-dir" }
+				}
+				options.checkpointDir = value
+				break
+			}
+			case "--no-memory":
+				options.noMemory = true
+				break
+			case "--no-checkpoints":
+				options.noCheckpoints = true
+				break
+			case "--dry-run":
+				options.dryRun = true
+				break
+			case "--version":
+				options.version = true
+				break
+			case "--help":
+			case "-h":
+				options.help = true
+				break
+			default:
+				return { options, error: `Unknown argument: ${arg}` }
+		}
+	}
+
+	return { options }
+}
+
+export async function main(argv: string[] = process.argv.slice(2)): Promise<number> {
+	// Phase 2 subcommand: `headlesscode orchestrate ...` — delegates to the
+	// orchestrator module (split → spawn → watch → review). Keeps the Phase 1
+	// run path untouched.
+	if (argv[0] === "orchestrate") {
+		return orchestrateMain(argv.slice(1))
+	}
+
+	// Issue #148 subcommand: `headlesscode pipeline ...` — run the stage-
+	// isolated research→filing pipeline (each stage a fresh session taking the
+	// prior stage's artifact as input).
+	if (argv[0] === "pipeline") {
+		const { pipelineMain } = await import("./orchestrator/cli.js")
+		return pipelineMain(argv.slice(1))
+	}
+
+	// Phase 5 subcommand: `headlesscode watch ...` — GitHub issue watcher
+	// (poll label → split → spawn → durable idempotency state).
+	if (argv[0] === "watch") {
+		return watchMain(argv.slice(1))
+	}
+
+	// Checkpoints subcommand: `headlesscode checkpoints ...` — list/restore/diff
+	// shadow-git checkpoints for a workspace (see src/checkpoints/).
+	if (argv[0] === "checkpoints") {
+		return checkpointsMain(argv.slice(1))
+	}
+
+	// Cost/token dashboard subcommand: `headlesscode dashboard ...` — local
+	// HTML dashboard with live per-session events + pause/resume control
+	// (Phase 3 — see src/dashboard/; no longer purely read-only).
+	if (argv[0] === "dashboard") {
+		return dashboardMain(argv.slice(1))
+	}
+
+	// Cross-repo cost-efficiency trend subcommand: `headlesscode trend ...` —
+	// a local, auto-refreshing page comparing multiple repos' cost-history
+	// side by side (see src/dashboard/trend.ts). Distinct from `dashboard`'s
+	// single-repo "Cost history" section: reads live on every request, no
+	// cached snapshot.
+	if (argv[0] === "trend") {
+		return trendMain(argv.slice(1))
+	}
+
+	// Codebase semantic-search index subcommand: `headlesscode index ...` —
+	// build/refresh <workspace>/.headlesscode/codesearch/index.jsonl for the
+	// codebase_search tool (see src/codesearch/). A separate, EXPLICIT step —
+	// never auto-triggered mid-session (it costs real money and takes time).
+	if (argv[0] === "index") {
+		return indexMain(argv.slice(1))
+	}
+
+	// Deterministic per-project codemap subcommand: `headlesscode codemap ...` —
+	// generate the module/import map (codemap.json/codemap.lock/codemap.html)
+	// into the central project store; `--watch` becomes a long-running poll
+	// loop (see src/codemap/ + docs/codemap.md). No LLM anywhere in the
+	// pipeline — mechanical, deterministic, cheap to regenerate.
+	if (argv[0] === "codemap") {
+		return codemapMain(argv.slice(1))
+	}
+
+	// One-command project registration subcommand: `headlesscode init ...` —
+	// resolve central data dir + detect stacks + ensure .gitignore excludes
+	// .headlesscode/ + build index + codemap in one step (see src/init/).
+	if (argv[0] === "init") {
+		return initMain(argv.slice(1))
+	}
+
+	// GitHub App repo provisioning subcommand: `headlesscode provision ...` —
+	// clone a repo the App installation can access into a local dir (token
+	// stripped from the remote), ready as a --workspace value. Also
+	// `--list-repos <id>` (see src/github/cli.ts + docs/github-app-setup.md).
+	if (argv[0] === "provision") {
+		return provisionMain(argv.slice(1))
+	}
+
+	// GitHub push-back subcommand: `headlesscode push-pr ...` — push a local
+	// branch to a repo the App installation can access (token scrubbed from
+	// .git/config immediately), then open a PR from it. The "write" half of
+	// provisioning (see src/github/cli.ts + docs/github-app-setup.md).
+	if (argv[0] === "push-pr") {
+		return pushPrMain(argv.slice(1))
+	}
+
+	// Decision-proxy subcommand: `headlesscode decision-proxy ...` — an
+	// OPT-IN (HEADLESSCODE_DECISION_PROXY=1) LLM stand-in for the human on
+	// ask_followup_question. Watches a workspace for .harness.needs-decision
+	// and writes .harness.decision-answer grounded in the session's original
+	// task text (see src/decision-proxy/ + plans/decision-proxy-agent.md).
+	if (argv[0] === "decision-proxy") {
+		return decisionProxyMain(argv.slice(1))
+	}
+
+	// Migration subcommand: `headlesscode migrate ...` — the explicit,
+	// human-triggered version of the one-time central-store migrations
+	// (shared instructions, checkpoint store, legacy workspace
+	// `.headlesscode/`). See src/migrate/ + src/project-store.ts.
+	if (argv[0] === "migrate") {
+		return migrateMain(argv.slice(1))
+	}
+
+	// Ad-hoc session log analysis: `headlesscode analyze-worktree ...` — the
+	// orchestrator already runs this automatically per group (see
+	// src/orchestrator/log-analysis.ts + cli.ts's onGroupUpdate); this
+	// subcommand lets a human point it at any worktree by hand.
+	if (argv[0] === "analyze-worktree") {
+		return analyzeCliMain(argv.slice(1))
+	}
+
+	// Cost/token history: `headlesscode cost-history ...` — read-side for
+	// the mandatory, automatic recording in watch.ts (recordCostIfTerminal).
+	if (argv[0] === "cost-history") {
+		return costHistoryCliMain(argv.slice(1))
+	}
+
+	// Central-store project registry: `headlesscode projects ...` — enumerate
+	// (`list`) and reclaim (`prune`) the central per-project store
+	// (~/.local/share/headlesscode/projects/; see src/projects/ + src/project-store.ts).
+	if (argv[0] === "projects") {
+		return projectsMain(argv.slice(1))
+	}
+
+	const { options, error } = parseArgs(argv)
+	if (error) {
+		process.stderr.write(`headlesscode: ${error}\n\n${USAGE}`)
+		return 2
+	}
+	if (options.help) {
+		process.stdout.write(USAGE)
+		return 0
+	}
+	if (options.version) {
+		process.stdout.write(`headlesscode ${VERSION}\n`)
+		return 0
+	}
+
+	const workspaceRoot = path.resolve(options.workspace ?? process.env.HEADLESSCODE_WORKSPACE_ROOT ?? process.cwd())
+	const logger = new Logger({ level: "info", filePath: options.logFile })
+
+	// Silent-death observability (issue #150): live-verified 2026-08-21
+	// (twice, across two different models) that this process can disappear
+	// entirely mid-run — no exit code, no error log, no trace, not even the
+	// wrapping shell's own `echo "exited with code $?"`. Confirmed via
+	// `grep -rn` across this file and loop.ts before this fix: zero
+	// process-level handlers existed for any of these events. Logger.error/
+	// warn write via fs.appendFileSync (synchronous — see logger.ts), so
+	// these are safe to call immediately before process.exit without an
+	// async flush race. This does NOT catch SIGKILL (uncatchable by
+	// definition — the suspected OOM-kill case in #150 may still be
+	// SIGKILL, not SIGTERM) or a hard crash inside a native addon, but it
+	// closes every JS-level silent-exit path: an uncaught throw, a rejected
+	// promise nobody awaited, or a graceful termination request.
+	process.on("uncaughtException", (err) => {
+		logger.error("[cli] uncaughtException — process terminating", {
+			message: err instanceof Error ? err.message : String(err),
+			stack: err instanceof Error ? err.stack : undefined,
+		})
+		process.exit(3)
+	})
+	process.on("unhandledRejection", (reason) => {
+		logger.error("[cli] unhandledRejection — process terminating", {
+			reason:
+				reason instanceof Error
+					? (reason.stack ?? reason.message)
+					: (() => {
+							try {
+								return JSON.stringify(reason)
+							} catch {
+								return String(reason)
+							}
+						})(),
+		})
+		process.exit(3)
+	})
+	process.on("SIGTERM", () => {
+		logger.warn("[cli] SIGTERM received — process terminating", {
+			rssMb: Math.round(process.memoryUsage().rss / 1024 / 1024),
+		})
+		process.exit(143)
+	})
+	// Cheap postmortem diagnostic for the #150 OOM hypothesis (unconfirmed —
+	// dmesg showed no OOM-killer entries when checked live, but access may
+	// have been permission-limited): RSS at session start costs one log
+	// line and needs no periodic timer, unlike full memory-pressure polling.
+	logger.info("[cli] session process started", {
+		pid: process.pid,
+		rssMb: Math.round(process.memoryUsage().rss / 1024 / 1024),
+	})
+
+	// Fresh-session memory trap (issue #138): every `npx tsx src/cli.ts`
+	// invocation is a COMPLETELY fresh process with zero memory of any
+	// prior invocation's model reads/edits, even against the same
+	// --workspace and --task-file. A task file written/edited across a
+	// restart can easily (and wrongly) claim "you already read X, don't
+	// re-read it" — live-verified 2026-08-21: a local model trusted
+	// exactly that kind of false claim and hallucinated a plausible-but-
+	// wrong edit_file call from the claim alone. Cheapest mitigation (the
+	// issue's own "direction 1"): a marker file this process itself
+	// writes/updates on every run against a workspace, so the NEXT
+	// invocation can print a loud, impossible-to-miss note when one
+	// existed already. Doesn't stop a bad task file from lying — makes
+	// the failure mode visible in the log for whoever's supervising.
+	// Scoped to --task-file specifically: the trap is about a task file's
+	// own false claims, not sessions in general.
+	if (options.taskFile) {
+		const markerPath = path.join(workspaceRoot, ".headlesscode", "last-session.json")
+		try {
+			const prior = JSON.parse(fs.readFileSync(markerPath, "utf-8")) as {
+				sessionId?: string
+				taskFile?: string
+				startedAt?: string
+			}
+			logger.warn(
+				"[cli] NOTE: this is a FRESH process with ZERO memory of any prior run against this workspace, even if the task file references one",
+				{
+					priorSessionId: prior.sessionId,
+					priorTaskFile: prior.taskFile,
+					priorStartedAt: prior.startedAt,
+					guidance:
+						"If the task file claims you already read/did something in an earlier turn, that claim is about a DIFFERENT process — verify everything yourself before acting on it.",
+				},
+			)
+		} catch {
+			// No marker (first run against this workspace) or unreadable/
+			// corrupt — either way, nothing to warn about, proceed silently.
+		}
+		try {
+			fs.mkdirSync(path.join(workspaceRoot, ".headlesscode"), { recursive: true })
+			fs.writeFileSync(
+				markerPath,
+				JSON.stringify({ sessionId: options.sessionId, taskFile: options.taskFile, startedAt: new Date().toISOString() }),
+				"utf-8",
+			)
+		} catch (err) {
+			// Non-fatal: the marker is a best-effort diagnostic, never a
+			// reason to abort a real session over a write failure.
+			logger.warn("[cli] failed to write last-session marker (non-fatal)", { error: String(err) })
+		}
+	}
+
+	// ── dry-run: no API key required ──────────────────────────────────────────
+	if (options.dryRun) {
+		try {
+			const customModes = await loadCustomModes(workspaceRoot)
+			const built = await buildSystemPrompt({
+				workspaceRoot,
+				mode: options.mode,
+				customModes,
+			})
+			// Dry-run advertises the same non-vendored tools a real session
+			// appends (code-intelligence + describe_image; browser_action is
+			// deliberately omitted here — the loop appends it, but this
+			// listing is a prompt/config check, not a live session).
+			const tools = appendCodeIntelTools(
+				appendDescribeImageTool(selectToolsForMode(options.mode, customModes)),
+			)
+			// Per-mode model assignment: dry-run resolves the model exactly
+			// like a real run (mode-models.json / _default / OPENROUTER_MODEL,
+			// with an explicit --model always winning) so the effective model
+			// is visible without an LLM call. undefined -> the client default.
+			const dryRunModel = resolveModelForMode({
+				workspaceRoot,
+				mode: options.mode,
+				explicitModel: options.model,
+				env: process.env,
+			})
+			// Reasoning effort (issue #30): resolved + validated here too so
+			// --dry-run catches a bad value (e.g. a typo in the env var or
+			// mode-models.json `_reasoning_effort` key) BEFORE the experiment
+			// burns any real LLM calls. A throw lands in the catch below.
+			const dryRunEffort = resolveReasoningEffortForMode({ workspaceRoot, env: process.env })
+			parseReasoningEffort(dryRunEffort)
+
+			process.stdout.write(built.prompt + "\n")
+			process.stdout.write(
+				`\n───── dry-run summary ─────\n` +
+					`mode:             ${options.mode}\n` +
+					`model:            ${dryRunModel ?? "deepseek/deepseek-v4-flash-0731 (client default)"}\n` +
+					`reasoning effort: ${dryRunEffort ?? "(unset — endpoint default)"}\n` +
+					`workspace:        ${workspaceRoot}\n` +
+					`custom modes:     ${customModes.length ? customModes.map((m) => m.slug).join(", ") : "(none, using built-ins)"}\n` +
+					`exposed tools:    ${tools.map((t) => (t.type === "function" ? t.function.name : t.type)).join(", ")}\n` +
+					`system prompt:    ${built.prompt.length} chars\n`,
+			)
+			logger.info("dry-run complete", { mode: options.mode, workspaceRoot })
+			return 0
+		} catch (err) {
+			process.stderr.write(`headlesscode: dry-run failed: ${err instanceof Error ? err.message : String(err)}\n`)
+			return 2
+		}
+	}
+
+	// ── real run: API key required ────────────────────────────────────────────
+	const apiKey = process.env.HEADLESSCODE_OPENROUTER_API_KEY
+	if (!apiKey) {
+		process.stderr.write(
+			"headlesscode: HEADLESSCODE_OPENROUTER_API_KEY is not set.\n" +
+				"  Export it (e.g. export HEADLESSCODE_OPENROUTER_API_KEY=sk-or-...) or use --dry-run to\n" +
+				"  validate the prompt/config without calling the LLM.\n",
+		)
+		return 2
+	}
+
+	if (!options.task && !options.taskFile) {
+		process.stderr.write(`headlesscode: provide a task with --task <text> or --task-file <path>\n\n${USAGE}`)
+		return 2
+	}
+	if (options.task && options.taskFile) {
+		process.stderr.write("headlesscode: use either --task or --task-file, not both\n")
+		return 2
+	}
+
+	let taskText = options.task ?? ""
+	if (options.taskFile) {
+		const taskFilePath = path.resolve(workspaceRoot, options.taskFile)
+		try {
+			taskText = fs.readFileSync(taskFilePath, "utf-8")
+		} catch (err) {
+			process.stderr.write(
+				`headlesscode: cannot read task file '${taskFilePath}': ${err instanceof Error ? err.message : String(err)}\n`,
+			)
+			return 2
+		}
+	}
+	if (taskText.trim() === "") {
+		process.stderr.write("headlesscode: task text is empty\n")
+		return 2
+	}
+
+	// Per-mode model assignment (plans/mode-model-assignment.md): the
+	// resolved mode's config entry / _default / OPENROUTER_MODEL apply only
+	// when no explicit --model flag was given (an explicit flag always wins).
+	// `undefined` is passed through so the OpenRouter client's own built-in
+	// default stays the single source of truth for the ultimate fallback.
+	const model = resolveModelForMode({
+		workspaceRoot,
+		mode: options.mode,
+		explicitModel: options.model,
+		env: process.env,
+	})
+
+	// Generalized 2026-08-21 (issue #142) beyond the original `code`-only
+	// scope (plans/local-dual-model-code-agent.md, D2) — real need: two
+	// separate local daemons on two different GPUs (a coder model and a
+	// review model), each needing its own mode -> URL/model mapping.
+	// HEADLESSCODE_LOCAL_BACKEND_MODES defaults to "code" alone, so
+	// nobody's existing setup changes behavior unless they opt in.
+	const codeModeBackend = process.env.HEADLESSCODE_CODE_MODE_BACKEND ?? "openrouter"
+	const localBackendModes = new Set(
+		(process.env.HEADLESSCODE_LOCAL_BACKEND_MODES ?? "code")
+			.split(",")
+			.map((s) => s.trim())
+			.filter(Boolean),
+	)
+	const useLocalCodeBackend = localBackendModes.has(options.mode) && codeModeBackend === "ollama"
+
+	// The local daemon's own proxy (ollama_shim.py) deliberately runs a 600s
+	// upstream request timeout — its own comment documents why: a shorter
+	// shim timeout was once found to cut off calls before the harness's own
+	// timeout would have. That fix only holds if the harness's own timeout
+	// is longer than the shim's. Two SEPARATE timeout mechanisms need this:
+	// loop.ts's llmTimeoutMs-driven AbortControllers (used below via
+	// `llmTimeoutMs`), and OllamaClient's own independent abort timer
+	// (ollama.ts's DEFAULT_OLLAMA_TIMEOUT_MS, passed as `timeoutMs` to the
+	// constructor just below) — a 2026-08-20 comment on that constructor
+	// call already documents discovering the SAME two-timeout trap for a
+	// different reason (`--llm-timeout-ms` being silently ignored). Verified
+	// live 2026-08-28: with the loop-level timeout alone raised to 630s, a
+	// session still died at exactly 300000ms — OllamaClient's own timer
+	// fired first every time since it was never told about the override.
+	// Resolved here (before both consumers) so neither can silently fall
+	// back to the wrong default the way the other already did once.
+	const LOCAL_LLM_TIMEOUT_MS = 630_000
+	const llmTimeoutMs = options.llmTimeoutMs ?? (useLocalCodeBackend ? LOCAL_LLM_TIMEOUT_MS : undefined)
+
+	// Issue #139 (updated for #142): warn whenever the local backend was
+	// requested via env var but the CURRENT mode isn't in the allow-list
+	// — was hardcoded to "code", now checks the real list.
+	if (codeModeBackend === "ollama" && !localBackendModes.has(options.mode)) {
+		process.stderr.write(
+			`[headlesscode] NOTE: HEADLESSCODE_CODE_MODE_BACKEND=ollama is set, but --mode "${options.mode}" is not in HEADLESSCODE_LOCAL_BACKEND_MODES ("${[...localBackendModes].join(",")}") — this session will use the cloud OpenRouter model instead.\n`,
+		)
+	}
+	// When the local backend is selected, every downstream consumer of
+	// `model` (session-start logs, event-feed session_start, cost/usage
+	// records, and — critically — the `request.model` sent on each
+	// OllamaClient call, since OllamaClient.resolveModel() prefers a
+	// non-empty request.model over its own defaultModel) must see the
+	// LOCAL model id, not the OpenRouter-resolved one. Without this,
+	// local sessions were tagged and logged as
+	// e.g. "deepseek/deepseek-v4-flash-0731" throughout — cosmetic for
+	// generation itself (the local daemon ignores the model string and
+	// serves whatever GGUF is loaded) but wrong everywhere the model id
+	// is recorded or reported (verified live 2026-08-21: session_start
+	// logged the cloud model id while actually running against the
+	// local Ollama daemon).
+	const effectiveModel = useLocalCodeBackend
+		? (resolvePerModeEnv("HEADLESSCODE_CODE_MODE_MODEL", options.mode) ?? model)
+		: model
+	const client: LlmClient = useLocalCodeBackend
+		? new OllamaClient({
+				defaultModel: effectiveModel,
+				// Issue #142: per-mode URL override (e.g. a review daemon on a
+				// different GPU than the code daemon) — falls back to the
+				// existing global HEADLESSCODE_OLLAMA_URL, then OllamaClient's
+				// own DEFAULT_OLLAMA_URL, when neither is set.
+				baseUrl: resolvePerModeEnv("HEADLESSCODE_OLLAMA_URL", options.mode),
+				// Without this, --llm-timeout-ms is silently ignored for the
+				// Ollama backend: OllamaClient has its own independent abort
+				// timer (ollama.ts's DEFAULT_OLLAMA_TIMEOUT_MS), separate
+				// from loop.ts's llmTimeoutMs-driven AbortControllers —
+				// verified live 2026-08-20: a trial dispatched with
+				// --llm-timeout-ms 900000 still aborted at exactly 300000ms
+				// because this constructor call never forwarded the option.
+				// `llmTimeoutMs` (not `options.llmTimeoutMs`) so the local-
+				// backend default resolved above reaches this timer too —
+				// verified live 2026-08-28: passing the raw option alone
+				// left this at the generic 300s default for every session
+				// that didn't explicitly pass --llm-timeout-ms.
+				timeoutMs: llmTimeoutMs,
+			})
+		: new OpenRouterClient({ apiKey, defaultModel: model })
+	// A small local model's context is dominated by the full tool catalog
+	// (see src/engine/lazy-tools.ts) — default lazy loading ON for local
+	// sessions specifically, without touching the cloud path's prompt-cache-
+	// friendly static catalog. An explicit env value always wins.
+	if (useLocalCodeBackend && process.env.HEADLESSCODE_LAZY_TOOL_CATALOG === undefined) {
+		process.env.HEADLESSCODE_LAZY_TOOL_CATALOG = "1"
+	}
+	// Same rationale (src/engine/prompt.ts's buildLeanSystemPrompt doc comment):
+	// the vendored system prompt alone is ~9.5K tokens, GUI-oriented content a
+	// headless local session doesn't need. Default on for local, off for cloud.
+	if (useLocalCodeBackend && process.env.HEADLESSCODE_LEAN_SYSTEM_PROMPT === undefined) {
+		process.env.HEADLESSCODE_LEAN_SYSTEM_PROMPT = "1"
+	}
+	// A local model that gives up mid-task and dumps prose was observed live
+	// (2026-08-19 baseline run) getting recorded as `session succeeded` with
+	// zero files touched — the bare-text-reply pragmatic-success fallback
+	// (loop.ts, HeadlessSessionConfig.requireExplicitCompletion) exists for
+	// cloud models that reliably signal completion through prose; a local
+	// session can't trust that signal, so require attempt_completion instead.
+	const requireExplicitCompletion =
+		useLocalCodeBackend && !envBoolean("HEADLESSCODE_ALLOW_TEXT_ONLY_COMPLETION")
+	// Works around a llama.cpp/llama-cpp-python grammar-constrained-decoding
+	// bug (ggml-org/llama.cpp#20164) that corrupts tool calls when a
+	// multi-parameter tool has any optional parameter — verified live
+	// 2026-08-20 against Qwen2.5-Coder-14B (edit_file failed 3/3 on an
+	// existing file; write_to_file, which has zero optional params,
+	// succeeded every time). See prompt.ts's
+	// patchEditFileToolForLocalModels doc comment. Cloud sessions aren't
+	// grammar-constrained this way, so this only applies to the local
+	// backend.
+	const patchLocalToolSchemas =
+		useLocalCodeBackend && !envBoolean("HEADLESSCODE_ALLOW_UNPATCHED_LOCAL_TOOL_SCHEMAS")
+	// A local model was observed calling attempt_completion for real and
+	// claiming success (e.g. "typecheck and tests passed") while the last
+	// execute_command it actually ran was still failing, never re-verifying
+	// in between (verified live 2026-08-20 against both Qwen2.5-Coder-14B
+	// and Qwen3-14B). requireExplicitCompletion above only catches a
+	// text-only non-call; this catches a real completion call whose claim
+	// the session's own last command result already contradicts. See
+	// loop.ts's HeadlessSessionConfig.verifyBeforeCompletion doc comment.
+	const verifyBeforeCompletion =
+		useLocalCodeBackend && !envBoolean("HEADLESSCODE_ALLOW_UNVERIFIED_COMPLETION")
+	// A local (Qwen3.5-9B) session was observed live 2026-08-27 doing the
+	// actual work correctly (a real, correct edit_file call) and then dying
+	// anyway: its first attempt_completion was deferred (a prior
+	// execute_command had failed), its next two execute_command retries
+	// ALSO failed (nested-quote shell one-liners it wrote — a
+	// jsonEscapingNote-class mistake, see prompt.ts — that ran fine when
+	// re-run by hand outside the harness), and by the time it gave up and
+	// wrote a prose explanation instead of retrying attempt_completion, that
+	// was already its 3rd consecutive mistake — DEFAULT_CONSECUTIVE_ERROR_LIMIT
+	// (3) counts tool errors and non-completing replies on the SAME counter,
+	// so two ordinary tool mistakes leave a local model exactly one strike
+	// from a hard stop even when the underlying task is already done. Cloud
+	// models haven't shown this failure shape (see prompt.ts's jsonEscapingNote
+	// doc comment — that failure was Qwen3-14B-specific too), so this is
+	// scoped to the local backend only, same opt-in-override pattern as the
+	// flags above. DEFAULT_TOOL_FAILURE_NUDGE_THRESHOLD (2) only needs to
+	// stay strictly below this value (see its own doc comment) — 6 leaves
+	// that comfortably true.
+	const DEFAULT_LOCAL_CONSECUTIVE_ERROR_LIMIT = 6
+	const consecutiveErrorLimit =
+		options.consecutiveErrorLimit ??
+		(useLocalCodeBackend ? DEFAULT_LOCAL_CONSECUTIVE_ERROR_LIMIT : undefined)
+	// Issue #144: local inference is free — a fabricated dollar figure in
+	// every log line is noise at best, misleading at worst.
+	const trackCost = !useLocalCodeBackend || envBoolean("HEADLESSCODE_FORCE_COST_TRACKING")
+	// Issue #143: unlike verifyBeforeCompletion above, this must NOT apply
+	// to every useLocalCodeBackend mode — deepseek-reviewer/qa-agent are
+	// read-only and their correct completion is often "read the files,
+	// verdict: clean" with zero write/execute calls. Scoped to an explicit
+	// allow-list (default: code + the orchestrator meta-mode, both of
+	// which are expected to actually change something or file something
+	// real), same opt-in pattern as HEADLESSCODE_LOCAL_BACKEND_MODES.
+	const artifactRequiredModes = new Set(
+		(process.env.HEADLESSCODE_REQUIRE_ARTIFACT_MODES ?? "code,multi-agent-orchestrator-headless")
+			.split(",")
+			.map((s) => s.trim())
+			.filter(Boolean),
+	)
+	const requireArtifactBeforeCompletion =
+		useLocalCodeBackend &&
+		artifactRequiredModes.has(options.mode) &&
+		!envBoolean("HEADLESSCODE_ALLOW_UNVERIFIED_COMPLETION")
+	// A local model was observed regenerating an entire existing ~500-line
+	// file from scratch via write_to_file for a one-function-add task
+	// instead of a targeted diff, getting cut off mid-regeneration and
+	// silently destroying everything after the cutoff (verified live
+	// 2026-08-20 against both Qwen2.5-Coder-14B and Qwen3-14B, reproduced
+	// with a synthetic request bypassing headlesscode entirely — see
+	// plans/local-dual-model-code-agent-PROMPT-2026-08-20.md, "Tonight's
+	// core finding"). See loop.ts's HeadlessSessionConfig.guardLargeOverwrites
+	// doc comment and executor.ts's largeOverwriteRefusal.
+	const guardLargeOverwrites =
+		useLocalCodeBackend && !envBoolean("HEADLESSCODE_ALLOW_UNGUARDED_OVERWRITES")
+	// The cloud-tuned condensation defaults (0.75 hard threshold, 0.6 early-fire
+	// — see condense.ts) were measured firing needlessly aggressively against a
+	// local model: a trial condensing at 38 messages against a 16384-token
+	// --context-window left most of the daemon's real n_ctx unused (verified
+	// live 2026-08-20 — see plans/local-dual-model-code-agent-PROMPT-2026-08-21.md,
+	// "Why is condensation firing so heavily"). Two local-only changes, an
+	// explicit --condense-threshold/--condense-early-fire flag always wins:
+	// (1) the hard threshold moves from 0.75 to 0.92 — condense only once the
+	// session is genuinely close to the real limit, not at 3/4 of it; (2) the
+	// early-fire background path (designed to hide a CLOUD provider's
+	// condensation-call latency behind the main loop) is disabled outright —
+	// against a single locally-loaded model it just fires a second concurrent
+	// generation request competing with the main loop for the same GPU, with
+	// no latency to hide. Disabling it is `earlyFire === hardThreshold`
+	// (fireBackgroundCondense's own off-switch, see loop.ts).
+	const LOCAL_CONDENSE_THRESHOLD_FRACTION = 0.92
+	const condenseThresholdFraction =
+		options.condenseThreshold ?? (useLocalCodeBackend ? LOCAL_CONDENSE_THRESHOLD_FRACTION : undefined)
+	const condenseEarlyFireFraction =
+		options.condenseEarlyFire ?? (useLocalCodeBackend ? LOCAL_CONDENSE_THRESHOLD_FRACTION : undefined)
+	// A local (Qwen3.5-9B+LoRA) condensation call was observed live
+	// 2026-08-28 turning a correctly-hedged note ("X is an existing gate,
+	// for reference") into a flat false claim ("X passed, ready to merge")
+	// for a feature the session never touched — a lossy ~13:1 compression
+	// under CONDENSE_SYSTEM_PROMPT's "never invent content" rule is only as
+	// reliable as the model executing it, and this one wasn't. The
+	// corrupted summary then re-entered history as trusted fact and the
+	// session repeated the false completion claim until bounded failure
+	// killed it. See HeadlessSessionConfig.disableLlmCondensation's doc
+	// comment (loop.ts) for the full tradeoff: local inference has no
+	// per-token cost pressure, so summarization's risk (a fabricated "fact"
+	// the model can't distinguish from a real one) isn't worth taking when
+	// truncateHistory's plain drop-oldest eviction — which keeps running
+	// either way — only ever loses information, never invents it.
+	const disableLlmCondensation =
+		useLocalCodeBackend && !envBoolean("HEADLESSCODE_ALLOW_LLM_CONDENSATION")
+
+	// Phase 3 context condensation: a cheaper model for the condensation
+	// call can be assigned via the `_condensation` key in
+	// .headlesscode/mode-models.json (consulted BEFORE the mode entry —
+	// its whole purpose is to override the session model for condensation,
+	// so a file that sets both `code` and `_condensation` must use the
+	// cheap model). An explicit --condense-model flag always wins; otherwise
+	// the session model is used (same model = simplest, consistent quality).
+	const condenseModel =
+		options.condenseModel ??
+		resolveModelForMode({
+			workspaceRoot,
+			mode: options.mode,
+			explicitModel: undefined,
+			extraKeys: ["_condensation"],
+			env: process.env,
+		})
+
+	// loop.ts's resolveContextWindowTokens() live-queries the OpenRouter
+	// catalog for the real context window and falls back to
+	// DEFAULT_CONTEXT_WINDOW_TOKENS (128000) when that lookup fails or isn't
+	// applicable — which is unconditional for the local backend (there's no
+	// OpenRouter catalog entry for a locally-loaded GGUF). Verified live
+	// 2026-08-27: the code-daemon's actual configured window
+	// (AIRUNNER_GGUF_N_CTX, checked via `docker inspect`) is 40960, well
+	// under the assumed 128000 — the opposite-direction version of the
+	// condenseThresholdFraction incident above (that one was a too-SMALL
+	// assumed window firing condensation too early; an unset context window
+	// here is too LARGE, so condensation at 92% of a wrong 128000 would fire
+	// at ~118000 tokens, past the real 40960 limit, risking a hard daemon
+	// failure/silent truncation instead of a graceful condense). No session
+	// observed tonight actually reached anywhere near 40960 real tokens, so
+	// this didn't cause any of tonight's local-model failures — but it's a
+	// real latent gap for any longer local session. Not auto-detectable (the
+	// Ollama-compat API doesn't expose it), so a documented env default,
+	// same override precedence as every other local-only default above.
+	const DEFAULT_LOCAL_CONTEXT_WINDOW_TOKENS = 40960
+	const localContextWindowTokens = Number(process.env.HEADLESSCODE_CODE_MODE_CONTEXT_WINDOW ?? DEFAULT_LOCAL_CONTEXT_WINDOW_TOKENS)
+	const contextWindowTokens =
+		options.contextWindowTokens ??
+		(useLocalCodeBackend && Number.isFinite(localContextWindowTokens) && localContextWindowTokens > 0
+			? localContextWindowTokens
+			: undefined)
+
+	// Graded reasoning effort for deepseek/* models (issue #30 experiment):
+	// the `_reasoning_effort` key in mode-models.json beats
+	// $HEADLESSCODE_REASONING_EFFORT. Deliberately NOT a CLI flag — the
+	// experiment compares env/config values and a flag would be one more
+	// surface to keep in sync. Validated here so a typo fails at startup
+	// (exit 2) with a clear message instead of mid-session on the first LLM
+	// call (fail-loudly, same idiom as mode-models.ts).
+	const reasoningEffort = resolveReasoningEffortForMode({ workspaceRoot, env: process.env })
+	try {
+		parseReasoningEffort(reasoningEffort)
+	} catch (err) {
+		process.stderr.write(`headlesscode: ${err instanceof Error ? err.message : String(err)}\n`)
+		return 2
+	}
+
+	// Phase 3 memory: OFF by default (preserves pre-Phase-3 behavior). Enabled
+	// only by --memory-dir or $HEADLESSCODE_MEMORY_DIR; --no-memory forces off.
+	const memory = resolveMemory(options, workspaceRoot)
+	const project = process.env.HEADLESSCODE_PROJECT ?? path.basename(workspaceRoot)
+
+	// Phase 6 per-session budget: flags win over the env fallbacks
+	// ($HEADLESSCODE_MAX_COST_USD / $HEADLESSCODE_MAX_DURATION_MS — set by
+	// run-worker.sh / run-qa.sh for workers). Off when neither is set.
+	const maxCostUsd = options.maxCostUsd ?? envNumber("HEADLESSCODE_MAX_COST_USD")
+	const maxDurationMs = options.maxDurationMs ?? envNumber("HEADLESSCODE_MAX_DURATION_MS")
+	const budget =
+		maxCostUsd !== undefined || maxDurationMs !== undefined ? { maxCostUsd, maxDurationMs } : undefined
+
+	// Decision escalation: flag wins over the env fallback
+	// ($HEADLESSCODE_DECISION_TIMEOUT_MS — set by run-worker.sh for workers).
+	// Off (undefined) falls back to executor.ts's own default (30 min).
+	const decisionTimeoutMs = options.decisionTimeoutMs ?? envNumber("HEADLESSCODE_DECISION_TIMEOUT_MS")
+
+	// Pause/resume (live worker monitoring): flag wins over the env fallback
+	// ($HEADLESSCODE_MAX_PAUSE_MS). Off (undefined) falls back to loop.ts's
+	// own default (2h — matching watch.ts's stall guard). Passing it through
+	// explicitly keeps the CLI the single place that resolves config.
+	const maxPauseMs = options.maxPauseMs ?? envNumber("HEADLESSCODE_MAX_PAUSE_MS")
+
+	// Recursive task decomposition (`new_task`): CLI flag wins over the env
+	// fallback; undefined falls back to loop.ts's own defaults (depth 2 /
+	// fraction 0.5). Passed through so children inherit the root's caps.
+	const maxRecursionDepth = options.maxRecursionDepth ?? envNumber("HEADLESSCODE_MAX_RECURSION_DEPTH")
+	const childIterationFraction =
+		options.childIterationFraction ?? envNumber("HEADLESSCODE_CHILD_ITERATION_FRACTION")
+
+	// switch_mode (plans/switch-mode-headless.md): the approval gate is OFF by
+	// default. Flag wins over the env fallback
+	// ($HEADLESSCODE_AUTO_APPROVE_MODE_SWITCH); undefined falls back to
+	// loop.ts's own cap default (DEFAULT_MAX_MODE_SWITCHES = 5).
+	const autoApproveModeSwitch =
+		options.autoApproveModeSwitch || envBoolean("HEADLESSCODE_AUTO_APPROVE_MODE_SWITCH")
+	const maxModeSwitches = options.maxModeSwitches ?? envNumber("HEADLESSCODE_MAX_MODE_SWITCHES")
+
+	// Flag wins over the env fallback; undefined falls back to loop.ts's own
+	// default (DEFAULT_MAX_TOKENS = 32768) — sized for a CLOUD reasoning
+	// model against a 128K+ context window (4x the heaviest real generation
+	// observed there, ~8,000 tokens). Verified live 2026-08-28 (joeos issue
+	// #26): applied unchanged to the local backend, this let a single
+	// generation run to 29,664 output tokens — on a real llama-server
+	// context window of only 65,536 total, that alone pushed the very next
+	// request to 65,657 tokens and crashed the session outright ("exceeds
+	// the available context size"), un-recoverably, unlike an iteration-cap
+	// exhaustion (no auto-continuation exists for a hard crash). The
+	// existing condensation threshold guard cannot prevent this class of
+	// failure: it only checks the LAST completed request's size before
+	// building the next one, with no way to know in advance that the
+	// upcoming single response will be enormous. Same local-only-override
+	// pattern already used for condenseThresholdFraction below: a runaway
+	// generation's blast radius should be a small fraction of the REAL
+	// local context window, not up to half of it.
+	const LOCAL_MAX_TOKENS = 8192
+	const maxTokens =
+		options.maxTokens ?? envNumber("HEADLESSCODE_MAX_TOKENS") ?? (useLocalCodeBackend ? LOCAL_MAX_TOKENS : undefined)
+
+	// Permissions (command allow/deny + protected files): CLI flags > env vars
+	// > <workspaceRoot>/.headlesscode/permissions.json > built-in defaults.
+	// A malformed permissions.json fails loudly (mirrors HEADLESSCODE_PRICING_JSON).
+	let permissions: PermissionsConfig
+	try {
+		permissions = resolvePermissions({
+			workspaceRoot,
+			overrides: {
+				allowedCommands: options.allowedCommands,
+				deniedCommands: options.deniedCommands,
+				protectedFiles: options.protectedFiles,
+				allowProtectedWrites: options.allowProtectedWrites ? true : null,
+			},
+			env: process.env,
+		})
+	} catch (err) {
+		process.stderr.write(`headlesscode: ${err instanceof Error ? err.message : String(err)}\n`)
+		return 2
+	}
+
+	const session = new HeadlessSession({
+		workspaceRoot,
+		sessionId: options.sessionId,
+		mode: options.mode,
+		model: effectiveModel,
+		taskText,
+		maxIterations: options.maxIterations,
+		maxRecursionDepth,
+		childIterationFraction,
+		consecutiveErrorLimit,
+		windowSize: options.windowSize,
+		contextWindowTokens,
+		condenseThresholdFraction,
+		condenseEarlyFireFraction,
+		condenseModel,
+		disableLlmCondensation,
+		llmTimeoutMs,
+		stream: options.stream,
+		reasoningEffort,
+		temperature: options.temperature,
+		requireExplicitCompletion,
+		patchLocalToolSchemas,
+		verifyBeforeCompletion,
+		trackCost,
+		requireArtifactBeforeCompletion,
+		requireArtifactPathPattern: options.requireArtifactPath,
+		requireArtifactMinCitations: options.requireArtifactMinCitations,
+		requireArtifactSections: options.requireArtifactSections,
+		guardLargeOverwrites,
+		llmClient: client,
+		logger,
+		memory,
+		project,
+		budget,
+		checkpoints: !options.noCheckpoints,
+		checkpointDir: options.checkpointDir,
+		decisionTimeoutMs,
+		autoApproveModeSwitch,
+		maxModeSwitches,
+		maxTokens,
+		maxPauseMs,
+		permissions,
+		// Opt-in local exploration phase (default OFF). Flag OR env var — the
+		// phase itself resolves the remaining HEADLESSCODE_LOCAL_EXPLORE_*
+		// defaults at call time. Any local failure fails open to cloud-only.
+		localExplore: options.localExplore || isLocalExploreEnabled(process.env),
+	})
+
+	const result = await session.run()
+
+	// A session writes into workspaceRoot throughout the run (file edits,
+	// its own .headlesscode/{events,usage,reports}, git's index as it
+	// stages things) AND, when workspaceRoot is a worktree, into the
+	// source repo's separate .git/worktrees/<name>/ admin dir — chowning
+	// only at worktree *creation* time (see session-launch.ts's
+	// ensureWorktree) misses all of this. Runs regardless of success/
+	// failure — a failed session can leave root-owned files too. No-ops
+	// when HEADLESSCODE_DASHBOARD_WORKTREE_OWNER isn't set (today's
+	// default for a non-container / non-root run).
+	chownWorktreeWorkspace(workspaceRoot)
+
+	if (session.memoryStats) {
+		process.stdout.write(
+			`[memory] project="${project}" recalled ${session.memoryStats.recalledFacts} fact(s) / ${session.memoryStats.recalledSessions} session(s); recorded ${session.memoryStats.recordedFacts} fact(s) / ${session.memoryStats.recordedSessions} session(s)\n`,
+		)
+	}
+
+	if (result.budgetUsage) {
+		process.stdout.write(
+			`[budget] cost $${result.budgetUsage.costUsd.toFixed(6)}, elapsed ${result.budgetUsage.elapsedMs}ms, iterations ${result.budgetUsage.iterations}, model ${result.budgetUsage.model}\n`,
+		)
+	}
+
+	if (result.status === "success") {
+		logger.info("session succeeded", { iterations: result.iterations, toolCalls: result.toolCalls })
+		process.stdout.write(result.result + "\n")
+		return 0
+	}
+
+	logger.error("session failed", { error: result.error, iterations: result.iterations, reason: result.reason })
+	if (result.reason === "budget") {
+		process.stderr.write(`headlesscode: task aborted by budget: ${result.error ?? "budget exceeded"}\n`)
+		return 1
+	}
+	process.stderr.write(`headlesscode: task failed: ${result.error ?? "unknown error"}\n`)
+	return 1
+}
+
+/**
+ * Per-mode env var lookup for issue #142: `HEADLESSCODE_<BASE>__<MODE>`
+ * (mode slug uppercased, "-" -> "_") wins if set, else the plain global
+ * `HEADLESSCODE_<BASE>`, else undefined. Shared by both the per-mode
+ * Ollama URL and model lookups so they resolve identically.
+ */
+export function resolvePerModeEnv(
+	baseName: string,
+	mode: string,
+	env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+	const modeKey = mode.toUpperCase().replace(/-/g, "_")
+	return env[`${baseName}__${modeKey}`] ?? env[baseName]
+}
+
+/** Parse a positive finite number from env (undefined when unset/invalid). */
+function envNumber(name: string): number | undefined {
+	const raw = process.env[name]
+	if (raw === undefined || raw === "") {
+		return undefined
+	}
+	const n = Number(raw)
+	return Number.isFinite(n) && n > 0 ? n : undefined
+}
+
+/** Parse an env boolean opt-in: "1"/"true"/"yes"/"on" → true; anything else (incl. unset) → false. */
+export function envBoolean(name: string): boolean {
+	const raw = process.env[name]
+	if (raw === undefined || raw === "") {
+		return false
+	}
+	return ["1", "true", "yes", "on"].includes(raw.trim().toLowerCase())
+}
+
+/**
+	* Resolve the Phase 3 memory store. Default OFF (null) to preserve existing
+	* behavior; enabled by --memory-dir or $HEADLESSCODE_MEMORY_DIR. --no-memory
+	* forces OFF even when the env var is set.
+	*/
+function resolveMemory(options: CliOptions, workspaceRoot: string): MemoryStore | null {
+	if (options.noMemory) {
+		return null
+	}
+	const dir = options.memoryDir ?? process.env.HEADLESSCODE_MEMORY_DIR
+	if (!dir) {
+		return null
+	}
+	return new LocalMemoryStore({ dir: path.resolve(dir) })
+}
+
+// Allow `tsx src/cli.ts` / `headlesscode` / `npm run cli` to run directly.
+if (import.meta.url === `file://${process.argv[1]}`) {
+	main().then(
+		(code) => {
+			process.exitCode = code
+		},
+		(err) => {
+			process.stderr.write(`headlesscode: unexpected error: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`)
+			process.exitCode = 2
+		},
+	)
+}