Merge feat/local-model-recommendation: recommend and install a local coding model on this Mac (experimental)

Conflicts resolved as on test/desktop-macbook: config/test-suites.ts keeps both browser tests (desktop-connect-page and local-model-ui), and the CLAUDE.md state-files line keeps #778's cli-installed entry with the local model's local-model.json and local-model/ entries.

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

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

@@ -1414,6 +1414,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>
@@ -2866,6 +2877,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 ═════════════════════════════════════════ -->
@@ -3644,6 +3677,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>
@@ -4684,6 +4738,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

@@ -1852,6 +1852,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;
@@ -4256,3 +4291,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

@@ -2970,6 +2970,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

@@ -147,6 +147,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,
@@ -265,6 +266,7 @@ import {
   pruneIdleLlamaSwapLogTails,
   tryWebviewRefererFallback,
   registerCliRegistryRoutes,
+  registerLocalModelRoutes,
 } from './routes/index.js';
 import { isLostWebviewFrameNavigation } from './webview-proxy.js';
 import { CronService } from '../cron/cron-service.js';
@@ -1418,6 +1420,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.
@@ -2192,6 +2195,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
@@ -3472,6 +3486,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.
@@ -4621,6 +4643,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();