fix(files): the review's fixes for the Files panel delete

The fixes #529's review asked for, each with a test.

- No inline handler. The button quoted the path inside
  onclick="...decodeURIComponent('<path>')", and encodeURIComponent leaves
  ' alone, so a file named x'-alert(1)-'.txt ran script in Codeman's
  origin and it's.txt was a syntax error. It is now bound in the existing
  .file-tree-item loops from the row's escaped data-path.
- Symbolic links are refused, never followed. validateSessionFilePath()
  returns the realpath, so deleting AGENTS.md -> CLAUDE.md deleted
  CLAUDE.md and left the link dangling. The path as named is lstat'ed,
  a link answers 400, and the inode is compared again before the unlink.
- The edit route's confinement whole: validateLocalSessionFilePath()
  behind withGuardedOutsideWorktree(), so an absolute path in a followed
  outside worktree obeys the same rules, and the sensitive, blocked and
  .git checks run on both the realpath and the path as named.
- Adopted sessions are refused like remote ones (the /tmp exception of
  the older file surfaces is not copied to a new one); Docker workspaces
  are allowed, as on the edit route. The workspace is probed bounded
  first (#516). Errors are thrown with their status.
- Deleting from search results re-runs the search, the row buttons stay
  visible on touch screens, the confirm and toasts have zh-CN text, and
  no button is drawn for remote or adopted sessions.
- Docs: CLAUDE.md, architecture-invariants, api-reference and the
  Working With Files wiki page.

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

CLAUDE.md

@@ -243,6 +243,8 @@ The terminal provider scans `terminalLinkLine()`, which extends `terminalPathLin
 
 **File Viewer edit mode** (issue #212): the file-preview overlay edits workspace text files in place: `GET .../file-content?edit=1` + `PUT /api/sessions/:id/file-content`, policy in `src/config/file-editing.ts`. This is a **third file surface and the only one that writes file contents** (the path picker's New folder creates folders only): read-path confinement (realpath + workspace + ownership, where an absolute path inside a followed outside worktree (`SessionState.outsideWorktree`) counts as a second workspace root) plus sensitive/blocked/`.git` denies and an extension **allowlist**; writes are `wx`-temp + rename (no `O_CREAT` anywhere = edit-in-place is structural); optimistic concurrency via sha256 `baseHash` → 409. ⚠️ `edit=1` never truncates and the client must never save a plain-preview buffer (the 500-line truncation would silently delete the rest). ⚠️ CRLF/UTF-8 guards: EOL re-applied server-side, non-UTF-8 refused via round-trip compare. → [architecture-invariants#file-viewer-edit-mode](docs/architecture-invariants.md#file-viewer-edit-mode), `docs/file-viewer-edit-plan.md`
 
+**Files panel delete** (salvaged from #529; `DELETE /api/sessions/:id/files?path=`, the × on a file row of the Files panel, tree and search results): removes ONE regular file and is the **only file surface that deletes**. It takes the edit route's confinement and guards whole (ownership via `findSessionOrFail`, `validateLocalSessionFilePath` behind `withGuardedOutsideWorktree`, so an absolute path in a followed outside worktree obeys the same rules, sensitive/blocked/`.git` 403), and both spellings are checked, the realpath and the path as named. ⚠️ **A symbolic link is refused (400), never followed**: the confinement check returns the REALPATH, i.e. the link's target, so an `unlink` of it deleted `CLAUDE.md` for `AGENTS.md -> CLAUDE.md` and left the link dangling. The final component is `lstat`ed on the path AS NAMED, only a plain file goes on, the inode is compared again before `unlink`, and `unlink` never follows a final link. A dangling link fails realpath and reads as 404. ⚠️ Remote sessions are refused before any path check (a same-named local folder would take the delete), and so are adopted ones (the `/tmp` file-surface exception is not copied to a new surface); Docker workspaces are allowed like the edit route. The workspace (and the outside worktree root) is probed bounded first (#516, `422` on a dead mount). ⚠️ The button is bound from the row's escaped `data-path` in the `.file-tree-item` loops, NEVER an inline `onclick` (`encodeURIComponent` leaves `'` alone, so `x'-alert(1)-'.txt` ran script); it asks with `confirm()`, reloads through `_reloadFileBrowserKeepingQuery()` so a search re-runs, stays visible under `@media (hover: none)`, and is not drawn for remote or adopted sessions. Tests: `test/routes/file-delete-routes.test.ts`, `test/file-delete-ui.test.ts`. → [architecture-invariants#files-panel-delete](docs/architecture-invariants.md#files-panel-delete)
+
 **Files panel search** (COD-236, the `q` param on `GET /api/sessions/:id/files`): `compileFileQuery()` (`utils/file-query.ts`, pure) compiles the query into a predicate the server-side walk prunes with; a query returns a FLAT match list and the walk recurses past non-matching directories. An empty, whitespace-only or overlong (`MAX_QUERY_LENGTH`, 256) query compiles to `null`, keeping the default tree response byte-identical. ⚠️ **Never compile a glob into a RegExp** (`*a*a*a…` backtracks and freezes the event loop for the whole server): `globMatch()` is a two-pointer wildcard walk. Tree and search share one walk shape: a per-directory round-robin (breadth-first, so fair per directory, not per subtree) over one 5,000-node budget, where a folder's own files count as one share beside the subfolders it just found (`walkTurnEnd()`). ⚠️ That budget caps what is LISTED, never what is read: a read keeps only what the listing can use (`readWalkFolder()`) and `MAX_WALK_ENTRIES_READ` (250,000) stops opening folders, or one GET reads the whole workspace into memory. ⚠️ A folder below the walk's root is probed (#516) before its `readdir`, and anything but `directory` is skipped unflagged. ⚠️ A directory has its node before it is read, so every cursor still queued or unread when the walk ends must get `incomplete: true` or it reads as an empty folder. → [architecture-invariants#files-panel-search](docs/architecture-invariants.md#files-panel-search)
 
 **Files panel in a worktree** (#765, `src/live-worktree.ts`, `root=live` and `root=live-any` on `GET /api/sessions/:id/files`): Claude's EnterWorktree moves the process, and `paneCwd` follows it (tmux reads the process cwd, measured on 2.1.318, back out on ExitWorktree too), while `workingDir` stays the session's identity. `refreshLiveWorktree()` (server.ts) turns a changed `paneCwd` into `SessionState.liveWorktree` by reading the `.git` FILE (never spawning git), walking up and stopping at `workingDir`, a repository or submodule of its own, or anything unreadable. That is the lookup for a pane inside `workingDir`; a pane outside it goes to `findOutsideWorktree()`, described below. ⚠️ The security argument has two halves. For a worktree inside `workingDir` the lookup only answers a folder strictly below it, but that is a LEXICAL judgement made when the pane moves, and a symlink can replace the folder or a parent later without moving the pane, so `root=live` re-checks on every request (`canWalkLiveWorktree()`, file-routes.ts: walk the worktree only when it resolves strictly inside the resolved `workingDir`, else walk `workingDir`). The walk starts there, returned `path`s stay relative to `workingDir`, and the routes keep confining to `workingDir`, so never make an INSIDE `liveWorktree` a confinement root. ⚠️ Only that check uses resolved paths: the walk keeps the session's spelling, or a workspace reached through a symlink stops producing paths relative to `workingDir`. ⚠️ A plain subfolder is deliberately no answer, or a `cd` in a shell would re-root the panel. ⚠️ A listing reports `worktree` whichever folder it walked, even when the worktree has gone or the check refused it: `_followFileBrowserWorktree()` compares that with the session's state, and an absent report would reload forever. The one exception is a listing without `root=live-any`, which omits an outside worktree; while the session folder is pinned, the panel compares with the worktree it pinned away from (`pinnedWorktree`, panels-ui.js). ⚠️ **A worktree OUTSIDE `workingDir` (`git worktree add ../feature`, or an EnterWorktree placed beside the repo) IS a second root**, answered only through `findOutsideWorktree()` with `outside: true` and published on the wire as `SessionState.outsideWorktree`, never in `liveWorktree`, which stays inside-only: the session's own repository must vouch for it by FILE READS (`workingDir` must be the top of its repository or worktree, so a session in a subfolder follows nothing outside it; the candidate's `.git` FILE names `<common dir>/worktrees/<id>` and that entry's `gitdir` names the candidate back, or its `.git` FOLDER is the session's common dir itself, which is the main worktree for a session started in a linked one, and a symlinked `.git` is refused; never spawn git from the pane watcher). It is refused at `/`, home or above, around `workingDir` and at/inside/around a Docker case workspace (an unreadable Docker list follows nothing). It is refused while attachment workspace confinement is on. It is also refused at, inside or around an attachment blocked tree, and at a root that is itself a sensitive folder such as `~/.ssh` (a child probe, since the sensitive patterns describe file locations). These rules are judged when the pane moves like the Docker rule, and multi-user mode applies `folderAllowedForUser`. The routes also re-check confinement and the blocked trees on every request (`isOutsideWorktreeRootRefused()`), so turning confinement on or blocking the folder stops serving it at once. ⚠️ `validateLocalSessionFilePath()` also refuses any file there that `isSensitivePath()` blocklists, so a root such as a credential folder can never serve its keys. Walking it is opt-in: only `root=live-any` (which the panel sends) lists it, with ABSOLUTE `path`s, while `root=live` never walks an outside worktree: it walks `workingDir` with relative paths, and its listing omits `worktree` for an outside one. An absolute path inside it is confined to it, falling back to `workingDir` when the worktree root refuses it (`validateLocalSessionFilePath()`, route-helpers.ts), while a relative path still resolves against `workingDir` alone. ⚠️ It is recorded as a REAL path, and every request re-checks that the folder still resolves to exactly that path (`outsideWorktreeRootFor()`, `canWalkOutsideWorktree()`), or a symlink swapped in would re-root the routes anywhere. Tests: `test/live-worktree.test.ts`, `test/live-worktree-outside.test.ts`, `test/routes/file-routes-live-worktree.test.ts`, `test/routes/file-routes-outside-worktree.test.ts`, `test/file-browser-worktree.test.ts`, `test/file-browser-outside-worktree.test.ts`. → [architecture-invariants#files-panel-in-a-worktree](docs/architecture-invariants.md#files-panel-in-a-worktree)

README.md

@@ -8,6 +8,12 @@
   <em>Claude Code &bull; OpenCode &bull; Codex &bull; Antigravity &bull; Gemini &bull; Pi &bull; Grok &bull; DeepSeek &bull; OMP &bull; Copilot &bull; Terminal - One Dashboard &bull; Any Device</em>
 </p>
 
+<p align="center">
+  <a href="https://github.com/Ark0N/Codeman/releases/latest/download/Codeman.dmg"><img src="https://img.shields.io/badge/Download_for_Mac-Codeman.dmg-2f6fe0?style=for-the-badge&logo=apple&logoColor=white&labelColor=000000" alt="Download Codeman for Mac (Codeman.dmg)" width="354"></a>
+  <br>
+  <sub>The native Mac app: signed and notarized, Apple Silicon and Intel, macOS 11.3 or later. <a href="#on-a-mac-the-codeman-app">What it does</a></sub>
+</p>
+
 <p align="center">
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-1e3a5f?style=flat-square" alt="License: MIT"></a>
   <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-22%2B-22c55e?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 22+"></a>
@@ -17,7 +23,6 @@
   <a href="https://github.com/Ark0N/Codeman/stargazers"><img src="https://img.shields.io/github/stars/Ark0N/Codeman?style=flat-square&color=eab308" alt="GitHub stars"></a>
   <a href="https://github.com/Ark0N/Codeman/graphs/contributors"><img src="https://img.shields.io/github/contributors/Ark0N/Codeman?style=flat-square&color=3b82f6" alt="Contributors"></a>
   <a href="https://github.com/Ark0N/Codeman/commits/master"><img src="https://img.shields.io/github/commit-activity/t/Ark0N/Codeman?style=flat-square&color=1e3a5f" alt="Total commits"></a>
-  <a href="https://github.com/NipunaRanasinghe/awesome-ai-agents"><img src="https://img.shields.io/badge/Featured_in-Awesome_AI_Agents-2ea44f?style=flat-square" alt="Featured in Awesome AI Agents"></a>
 </p>
 
 <p align="center">

README.zh-CN.md

@@ -8,6 +8,12 @@
   <em>Claude Code &bull; OpenCode &bull; Codex &bull; Antigravity &bull; Gemini &bull; Pi &bull; Grok &bull; DeepSeek &bull; OMP &bull; Copilot &bull; 终端 —— 统一仪表盘 &bull; 任意设备</em>
 </p>
 
+<p align="center">
+  <a href="https://github.com/Ark0N/Codeman/releases/latest/download/Codeman.dmg"><img src="https://img.shields.io/badge/%E4%B8%8B%E8%BD%BD_Mac_%E7%89%88-Codeman.dmg-2f6fe0?style=for-the-badge&logo=apple&logoColor=white&labelColor=000000" alt="下载 Mac 版 Codeman（Codeman.dmg）" width="281"></a>
+  <br>
+  <sub>原生 Mac 应用：已签名并经过 Apple 公证，支持 Apple 芯片和 Intel，macOS 11.3 或更高版本。<a href="#在-mac-上codeman-应用">它能做什么</a></sub>
+</p>
+
 <p align="center">
   <a href="README.md">English</a> &bull; <strong>简体中文</strong>
 </p>
@@ -21,7 +27,6 @@
   <a href="https://github.com/Ark0N/Codeman/stargazers"><img src="https://img.shields.io/github/stars/Ark0N/Codeman?style=flat-square&color=eab308" alt="GitHub stars"></a>
   <a href="https://github.com/Ark0N/Codeman/graphs/contributors"><img src="https://img.shields.io/github/contributors/Ark0N/Codeman?style=flat-square&color=3b82f6" alt="Contributors"></a>
   <a href="https://github.com/Ark0N/Codeman/commits/master"><img src="https://img.shields.io/github/commit-activity/t/Ark0N/Codeman?style=flat-square&color=1e3a5f" alt="Total commits"></a>
-  <a href="https://github.com/NipunaRanasinghe/awesome-ai-agents"><img src="https://img.shields.io/badge/Featured_in-Awesome_AI_Agents-2ea44f?style=flat-square" alt="Featured in Awesome AI Agents"></a>
 </p>
 
 <p align="center">

docs/api-reference.md

@@ -901,6 +901,25 @@ already serves non-media text inert (`text/plain`, `nosniff`), so this just
 keeps the server from storing what it would serve or an agent could run, and
 html and svg are the ones deliberately kept out.
 
+## Deleting a file (`DELETE /api/v1/sessions/:id/files?path=`)
+
+The Files panel's delete button. `path` is what the listing gave the row: relative to the
+session's `workingDir`, or absolute inside the session's outside worktree (see
+[Live worktree](#live-worktree-liveworktree-outsideworktree)). It removes that one regular file
+and answers `{ path }` as sent. It never deletes a folder and never follows a symbolic link:
+the file routes resolve a link to its target, so deleting through one would remove the file it
+points to.
+
+| Status | When |
+| ------ | ---- |
+| `200`  | The file is gone. |
+| `400`  | A remote (SSH) session or an adopted session (both refused before any path is looked at), a missing or repeated `path`, a symbolic link, or anything that is not a regular file. |
+| `403`  | A sensitive file (`.env`, credentials and the like), a blocked attachment tree, or anything under `.git`. |
+| `404`  | No such file, a path outside the workspace (`../`, an absolute path elsewhere, a link leading out), a dangling link, or a session the caller does not own in multi-user mode. |
+| `409`  | The file was replaced between the checks and the delete; reload the listing. |
+| `422`  | The workspace's mount did not answer. |
+
+## New folder in the path picker
 ## New folder in the path picker
 
 `POST /api/filesystem/mkdir` with `{ path, name, sessionId?, showHidden? }` makes one
@@ -1021,8 +1040,8 @@ of `liveWorktree` and `outsideWorktree`:
 Like `liveWorktree`, it is never restored after a restart.
 
 Such a worktree is a second root for the session's file routes. `file-content` (read and edit),
-`file-raw`, `file-preview`, `file-thumbnail`, `GET /api/v1/download` and
-`POST /api/v1/sessions/:id/html-view` accept an ABSOLUTE path inside it, while a relative path
+`file-raw`, `file-preview`, `file-thumbnail`, `GET /api/v1/download`,
+`POST /api/v1/sessions/:id/html-view` and `DELETE /api/v1/sessions/:id/files` accept an ABSOLUTE path inside it, while a relative path
 still resolves against `workingDir` only. A file there that the sensitive-path blocklist names
 (`.env`, `.aws/credentials`, `users.json` and the like) is refused on every one of those routes.
 Codeman reports the worktree only when the session's own repository lists it, and only when `workingDir` is the top of that repository or of a linked worktree, so a session started in a subfolder of its repository reports none. It never reports:

docs/architecture-invariants.md

@@ -468,7 +468,7 @@ The general rule: **any new endpoint that turns a caller-supplied `sessionId` in
 
 ### File Viewer edit mode
 
-**File Viewer edit mode** (issue #212, design in `docs/file-viewer-edit-plan.md`): the file-preview overlay can edit workspace text files in place — `GET /api/sessions/:id/file-content?edit=1` (read-for-edit) + `PUT /api/sessions/:id/file-content` (save), policy in `src/config/file-editing.ts`, UI in `panels-ui.js`. This is the **only file surface that writes**, so it carries every rule the read surfaces have plus its own:
+**File Viewer edit mode** (issue #212, design in `docs/file-viewer-edit-plan.md`): the file-preview overlay can edit workspace text files in place — `GET /api/sessions/:id/file-content?edit=1` (read-for-edit) + `PUT /api/sessions/:id/file-content` (save), policy in `src/config/file-editing.ts`, UI in `panels-ui.js`. This is the **only file surface that writes file contents** (the Files panel's delete, [below](#files-panel-delete), removes whole files and borrows these confinement rules), so it carries every rule the read surfaces have plus its own:
 
 - **Confinement is the read path's, plus write-only gates.** `findSessionOrFail` (ownership) → `validateSessionFilePath` (realpath + workspace boundary; escapes report as 404, same as reads) → sensitive-path + attachment-guard blocklists (403) → `.git/` subtree deny (403 — `.git/hooks/*` is code execution) → extension **allowlist** (400; `svg` and `env` deliberately excluded). ⚠️ **There is no `O_CREAT` anywhere in the handler** — that absence is what makes "edit-in-place only, never create" a structural property instead of a convention. Do not add a create path without treating it as a new security surface.
 - **A truncated buffer must never become an edit buffer.** The plain preview truncates to `lines` (default 500); saving such a buffer would silently delete everything past the cut, and the hash check cannot catch it (the loaded prefix hashes differently from the full file, which reads as an ordinary conflict at best). `edit=1` therefore never truncates — it 413s over `MAX_EDITABLE_BYTES` (512KB) instead — and the frontend always re-fetches with `edit=1` before swapping in the textarea, even though the preview already holds content.
@@ -479,6 +479,18 @@ The general rule: **any new endpoint that turns a caller-supplied `sessionId` in
 
 Tests: `test/file-editing-policy.test.ts` (pure policy), `test/routes/file-write-routes.test.ts` (deliberately **unmocked fs** against a real temp workspace — symlink/TOCTOU/mode behavior must be exercised for real).
 
+### Files panel delete
+
+**Files panel delete** (salvaged from contributor PR #529, which was closed; its upload half was dropped because `.codeman-uploads/` and the Attach button already cover it): a × on each file row of the Files panel, tree and search results alike, backed by `DELETE /api/sessions/:id/files?path=` in `file-routes.ts`. It removes ONE regular file and is the only file surface that deletes, so it takes the edit route's confinement whole and adds a rule of its own.
+
+- **Order of checks**: `findSessionOrFail` (ownership; a foreign session is a 404 in multi-user mode) → remote refused (400, before any path check, for the same reason as the edit route: `validateSessionFilePath` resolves against the LOCAL filesystem, so a same-named local folder would take the delete) → adopted refused (400) → a missing or repeated `path` (400) → a bounded probe of `workingDir`, and of the outside worktree root for an absolute path (#516; `422` on a mount that does not answer) → `validateLocalSessionFilePath(await withGuardedOutsideWorktree(...))` (realpath + boundary, an absolute path inside a followed outside worktree confined to it, the attachment guard re-read per request; any escape, a dangling link and a missing file are all 404) → sensitive / blocked trees / `.git` (403), each tested against BOTH the realpath and the path as named, so a `.git` reached through a linked folder and a linked `.git` are both caught → the link rule below → not a regular file (a folder: 400).
+- **A symbolic link is refused, never followed.** The confinement helper returns the REALPATH, which for a link is its target. #529 unlinked that path, so `DELETE ?path=AGENTS.md` with `AGENTS.md -> CLAUDE.md` deleted `CLAUDE.md` and left `AGENTS.md` dangling. The route therefore `lstat`s the path as the client named it (`resolve(workingDir, path)`, which keeps an absolute outside-worktree path as it is) and answers 400 for a link. The listing shows a link to a folder as a file row, so it gets a button, and the same 400 answers it. Deleting the link itself was the other option (confine the PARENT's realpath, unlink the link); it was not taken because refusing has no way to touch the target at all.
+- **The file checked is the file deleted.** A path whose last part is not a link has a realpath naming the same inode, so the route `lstat`s the realpath again and refuses with 409 if the inode, the device or the file type changed in between. `unlink` never follows a final symlink, so a link swapped in after that still removes only the link. A parent folder swapped for a link between the realpath and the `unlink` is the same check-then-use window every file route accepts (an agent running as the same user can delete the file anyway).
+- **Adopted and Docker.** An adopted session's folder is the neutral `/tmp`. The older file surfaces keep serving it as a standing exception (root `CLAUDE.md`, Adopted tmux sessions), which is not copied to a new surface, least of all one that deletes; the prompt-upload route refuses adopted sessions the same way. A Docker case workspace is bind-mounted at the same path and an `unlink` runs no hooks or filters (the reason git is kept away from those folders), so the route treats it like the edit route does: allowed.
+- **Frontend.** The button carries no inline handler: `encodeURIComponent` leaves `'` alone, so #529's `onclick="...decodeURIComponent('<path>')"` let a file named `x'-alert(1)-'.txt` run script in Codeman's origin, and `it's.txt` was a syntax error. It is bound in the existing `.file-tree-item` loops (`renderFileBrowserTree`, `_renderFileBrowserSearchResults`) from the row's escaped `data-path`, with `stopPropagation` so the row does not also open the preview. `deleteFileFromBrowser()` asks with `confirm()` (the panel's other destructive actions use the same native dialog, translated by i18n.js's wrapper) and reloads through `_reloadFileBrowserKeepingQuery()`, which re-runs a search in the box, so a row deleted from search results leaves them. The row buttons stay visible under `@media (hover: none)`, where the old hover-only rule meant the first tap opened the preview instead. `_fileBrowserCanDelete()` draws no button for a remote or an adopted session (`session.remote` is undefined on an adopted one, so `session.adopt` is tested too).
+
+Tests: `test/routes/file-delete-routes.test.ts` (unmocked fs again: the symlink defect only shows against a real link), `test/file-delete-ui.test.ts` (jsdom with `runScripts: 'dangerously'`, so the old inline handler would really run there, and the real `escapeHtml` from constants.js).
+
 ### File Viewer text view: rendered markdown and text toggles
 
 **Rendered markdown + Lines/Wrap** (`_renderFilePreviewText()` and its helpers in `panels-ui.js`, buttons in the `.file-preview-actions` row): a `.md`/`.markdown` opened in the File Viewer renders as a document by default, with an `MD` pill back to source; the plain-text view has `Lines` (a CSS-counter gutter) and `Wrap` toggles. Codeman already had `marked` + DOMPurify behind `_renderMarkdown()` for the Response Viewer, so the viewer reuses that and the codebase keeps ONE markdown pipeline.

docs/wiki/Working-With-Files.md

@@ -19,6 +19,13 @@ not finish shows **Not fully scanned** rather than looking empty. A folder that
 such as a network mount that went away, is skipped rather than waited on and is marked the same way,
 so a search can miss what is inside it. The panel's Refresh button tries it again.
 
+Each file row has a download arrow and a × that deletes the file after you confirm. Both show
+when you point at the row, and always on a touch screen. Delete removes one file at a time,
+never a folder, and refuses a symbolic link (deleting one from here would remove the file it
+points to), anything under `.git`, and the sensitive files the viewer will not serve. It is not
+offered for remote (SSH) sessions or for tmux sessions opened from outside Codeman. Deleting
+from search results takes the row out of the results.
+
 It renders what it can:
 
 | Kind                     | Behaviour                                                                 |

packages/desktop/Cargo.lock

@@ -37,12 +37,6 @@ version = "1.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
 
-[[package]]
-name = "base64"
-version = "0.22.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
-
 [[package]]
 name = "base64"
 version = "0.23.1"
@@ -161,9 +155,9 @@ checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
 name = "codeman-desktop"
 version = "0.1.0"
 dependencies = [
- "base64 0.22.1",
+ "base64",
  "block2",
- "dirs 6.0.0",
+ "dirs",
  "libc",
  "muda",
  "objc2",
@@ -353,15 +347,6 @@ dependencies = [
  "crypto-common",
 ]
 
-[[package]]
-name = "dirs"
-version = "6.0.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c3e8aa94d75141228480295a7d0e7feb620b1a5ad9f12bc40be62411e38cce4e"
-dependencies = [
- "dirs-sys",
-]
-
 [[package]]
 name = "dirs"
 version = "7.0.0"
@@ -2460,7 +2445,7 @@ version = "3.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cde93ff05758a36a851a398a772b0b79a82fbe3c186a46f2696baaeaf84c966b"
 dependencies = [
- "base64 0.23.1",
+ "base64",
  "flate2",
  "log",
  "percent-encoding",
@@ -2478,7 +2463,7 @@ version = "0.6.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "841583fc36089d7d59419568ae157f43a5a03a2e5a81ba87c77d1596ef46e922"
 dependencies = [
- "base64 0.23.1",
+ "base64",
  "http",
  "httparse",
  "log",
@@ -2981,11 +2966,11 @@ version = "0.57.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "759c50ddad0ef9913bb5496cb9d509a50433a3b78cb0238d61105526589cf0e9"
 dependencies = [
- "base64 0.23.1",
+ "base64",
  "block2",
  "cookie",
  "crossbeam-channel",
- "dirs 7.0.0",
+ "dirs",
  "dom_query",
  "dpi",
  "dunce",

packages/desktop/Cargo.toml

@@ -22,8 +22,10 @@ muda = "0.21"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 url = "2"
-base64 = "0.22"
-dirs = "6"
+# The versions ureq and wry already pull in, so neither crate is built twice
+# (ureq builds base64 without its default SIMD engines, and so do we).
+base64 = { version = "0.23", default-features = false, features = ["std"] }
+dirs = "7"
 # The reachability probe. platform-verifier = the OS trust store, the same one
 # WKWebView uses, so the probe and the window agree on which certificates pass.
 ureq = { version = "3", features = ["platform-verifier"] }

packages/desktop/README.md

@@ -9,7 +9,7 @@ macOS first: the app runs on 11.3 or later, and Codeman's own page needs the
 WebKit of Safari 16.4 (see Known limits). The same code is meant to build for
 Windows and Linux later.
 
-- **Size:** 4.6 MB for the universal `Codeman.app` (Apple Silicon + Intel), 3 MB as a `.dmg` (measured on the first build).
+- **Size:** 5.3 MB for the universal `Codeman.app` (Apple Silicon + Intel), 3.5 MB as a `.dmg` (measured 2026-11-09).
 - **Stack:** Rust with [tao](https://crates.io/crates/tao) (window and event loop),
   [wry](https://crates.io/crates/wry) (the system web view: WKWebView on macOS) and
   [muda](https://crates.io/crates/muda) (native menus), plus [objc2](https://crates.io/crates/objc2)
@@ -24,7 +24,7 @@ operating system's own web view. An Electron build of the same thing would ship
 a whole Chromium (around 150 MB). The native side only adds what a browser tab
 cannot do.
 
-## What it does (v0.1)
+## What it does
 
 | | |
 | --- | --- |
@@ -109,8 +109,9 @@ classes of wry's own delegates, so wry stays an unmodified crates.io dependency.
   base path, checked after decoding the path once, and which ones depends on
   who asks. `window.CodemanHost` (the app shell only) may open sessions,
   rendered HTML views, the raw, preview, attachment and folder file routes, the
-  path picker's preview and `api/download`. A `window.open` or `target=_blank` link, which WebKit passes
-  on from any frame without saying which, gets only the file routes and
+  path picker's preview and `api/download`. A `window.open` or `target=_blank`
+  link, which WebKit passes on from any frame without saying which, gets only
+  the file routes and
   `api/download`, the pages Codeman itself opens that way; otherwise a rendered
   HTML file could open copies of itself as top-level windows that pass for the
   app's own. Such a window does not take keyboard focus, and these windows
@@ -218,11 +219,12 @@ Codeman counts a request without valid credentials against its login rate
 limit (10 per IP, 15 minutes; a successful login resets the count), so the app
 never retries in a loop. A look at this Mac asks each Codeman server found
 here once; the app has a login only for the one at the usual address, so the
-others are asked without one. Once the server refuses the login in a challenge, the
-app sends it only once more, in the single probe that checks the refusal. If
-that probe is refused or rate limited, the connect screen comes back; the
-app does not send the refused login again. Keeping no copy of the login in WebKit has a cost here: after a server
-restart, each request that arrives without a cookie gets a 401 before the
+others are asked without one. Once the server refuses the login in a challenge,
+the app sends it only once more, in the single probe that checks the refusal.
+If that probe is refused or rate limited, the connect screen comes back; the
+app does not send the refused login again. Keeping no copy of the login in
+WebKit has a cost here: after a server restart, each request that arrives
+without a cookie gets a 401 before the
 login goes out, and those count until one succeeds. Many windows reconnecting
 at once can push a request past 10, and that request then fails with a 429
 instead of being answered. A refusal that lands while you are in another app
@@ -305,15 +307,15 @@ crosses, so the login is never on a command line.
   answers at the usual address). A password-protected one counts the
   look as a failed login, like any look at a server the app has no login for.
   *Check again* asks again.
-
 - **The logo blink rests on a private macOS interface.** Apple documents the
   setting, not the way the app reaches it, so a macOS update can take it away;
   the menu then disappears. Every change of the logo writes `LEBacklightMode`,
   from about once every two seconds (*Slow*, *Wink*) to about three times a
   second (*Fast*), which `corebrightnessd` keeps in root's preferences. The
-  setting is on or off, so these styles are rhythms of hard changes. After a blink
-  the key stays there rather than being absent as on a fresh Mac. That reads the same to macOS; `sudo defaults delete
-  com.apple.CoreBrightness LEBacklightMode` removes it. After a power cut in a
+  setting is on or off, so these styles are rhythms of hard changes. After a
+  blink the key stays there rather than being absent as on a fresh Mac. That
+  reads the same to macOS; `sudo defaults delete com.apple.CoreBrightness
+  LEBacklightMode` removes it. After a power cut in a
   dark phase the logo stays dark until the app next starts. `api/sessions` does
   not say which turns are Codeman's own, so with prompt-cache keep-warm on, a
   keep-alive turn blinks too.
@@ -335,16 +337,16 @@ crosses, so the login is never on a command line.
   `SIGN_IDENTITY` (a self-made code-signing certificate from Keychain Access
   is enough). Microphone and camera permissions are asked again for the same
   reason.
-- **Gatekeeper.** Without a Developer ID the app is signed ad hoc. A build you
-  made yourself opens normally; a copy that arrived by download or AirDrop is
+- **Gatekeeper, for a build of your own.** The `Codeman.dmg` on each GitHub
+  release is signed with a Developer ID and notarized by CI
+  (`.github/workflows/desktop-dmg.yml`), so it opens like any downloaded app.
+  A build without a Developer ID is signed ad hoc: it opens normally on the Mac
+  that built it, while a copy that arrived by download or AirDrop is
   quarantined. On macOS 15 and later, try to open it once, then click *Open
   Anyway* in System Settings > Privacy & Security (it asks for an administrator
   password). On macOS 14 and earlier, right-click it and choose *Open* once.
   Either way, `xattr -dr com.apple.quarantine /Applications/Codeman.app` on the
-  copy in Applications works too. The `Codeman.dmg` on each GitHub release is
-  signed with a Developer ID and notarized by CI
-  (`.github/workflows/desktop-dmg.yml`), so it skips all of this. To do the
-  same by hand:
+  copy in Applications works too. To sign and notarize by hand:
   `SIGN_IDENTITY="Developer ID Application: ..." NOTARY_PROFILE=<profile> ./scripts/bundle-macos.sh --universal --notarize`,
   where `scripts/sign-macos.sh` lists what it needs.
 - **Local Network permission (macOS 15 and later).** The first connection to an

packages/desktop/assets/connect.html

@@ -53,7 +53,7 @@
     padding: 20px; box-shadow: 0 20px 60px rgba(0,0,0,0.45);
   }
   label.field { display: block; font-size: 12px; color: var(--muted); margin: 0 0 6px; }
-  input[type=text], input[type=password], input[type=url] {
+  input[type=text], input[type=password] {
     width: 100%; height: 38px; padding: 0 12px; border-radius: 9px;
     border: 1px solid var(--line-strong); background: #0c0d10; color: var(--text);
     font: inherit; outline: none; -webkit-user-select: text; user-select: text;
@@ -61,7 +61,6 @@
   input:focus { border-color: var(--accent-2); box-shadow: 0 0 0 3px rgba(59,130,246,0.25); }
   .row { display: flex; gap: 10px; }
   .row > * { flex: 1; }
-  .gap { height: 14px; }
   #recent { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 10px; }
   #recent:empty { display: none; }
   .chip {
@@ -128,7 +127,7 @@
   /* The Codeman servers found on this Mac: a row each, in the look of a choice
      in the install, with the row's own Connect button. */
   #local-found-note { margin: 8px 0 0; }
-  #local-also { margin-top: 16px; padding-top: 14px; border-top: 1px solid var(--line); }
+  #local-also, #elsewhere { margin-top: 16px; padding-top: 14px; border-top: 1px solid var(--line); }
   #local-also-head { color: var(--muted); font-size: 12px; margin: 0 0 6px; }
   .found {
     display: flex; gap: 10px; align-items: center; padding: 9px 11px; border-radius: 9px;
@@ -139,7 +138,6 @@
   .found b { display: block; font-weight: 600; }
   .found small { display: block; margin-top: 1px; color: var(--muted); font-size: 12px; }
   .found button { flex: none; }
-  #elsewhere { margin-top: 16px; padding-top: 14px; border-top: 1px solid var(--line); }
   #elsewhere[hidden] { display: none; }
   #elsewhere summary { color: var(--muted); font-size: 13px; cursor: default; list-style: none; }
   #elsewhere summary::-webkit-details-marker { display: none; }
@@ -231,7 +229,6 @@
     border: 1px solid var(--line); color: #aab1bb; font: 11px/1.45 ui-monospace, SFMono-Regular, Menlo, monospace;
     white-space: pre-wrap; overflow-wrap: anywhere; -webkit-user-select: text; user-select: text;
   }
-  #wizard .actions .wiz-busy { display: inline-flex; align-items: center; gap: 8px; color: var(--muted); font-size: 13px; }
   footer { margin-top: 18px; text-align: center; color: var(--muted); font-size: 12px; }
   footer a { color: #aab1bb; text-decoration: none; cursor: default; }
   footer a:hover { color: var(--accent); }
@@ -416,9 +413,11 @@
   // suggestion: the address the suggest button connects to.
   // tab: 'local' (This Mac) or 'remote' (Another machine). askedFrom: the tab
   // the connect under way was asked from, where its answer belongs. local: the
-  // last This Mac status from the app. wait: set while an install runs in
-  // Terminal and this page polls for the server it brings up. gui: the
-  // graphical install while its screens are up (newWizard), null otherwise.
+  // last This Mac status from the app. wait: set while this page polls for the
+  // server an install brings up (one in Terminal, or a graphical one that
+  // finished; newWait). gui: the graphical install or the agent chooser while
+  // its screens are up (newWizard), null otherwise. clock: the timer of the
+  // running phase's clock.
   // reopen: a connect to this Mac was refused, so open it if it turns out to
   // be starting. startingLooks: how often the page has looked again at a
   // starting server. askedFound: the connect under way was asked from the row
@@ -427,7 +426,7 @@
     servers: [], busy: false, lastUrl: '', startUrl: '', suggestion: '',
     tab: 'local', askedFrom: 'local', askedFound: false, local: null, localChecking: false, opening: false,
     wait: null, waitTimer: 0, stoppedWaiting: false, gui: null, wantAgents: false,
-    reopen: false, startingLooks: 0, startingTimer: 0
+    reopen: false, startingLooks: 0, startingTimer: 0, clock: 0
   };
   // While an install runs: how often to look, how long a finished install may
   // take to answer before Start is offered, and when to stop looking.
@@ -511,14 +510,15 @@
     els.suggest.hidden = true;
   }
 
-  function host(url) {
+  function displayAddress(url) {
     try { var u = new URL(url); return u.host + (u.pathname === '/' ? '' : u.pathname.replace(/\/$/, '')); } catch (e) { return url; }
   }
 
   // The address as the app normalizes it (policy::normalize_server_url):
   // http:// by default, https:// for a .ts.net name without a port, no query
-  // or fragment, a trailing slash. Only used to tell whether two addresses
-  // are one server.
+  // or fragment, a trailing slash. Used to tell whether two addresses are one
+  // server, and which scheme and host a typed address ends up with
+  // (isLocalUrl, the http:// warning).
   function normalize(raw) {
     var s = String(raw || '').trim();
     if (!s) return '';
@@ -553,7 +553,7 @@
       chip.className = 'chip';
       var pick = document.createElement('button');
       pick.type = 'button';
-      pick.textContent = host(s.url) + (s.username ? '  (' + s.username + ')' : '');
+      pick.textContent = displayAddress(s.url) + (s.username ? '  (' + s.username + ')' : '');
       pick.title = 'Connect to ' + s.url;
       pick.addEventListener('click', function () {
         if (state.busy) return;
@@ -565,7 +565,7 @@
       x.className = 'x';
       x.textContent = '×';
       x.title = 'Forget this server' + (s.hasSavedPassword ? ' and its saved password' : '');
-      x.setAttribute('aria-label', 'Forget ' + host(s.url));
+      x.setAttribute('aria-label', 'Forget ' + displayAddress(s.url));
       x.addEventListener('click', function () { if (!state.busy) post({ cmd: 'forget', url: s.url }); });
       chip.appendChild(pick);
       chip.appendChild(x);
@@ -782,8 +782,11 @@
     return (s.found || []).filter(function (f) { return f && f.url !== s.url; });
   }
 
-  function canConnect(f) {
-    return f.state === 'running' || f.state === 'needsLogin';
+  // Codeman answers there, with or without a login, so the app can connect
+  // to it. Read the same way for a found server's row and for the This Mac
+  // status.
+  function answers(s) {
+    return s.state === 'running' || s.state === 'needsLogin';
   }
 
   // What a found server's row says under its address: its version, or why the
@@ -815,7 +818,7 @@
         text.appendChild(small);
       }
       row.appendChild(text);
-      if (canConnect(f)) {
+      if (answers(f)) {
         var button = document.createElement('button');
         button.type = 'button';
         button.className = primary ? 'primary' : 'secondary';
@@ -848,7 +851,7 @@
     } else if (!s) {
       dot = 'busy';
       title = 'Looking for Codeman on this Mac…';
-    } else if (s.installRunning && s.state !== 'running' && s.state !== 'needsLogin') {
+    } else if (s.installRunning && !answers(s)) {
       dot = 'busy';
       title = 'Codeman is being installed in Terminal.';
       detail = 'Finish the installer there, then Check again.';
@@ -861,7 +864,7 @@
     } else if (s.state === 'runningElsewhere') {
       // Not at the address the app opens by default: each one gets a row.
       main = (s.found || []).filter(Boolean);
-      dot = main.some(canConnect) ? 'ok' : 'warn';
+      dot = main.some(answers) ? 'ok' : 'warn';
       title = 'Codeman is already running on this Mac.';
       // No row: the app found the server's process, but no address to try.
       if (!main.length) {
@@ -869,16 +872,12 @@
           'Starting another server here would take over its sessions.';
       }
       show.check = true;
-    } else if (s.state === 'running') {
+    } else if (answers(s)) {
       dot = 'ok';
       title = 'Codeman is running on this Mac.';
-      detail = s.url + (s.version ? '  ·  version ' + s.version : '');
-      show.open = true;
-      also = otherServers(s);
-    } else if (s.state === 'needsLogin') {
-      dot = 'ok';
-      title = 'Codeman is running on this Mac.';
-      detail = s.url + ' asks for a login: Open asks for the password.';
+      detail = s.state === 'needsLogin'
+        ? s.url + ' asks for a login: Open asks for the password.'
+        : s.url + (s.version ? '  ·  version ' + s.version : '');
       show.open = true;
       also = otherServers(s);
     } else if (s.state === 'stopped') {
@@ -915,7 +914,7 @@
       if (o.kind === 'notCodeman') {
         title = 'Something else answers at ' + s.url;
         detail = 'It is not Codeman (HTTP ' + o.status + '). Stop what runs on that port, or connect to ' +
-          (also.some(canConnect) ? 'the Codeman listed below.' : 'Codeman’s real address under Another machine.');
+          (also.some(answers) ? 'the Codeman listed below.' : 'Codeman’s real address under Another machine.');
       } else {
         var e = explain[o.kind];
         title = e ? e[1] : 'Could not reach Codeman on this Mac.';
@@ -959,8 +958,8 @@
     }
     // An install from this app is still running (this page was shown again
     // while it ran): wait for it, unless the user stopped waiting.
-    if (!state.wait && s && s.installRunning && !s.installInApp && !state.stoppedWaiting && s.state !== 'running' && s.state !== 'needsLogin') {
-      state.wait = { since: Date.now(), finishedAt: 0, port: s.installPort || 3000 };
+    if (!state.wait && s && s.installRunning && !s.installInApp && !state.stoppedWaiting && !answers(s)) {
+      state.wait = newWait(s.installPort || 3000);
       renderLocal();
       scheduleWait();
     }
@@ -989,7 +988,7 @@
       }
       return false;
     }
-    var up = !!s && (s.state === 'running' || s.state === 'needsLogin');
+    var up = !!s && answers(s);
     var open = up && state.reopen && state.startingLooks > 0 && state.tab === 'local' && !state.busy;
     state.startingLooks = 0;
     state.reopen = false;
@@ -1041,10 +1040,15 @@
     var network = !!state.gui && state.gui.reach === 'network';
     closeWizard();
     selectTab('local');
+    openTerminal({ cmd: 'installLocal', network: network });
+  }
+
+  // Both Terminal installs: no second one while Terminal opens.
+  function openTerminal(msg) {
     state.opening = true;
     syncLocalButtons();
     setStatus('busy', 'Opening Terminal…');
-    post({ cmd: 'installLocal', network: network });
+    post(msg);
   }
 
   // mode 'install': Codeman itself. mode 'agent': one coding agent for a Mac
@@ -1056,17 +1060,22 @@
     };
   }
 
+  // The first screen of the graphical install ('install') or of adding an
+  // agent ('agent'), which asks the installer for its plan.
+  function prepareWizard(mode) {
+    state.gui = newWizard('preparing', mode);
+    post({ cmd: mode === 'agent' ? 'agentPrepare' : 'installPrepare' });
+  }
+
   function openWizard() {
     if (state.busy || tooOld || state.opening) return;
-    state.gui = newWizard('preparing');
-    post({ cmd: 'installPrepare' });
+    prepareWizard('install');
     renderWizard();
   }
 
   function openAgentChooser() {
     if (state.busy || tooOld || state.opening) return;
-    state.gui = newWizard('preparing', 'agent');
-    post({ cmd: 'agentPrepare' });
+    prepareWizard('agent');
     renderWizard();
   }
 
@@ -1086,14 +1095,14 @@
     renderLocal();
   }
 
+  // Try again keeps what was chosen.
   function retryWizard() {
-    var reach = state.gui ? state.gui.reach : 'local';
-    var agent = state.gui ? state.gui.agent : '';
-    var mode = state.gui ? state.gui.mode : 'install';
-    state.gui = newWizard('preparing', mode);
-    state.gui.reach = reach;
-    state.gui.agent = agent;
-    post({ cmd: mode === 'agent' ? 'agentPrepare' : 'installPrepare' });
+    var old = state.gui;
+    prepareWizard(old ? old.mode : 'install');
+    if (old) {
+      state.gui.reach = old.reach;
+      state.gui.agent = old.agent;
+    }
     renderWizard();
   }
 
@@ -1111,6 +1120,12 @@
     return offeredAgents().filter(function (c) { return c.id === id; })[0] || null;
   }
 
+  // This Mac has no coding agent and the installer offers one, so an install
+  // asks which one.
+  function needsAgent() {
+    return !installedAgents().length && offeredAgents().length > 0;
+  }
+
   // A run this page did not start has no plan, so no name for the agent.
   function agentName() {
     var c = agentById(state.gui.agent);
@@ -1129,7 +1144,7 @@
       g.step = 'agent';
     } else if (plan.blocker) {
       g.step = 'blocked';
-    } else if (!installedAgents().length && offeredAgents().length) {
+    } else if (needsAgent()) {
       // Kept across Try again; otherwise the first of the catalogue's order.
       if (!agentById(g.agent)) g.agent = offeredAgents()[0].id;
       g.step = 'agent';
@@ -1229,7 +1244,7 @@
     PHASES.forEach(function (id) {
       var label = {
         runtime: 'Getting Node.js and tmux',
-        agent: 'Installing ' + (chosen ? chosen.label : 'a coding agent'),
+        agent: 'Installing ' + agentName(),
         source: 'Downloading Codeman',
         packages: 'Installing packages',
         build: 'Building Codeman',
@@ -1313,21 +1328,14 @@
     if (!g) return;
     appendLog(msg.log);
     clearInterval(state.clock);
-    if (msg.ok && g.mode === 'agent') {
-      g.ok = true;
-      g.step = 'added';
-      renderWizard();
-      // Whether there is a Codeman to open from here.
-      checkLocal('quick');
-      return;
-    }
     if (msg.ok) {
       g.ok = true;
-      g.step = 'finishing';
+      g.step = g.mode === 'agent' ? 'added' : 'finishing';
       renderWizard();
-      // The same watch as a Terminal install: it opens Codeman at the first
-      // answer, and offers Start when none comes.
-      state.wait = { since: Date.now(), finishedAt: 0, port: g.port };
+      // An install gets the same watch as a Terminal install: it opens Codeman
+      // at the first answer, and offers Start when none comes. An added agent
+      // only asks whether there is a Codeman to open from here.
+      if (g.mode !== 'agent') state.wait = newWait(g.port);
       checkLocal('quick');
       return;
     }
@@ -1346,7 +1354,8 @@
     renderLog();
   }
 
-  // Each screen of the graphical install, drawn from state.gui alone.
+  // Each screen of the graphical install and of adding an agent, drawn from
+  // state.gui (and state.local for Open Codeman).
   function renderWizard() {
     var g = state.gui;
     els.card.classList.toggle('wizard-on', !!g);
@@ -1418,10 +1427,6 @@
     else els.wizTitle.focus();
   }
 
-  function localAnswers() {
-    return !!state.local && (state.local.state === 'running' || state.local.state === 'needsLogin');
-  }
-
   function renderWizardButtons() {
     var g = state.gui;
     var step = g.step;
@@ -1430,7 +1435,7 @@
     var next = {
       agent: agentMode ? (chosen ? 'Install ' + chosen.label : '') : 'Continue',
       reach: 'Install Codeman', failed: 'Try again', prepareFailed: 'Try again', blocked: 'Install in Terminal',
-      ready: 'Open Codeman', added: localAnswers() ? 'Open Codeman' : ''
+      ready: 'Open Codeman', added: state.local && answers(state.local) ? 'Open Codeman' : ''
     }[step];
     els.wizNext.hidden = !next;
     els.wizNext.textContent = next || '';
@@ -1478,7 +1483,7 @@
     els.wizPw.value = '';
     els.wizPw2.value = '';
     // Skipped: the first thing to say once Codeman answers.
-    g.noAgent = !installedAgents().length && !msg.aiCli && offeredAgents().length > 0;
+    g.noAgent = needsAgent() && !msg.aiCli;
     beginRun();
     post(msg);
   }
@@ -1524,7 +1529,7 @@
   function wizardBack() {
     var g = state.gui;
     if (!g) return;
-    if (g.step === 'reach' && !installedAgents().length && offeredAgents().length && !g.plan.blocker) {
+    if (g.step === 'reach' && needsAgent() && !g.plan.blocker) {
       g.step = 'agent';
       renderWizard();
     } else {
@@ -1532,6 +1537,12 @@
     }
   }
 
+  // A wait for the server an install brings up, on `port` until the
+  // installer says otherwise.
+  function newWait(port) {
+    return { since: Date.now(), finishedAt: 0, port: port };
+  }
+
   function scheduleWait() {
     clearTimeout(state.waitTimer);
     state.waitTimer = setTimeout(function () { if (state.wait) checkLocal('quick'); }, WAIT_POLL_MS);
@@ -1560,7 +1571,7 @@
     // Until the installer writes its LaunchAgent, the app looks at port 3000,
     // where something else may answer when the install took another port.
     var ours = portOf(s.url) === w.port;
-    if (ours && (s.state === 'running' || s.state === 'needsLogin')) {
+    if (ours && answers(s)) {
       var g = state.gui;
       if (g && g.step === 'finishing' && g.noAgent) {
         clearTimeout(state.waitTimer);
@@ -1608,10 +1619,7 @@
       els.ssh.focus();
       return;
     }
-    state.opening = true;
-    syncLocalButtons();
-    setStatus('busy', 'Opening Terminal…');
-    post({ cmd: 'installRemote', target: target });
+    openTerminal({ cmd: 'installRemote', target: target });
   }
 
   window.__codemanDesktop = {
@@ -1690,7 +1698,7 @@
         case 'installStarted':
           state.opening = false;
           setStatus('', '');
-          state.wait = { since: Date.now(), finishedAt: 0, port: Number(msg.port) || 3000 };
+          state.wait = newWait(Number(msg.port) || 3000);
           selectTab('local');
           renderLocal();
           scheduleWait();

packages/desktop/src/agents.rs

@@ -115,19 +115,22 @@ fn session_cookie(header: &str) -> Option<&str> {
     (name == COOKIE_NAME && !value.is_empty()).then_some(pair)
 }
 
+/// A refused login: Codeman counts each against the login rate limit, so the
+/// polling ends.
+fn refused(status: u16) -> bool {
+    matches!(status, 401 | 403 | 429)
+}
+
 /// What a status code says about asking again.
-fn answer(status: u16, body: impl FnOnce() -> Option<String>) -> Poll {
+fn answer(status: u16, body: Option<&str>) -> Poll {
     match status {
-        200 => body()
-            .as_deref()
-            .and_then(count_working)
-            .map_or(Poll::Failed, |working| {
-                Poll::Seen(Activity {
-                    working: working > 0,
-                    ..Activity::default()
-                })
-            }),
-        401 | 403 | 429 => Poll::Refused,
+        200 => body.and_then(count_working).map_or(Poll::Failed, |working| {
+            Poll::Seen(Activity {
+                working: working > 0,
+                ..Activity::default()
+            })
+        }),
+        s if refused(s) => Poll::Refused,
         _ => Poll::Failed,
     }
 }
@@ -192,7 +195,7 @@ impl Poller {
         let Some((status, body)) = self.ask(&url) else {
             return Poll::Failed;
         };
-        let mut activity = match answer(status, || body) {
+        let mut activity = match answer(status, body.as_deref()) {
             Poll::Seen(activity) => activity,
             other => return other,
         };
@@ -203,7 +206,7 @@ impl Poller {
                         self.alerts = alerts;
                     }
                 }
-                Some((401 | 403 | 429, _)) => return Poll::Refused,
+                Some((s, _)) if refused(s) => return Poll::Refused,
                 // A server from before the list has no alerts to report.
                 Some((404, _)) => self.alerts = (false, false),
                 _ => {}
@@ -264,17 +267,17 @@ mod tests {
     fn a_body_that_is_not_the_list_is_no_answer() {
         assert_eq!(count_working("<html>"), None);
         assert_eq!(count_working(r#"{"success":false,"error":"nope"}"#), None);
-        assert_eq!(answer(200, || Some("<html>".into())), Poll::Failed);
-        assert_eq!(answer(200, || None), Poll::Failed);
+        assert_eq!(answer(200, Some("<html>")), Poll::Failed);
+        assert_eq!(answer(200, None), Poll::Failed);
     }
 
     #[test]
     fn only_a_login_refusal_ends_the_polling() {
         for status in [401, 403, 429] {
-            assert_eq!(answer(status, || None), Poll::Refused, "{status}");
+            assert_eq!(answer(status, None), Poll::Refused, "{status}");
         }
         for status in [301, 404, 500, 502, 503] {
-            assert_eq!(answer(status, || None), Poll::Failed, "{status}");
+            assert_eq!(answer(status, None), Poll::Failed, "{status}");
         }
     }
 

packages/desktop/src/config.rs

@@ -13,8 +13,8 @@ const MAX_SERVERS: usize = 8;
 /// How many recovery copies of an unreadable config can sit side by side:
 /// `desktop.json.corrupt`, then `desktop.json.corrupt.1` to `.9`.
 const ASIDE_SLOTS: usize = 10;
-const MIN_WIDTH: f64 = 480.0;
-const MIN_HEIGHT: f64 = 360.0;
+pub const MIN_WIDTH: f64 = 480.0;
+pub const MIN_HEIGHT: f64 = 360.0;
 const MAX_EDGE: f64 = 20_000.0;
 
 /// Height of a standard title bar, in points.

packages/desktop/src/credentials.rs

@@ -88,9 +88,7 @@ impl Keychain {
             password: password.to_owned(),
             reply,
         };
-        if self.jobs.send(job).is_err() {
-            return Err(WORKER_GONE.into());
-        }
+        self.jobs.send(job).map_err(|_| WORKER_GONE.to_string())?;
         answer.recv().unwrap_or_else(|_| Err(WORKER_GONE.into()))
     }
 

packages/desktop/src/gui_install.rs

@@ -6,8 +6,8 @@
 //! tmux in the home folder, so nothing in it asks for a password, and the two
 //! questions only a person can answer (which coding agent, who may reach
 //! Codeman) are asked by the page and passed as flags. The Terminal route in
-//! `setup.rs` stays for what this one cannot do, a Mac older than macOS 15 with
-//! no tmux first of all.
+//! `terminal_install.rs` stays for what this one cannot do, a Mac older than
+//! macOS 15 with no tmux first of all.
 //!
 //! `prepare` downloads the installer once into a private folder and asks it
 //! what is on this Mac (`install.sh preflight`); `start` runs the same file with
@@ -100,8 +100,8 @@ impl Run {
     /// not one: it has no `--progress`.
     pub fn matches(self, command: &str) -> bool {
         let suffix = format!("/{}/{SCRIPT_FILE}", self.folder());
-        let mut words = command.split_whitespace();
-        words.any(|w| w.ends_with(&suffix)) && command.split_whitespace().any(|w| w == "--progress")
+        command.split_whitespace().any(|w| w.ends_with(&suffix))
+            && command.split_whitespace().any(|w| w == "--progress")
     }
 
     /// A process of this run, if it is running.
@@ -269,11 +269,12 @@ fn download_installer(script: &Path) -> Result<(), String> {
     if out.code == Some(0) && script.is_file() {
         return Ok(());
     }
+    const FAILED: &str = "Could not download the installer. Check the internet connection, then try again.";
     let said = out.stderr.trim();
     Err(if said.is_empty() {
-        "Could not download the installer. Check the internet connection, then try again.".to_string()
+        FAILED.to_string()
     } else {
-        format!("Could not download the installer. Check the internet connection, then try again.\n{said}")
+        format!("{FAILED}\n{said}")
     })
 }
 
@@ -571,9 +572,8 @@ pub fn follow(run: Run, stale: impl Fn() -> bool, send: impl Fn(Value)) {
             return;
         }
         let running = run.process().is_some();
-        let log = progress.feed(&read_more(&mut file, &path, &mut offset));
+        let mut log = progress.feed(&read_more(&mut file, &path, &mut offset));
         if !running || progress.done {
-            let mut log = log;
             log.extend(progress.finish());
             let cancelled = CANCELLED.load(Ordering::SeqCst);
             if progress.done {

packages/desktop/src/local_server.rs

@@ -1,4 +1,7 @@
 //! "Start Codeman on this Mac": `codeman web -d` through the user's login shell.
+//! The same login-shell machinery answers whether Codeman is installed
+//! (`installed`) and hands its environment to the graphical install
+//! (`login_environment`); `exec_bounded` is the crate's bounded process runner.
 //!
 //! A double-clicked app gets launchd's bare PATH (`/usr/bin:/bin:...`), which
 //! finds neither `codeman` nor `node`, and the server inherits whatever
@@ -143,7 +146,8 @@ fn pump<R: Read + Send + 'static>(pipe: Option<R>, stream: usize, tx: mpsc::Send
     });
 }
 
-/// `exec_bounded` for a start.
+/// `exec_bounded` with the start's timeout message. The installed check and
+/// `login_environment` run through it too, and drop its error.
 fn exec(cmd: Command, deadline: Instant) -> Result<Output, String> {
     exec_bounded(
         cmd,
@@ -248,13 +252,16 @@ fn parse_env(output: &str) -> Option<Vec<(String, String)>> {
     None
 }
 
+/// A portable variable name: a letter or `_`, then letters, digits or `_`.
+pub fn is_env_name(name: &str) -> bool {
+    let mut chars = name.chars();
+    chars.next().is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
+        && chars.all(|c| c.is_ascii_alphanumeric() || c == '_')
+}
+
 fn env_entry(line: &str) -> Option<(&str, &str)> {
     let (name, value) = line.split_once('=')?;
-    let mut chars = name.chars();
-    let first = chars.next()?;
-    let portable =
-        (first.is_ascii_alphabetic() || first == '_') && chars.all(|c| c.is_ascii_alphanumeric() || c == '_');
-    portable.then_some((name, value))
+    is_env_name(name).then_some((name, value))
 }
 
 /// Ask `shell` for its environment with `flags`. The outer error ends the
@@ -339,16 +346,13 @@ fn run_in_shell(
 /// 127 means "no codeman here" and moves on to the next way of asking; the
 /// interactive profile is asked only when `interactive` allows it.
 fn launch(script: &str, shell: &Path, args: &[String], deadline: Instant, interactive: bool) -> Result<Run, String> {
-    let attempts = match flavor(shell) {
-        Flavor::Posix => {
-            let result = run_in_shell(script, shell, false, args, deadline)?;
-            if result.code != Some(127) || !interactive {
-                return Ok(result);
-            }
-            // Not on the login PATH; try the interactive profile too.
-            return run_in_shell(script, shell, true, args, deadline);
+    let Flavor::Capture(attempts) = flavor(shell) else {
+        let result = run_in_shell(script, shell, false, args, deadline)?;
+        if result.code != Some(127) || !interactive {
+            return Ok(result);
         }
-        Flavor::Capture(attempts) => attempts,
+        // Not on the login PATH; try the interactive profile too.
+        return run_in_shell(script, shell, true, args, deadline);
     };
     let mut last_run = None;
     let mut capture_error = None;
@@ -386,8 +390,8 @@ const FIND_SCRIPT: &str = r#"if command -v codeman >/dev/null 2>&1; then exit 0;
 if [ -f "$HOME/.codeman/app/dist/index.js" ] && command -v node >/dev/null 2>&1; then exit 0; fi
 exit 127"#;
 
-/// How long the This Mac tab waits for the login shell to answer whether
-/// Codeman is installed.
+/// How long one look at the login shell may take: whether Codeman is
+/// installed (the This Mac tab), or its environment for the graphical install.
 const FIND_TIMEOUT: Duration = Duration::from_secs(15);
 
 /// `installed` with the shell given, so tests need not touch `$SHELL`.
@@ -453,7 +457,7 @@ mod tests {
             })
             .output
         };
-        // stdout that ended without a newline used to be glued to stderr.
+        // stdout that ends without a newline: stderr still starts a line of its own.
         assert_eq!(
             said("Starting Codeman", "Error: port 3000 is in use\n"),
             "Starting Codeman\nError: port 3000 is in use"

packages/desktop/src/login.rs

@@ -0,0 +1,256 @@
+//! The login a connect goes out with, and what the Keychain keeps once the
+//! server has answered it.
+
+use crate::credentials::{self, Keychain};
+use crate::probe::ProbeOutcome;
+
+/// The login a connect goes out with, and where its password came from. A
+/// typed password wins, then the one the Keychain holds for this user. Last
+/// comes the login of the Codeman on this Mac, which keeps it where its own
+/// clients find it (setup::local_login: its launchd job, then
+/// ~/.codeman/.env) and only answers it at its own loopback address. That one
+/// is used only when the config expected no password in the Keychain
+/// (`expect_saved`: one that should be there and is not is reported, not
+/// papered over), only for the username in use when there is one, and it is
+/// never saved anywhere. `local` is asked only then: it runs processes.
+pub fn choose_login(
+    user: Option<String>,
+    typed_password: Option<String>,
+    saved: Option<String>,
+    expect_saved: bool,
+    local: impl FnOnce() -> Option<(String, String)>,
+) -> (Option<String>, Option<String>, PasswordSource) {
+    if let Some(password) = typed_password {
+        return (user, Some(password), PasswordSource::Typed);
+    }
+    if let Some(password) = saved {
+        return (user, Some(password), PasswordSource::Keychain);
+    }
+    if !expect_saved {
+        if let Some((local_user, password)) = local() {
+            if user.as_deref().is_none_or(|current| current == local_user) {
+                return (Some(local_user), Some(password), PasswordSource::LocalServer);
+            }
+        }
+    }
+    (user, None, PasswordSource::Absent)
+}
+
+/// A login the probe just tried, and what the user asked for it.
+pub struct ProbedLogin<'a> {
+    /// The server, as the config and the Keychain accounts key it.
+    pub server: &'a str,
+    /// The username the config named for this server before the connect.
+    pub previous_user: Option<&'a str>,
+    pub username: Option<&'a str>,
+    pub password: Option<&'a str>,
+    /// Where the password came from.
+    pub source: PasswordSource,
+    pub remember: bool,
+}
+
+/// Where a connect's password came from, which decides what the Keychain
+/// does with it (update_keychain).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PasswordSource {
+    /// Typed on the connect page this time: saved if Remember is on.
+    Typed,
+    /// From the Keychain: there already.
+    Keychain,
+    /// The local Codeman's own login (setup::local_login): it stays where it
+    /// is, and the Keychain never gets a copy.
+    LocalServer,
+    /// No password.
+    Absent,
+}
+
+/// What update_keychain did: whether the Keychain now holds the login's
+/// password, and whose items it deleted.
+#[derive(Default)]
+pub struct KeychainUpdate {
+    pub saved: bool,
+    pub deleted: Vec<String>,
+}
+
+/// Bring the Keychain in line with a probe the server answered, on the probe
+/// worker. Only an accepted login changes anything (Ok, or a password the
+/// server wants changed), since only then does the config get the new entry.
+///
+/// When that entry names another user than the config did (compared exactly,
+/// as the account string is), the old user's item is deleted FIRST, before any
+/// save: the Keychain worker runs jobs in order, so a Keychain that treats two
+/// spellings of a name as one item cannot lose the new password to that
+/// delete. Then the typed password is saved when Remember is on and deleted
+/// when it is off, and a password the server wants changed is never kept.
+pub fn update_keychain(keychain: &Keychain, outcome: &ProbeOutcome, login: &ProbedLogin<'_>) -> KeychainUpdate {
+    let mut update = KeychainUpdate::default();
+    if !matches!(outcome, ProbeOutcome::Ok { .. } | ProbeOutcome::PasswordChangeRequired) {
+        return update;
+    }
+    let mut delete = |user: &str| {
+        keychain.delete(&credentials::account(login.server, user));
+        update.deleted.push(user.to_string());
+    };
+    if let Some(old) = login.previous_user.filter(|old| login.username != Some(*old)) {
+        delete(old);
+    }
+    let saved = match (outcome, login.username, login.password) {
+        (ProbeOutcome::Ok { .. }, Some(user), Some(password)) if login.source == PasswordSource::Typed => {
+            if login.remember {
+                keychain
+                    .save_blocking(&credentials::account(login.server, user), password)
+                    .is_ok()
+            } else {
+                delete(user);
+                false
+            }
+        }
+        // A password that came from the Keychain is saved there already.
+        (ProbeOutcome::Ok { .. }, Some(_), Some(_)) => login.source == PasswordSource::Keychain,
+        (ProbeOutcome::PasswordChangeRequired, Some(user), _) => {
+            delete(user);
+            false
+        }
+        _ => false,
+    };
+    update.saved = saved;
+    update
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::credentials::memory;
+
+    fn none() -> Option<(String, String)> {
+        panic!("the local login must not be looked up here");
+    }
+
+    #[test]
+    fn the_login_a_connect_uses() {
+        let s = |v: &str| Some(v.to_string());
+        let local = || Some(("admin".to_string(), "from-this-mac".to_string()));
+
+        // A typed password wins over everything, and nothing else is asked.
+        assert_eq!(
+            choose_login(s("kay"), s("typed"), s("kept"), true, none),
+            (s("kay"), s("typed"), PasswordSource::Typed)
+        );
+        // Then the Keychain's.
+        assert_eq!(
+            choose_login(s("kay"), None, s("kept"), true, none),
+            (s("kay"), s("kept"), PasswordSource::Keychain)
+        );
+        // The Keychain should hold one and does not: reported as absent, the
+        // local login is not tried in its place.
+        assert_eq!(
+            choose_login(s("kay"), None, None, true, none),
+            (s("kay"), None, PasswordSource::Absent)
+        );
+        // Nothing typed, nothing expected: the Codeman on this Mac's own
+        // login, for no username or the same one.
+        assert_eq!(
+            choose_login(None, None, None, false, local),
+            (s("admin"), s("from-this-mac"), PasswordSource::LocalServer)
+        );
+        assert_eq!(
+            choose_login(s("admin"), None, None, false, local),
+            (s("admin"), s("from-this-mac"), PasswordSource::LocalServer)
+        );
+        // Never for another user: the names are compared exactly.
+        assert_eq!(
+            choose_login(s("kay"), None, None, false, local),
+            (s("kay"), None, PasswordSource::Absent)
+        );
+        assert_eq!(
+            choose_login(s("Admin"), None, None, false, local),
+            (s("Admin"), None, PasswordSource::Absent)
+        );
+        // No local login either.
+        assert_eq!(
+            choose_login(None, None, None, false, || None),
+            (None, None, PasswordSource::Absent)
+        );
+    }
+
+    /// update_keychain for one probe answer; the log is what the Keychain did,
+    /// in order (the last load only waits for the queue to drain).
+    fn keychain_after(outcome: ProbeOutcome, login: ProbedLogin<'_>) -> (KeychainUpdate, Vec<String>) {
+        let (keychain, store) = memory::keychain();
+        let update = update_keychain(&keychain, &outcome, &login);
+        keychain.load_blocking("done");
+        let mut log = store.log();
+        assert_eq!(log.pop().as_deref(), Some("load done"));
+        (update, log)
+    }
+
+    fn login<'a>(
+        previous_user: Option<&'a str>,
+        username: Option<&'a str>,
+        source: PasswordSource,
+        remember: bool,
+    ) -> ProbedLogin<'a> {
+        ProbedLogin {
+            server: "http://a/",
+            previous_user,
+            username,
+            password: (source != PasswordSource::Absent).then_some("secret"),
+            source,
+            remember,
+        }
+    }
+
+    #[test]
+    fn what_the_keychain_keeps_after_a_connect() {
+        let ok = || ProbeOutcome::Ok {
+            version: "1.48.0".into(),
+        };
+        let item = |user: &str| credentials::account("http://a/", user);
+
+        // A typed password is saved when Remember is on, deleted when it is off.
+        let (update, log) = keychain_after(ok(), login(Some("kay"), Some("kay"), PasswordSource::Typed, true));
+        assert!(update.saved && update.deleted.is_empty());
+        assert_eq!(log, [format!("save {}", item("kay"))]);
+        let (update, log) = keychain_after(ok(), login(Some("kay"), Some("kay"), PasswordSource::Typed, false));
+        assert!(!update.saved);
+        assert_eq!(update.deleted, ["kay"]);
+        assert_eq!(log, [format!("delete {}", item("kay"))]);
+
+        // One that came from the Keychain is there already: nothing is written.
+        let (update, log) = keychain_after(ok(), login(Some("kay"), Some("kay"), PasswordSource::Keychain, true));
+        assert!(update.saved && log.is_empty());
+
+        // The local Codeman's own login never gets a copy, Remember or not.
+        let (update, log) = keychain_after(ok(), login(None, Some("admin"), PasswordSource::LocalServer, true));
+        assert!(!update.saved && update.deleted.is_empty() && log.is_empty());
+
+        // Another user than before: the old user's item goes FIRST, then the save.
+        let (update, log) = keychain_after(ok(), login(Some("old"), Some("new"), PasswordSource::Typed, true));
+        assert!(update.saved);
+        assert_eq!(update.deleted, ["old"]);
+        assert_eq!(
+            log,
+            [format!("delete {}", item("old")), format!("save {}", item("new"))]
+        );
+
+        // A password the server wants changed is never kept.
+        let (update, log) = keychain_after(
+            ProbeOutcome::PasswordChangeRequired,
+            login(Some("kay"), Some("kay"), PasswordSource::Typed, true),
+        );
+        assert!(!update.saved);
+        assert_eq!(update.deleted, ["kay"]);
+        assert_eq!(log, [format!("delete {}", item("kay"))]);
+
+        // A login the server did not accept changes nothing.
+        for refused in [
+            ProbeOutcome::BadCredentials,
+            ProbeOutcome::NeedsLogin,
+            ProbeOutcome::Refused,
+            ProbeOutcome::Timeout,
+        ] {
+            let (update, log) = keychain_after(refused, login(Some("old"), Some("new"), PasswordSource::Typed, true));
+            assert!(!update.saved && update.deleted.is_empty() && log.is_empty());
+        }
+    }
+}

packages/desktop/src/logo.rs

@@ -270,7 +270,7 @@ const SETTLE: Duration = Duration::from_secs(3);
 const LOOK_EVERY: Duration = Duration::from_millis(250);
 
 /// What a blink needs from the machine, so its decisions can be tested.
-pub trait Logo {
+trait Logo {
     /// The current mode, None if it could not be read.
     fn mode(&self) -> Option<i64>;
     /// Set the mode; false if the daemon did not take it.
@@ -281,7 +281,7 @@ pub trait Logo {
 }
 
 /// The file that says a blink may have left the logo dark.
-pub struct Marker(Option<PathBuf>);
+struct Marker(Option<PathBuf>);
 
 impl Marker {
     fn default_location() -> Self {
@@ -363,7 +363,7 @@ fn blink(logo: &impl Logo, marker: &Marker, pattern: &[Beat], mut wait: impl FnM
 }
 
 /// Put back a logo that a blink could not finish with.
-pub fn recover(logo: &impl Logo, marker: &Marker) {
+fn recover(logo: &impl Logo, marker: &Marker) {
     if !marker.is_set() {
         return;
     }
@@ -507,25 +507,24 @@ fn spawn_child(connection: Connection) -> Option<(Connection, ChildStdin)> {
     Some((connection, stdin))
 }
 
-#[cfg(target_os = "macos")]
 pub use system::{available, blink_main, recover_at_launch, switched_off};
 
+/// No lit logo to blink outside macOS.
 #[cfg(not(target_os = "macos"))]
-pub fn available() -> bool {
-    false
-}
+mod system {
+    pub fn available() -> bool {
+        false
+    }
 
-#[cfg(not(target_os = "macos"))]
-pub fn blink_main() -> ! {
-    std::process::exit(0)
-}
+    pub fn blink_main() -> ! {
+        std::process::exit(0)
+    }
 
-#[cfg(not(target_os = "macos"))]
-pub fn recover_at_launch() {}
+    pub fn recover_at_launch() {}
 
-#[cfg(not(target_os = "macos"))]
-pub fn switched_off() -> bool {
-    false
+    pub fn switched_off() -> bool {
+        false
+    }
 }
 
 #[cfg(target_os = "macos")]

packages/desktop/src/menu.rs

@@ -0,0 +1,161 @@
+//! The menu bar.
+
+use muda::accelerator::{Accelerator, Code, Modifiers};
+use muda::{AboutMetadata, CheckMenuItem, Menu, MenuItem, PredefinedMenuItem, Submenu};
+
+use crate::config::Config;
+use crate::logo::{self, BlinkStyle, Signal};
+use crate::{APP_NAME, VERSION};
+
+/// Codeman's repository and its documentation (the Help menu, About).
+pub const REPO_URL: &str = "https://github.com/Ark0N/Codeman";
+pub const DOCS_URL: &str = "https://github.com/Ark0N/Codeman/wiki";
+
+pub mod menu_id {
+    pub const SWITCH: &str = "switch-server";
+    pub const ADD_AGENT: &str = "add-agent";
+    pub const RELOAD: &str = "reload";
+    pub const START_FULLSCREEN: &str = "start-fullscreen";
+    pub const DEVTOOLS: &str = "devtools";
+    pub const HELP_DOCS: &str = "help-docs";
+    pub const HELP_GITHUB: &str = "help-github";
+}
+
+pub struct AppMenu {
+    pub bar: Menu,
+    pub window_menu: Submenu,
+    pub help_menu: Submenu,
+    pub start_fullscreen: CheckMenuItem,
+    /// One item per state and style. Empty on a Mac without a lit logo, which has no
+    /// such menu.
+    pub logo_styles: Vec<(Signal, BlinkStyle, CheckMenuItem)>,
+}
+
+pub fn build_menu(config: &Config) -> muda::Result<AppMenu> {
+    let bar = Menu::new();
+    let about = PredefinedMenuItem::about(
+        Some("About Codeman"),
+        Some(AboutMetadata {
+            name: Some(APP_NAME.into()),
+            version: Some(VERSION.into()),
+            comments: Some("A native window for your Codeman server.".into()),
+            website: Some(REPO_URL.into()),
+            ..Default::default()
+        }),
+    );
+    let switch = MenuItem::with_id(
+        menu_id::SWITCH,
+        "Switch Server\u{2026}",
+        true,
+        Some(Accelerator::new(Modifiers::META | Modifiers::SHIFT, Code::KeyO)),
+    );
+    let app_menu = Submenu::with_items(
+        APP_NAME,
+        true,
+        &[
+            &about,
+            &PredefinedMenuItem::separator(),
+            &switch,
+            &MenuItem::with_id(menu_id::ADD_AGENT, "Add a Coding Agent to This Mac\u{2026}", true, None),
+            &PredefinedMenuItem::separator(),
+            &PredefinedMenuItem::services(None),
+            &PredefinedMenuItem::separator(),
+            &PredefinedMenuItem::hide(None),
+            &PredefinedMenuItem::hide_others(None),
+            &PredefinedMenuItem::show_all(None),
+            &PredefinedMenuItem::separator(),
+            &PredefinedMenuItem::quit(None),
+        ],
+    )?;
+    // Without these items Cmd+C / Cmd+V do nothing inside a WKWebView.
+    let edit = Submenu::with_items(
+        "Edit",
+        true,
+        &[
+            &PredefinedMenuItem::undo(None),
+            &PredefinedMenuItem::redo(None),
+            &PredefinedMenuItem::separator(),
+            &PredefinedMenuItem::cut(None),
+            &PredefinedMenuItem::copy(None),
+            &PredefinedMenuItem::paste(None),
+            &PredefinedMenuItem::select_all(None),
+        ],
+    )?;
+    let start_fullscreen = CheckMenuItem::with_id(
+        menu_id::START_FULLSCREEN,
+        "Always Open in Full Screen",
+        true,
+        config.start_fullscreen,
+        None,
+    );
+    let view = Submenu::with_items(
+        "View",
+        true,
+        &[
+            &MenuItem::with_id(
+                menu_id::RELOAD,
+                "Reload",
+                true,
+                Some(Accelerator::new(Modifiers::META, Code::KeyR)),
+            ),
+            &PredefinedMenuItem::separator(),
+            &PredefinedMenuItem::fullscreen(None),
+            &start_fullscreen,
+            &PredefinedMenuItem::separator(),
+            &MenuItem::with_id(
+                menu_id::DEVTOOLS,
+                "Developer Tools",
+                true,
+                Some(Accelerator::new(Modifiers::META | Modifiers::ALT, Code::KeyI)),
+            ),
+        ],
+    )?;
+    // Only a Mac with a lit Apple logo has this menu at all.
+    let mut logo_styles = Vec::new();
+    if logo::available() {
+        let submenu = Submenu::new("Blink Apple Logo", true);
+        for signal in Signal::ALL {
+            let group = Submenu::new(signal.label(), true);
+            for style in BlinkStyle::ALL {
+                let chosen = style == config.logo_blink.get(signal);
+                let item = CheckMenuItem::with_id(style.menu_id(signal), style.label(), true, chosen, None);
+                group.append(&item)?;
+                if style == BlinkStyle::Off {
+                    group.append(&PredefinedMenuItem::separator())?;
+                }
+                logo_styles.push((signal, style, item));
+            }
+            submenu.append(&group)?;
+        }
+        // Right under "Always Open in Full Screen", before the separator.
+        view.insert(&submenu, 4)?;
+    }
+    let window_menu = Submenu::with_items(
+        "Window",
+        true,
+        &[
+            &PredefinedMenuItem::minimize(None),
+            &PredefinedMenuItem::maximize(None),
+            &PredefinedMenuItem::separator(),
+            &PredefinedMenuItem::close_window(None),
+            &PredefinedMenuItem::separator(),
+            &PredefinedMenuItem::bring_all_to_front(None),
+        ],
+    )?;
+    let help_menu = Submenu::with_items(
+        "Help",
+        true,
+        &[
+            &MenuItem::with_id(menu_id::HELP_DOCS, "Codeman Documentation", true, None),
+            &MenuItem::with_id(menu_id::HELP_GITHUB, "Codeman on GitHub", true, None),
+        ],
+    )?;
+    bar.append_items(&[&app_menu, &edit, &view, &window_menu, &help_menu])?;
+    Ok(AppMenu {
+        bar,
+        window_menu,
+        help_menu,
+        start_fullscreen,
+        logo_styles,
+    })
+}

packages/desktop/src/policy.rs

@@ -21,6 +21,7 @@ pub const CONNECT_PAGE: &str = "codemanapp://localhost/index.html";
 /// Caps on what a page may hand the native side.
 pub const MAX_URL_LEN: usize = 4096;
 pub const MAX_FIELD_LEN: usize = 1024;
+const MAX_MESSAGE_LEN: usize = 16 * 1024;
 
 /// Where the main window is in reaching a server. The gates below take it
 /// instead of "is a server set", because what may talk to the native side
@@ -61,6 +62,16 @@ impl Phase {
     }
 }
 
+/// The phase a commit of `committed` in the main window moves to: Loaded once
+/// a page from the server that is loading is the document.
+pub fn loaded_on_commit(phase: &Phase, committed: &str) -> Option<Phase> {
+    let Phase::Loading(server) = phase else {
+        return None;
+    };
+    let url = Url::parse(committed).ok()?;
+    same_origin(&url, server).then(|| Phase::Loaded(server.clone()))
+}
+
 /// Turn what the user typed into a server URL: scheme added when missing,
 /// query and fragment dropped, and the path ending in `/` so `api/status`
 /// joins below a base path. The scheme is `https` for a tailnet `.ts.net`
@@ -542,12 +553,9 @@ pub fn new_window(target: &str, phase: &Phase, via: Via) -> NewWindow {
     if target.len() > MAX_URL_LEN {
         return NewWindow::Deny;
     }
-    let Ok(url) = Url::parse(target) else {
+    let Some(url) = external_url(target) else {
         return NewWindow::Deny;
     };
-    if !matches!(url.scheme(), "http" | "https") {
-        return NewWindow::Deny;
-    }
     let Some(srv) = phase.loaded() else {
         return NewWindow::Deny;
     };
@@ -631,7 +639,7 @@ pub enum ConnectCmd {
     /// Show the agent install that is running already.
     AgentAttach,
     /// Run the installer on another machine over SSH, in Terminal. `target`
-    /// is what the user typed; setup::SshTarget::parse checks it.
+    /// is what the user typed; terminal_install::SshTarget::parse checks it.
     InstallRemote {
         target: String,
     },
@@ -646,7 +654,12 @@ pub enum Ipc {
 }
 
 #[derive(Deserialize)]
-#[serde(tag = "cmd", rename_all = "camelCase", deny_unknown_fields)]
+#[serde(
+    tag = "cmd",
+    rename_all = "camelCase",
+    rename_all_fields = "camelCase",
+    deny_unknown_fields
+)]
 enum RawConnect {
     Ready,
     Connect {
@@ -686,18 +699,15 @@ enum RawConnect {
     },
     InstallPrepare,
     InstallStart {
-        // rename_all above reaches variant names only, and deny_unknown_fields
-        // would refuse the page's spelling of these.
-        #[serde(default, rename = "networkPassword")]
+        #[serde(default)]
         network_password: Option<String>,
-        #[serde(default, rename = "aiCli")]
+        #[serde(default)]
         ai_cli: Option<String>,
     },
     InstallAttach,
     InstallCancel,
     AgentPrepare,
     AgentStart {
-        #[serde(rename = "aiCli")]
         ai_cli: String,
     },
     AgentAttach,
@@ -751,7 +761,7 @@ fn is_connect_page(frame: &Url) -> bool {
 /// - A server page is listened to only once it committed, and only from a
 ///   frame running Codeman's own app shell (trusted_frame).
 pub fn parse_ipc(frame_url: &str, body: &str, phase: &Phase, is_main_window: bool) -> Option<Ipc> {
-    if body.len() > 16 * 1024 {
+    if body.len() > MAX_MESSAGE_LEN {
         return None;
     }
     let frame = Url::parse(frame_url).ok()?;
@@ -766,17 +776,12 @@ pub fn parse_ipc(frame_url: &str, body: &str, phase: &Phase, is_main_window: boo
                 username,
                 password,
                 remember,
-            } => {
-                if url.len() > MAX_URL_LEN {
-                    return None;
-                }
-                ConnectCmd::Connect {
-                    url,
-                    username: bounded(username, MAX_FIELD_LEN)?,
-                    password: bounded(password, MAX_FIELD_LEN)?,
-                    remember,
-                }
-            }
+            } if url.len() <= MAX_URL_LEN => ConnectCmd::Connect {
+                url,
+                username: bounded(username, MAX_FIELD_LEN)?,
+                password: bounded(password, MAX_FIELD_LEN)?,
+                remember,
+            },
             RawConnect::Cancel => ConnectCmd::Cancel,
             RawConnect::StartServer { url } if url.len() <= MAX_URL_LEN => ConnectCmd::StartServer { url },
             RawConnect::Forget { url } if url.len() <= MAX_URL_LEN => ConnectCmd::Forget { url },
@@ -789,15 +794,10 @@ pub fn parse_ipc(frame_url: &str, body: &str, phase: &Phase, is_main_window: boo
             RawConnect::InstallStart {
                 network_password,
                 ai_cli,
-            } => {
-                if ai_cli.as_deref().is_some_and(|id| !is_cli_id(id)) {
-                    return None;
-                }
-                ConnectCmd::InstallStart {
-                    network_password: bounded(network_password, MAX_FIELD_LEN)?.filter(|p| !p.is_empty()),
-                    ai_cli,
-                }
-            }
+            } if ai_cli.as_deref().is_none_or(is_cli_id) => ConnectCmd::InstallStart {
+                network_password: bounded(network_password, MAX_FIELD_LEN)?.filter(|p| !p.is_empty()),
+                ai_cli,
+            },
             RawConnect::InstallAttach => ConnectCmd::InstallAttach,
             RawConnect::InstallCancel => ConnectCmd::InstallCancel,
             RawConnect::AgentPrepare => ConnectCmd::AgentPrepare,
@@ -959,6 +959,32 @@ mod tests {
         assert!(!Phase::Loaded(srv).connect_page_live());
     }
 
+    #[test]
+    fn a_commit_from_the_loading_server_is_the_loaded_page() {
+        let server = Url::parse("https://box.ts.net/codeman/").unwrap();
+        let loading = Phase::Loading(server.clone());
+        assert_eq!(
+            loaded_on_commit(&loading, "https://box.ts.net/codeman/"),
+            Some(Phase::Loaded(server.clone()))
+        );
+        // Any page of that origin counts: the server may redirect within it.
+        assert_eq!(
+            loaded_on_commit(&loading, "https://box.ts.net/codeman/session/abc"),
+            Some(Phase::Loaded(server.clone()))
+        );
+        // Another origin, the connect page, or junk: still loading.
+        assert_eq!(loaded_on_commit(&loading, "https://other.ts.net/codeman/"), None);
+        assert_eq!(loaded_on_commit(&loading, "http://box.ts.net/codeman/"), None);
+        assert_eq!(loaded_on_commit(&loading, CONNECT_PAGE), None);
+        assert_eq!(loaded_on_commit(&loading, "not a url"), None);
+        // Only a load under way can finish.
+        assert_eq!(loaded_on_commit(&Phase::Connect, "https://box.ts.net/codeman/"), None);
+        assert_eq!(
+            loaded_on_commit(&Phase::Loaded(server), "https://box.ts.net/codeman/"),
+            None
+        );
+    }
+
     #[test]
     fn navigation_policy() {
         let srv = u("http://127.0.0.1:3000/");

packages/desktop/src/probe.rs

@@ -2,8 +2,10 @@
 //!
 //! One `GET <server>/api/status`, five seconds at most, run off the UI thread.
 //! The answer is classified into something the connect page can explain. It is
-//! asked once per user action, never in a loop: Codeman counts a request
-//! without valid credentials against the login rate limit (10 per IP).
+//! asked on a user action, or by one of the This Mac tab's waits (for an
+//! install to bring Codeman up, for a server that is starting), which end at
+//! the first answer, never as a standing poll: Codeman counts a request without
+//! valid credentials against the login rate limit (10 per IP).
 
 use serde::Serialize;
 use std::time::Duration;
@@ -82,6 +84,16 @@ pub enum ProbeOutcome {
     },
 }
 
+impl ProbeOutcome {
+    /// The server's version, when it answered as Codeman.
+    pub fn version(&self) -> Option<String> {
+        match self {
+            ProbeOutcome::Ok { version } => Some(version.clone()),
+            _ => None,
+        }
+    }
+}
+
 /// Classify an HTTP answer to `<server>/api/status`. `request` is the URL that
 /// was asked, `location` and `retry_after` are those response headers.
 pub fn classify_response(
@@ -94,12 +106,10 @@ pub fn classify_response(
 ) -> ProbeOutcome {
     match status {
         200 => {
-            let parsed: Option<serde_json::Value> = serde_json::from_str(body).ok();
-            let version = parsed.as_ref().and_then(|v| {
-                (v.get("success")? == &serde_json::Value::Bool(true))
-                    .then(|| v.get("data")?.get("version")?.as_str().map(str::to_string))
-                    .flatten()
-            });
+            let version = serde_json::from_str::<serde_json::Value>(body)
+                .ok()
+                .filter(|v| v["success"] == true)
+                .and_then(|v| v["data"]["version"].as_str().map(str::to_string));
             match version {
                 Some(version) => ProbeOutcome::Ok { version },
                 None => ProbeOutcome::NotCodeman { status },
@@ -742,8 +752,8 @@ mod tests {
     }
 
     /// A Codeman that sends its status headers and then stalls (a blocked
-    /// event loop, a lossy link) did not answer in time. It is not "something
-    /// else on this port", which is what an empty body read as before.
+    /// event loop, a lossy link) did not answer in time: a Timeout, not
+    /// NotCodeman ("something else on this port").
     #[test]
     fn a_body_that_stalls_is_a_timeout() {
         use std::io::{Read, Write};

packages/desktop/src/setup.rs

@@ -1,25 +1,12 @@
-//! The connect screen's "This Mac" tab and its Terminal installs: where the
-//! Codeman on this Mac listens, whether it is installed, its login, which
-//! other Codeman servers of this user run here, and the installer runs in
-//! Terminal for this Mac and for another machine over SSH.
-//! The install most people get runs in the app, in `gui_install.rs`.
-//!
-//! The Terminal route is for what that one cannot do. `install.sh` asks for
-//! the administrator password on a terminal (Homebrew, its sudo keep-alive),
-//! the Xcode tools arrive as a system dialog, and ssh asks about host keys and
-//! passwords on a terminal too. So the app writes a small script that deletes itself and
-//! hands it to Terminal (`open -b com.apple.Terminal`), which needs no
-//! permission, unlike scripting Terminal through osascript (an Automation
-//! prompt). Everything the scripts contain is built here and unit-tested; the
-//! only text from the user is the SSH login, which `SshTarget::parse` limits to
-//! the characters of a user and host name before it is quoted.
+//! The connect screen's "This Mac" tab: where the Codeman on this Mac listens,
+//! whether it is installed, its login, and which other Codeman servers of this
+//! user run here. The install most people get runs in the app
+//! (`gui_install.rs`); the Terminal installs are in `terminal_install.rs`.
 
 use std::collections::HashMap;
-use std::io::Write;
 use std::net::{Ipv4Addr, SocketAddr, TcpStream};
 use std::path::{Path, PathBuf};
 use std::process::{Command, Stdio};
-use std::sync::atomic::{AtomicU64, Ordering};
 use std::time::Duration;
 
 use serde::Serialize;
@@ -29,6 +16,7 @@ use crate::gui_install;
 use crate::local_server;
 use crate::policy;
 use crate::probe::{self, ProbeOutcome};
+use crate::terminal_install::LOCAL_SCRIPT_NAME;
 
 /// Codeman's published installer (a redirect to `install.sh` on master). A test
 /// build of an installer change sets `CODEMAN_DESKTOP_INSTALLER_URL` when it is
@@ -49,10 +37,9 @@ pub const INSTALL_ONE_LINER: &str = "curl -fsSL https://getcodeman.com/install |
 /// Codeman's default port, and the first one a fresh install tries.
 pub const DEFAULT_PORT: u16 = 3000;
 
-/// The Terminal scripts' file names (`<name>-<pid>-<n>.command`). The local
-/// one is also how `inspect` recognizes an install that is still running.
-pub const LOCAL_SCRIPT_NAME: &str = "install-codeman-local";
-pub const REMOTE_SCRIPT_NAME: &str = "install-codeman-remote";
+/// The username Codeman logs in with when only a password is set
+/// (`CODEMAN_USERNAME` unset).
+pub const DEFAULT_USERNAME: &str = "admin";
 
 /// How many ports above 3000 a fresh install tries when 3000 is taken.
 const PORT_SEARCH: u16 = 100;
@@ -195,10 +182,7 @@ pub fn parse_env_file(text: &str) -> HashMap<String, String> {
         let Some((name, value)) = line.split_once('=') else {
             continue;
         };
-        let mut chars = name.chars();
-        let portable = chars.next().is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
-            && chars.all(|c| c.is_ascii_alphanumeric() || c == '_');
-        if !portable {
+        if !local_server::is_env_name(name) {
             continue;
         }
         let mut value = value.trim();
@@ -246,13 +230,13 @@ pub fn login_for(
     }
     if let Some(s) = service {
         if let Some(password) = &s.password {
-            let username = s.username.clone().unwrap_or_else(|| "admin".into());
+            let username = s.username.clone().unwrap_or_else(|| DEFAULT_USERNAME.into());
             return Some((username, password.clone()));
         }
     }
     let from_file = |key: &str| env_file.get(key).filter(|v| !v.is_empty()).cloned();
     let password = from_file("CODEMAN_PASSWORD")?;
-    let username = from_file("CODEMAN_USERNAME").unwrap_or_else(|| "admin".into());
+    let username = from_file("CODEMAN_USERNAME").unwrap_or_else(|| DEFAULT_USERNAME.into());
     Some((username, password))
 }
 
@@ -348,12 +332,17 @@ pub fn is_codeman_server(command: &str) -> bool {
     server_args(command).is_some()
 }
 
+/// The last path component of a command-line word.
+fn basename(word: &str) -> &str {
+    word.rsplit('/').next().unwrap_or(word)
+}
+
 /// What follows `web` on a Codeman server's command line, or None for any
 /// other command.
 fn server_args(command: &str) -> Option<Vec<&str>> {
     let words: Vec<&str> = command.split_whitespace().collect();
     let is_entry = |w: &str| {
-        let name = w.rsplit('/').next().unwrap_or(w);
+        let name = basename(w);
         w.ends_with("dist/index.js") || w.ends_with("src/index.ts") || name == "codeman" || name == "aicodeman"
     };
     // Any entry word that `web` follows: an earlier word may only look like
@@ -372,14 +361,14 @@ fn server_args(command: &str) -> Option<Vec<&str>> {
 /// the port it asked for once the installer runs.
 pub fn install_in_progress(command: &str) -> Option<Option<u16>> {
     let words: Vec<&str> = command.split_whitespace().collect();
-    let name = |w: &&str| w.rsplit('/').next().unwrap_or(w).to_string();
+    let script = format!("{LOCAL_SCRIPT_NAME}-");
     if words.iter().any(|w| {
-        let n = name(w);
-        n.starts_with(&format!("{LOCAL_SCRIPT_NAME}-")) && n.ends_with(".command")
+        let n = basename(w);
+        n.starts_with(&script) && n.ends_with(".command")
     }) {
         return Some(None);
     }
-    if words.iter().any(|w| name(w).starts_with("codeman-install.")) || gui_install::Run::Codeman.matches(command) {
+    if words.iter().any(|w| basename(w).starts_with("codeman-install.")) || gui_install::Run::Codeman.matches(command) {
         let port = words
             .iter()
             .position(|w| *w == "--port")
@@ -552,10 +541,7 @@ fn found_server(url: &Url, answer: &ProbeOutcome, default: &Url) -> FoundServer
     };
     FoundServer {
         url: url.to_string(),
-        version: match answer {
-            ProbeOutcome::Ok { version } => Some(version.clone()),
-            _ => None,
-        },
+        version: answer.version(),
         state,
         is_default: url == default,
     }
@@ -715,11 +701,10 @@ pub fn inspect(depth: Depth) -> LocalStatus {
     };
     let answer = probe::probe(&default, auth.as_deref());
 
-    // Every address one of this user's Codeman servers listens at. The one at
-    // the default address has just answered; the others are asked now, once
-    // each. With nothing at the default address, the first of them that
-    // answers is what the tab opens, as it always was, so each gets the
-    // probe's usual time; otherwise they are only listed, and get less.
+    // The other addresses this user's Codeman servers listen at, asked once
+    // each. With nothing at the default address, the first that answers is
+    // what the tab opens (`shown`), so each gets the probe's usual time;
+    // otherwise they are only listed, and get less.
     let patience = if answer == ProbeOutcome::Refused {
         probe::TIMEOUT
     } else {
@@ -755,10 +740,7 @@ pub fn inspect(depth: Depth) -> LocalStatus {
             Depth::Interactive => local_server::installed(true),
         };
     let state = local_state(&outcome, !servers.is_empty(), !listening.is_empty(), installed);
-    let version = match &outcome {
-        ProbeOutcome::Ok { version } => Some(version.clone()),
-        _ => None,
-    };
+    let version = outcome.version();
     LocalStatus {
         url: url.to_string(),
         state,
@@ -896,290 +878,6 @@ fn pick_port(free: impl Fn(u16) -> bool) -> u16 {
         .unwrap_or(DEFAULT_PORT)
 }
 
-/// `s` as one bash word.
-pub fn sh_quote(s: &str) -> String {
-    format!("'{}'", s.replace('\'', r"'\''"))
-}
-
-/// What the This Mac install asks `install.sh` for.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct LocalInstall {
-    pub port: u16,
-    /// Let the installer ask how other devices reach Codeman (Tailscale, the
-    /// local network with a password). Off: this Mac only (`--local`).
-    pub network: bool,
-}
-
-/// `install.sh`'s flags for a This Mac install. Always `--service`: a
-/// LaunchAgent runs Codeman, so it keeps running when the app quits and starts
-/// again at login, and the app finds it there (read_service). No `--yes`: the
-/// user answers the installer's questions (Homebrew, AI coding tools).
-pub fn local_install_args(opts: LocalInstall) -> Vec<String> {
-    let mut args = Vec::new();
-    if !opts.network {
-        args.push("--local".to_string());
-    }
-    args.push("--service".to_string());
-    args.push("--port".to_string());
-    args.push(opts.port.to_string());
-    args
-}
-
-/// The Terminal script for a This Mac install. It downloads the installer to a
-/// temporary file and runs it from there, so the installer's input is the
-/// terminal itself.
-pub fn local_install_script(opts: LocalInstall) -> String {
-    let args = local_install_args(opts);
-    let shown = format!("bash install.sh {}", args.join(" "));
-    let quoted: Vec<String> = args.iter().map(|a| sh_quote(a)).collect();
-    format!(
-        r#"#!/bin/bash
-rm -f -- "$0"
-printf '\033]0;%s\007' 'Install Codeman'
-cat <<'CODEMAN_MSG'
-Installing Codeman on this Mac.
-
-The installer may ask for your Mac password (it installs Homebrew, Node.js and
-tmux when they are missing) and which AI coding tools to set up. Codeman then
-runs in the background and starts when you log in, so your sessions keep
-running when the app is closed. The Codeman app opens it by itself when the
-install is done.
-
-CODEMAN_MSG
-tmp=$(mktemp "${{TMPDIR:-/tmp}}/codeman-install.XXXXXX") || exit 1
-trap 'rm -f "$tmp"' EXIT
-echo {from}
-if ! curl -fsSL {url} -o "$tmp"; then
-  echo
-  echo 'Could not download the installer. Check the internet connection, then try again from the Codeman app.'
-  exit 1
-fi
-echo {shown}
-echo
-bash "$tmp" {args}
-status=$?
-echo
-if [ "$status" -eq 0 ]; then
-  echo 'Done. You can close this window.'
-else
-  echo "The installer stopped (exit $status). Its log is ~/.codeman/install.log"
-fi
-exit "$status"
-"#,
-        from = sh_quote(&format!("Downloading the installer from {INSTALLER_URL}")),
-        url = sh_quote(INSTALLER_URL),
-        shown = sh_quote(&format!("$ {shown}")),
-        args = quoted.join(" "),
-    )
-}
-
-/// A machine to install Codeman on, as ssh takes it: `[user@]host`, plus a
-/// `:port` the app passes as `-p`. The host may be a name from `~/.ssh/config`.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct SshTarget {
-    pub user: Option<String>,
-    pub host: String,
-    pub port: Option<u16>,
-}
-
-const SSH_FORMAT: &str =
-    "Enter the machine the way ssh takes it: user@host (for example kay@build-box), or a name from your ssh config.";
-
-impl SshTarget {
-    /// Only the characters of a user and host name, never a leading `-` (ssh
-    /// would read it as an option) and never an IPv6 literal (ambiguous with
-    /// the port; a host name or an IPv4 address works).
-    pub fn parse(input: &str) -> Result<Self, String> {
-        let s = input.trim();
-        if s.is_empty() || s.len() > 300 {
-            return Err(SSH_FORMAT.into());
-        }
-        let (user, rest) = match s.split_once('@') {
-            Some((u, r)) => (Some(u), r),
-            None => (None, s),
-        };
-        let (host, port) = match rest.split_once(':') {
-            Some((h, p)) => {
-                let port = p.parse::<u16>().ok().filter(|p| *p > 0).ok_or_else(|| {
-                    "The part after the colon must be the SSH port, for example kay@build-box:2222.".to_string()
-                })?;
-                (h, Some(port))
-            }
-            None => (rest, None),
-        };
-        let name_ok = |v: &str, max: usize| {
-            !v.is_empty()
-                && v.len() <= max
-                && !v.starts_with(['-', '.'])
-                && v.chars().all(|c| c.is_ascii_alphanumeric() || "._-".contains(c))
-        };
-        if let Some(u) = user {
-            if !name_ok(u, 64) {
-                return Err(SSH_FORMAT.into());
-            }
-        }
-        if !name_ok(host, 253) {
-            return Err(SSH_FORMAT.into());
-        }
-        Ok(SshTarget {
-            user: user.map(str::to_string),
-            host: host.to_string(),
-            port,
-        })
-    }
-
-    /// `user@host`, or `host`.
-    pub fn destination(&self) -> String {
-        match &self.user {
-            Some(u) => format!("{u}@{}", self.host),
-            None => self.host.clone(),
-        }
-    }
-
-    /// The address the connect screen suggests once the install is done: the
-    /// installer's default port on that host. Tailscale and a sub-path give
-    /// another address, which the installer prints at the end.
-    pub fn suggested_url(&self) -> String {
-        format!("http://{}:{DEFAULT_PORT}", self.host)
-    }
-}
-
-/// What the remote login shell runs. It may be fish or tcsh, so the work is
-/// one single-quoted `bash -c` word with nothing in it those shells treat
-/// specially (no `!`, `$`, backslash or single quote). `curl | bash` is the
-/// documented install and the installer asks its questions on ssh's terminal
-/// (`-t`); `pipefail` makes a failed download fail the whole command, where a
-/// plain pipe would report bash's success on an empty script. The installer
-/// needs bash anyway.
-pub fn remote_command() -> String {
-    format!(
-        "bash -o pipefail -c 'if command -v curl >/dev/null 2>&1; then curl -fsSL {u} | bash; \
-         elif command -v wget >/dev/null 2>&1; then wget -qO- {u} | bash; \
-         else echo \"Codeman needs curl or wget on this machine.\" >&2; exit 1; fi'",
-        u = INSTALLER_URL
-    )
-}
-
-/// `ssh`'s arguments for an install on `target`: a terminal (`-t`) for the
-/// installer's questions, the port, and `--` before the destination.
-pub fn ssh_args(target: &SshTarget) -> Vec<String> {
-    let mut args = vec!["-t".to_string()];
-    if let Some(port) = target.port {
-        args.push("-p".into());
-        args.push(port.to_string());
-    }
-    args.push("--".into());
-    args.push(target.destination());
-    args.push(remote_command());
-    args
-}
-
-/// The Terminal script for an install on another machine over SSH.
-pub fn remote_install_script(target: &SshTarget) -> String {
-    let args: Vec<String> = ssh_args(target).iter().map(|a| sh_quote(a)).collect();
-    let dest = target.destination();
-    format!(
-        r#"#!/bin/bash
-rm -f -- "$0"
-printf '\033]0;%s\007' {title}
-echo {what}
-cat <<'CODEMAN_MSG'
-
-ssh may ask you to confirm the machine and for its password. Then the installer
-asks how Codeman should be reached (Tailscale, the local network with a password,
-or that machine only) and whether to run it in the background. At the end it
-prints the address of Codeman there: connect to it in the Codeman app, under
-Another machine.
-
-CODEMAN_MSG
-ssh {args}
-status=$?
-echo
-if [ "$status" -eq 0 ]; then
-  echo 'Done. You can close this window.'
-else
-  echo "ssh or the installer stopped (exit $status)."
-fi
-exit "$status"
-"#,
-        title = sh_quote(&format!("Install Codeman on {}", target.host)),
-        what = sh_quote(&format!("Installing Codeman on {dest} over SSH.")),
-        args = args.join(" "),
-    )
-}
-
-static SCRIPT_COUNTER: AtomicU64 = AtomicU64::new(0);
-
-/// Run `script` in a new Terminal window. The script file is private to this
-/// user (the per-user temporary folder, mode 0700, created fresh) and deletes
-/// itself as it starts.
-#[cfg(target_os = "macos")]
-pub fn open_in_terminal(name: &str, script: &str) -> Result<(), String> {
-    use std::os::unix::fs::OpenOptionsExt;
-
-    let n = SCRIPT_COUNTER.fetch_add(1, Ordering::Relaxed);
-    let path = std::env::temp_dir().join(format!("{name}-{}-{n}.command", std::process::id()));
-    let written = std::fs::OpenOptions::new()
-        .write(true)
-        .create_new(true)
-        .mode(0o700)
-        .open(&path)
-        .and_then(|mut f| f.write_all(script.as_bytes()));
-    if let Err(e) = written {
-        let _ = std::fs::remove_file(&path);
-        return Err(format!("Could not write the install script: {e}"));
-    }
-    let out = Command::new("/usr/bin/open")
-        .args(["-b", "com.apple.Terminal"])
-        .arg(&path)
-        .stdin(Stdio::null())
-        .stdout(Stdio::null())
-        .stderr(Stdio::piped())
-        .output();
-    match out {
-        Ok(o) if o.status.success() => Ok(()),
-        Ok(o) => {
-            let _ = std::fs::remove_file(&path);
-            let said = String::from_utf8_lossy(&o.stderr).trim().to_string();
-            Err(if said.is_empty() {
-                "Could not open Terminal.".into()
-            } else {
-                format!("Could not open Terminal: {said}")
-            })
-        }
-        Err(e) => {
-            let _ = std::fs::remove_file(&path);
-            Err(format!("Could not open Terminal: {e}"))
-        }
-    }
-}
-
-#[cfg(not(target_os = "macos"))]
-pub fn open_in_terminal(_name: &str, _script: &str) -> Result<(), String> {
-    let _ = &SCRIPT_COUNTER;
-    Err("Installing from the app is only available on macOS so far.".into())
-}
-
-/// Put `text` on the clipboard (`pbcopy`). The connect page is not a secure
-/// context, so it cannot use the web clipboard API itself.
-pub fn copy_to_clipboard(text: &str) -> Result<(), String> {
-    let mut child = Command::new("/usr/bin/pbcopy")
-        .stdin(Stdio::piped())
-        .stdout(Stdio::null())
-        .stderr(Stdio::null())
-        .spawn()
-        .map_err(|e| format!("Could not copy: {e}"))?;
-    if let Some(mut stdin) = child.stdin.take() {
-        stdin
-            .write_all(text.as_bytes())
-            .map_err(|e| format!("Could not copy: {e}"))?;
-    }
-    match child.wait() {
-        Ok(s) if s.success() => Ok(()),
-        _ => Err("Could not copy the command.".into()),
-    }
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -1217,8 +915,7 @@ mod tests {
     #[cfg(target_os = "macos")]
     #[test]
     fn plutil_reads_both_launch_agent_shapes() {
-        let n = SCRIPT_COUNTER.fetch_add(1, Ordering::Relaxed);
-        let dir = std::env::temp_dir().join(format!("codeman-plist-test-{}-{n}", std::process::id()));
+        let dir = std::env::temp_dir().join(format!("codeman-plist-test-{}", std::process::id()));
         std::fs::create_dir_all(&dir).unwrap();
         let install_sh = r#"<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -1850,7 +1547,7 @@ mod tests {
     /// the answers come back in the order of the addresses.
     #[test]
     fn found_servers_are_asked_together() {
-        use std::io::Read;
+        use std::io::{Read, Write};
         use std::net::TcpListener;
         use std::sync::mpsc;
 
@@ -1923,238 +1620,4 @@ mod tests {
         assert_eq!(pick_port(|p| p >= 3002), 3002);
         assert_eq!(pick_port(|_| false), 3000);
     }
-
-    #[test]
-    fn quoting() {
-        assert_eq!(sh_quote("plain"), "'plain'");
-        assert_eq!(sh_quote("it's"), r"'it'\''s'");
-        assert_eq!(sh_quote(""), "''");
-    }
-
-    #[test]
-    fn local_install_flags() {
-        assert_eq!(
-            local_install_args(LocalInstall {
-                port: 3000,
-                network: false
-            }),
-            ["--local", "--service", "--port", "3000"]
-        );
-        assert_eq!(
-            local_install_args(LocalInstall {
-                port: 3007,
-                network: true
-            }),
-            ["--service", "--port", "3007"]
-        );
-    }
-
-    /// Run a script under bash with `curl` and `bash`... replaced, and report
-    /// what it did. The real installer never runs in a test.
-    #[cfg(unix)]
-    fn run_script(script: &str, fakes: &[(&str, &str)]) -> (String, i32, bool) {
-        use std::os::unix::fs::PermissionsExt;
-        let n = SCRIPT_COUNTER.fetch_add(1, Ordering::Relaxed);
-        let dir = std::env::temp_dir().join(format!("codeman-setup-test-{}-{n}", std::process::id()));
-        let _ = std::fs::remove_dir_all(&dir);
-        std::fs::create_dir_all(dir.join("bin")).unwrap();
-        for (name, body) in fakes {
-            let p = dir.join("bin").join(name);
-            std::fs::write(&p, body.replace("DIR", &dir.display().to_string())).unwrap();
-            std::fs::set_permissions(&p, std::fs::Permissions::from_mode(0o755)).unwrap();
-        }
-        let file = dir.join("run.command");
-        std::fs::write(&file, script).unwrap();
-        let out = Command::new("/bin/bash")
-            .arg(&file)
-            .env("PATH", format!("{}:/usr/bin:/bin", dir.join("bin").display()))
-            .env("TMPDIR", &dir)
-            .stdin(Stdio::null())
-            .output()
-            .unwrap();
-        let log = std::fs::read_to_string(dir.join("log")).unwrap_or_default();
-        let self_deleted = !file.exists();
-        let _ = std::fs::remove_dir_all(&dir);
-        (log, out.status.code().unwrap_or(-1), self_deleted)
-    }
-
-    #[cfg(unix)]
-    #[test]
-    fn local_script_downloads_then_runs_the_installer_with_its_flags() {
-        let script = local_install_script(LocalInstall {
-            port: 3001,
-            network: false,
-        });
-        let (log, code, self_deleted) = run_script(
-            &script,
-            &[(
-                "curl",
-                r#"#!/bin/sh
-echo "curl $*" >> DIR/log
-out=""
-while [ $# -gt 0 ]; do [ "$1" = -o ] && out="$2"; shift; done
-cat > "$out" <<'INSTALLER'
-for a in "$@"; do printf '[%s]' "$a" >> DIR/log; done
-echo >> DIR/log
-exit 7
-INSTALLER
-"#,
-            )],
-        );
-        assert!(self_deleted, "the script must delete itself");
-        assert!(
-            log.starts_with("curl -fsSL https://getcodeman.com/install -o "),
-            "{log}"
-        );
-        assert!(log.contains("\n[--local][--service][--port][3001]\n"), "{log}");
-        assert_eq!(code, 7, "the installer's exit status is the script's");
-    }
-
-    #[cfg(unix)]
-    #[test]
-    fn local_script_stops_when_the_download_fails() {
-        let script = local_install_script(LocalInstall {
-            port: 3000,
-            network: true,
-        });
-        let (log, code, _) = run_script(&script, &[("curl", "#!/bin/sh\necho curl >> DIR/log\nexit 22\n")]);
-        assert_eq!(log, "curl\n");
-        assert_eq!(code, 1);
-    }
-
-    #[test]
-    fn ssh_targets() {
-        assert_eq!(
-            SshTarget::parse(" kay@build-box ").unwrap(),
-            SshTarget {
-                user: Some("kay".into()),
-                host: "build-box".into(),
-                port: None
-            }
-        );
-        assert_eq!(
-            SshTarget::parse("pi@192.168.1.20:2222").unwrap(),
-            SshTarget {
-                user: Some("pi".into()),
-                host: "192.168.1.20".into(),
-                port: Some(2222)
-            }
-        );
-        assert_eq!(SshTarget::parse("macmini").unwrap().destination(), "macmini");
-        assert_eq!(
-            SshTarget::parse("a.b@tnode.tailnet.ts.net").unwrap().destination(),
-            "a.b@tnode.tailnet.ts.net"
-        );
-        for bad in [
-            "",
-            "-oProxyCommand=touch /tmp/x",
-            "kay@-oProxyCommand=x",
-            "-l@host",
-            "kay@host name",
-            "kay@host;rm",
-            "kay@host$(x)",
-            "k'y@host",
-            "kay@",
-            "@host",
-            "kay@host:",
-            "kay@host:0",
-            "kay@host:x",
-            "kay@fe80::1",
-            "kay@[::1]",
-            "a@b@c",
-            ".hidden",
-        ] {
-            assert!(SshTarget::parse(bad).is_err(), "accepted {bad:?}");
-        }
-        assert_eq!(SshTarget::parse("kay@box").unwrap().suggested_url(), "http://box:3000");
-    }
-
-    #[test]
-    fn ssh_arguments() {
-        let t = SshTarget::parse("kay@box:2222").unwrap();
-        let args = ssh_args(&t);
-        assert_eq!(&args[..5], ["-t", "-p", "2222", "--", "kay@box"]);
-        assert_eq!(args.len(), 6);
-        let remote = &args[5];
-        let head = "bash -o pipefail -c '";
-        assert!(remote.starts_with(head) && remote.ends_with('\''));
-        // One word for fish and tcsh: no quote inside, nothing they expand.
-        let inner = &remote[head.len()..remote.len() - 1];
-        assert!(!inner.contains(['\'', '!', '$', '\\', '`']), "{inner}");
-        assert!(inner.contains("curl -fsSL https://getcodeman.com/install | bash"));
-        assert_eq!(ssh_args(&SshTarget::parse("box").unwrap())[..3], ["-t", "--", "box"]);
-    }
-
-    #[cfg(unix)]
-    #[test]
-    fn remote_script_runs_ssh_with_exactly_those_arguments() {
-        let t = SshTarget::parse("kay@box:2222").unwrap();
-        let (log, code, self_deleted) = run_script(
-            &remote_install_script(&t),
-            &[(
-                "ssh",
-                "#!/bin/sh\nfor a in \"$@\"; do printf '[%s]' \"$a\" >> DIR/log; done\necho >> DIR/log\nexit 3\n",
-            )],
-        );
-        assert!(self_deleted);
-        let expected: String = ssh_args(&t).iter().map(|a| format!("[{a}]")).collect();
-        assert_eq!(log, format!("{expected}\n"));
-        assert_eq!(code, 3);
-    }
-
-    /// The remote command does what it says under a POSIX shell: curl first,
-    /// wget without curl, and a clear error with neither.
-    #[cfg(unix)]
-    #[test]
-    fn remote_command_picks_a_downloader() {
-        use std::os::unix::fs::PermissionsExt;
-        let n = SCRIPT_COUNTER.fetch_add(1, Ordering::Relaxed);
-        let dir = std::env::temp_dir().join(format!("codeman-remote-cmd-{}-{n}", std::process::id()));
-        let _ = std::fs::remove_dir_all(&dir);
-        std::fs::create_dir_all(dir.join("bin")).unwrap();
-        let exe = |name: &str, body: &str| {
-            let p = dir.join("bin").join(name);
-            std::fs::write(&p, body).unwrap();
-            std::fs::set_permissions(&p, std::fs::Permissions::from_mode(0o755)).unwrap();
-        };
-        // The outer `bash -o pipefail` is the real one; the `bash` the
-        // download is piped into only reports what it was fed.
-        exe(
-            "bash",
-            "#!/bin/sh\nif [ \"$1\" = -o ]; then exec /bin/bash \"$@\"; fi\nprintf 'bash got: '; /bin/cat\n",
-        );
-        exe("wget", "#!/bin/sh\necho \"wget $*\"\n");
-        let run = || {
-            let out = Command::new("/bin/sh")
-                .arg("-c")
-                .arg(remote_command())
-                .env("PATH", dir.join("bin"))
-                .output()
-                .unwrap();
-            (
-                String::from_utf8_lossy(&out.stdout).into_owned(),
-                String::from_utf8_lossy(&out.stderr).into_owned(),
-                out.status.code(),
-            )
-        };
-        let (out, _, _) = run();
-        assert_eq!(out, "bash got: wget -qO- https://getcodeman.com/install\n");
-        exe("curl", "#!/bin/sh\necho \"curl $*\"\n");
-        let (out, _, _) = run();
-        assert_eq!(out, "bash got: curl -fsSL https://getcodeman.com/install\n");
-        // A failed download fails the command (pipefail), not "Done".
-        exe(
-            "curl",
-            "#!/bin/sh\necho 'curl: (6) Could not resolve host' >&2\nexit 6\n",
-        );
-        let (_, _, code) = run();
-        assert_ne!(code, Some(0));
-        std::fs::remove_file(dir.join("bin/curl")).unwrap();
-        std::fs::remove_file(dir.join("bin/wget")).unwrap();
-        let (out, err, code) = run();
-        assert_eq!(out, "");
-        assert!(err.contains("needs curl or wget"), "{err}");
-        assert_eq!(code, Some(1));
-        let _ = std::fs::remove_dir_all(&dir);
-    }
 }

packages/desktop/src/terminal_install.rs

@@ -0,0 +1,547 @@
+//! The installs that run in Terminal: on this Mac, and on another machine over
+//! SSH.
+//!
+//! The Terminal route is for what the in-app install (`gui_install.rs`) cannot
+//! do. `install.sh` asks for the administrator password on a terminal
+//! (Homebrew, its sudo keep-alive), the Xcode tools arrive as a system dialog,
+//! and ssh asks about host keys and passwords on a terminal too. So the app
+//! writes a small script that deletes itself and hands it to Terminal
+//! (`open -b com.apple.Terminal`), which needs no permission, unlike scripting
+//! Terminal through osascript (an Automation prompt). Everything the scripts
+//! contain is built here and unit-tested; the only text from the user is the
+//! SSH login, which `SshTarget::parse` limits to the characters of a user and
+//! host name before it is quoted.
+
+use std::io::Write;
+use std::process::{Command, Stdio};
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use crate::setup::{DEFAULT_PORT, INSTALLER_URL};
+
+/// The Terminal scripts' file names (`<name>-<pid>-<n>.command`). The local
+/// one is also how `inspect` recognizes an install that is still running.
+pub const LOCAL_SCRIPT_NAME: &str = "install-codeman-local";
+pub const REMOTE_SCRIPT_NAME: &str = "install-codeman-remote";
+
+/// `s` as one bash word.
+pub fn sh_quote(s: &str) -> String {
+    format!("'{}'", s.replace('\'', r"'\''"))
+}
+
+/// What the This Mac install asks `install.sh` for.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct LocalInstall {
+    pub port: u16,
+    /// Let the installer ask how other devices reach Codeman (Tailscale, the
+    /// local network with a password). Off: this Mac only (`--local`).
+    pub network: bool,
+}
+
+/// `install.sh`'s flags for a This Mac install. Always `--service`: a
+/// LaunchAgent runs Codeman, so it keeps running when the app quits and starts
+/// again at login, and the app finds it there (read_service). No `--yes`: the
+/// user answers the installer's questions (Homebrew, AI coding tools).
+pub fn local_install_args(opts: LocalInstall) -> Vec<String> {
+    let mut args = Vec::new();
+    if !opts.network {
+        args.push("--local".to_string());
+    }
+    args.push("--service".to_string());
+    args.push("--port".to_string());
+    args.push(opts.port.to_string());
+    args
+}
+
+/// The Terminal script for a This Mac install. It downloads the installer to a
+/// temporary file and runs it from there, so the installer's input is the
+/// terminal itself.
+pub fn local_install_script(opts: LocalInstall) -> String {
+    let args = local_install_args(opts);
+    let shown = format!("bash install.sh {}", args.join(" "));
+    let quoted: Vec<String> = args.iter().map(|a| sh_quote(a)).collect();
+    format!(
+        r#"#!/bin/bash
+rm -f -- "$0"
+printf '\033]0;%s\007' 'Install Codeman'
+cat <<'CODEMAN_MSG'
+Installing Codeman on this Mac.
+
+The installer may ask for your Mac password (it installs Homebrew, Node.js and
+tmux when they are missing) and which AI coding tools to set up. Codeman then
+runs in the background and starts when you log in, so your sessions keep
+running when the app is closed. The Codeman app opens it by itself when the
+install is done.
+
+CODEMAN_MSG
+tmp=$(mktemp "${{TMPDIR:-/tmp}}/codeman-install.XXXXXX") || exit 1
+trap 'rm -f "$tmp"' EXIT
+echo {from}
+if ! curl -fsSL {url} -o "$tmp"; then
+  echo
+  echo 'Could not download the installer. Check the internet connection, then try again from the Codeman app.'
+  exit 1
+fi
+echo {shown}
+echo
+bash "$tmp" {args}
+status=$?
+echo
+if [ "$status" -eq 0 ]; then
+  echo 'Done. You can close this window.'
+else
+  echo "The installer stopped (exit $status). Its log is ~/.codeman/install.log"
+fi
+exit "$status"
+"#,
+        from = sh_quote(&format!("Downloading the installer from {INSTALLER_URL}")),
+        url = sh_quote(INSTALLER_URL),
+        shown = sh_quote(&format!("$ {shown}")),
+        args = quoted.join(" "),
+    )
+}
+
+/// A machine to install Codeman on, as ssh takes it: `[user@]host`, plus a
+/// `:port` the app passes as `-p`. The host may be a name from `~/.ssh/config`.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SshTarget {
+    pub user: Option<String>,
+    pub host: String,
+    pub port: Option<u16>,
+}
+
+const SSH_FORMAT: &str =
+    "Enter the machine the way ssh takes it: user@host (for example kay@build-box), or a name from your ssh config.";
+
+impl SshTarget {
+    /// Only the characters of a user and host name, never a leading `-` (ssh
+    /// would read it as an option) and never an IPv6 literal (ambiguous with
+    /// the port; a host name or an IPv4 address works).
+    pub fn parse(input: &str) -> Result<Self, String> {
+        let s = input.trim();
+        if s.is_empty() || s.len() > 300 {
+            return Err(SSH_FORMAT.into());
+        }
+        let (user, rest) = match s.split_once('@') {
+            Some((u, r)) => (Some(u), r),
+            None => (None, s),
+        };
+        let (host, port) = match rest.split_once(':') {
+            Some((h, p)) => {
+                let port = p.parse::<u16>().ok().filter(|p| *p > 0).ok_or_else(|| {
+                    "The part after the colon must be the SSH port, for example kay@build-box:2222.".to_string()
+                })?;
+                (h, Some(port))
+            }
+            None => (rest, None),
+        };
+        let name_ok = |v: &str, max: usize| {
+            !v.is_empty()
+                && v.len() <= max
+                && !v.starts_with(['-', '.'])
+                && v.chars().all(|c| c.is_ascii_alphanumeric() || "._-".contains(c))
+        };
+        if let Some(u) = user {
+            if !name_ok(u, 64) {
+                return Err(SSH_FORMAT.into());
+            }
+        }
+        if !name_ok(host, 253) {
+            return Err(SSH_FORMAT.into());
+        }
+        Ok(SshTarget {
+            user: user.map(str::to_string),
+            host: host.to_string(),
+            port,
+        })
+    }
+
+    /// `user@host`, or `host`.
+    pub fn destination(&self) -> String {
+        match &self.user {
+            Some(u) => format!("{u}@{}", self.host),
+            None => self.host.clone(),
+        }
+    }
+
+    /// The address the connect screen suggests once the install is done: the
+    /// installer's default port on that host. Tailscale and a sub-path give
+    /// another address, which the installer prints at the end.
+    pub fn suggested_url(&self) -> String {
+        format!("http://{}:{DEFAULT_PORT}", self.host)
+    }
+}
+
+/// What the remote login shell runs. It may be fish or tcsh, so the work is
+/// one single-quoted `bash -c` word with nothing in it those shells treat
+/// specially (no `!`, `$`, backslash or single quote). `curl | bash` is the
+/// documented install and the installer asks its questions on ssh's terminal
+/// (`-t`); `pipefail` makes a failed download fail the whole command, where a
+/// plain pipe would report bash's success on an empty script. The installer
+/// needs bash anyway.
+pub fn remote_command() -> String {
+    format!(
+        "bash -o pipefail -c 'if command -v curl >/dev/null 2>&1; then curl -fsSL {u} | bash; \
+         elif command -v wget >/dev/null 2>&1; then wget -qO- {u} | bash; \
+         else echo \"Codeman needs curl or wget on this machine.\" >&2; exit 1; fi'",
+        u = INSTALLER_URL
+    )
+}
+
+/// `ssh`'s arguments for an install on `target`: a terminal (`-t`) for the
+/// installer's questions, the port, and `--` before the destination.
+pub fn ssh_args(target: &SshTarget) -> Vec<String> {
+    let mut args = vec!["-t".to_string()];
+    if let Some(port) = target.port {
+        args.push("-p".into());
+        args.push(port.to_string());
+    }
+    args.push("--".into());
+    args.push(target.destination());
+    args.push(remote_command());
+    args
+}
+
+/// The Terminal script for an install on another machine over SSH.
+pub fn remote_install_script(target: &SshTarget) -> String {
+    let args: Vec<String> = ssh_args(target).iter().map(|a| sh_quote(a)).collect();
+    let dest = target.destination();
+    format!(
+        r#"#!/bin/bash
+rm -f -- "$0"
+printf '\033]0;%s\007' {title}
+echo {what}
+cat <<'CODEMAN_MSG'
+
+ssh may ask you to confirm the machine and for its password. Then the installer
+asks how Codeman should be reached (Tailscale, the local network with a password,
+or that machine only) and whether to run it in the background. At the end it
+prints the address of Codeman there: connect to it in the Codeman app, under
+Another machine.
+
+CODEMAN_MSG
+ssh {args}
+status=$?
+echo
+if [ "$status" -eq 0 ]; then
+  echo 'Done. You can close this window.'
+else
+  echo "ssh or the installer stopped (exit $status)."
+fi
+exit "$status"
+"#,
+        title = sh_quote(&format!("Install Codeman on {}", target.host)),
+        what = sh_quote(&format!("Installing Codeman on {dest} over SSH.")),
+        args = args.join(" "),
+    )
+}
+
+static SCRIPT_COUNTER: AtomicU64 = AtomicU64::new(0);
+
+/// Run `script` in a new Terminal window. The script file is private to this
+/// user (the per-user temporary folder, mode 0700, created fresh) and deletes
+/// itself as it starts.
+#[cfg(target_os = "macos")]
+pub fn open_in_terminal(name: &str, script: &str) -> Result<(), String> {
+    use std::os::unix::fs::OpenOptionsExt;
+
+    let n = SCRIPT_COUNTER.fetch_add(1, Ordering::Relaxed);
+    let path = std::env::temp_dir().join(format!("{name}-{}-{n}.command", std::process::id()));
+    let written = std::fs::OpenOptions::new()
+        .write(true)
+        .create_new(true)
+        .mode(0o700)
+        .open(&path)
+        .and_then(|mut f| f.write_all(script.as_bytes()));
+    if let Err(e) = written {
+        let _ = std::fs::remove_file(&path);
+        return Err(format!("Could not write the install script: {e}"));
+    }
+    let out = Command::new("/usr/bin/open")
+        .args(["-b", "com.apple.Terminal"])
+        .arg(&path)
+        .stdin(Stdio::null())
+        .stdout(Stdio::null())
+        .stderr(Stdio::piped())
+        .output();
+    match out {
+        Ok(o) if o.status.success() => Ok(()),
+        Ok(o) => {
+            let _ = std::fs::remove_file(&path);
+            let said = String::from_utf8_lossy(&o.stderr).trim().to_string();
+            Err(if said.is_empty() {
+                "Could not open Terminal.".into()
+            } else {
+                format!("Could not open Terminal: {said}")
+            })
+        }
+        Err(e) => {
+            let _ = std::fs::remove_file(&path);
+            Err(format!("Could not open Terminal: {e}"))
+        }
+    }
+}
+
+#[cfg(not(target_os = "macos"))]
+pub fn open_in_terminal(_name: &str, _script: &str) -> Result<(), String> {
+    let _ = &SCRIPT_COUNTER;
+    Err("Installing from the app is only available on macOS so far.".into())
+}
+
+/// Put `text` on the clipboard (`pbcopy`). The connect page is not a secure
+/// context, so it cannot use the web clipboard API itself.
+pub fn copy_to_clipboard(text: &str) -> Result<(), String> {
+    let mut child = Command::new("/usr/bin/pbcopy")
+        .stdin(Stdio::piped())
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .spawn()
+        .map_err(|e| format!("Could not copy: {e}"))?;
+    if let Some(mut stdin) = child.stdin.take() {
+        stdin
+            .write_all(text.as_bytes())
+            .map_err(|e| format!("Could not copy: {e}"))?;
+    }
+    match child.wait() {
+        Ok(s) if s.success() => Ok(()),
+        _ => Err("Could not copy the command.".into()),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn quoting() {
+        assert_eq!(sh_quote("plain"), "'plain'");
+        assert_eq!(sh_quote("it's"), r"'it'\''s'");
+        assert_eq!(sh_quote(""), "''");
+    }
+
+    #[test]
+    fn local_install_flags() {
+        assert_eq!(
+            local_install_args(LocalInstall {
+                port: 3000,
+                network: false
+            }),
+            ["--local", "--service", "--port", "3000"]
+        );
+        assert_eq!(
+            local_install_args(LocalInstall {
+                port: 3007,
+                network: true
+            }),
+            ["--service", "--port", "3007"]
+        );
+    }
+
+    /// Run a script under bash with `curl` and `bash`... replaced, and report
+    /// what it did. The real installer never runs in a test.
+    #[cfg(unix)]
+    fn run_script(script: &str, fakes: &[(&str, &str)]) -> (String, i32, bool) {
+        use std::os::unix::fs::PermissionsExt;
+        let n = SCRIPT_COUNTER.fetch_add(1, Ordering::Relaxed);
+        let dir = std::env::temp_dir().join(format!("codeman-setup-test-{}-{n}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(dir.join("bin")).unwrap();
+        for (name, body) in fakes {
+            let p = dir.join("bin").join(name);
+            std::fs::write(&p, body.replace("DIR", &dir.display().to_string())).unwrap();
+            std::fs::set_permissions(&p, std::fs::Permissions::from_mode(0o755)).unwrap();
+        }
+        let file = dir.join("run.command");
+        std::fs::write(&file, script).unwrap();
+        let out = Command::new("/bin/bash")
+            .arg(&file)
+            .env("PATH", format!("{}:/usr/bin:/bin", dir.join("bin").display()))
+            .env("TMPDIR", &dir)
+            .stdin(Stdio::null())
+            .output()
+            .unwrap();
+        let log = std::fs::read_to_string(dir.join("log")).unwrap_or_default();
+        let self_deleted = !file.exists();
+        let _ = std::fs::remove_dir_all(&dir);
+        (log, out.status.code().unwrap_or(-1), self_deleted)
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn local_script_downloads_then_runs_the_installer_with_its_flags() {
+        let script = local_install_script(LocalInstall {
+            port: 3001,
+            network: false,
+        });
+        let (log, code, self_deleted) = run_script(
+            &script,
+            &[(
+                "curl",
+                r#"#!/bin/sh
+echo "curl $*" >> DIR/log
+out=""
+while [ $# -gt 0 ]; do [ "$1" = -o ] && out="$2"; shift; done
+cat > "$out" <<'INSTALLER'
+for a in "$@"; do printf '[%s]' "$a" >> DIR/log; done
+echo >> DIR/log
+exit 7
+INSTALLER
+"#,
+            )],
+        );
+        assert!(self_deleted, "the script must delete itself");
+        assert!(
+            log.starts_with("curl -fsSL https://getcodeman.com/install -o "),
+            "{log}"
+        );
+        assert!(log.contains("\n[--local][--service][--port][3001]\n"), "{log}");
+        assert_eq!(code, 7, "the installer's exit status is the script's");
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn local_script_stops_when_the_download_fails() {
+        let script = local_install_script(LocalInstall {
+            port: 3000,
+            network: true,
+        });
+        let (log, code, _) = run_script(&script, &[("curl", "#!/bin/sh\necho curl >> DIR/log\nexit 22\n")]);
+        assert_eq!(log, "curl\n");
+        assert_eq!(code, 1);
+    }
+
+    #[test]
+    fn ssh_targets() {
+        assert_eq!(
+            SshTarget::parse(" kay@build-box ").unwrap(),
+            SshTarget {
+                user: Some("kay".into()),
+                host: "build-box".into(),
+                port: None
+            }
+        );
+        assert_eq!(
+            SshTarget::parse("pi@192.168.1.20:2222").unwrap(),
+            SshTarget {
+                user: Some("pi".into()),
+                host: "192.168.1.20".into(),
+                port: Some(2222)
+            }
+        );
+        assert_eq!(SshTarget::parse("macmini").unwrap().destination(), "macmini");
+        assert_eq!(
+            SshTarget::parse("a.b@tnode.tailnet.ts.net").unwrap().destination(),
+            "a.b@tnode.tailnet.ts.net"
+        );
+        for bad in [
+            "",
+            "-oProxyCommand=touch /tmp/x",
+            "kay@-oProxyCommand=x",
+            "-l@host",
+            "kay@host name",
+            "kay@host;rm",
+            "kay@host$(x)",
+            "k'y@host",
+            "kay@",
+            "@host",
+            "kay@host:",
+            "kay@host:0",
+            "kay@host:x",
+            "kay@fe80::1",
+            "kay@[::1]",
+            "a@b@c",
+            ".hidden",
+        ] {
+            assert!(SshTarget::parse(bad).is_err(), "accepted {bad:?}");
+        }
+        assert_eq!(SshTarget::parse("kay@box").unwrap().suggested_url(), "http://box:3000");
+    }
+
+    #[test]
+    fn ssh_arguments() {
+        let t = SshTarget::parse("kay@box:2222").unwrap();
+        let args = ssh_args(&t);
+        assert_eq!(&args[..5], ["-t", "-p", "2222", "--", "kay@box"]);
+        assert_eq!(args.len(), 6);
+        let remote = &args[5];
+        let head = "bash -o pipefail -c '";
+        assert!(remote.starts_with(head) && remote.ends_with('\''));
+        // One word for fish and tcsh: no quote inside, nothing they expand.
+        let inner = &remote[head.len()..remote.len() - 1];
+        assert!(!inner.contains(['\'', '!', '$', '\\', '`']), "{inner}");
+        assert!(inner.contains("curl -fsSL https://getcodeman.com/install | bash"));
+        assert_eq!(ssh_args(&SshTarget::parse("box").unwrap())[..3], ["-t", "--", "box"]);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn remote_script_runs_ssh_with_exactly_those_arguments() {
+        let t = SshTarget::parse("kay@box:2222").unwrap();
+        let (log, code, self_deleted) = run_script(
+            &remote_install_script(&t),
+            &[(
+                "ssh",
+                "#!/bin/sh\nfor a in \"$@\"; do printf '[%s]' \"$a\" >> DIR/log; done\necho >> DIR/log\nexit 3\n",
+            )],
+        );
+        assert!(self_deleted);
+        let expected: String = ssh_args(&t).iter().map(|a| format!("[{a}]")).collect();
+        assert_eq!(log, format!("{expected}\n"));
+        assert_eq!(code, 3);
+    }
+
+    /// The remote command does what it says under a POSIX shell: curl first,
+    /// wget without curl, and a clear error with neither.
+    #[cfg(unix)]
+    #[test]
+    fn remote_command_picks_a_downloader() {
+        use std::os::unix::fs::PermissionsExt;
+        let n = SCRIPT_COUNTER.fetch_add(1, Ordering::Relaxed);
+        let dir = std::env::temp_dir().join(format!("codeman-remote-cmd-{}-{n}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(dir.join("bin")).unwrap();
+        let exe = |name: &str, body: &str| {
+            let p = dir.join("bin").join(name);
+            std::fs::write(&p, body).unwrap();
+            std::fs::set_permissions(&p, std::fs::Permissions::from_mode(0o755)).unwrap();
+        };
+        // The outer `bash -o pipefail` is the real one; the `bash` the
+        // download is piped into only reports what it was fed.
+        exe(
+            "bash",
+            "#!/bin/sh\nif [ \"$1\" = -o ]; then exec /bin/bash \"$@\"; fi\nprintf 'bash got: '; /bin/cat\n",
+        );
+        exe("wget", "#!/bin/sh\necho \"wget $*\"\n");
+        let run = || {
+            let out = Command::new("/bin/sh")
+                .arg("-c")
+                .arg(remote_command())
+                .env("PATH", dir.join("bin"))
+                .output()
+                .unwrap();
+            (
+                String::from_utf8_lossy(&out.stdout).into_owned(),
+                String::from_utf8_lossy(&out.stderr).into_owned(),
+                out.status.code(),
+            )
+        };
+        let (out, _, _) = run();
+        assert_eq!(out, "bash got: wget -qO- https://getcodeman.com/install\n");
+        exe("curl", "#!/bin/sh\necho \"curl $*\"\n");
+        let (out, _, _) = run();
+        assert_eq!(out, "bash got: curl -fsSL https://getcodeman.com/install\n");
+        // A failed download fails the command (pipefail), not "Done".
+        exe(
+            "curl",
+            "#!/bin/sh\necho 'curl: (6) Could not resolve host' >&2\nexit 6\n",
+        );
+        let (_, _, code) = run();
+        assert_ne!(code, Some(0));
+        std::fs::remove_file(dir.join("bin/curl")).unwrap();
+        std::fs::remove_file(dir.join("bin/wget")).unwrap();
+        let (out, err, code) = run();
+        assert_eq!(out, "");
+        assert!(err.contains("needs curl or wget"), "{err}");
+        assert_eq!(code, Some(1));
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+}

src/local-model/install-job.ts

@@ -1053,9 +1053,16 @@ class LocalModelServiceImpl implements LocalModelService {
     return progress ? { ...next, progress } : next;
   }
 
-  /** The stored state as a view or a verb must see it: settled, unless a verb is just starting a job. */
+  /**
+   * The stored state as a view or a verb must see it: settled, unless a verb is just starting a
+   * job. A job writes its last state BEFORE it lets go of `this.job`, so when the job ended while
+   * this read was out, the read may hold the `installing` from before that write; it is read
+   * again rather than settled, or it would show as an interrupted (`paused`) job for a tick.
+   */
   private async currentState(): Promise<LocalModelStateFile> {
-    const state = await this.deps.readState();
+    const jobAtRead = this.job;
+    let state = await this.deps.readState();
+    if (jobAtRead && !this.job) state = await this.deps.readState();
     return this.jobStarting ? state : this.settled(state);
   }
 

src/types/common.ts

@@ -115,6 +115,12 @@ export interface FileWriteData {
   eol: 'lf' | 'crlf';
 }
 
+/** Response payload for `DELETE /api/sessions/:id/files?path=` (the Files panel's delete button). */
+export interface FileDeleteData {
+  /** The path as submitted (workspace-relative, or absolute inside the session's outside worktree) */
+  path: string;
+}
+
 export type CleanupResourceType = 'timer' | 'interval' | 'watcher' | 'listener' | 'stream';
 
 /**

src/web/public/i18n.js

@@ -1688,6 +1688,11 @@
       // The file name is user text: it passes through untranslated.
       [/^Downloaded (.+) to Downloads$/, (_m, name) => `已将 ${name} 下载到“下载”文件夹`],
       [/^Download of (.+) failed$/, (_m, name) => `下载 ${name} 失败`],
+      // The Files panel's delete button (panels-ui.js): the path is user text, and the server's
+      // reason passes through untranslated.
+      [/^Delete the file ([\s\S]+)\? This cannot be undone\.$/, (_m, path) => `删除文件 ${path}？此操作无法撤销。`],
+      [/^File deleted: ([\s\S]+)$/, (_m, path) => `已删除文件：${path}`],
+      [/^Delete failed: ([\s\S]+)$/, (_m, why) => `删除失败：${why}`],
       // Group names are user text: they pass through untranslated.
       [/^Move to "(.+)"$/, (_m, group) => `移到“${group}”`],
       // Session names are user text too.

src/web/public/panels-ui.js

@@ -3777,6 +3777,7 @@ Object.assign(CodemanApp.prototype, {
     }
 
     const html = [];
+    const canDelete = this._fileBrowserCanDelete(owner);
 
     const renderNode = (node, depth) => {
       const isDir = node.type === 'directory';
@@ -3799,6 +3800,13 @@ Object.assign(CodemanApp.prototype, {
       const downloadBtn = !isDir
         ? `<a class="file-tree-download" href="${escapeHtml(CodemanBase.url(`/api/sessions/${encodeURIComponent(owner)}/file-raw?path=${encodeURIComponent(node.path)}&download=true`))}" title="Download" onclick="event.stopPropagation()">&#x2B07;</a>`
         : '';
+      // No inline handler: the path is a workspace file name, which an agent or a cloned repo
+      // chose, and `encodeURIComponent` leaves `'` alone, so a quoted string in an onclick ran
+      // whatever a file name like `x'-alert(1)-'.txt` held (#529's review). The click is bound
+      // below from the row's already-escaped `data-path`.
+      const deleteBtn = !isDir && canDelete
+        ? `<button type="button" class="file-tree-delete" title="Delete" aria-label="Delete ${escapeHtml(node.name)}">&times;</button>`
+        : '';
 
       html.push(`
         <div class="file-tree-item" data-path="${escapeHtml(node.path)}" data-type="${escapeHtml(node.type)}" data-depth="${depth}">
@@ -3807,6 +3815,7 @@ Object.assign(CodemanApp.prototype, {
           <span class="${nameClass}">${escapeHtml(node.name)}</span>
           ${sizeStr}
           ${downloadBtn}
+          ${deleteBtn}
         </div>
       `);
 
@@ -3842,9 +3851,21 @@ Object.assign(CodemanApp.prototype, {
           this.openFilePreview(path, owner);
         }
       });
+      item.querySelector('.file-tree-delete')?.addEventListener('click', (e) => {
+        e.stopPropagation();
+        this.deleteFileFromBrowser(owner, item.dataset.path);
+      });
     });
   },
 
+  // The delete button is offered only where the route can act: never for a remote (SSH) session,
+  // whose files live on another host, nor for an adopted one, whose folder is not a workspace of
+  // ours (`session.remote` is undefined on an adopted session, so both are tested).
+  _fileBrowserCanDelete(sessionId) {
+    const session = this.sessions?.get?.(sessionId);
+    return !session?.remote && !session?.adopt;
+  },
+
   toggleFileBrowserFolder(path) {
     if (this.fileBrowserExpandedDirs.has(path)) {
       this.fileBrowserExpandedDirs.delete(path);
@@ -3970,6 +3991,7 @@ Object.assign(CodemanApp.prototype, {
       treeEl.innerHTML = `<div class="file-browser-empty">${escapeHtml('No matches')}</div>`;
     } else {
       const ownerPath = encodeURIComponent(ownerSessionId);
+      const canDelete = this._fileBrowserCanDelete(ownerSessionId);
       treeEl.innerHTML = matches
         .map(match => {
           const isDir = match.type === 'directory';
@@ -3981,6 +4003,10 @@ Object.assign(CodemanApp.prototype, {
           const downloadBtn = !isDir
             ? `<a class="file-tree-download" href="${escapeHtml(CodemanBase.url(`/api/sessions/${ownerPath}/file-raw?path=${encodeURIComponent(match.path)}&download=true`))}" title="Download" onclick="event.stopPropagation()">&#x2B07;</a>`
             : '';
+          // Bound below from `data-path`, never an inline handler (see renderFileBrowserTree).
+          const deleteBtn = !isDir && canDelete
+            ? `<button type="button" class="file-tree-delete" title="Delete" aria-label="Delete ${escapeHtml(match.name)}">&times;</button>`
+            : '';
           return `
             <div class="file-tree-item" data-path="${escapeHtml(match.path)}" data-type="${escapeHtml(match.type)}" data-owner="${escapeHtml(ownerSessionId)}">
               <span class="file-tree-expand"></span>
@@ -3988,6 +4014,7 @@ Object.assign(CodemanApp.prototype, {
               <span class="${nameClass}">${escapeHtml(match.name)}</span>
               ${sizeStr}
               ${downloadBtn}
+              ${deleteBtn}
             </div>
           `;
         })
@@ -4003,6 +4030,10 @@ Object.assign(CodemanApp.prototype, {
           this.openFilePreview(path, ownerSessionId);
         }
       });
+      item.querySelector('.file-tree-delete')?.addEventListener('click', (e) => {
+        e.stopPropagation();
+        this.deleteFileFromBrowser(ownerSessionId, item.dataset.path);
+      });
     });
 
     const statusEl = this.$('fileBrowserStatus');
@@ -4012,6 +4043,33 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
+  // The Files panel's delete button (DELETE .../files?path=): asks first, in the same native
+  // dialog the panel's other destructive actions use, then reloads the listing. With a search in
+  // the box the reload re-runs it, so the deleted row leaves the results too; a plain reload
+  // would refresh the tree behind them and leave the row on screen.
+  async deleteFileFromBrowser(sessionId, filePath) {
+    if (!sessionId || !filePath) return;
+    if (!confirm(`Delete the file ${filePath}? This cannot be undone.`)) return;
+    let result = null;
+    try {
+      const response = await fetch(
+        `/api/sessions/${encodeURIComponent(sessionId)}/files?path=${encodeURIComponent(filePath)}`,
+        { method: 'DELETE' },
+      );
+      result = await response.json().catch(() => null);
+      if (!response.ok || result?.success !== true) {
+        throw new Error(result?.error || `HTTP ${response.status}`);
+      }
+    } catch (error) {
+      console.error('File browser delete failed:', error);
+      this.showToast(`Delete failed: ${error?.message || 'network error'}`, 'error');
+      return;
+    }
+    this.showToast(`File deleted: ${filePath}`, 'success');
+    const state = this._ensureFileBrowserState();
+    if (state.ownerSessionId === sessionId) await this._reloadFileBrowserKeepingQuery();
+  },
+
   _findFileBrowserDirectory(nodes, targetPath, ancestors = []) {
     if (!Array.isArray(nodes)) return null;
     for (const node of nodes) {

src/web/public/styles.css

@@ -12386,6 +12386,32 @@ html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="cat
 .file-tree-download:hover {
   color: #4fc3f7;
 }
+.file-tree-delete {
+  display: none;
+  margin-left: 2px;
+  padding: 0 4px;
+  border: 0;
+  background: transparent;
+  color: #888;
+  font-size: 14px;
+  line-height: 1;
+  cursor: pointer;
+  flex-shrink: 0;
+}
+.file-tree-item:hover .file-tree-delete {
+  display: inline;
+}
+.file-tree-delete:hover {
+  color: #ef5350;
+}
+/* A touch screen has no hover, so the row's buttons stay visible there: otherwise the first tap
+   on a row opens the preview and the buttons never show. */
+@media (hover: none) {
+  .file-tree-download,
+  .file-tree-delete {
+    display: inline;
+  }
+}
 
 /* File tree indent levels */
 .file-tree-item[data-depth="0"] { padding-left: 0.5rem; }

src/web/routes/file-routes.ts

@@ -1,9 +1,11 @@
 /**
  * @fileoverview File browser and streaming routes.
  * Provides directory listing, file content preview, raw file serving, tail
- * streaming, and the File Viewer edit-mode write path (edit=1 read +
+ * streaming, the File Viewer edit-mode write path (edit=1 read +
  * PUT /api/sessions/:id/file-content; policy in src/config/file-editing.ts,
- * design in docs/file-viewer-edit-plan.md).
+ * design in docs/file-viewer-edit-plan.md), and the Files panel's delete
+ * (DELETE /api/sessions/:id/files?path=: one regular file, the edit route's
+ * confinement and guards, symbolic links refused).
  */
 
 import { FastifyInstance, type FastifyReply } from 'fastify';
@@ -19,6 +21,7 @@ import type {
   FilesystemBrowseEntry,
   FilesystemBrowseRoot,
   FilesystemPreviewKind,
+  FileDeleteData,
   FileWriteData,
 } from '../../types.js';
 import { ApiErrorCode, createErrorResponse, getErrorMessage } from '../../types.js';
@@ -2000,6 +2003,103 @@ export function registerFileRoutes(app: FastifyInstance, ctx: SessionPort & Even
     };
   });
 
+  // The Files panel's delete button: remove ONE regular file from the session's workspace (or from
+  // its outside worktree, for an absolute path inside it). A write surface like the edit route
+  // above, so it takes that route's confinement and guards whole (ownership, realpath + workspace boundary, sensitive and blocked trees, `.git`), and adds
+  // its own rule for links: a symbolic link is REFUSED, never followed. The confinement check
+  // returns the link's realpath, which is its TARGET, so an `unlink` of that path deletes the file
+  // the link points at and leaves the link dangling (#529's review: `AGENTS.md -> CLAUDE.md`
+  // deleted CLAUDE.md). The final component is therefore read with `lstat` on the path as the
+  // client named it, and only a path whose last part is a plain file goes on; `unlink` never
+  // follows a final symlink, so a link swapped in after that check is removed rather than its
+  // target, and the inode is compared again right before the unlink.
+  app.delete('/api/sessions/:id/files', async (req): Promise<ApiResponse<FileDeleteData>> => {
+    const { id } = req.params as { id: string };
+    const { path: filePath } = req.query as { path?: string };
+    const session = findSessionOrFail(ctx, id, req);
+    // Ahead of any path check, as on the edit route: the validation below resolves against the
+    // LOCAL filesystem, so a same-named local directory would take the delete.
+    if (session.remote) {
+      throwRouteError(400, ApiErrorCode.INVALID_INPUT, 'Deleting is not supported for remote (SSH) sessions');
+    }
+    // An adopted session has no workspace of ours: its folder is the neutral `/tmp`. The older
+    // file surfaces keep serving it as a standing exception (root CLAUDE.md, Adopted tmux
+    // sessions), which is not copied to a new surface, least of all one that deletes.
+    if (session.isAdopted) {
+      throwRouteError(400, ApiErrorCode.INVALID_INPUT, 'Deleting is not supported for adopted sessions');
+    }
+    // A repeated `?path=` arrives as an array.
+    if (typeof filePath !== 'string' || !filePath) {
+      throwRouteError(400, ApiErrorCode.INVALID_INPUT, 'Missing path parameter');
+    }
+    // #516: the confinement check below runs realpathSync, which freezes the server on a mount
+    // that stopped answering. Probe the folders it will touch first, bounded.
+    const scope = await withGuardedOutsideWorktree({
+      workingDir: session.workingDir,
+      liveWorktree: session.liveWorktree,
+    });
+    const worktreeRoot = scope.liveWorktree?.outside && isAbsolute(filePath) ? scope.liveWorktree.path : null;
+    for (const folder of worktreeRoot ? [session.workingDir, worktreeRoot] : [session.workingDir]) {
+      if ((await probePathKind(folder, { pastCap: true })) === 'unknown') {
+        throwRouteError(
+          422,
+          ApiErrorCode.OPERATION_FAILED,
+          describeUnknownPath('Workspace', folder, { pastCap: true })
+        );
+      }
+    }
+    const validated = validateLocalSessionFilePath(scope, filePath);
+    if (!validated) {
+      // Missing files, traversal and symlink escapes alike, as on every other file route.
+      throwRouteError(404, ApiErrorCode.NOT_FOUND, 'File not found');
+    }
+    const { resolvedPath, relativePath } = validated;
+    // The path as the client named it: `resolve` keeps an absolute (outside worktree) path as is.
+    const namedPath = resolve(session.workingDir, filePath);
+    const guard = await loadAttachmentGuardConfig();
+    if (
+      isSensitivePath(resolvedPath) ||
+      isSensitivePath(namedPath) ||
+      isBlockedAttachmentPath(resolvedPath, guard.blockedTrees) ||
+      isBlockedAttachmentPath(namedPath, guard.blockedTrees)
+    ) {
+      throwRouteError(403, ApiErrorCode.FORBIDDEN, 'Deleting this file is blocked');
+    }
+    // Both spellings: a `.git` reached through a linked folder, and a linked `.git`.
+    if (isDeniedEditRelativePath(relativePath) || isDeniedEditRelativePath(relative(session.workingDir, namedPath))) {
+      throwRouteError(403, ApiErrorCode.FORBIDDEN, 'Files under .git cannot be deleted');
+    }
+    const named = await fs.lstat(namedPath).catch(() => undefined);
+    if (!named) {
+      throwRouteError(404, ApiErrorCode.NOT_FOUND, 'File not found');
+    }
+    if (named.isSymbolicLink()) {
+      throwRouteError(
+        400,
+        ApiErrorCode.INVALID_INPUT,
+        'Symbolic links are not deleted from the Files panel (deleting one here would remove the file it points to)'
+      );
+    }
+    if (!named.isFile()) {
+      throwRouteError(400, ApiErrorCode.INVALID_INPUT, 'Only regular files can be deleted');
+    }
+    // The same file the checks were made on: realpath of a path whose last part is no link names
+    // the same inode. A change in between (the file replaced) refuses rather than guesses.
+    const real = await fs.lstat(resolvedPath).catch(() => undefined);
+    if (!real || !real.isFile() || real.ino !== named.ino || real.dev !== named.dev) {
+      throwRouteError(409, ApiErrorCode.CONFLICT, 'The file changed while it was being deleted; reload and try again');
+    }
+    try {
+      await fs.unlink(resolvedPath);
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === 'ENOENT') throwRouteError(404, ApiErrorCode.NOT_FOUND, 'File not found');
+      // The errno text names the resolved path, so only its code goes back.
+      throwRouteError(500, ApiErrorCode.OPERATION_FAILED, `Failed to delete the file (${code ?? 'error'})`);
+    }
+    return { success: true, data: { path: filePath } };
+  });
+
   // Get file content for preview (File Browser)
   app.get('/api/sessions/:id/file-content', async (req) => {
     const { id } = req.params as { id: string };

test/file-browser-search.test.ts

@@ -30,6 +30,9 @@ interface FakeRow {
   dataset: Record<string, string>;
   addEventListener: (type: string, handler: ClickHandler) => void;
   click: () => void;
+  // The row's delete button is looked up per row; the fake rows carry none (file-delete-ui.test.ts
+  // drives it over a real DOM).
+  querySelector: (selector: string) => null;
 }
 
 interface FakeElement {
@@ -105,6 +108,7 @@ function fakeElement(initialClasses: string[] = []): FakeElement {
           click() {
             clickHandler?.();
           },
+          querySelector: () => null,
         });
       }
     },

test/file-delete-ui.test.ts

@@ -0,0 +1,264 @@
+/**
+ * @fileoverview The Files panel's delete button (salvaged from #529), in the browser module.
+ *
+ * #529 first rendered the button with an inline `onclick` that quoted the path inside
+ * `decodeURIComponent('...')`. `encodeURIComponent` leaves `'` alone, so a file named
+ * `x'-alert(1)-'.txt` ran script in Codeman's origin, and `it's.txt` was a syntax error whose
+ * button did nothing. Workspace names come from agents and cloned repos, so the click is now
+ * bound from the row's escaped `data-path`.
+ *
+ * The DOM is jsdom with `runScripts: 'dangerously'` on purpose: jsdom then compiles inline event
+ * attributes the way a browser does, with `window.app` and `window.alert` present, so the old
+ * markup would really call `alert` here and this test would fail on it. The escaper is the real
+ * one from constants.js, not a stub. panels-ui.js loads via `vm` as in
+ * test/file-browser-incomplete.test.ts. 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, vi } from 'vitest';
+
+const PUBLIC = resolve(import.meta.dirname, '../src/web/public');
+const PANELS = readFileSync(resolve(PUBLIC, 'panels-ui.js'), 'utf8');
+const CONSTANTS = readFileSync(resolve(PUBLIC, 'constants.js'), 'utf8');
+const STYLES = readFileSync(resolve(PUBLIC, 'styles.css'), 'utf8');
+
+// The shipped escaper: its map, its pattern and the function, cut from constants.js.
+const ESCAPE_START = CONSTANTS.indexOf('const _htmlEscapeMap');
+const ESCAPE_END = CONSTANTS.indexOf('\n}\n', CONSTANTS.indexOf('function escapeHtml(')) + 3;
+const ESCAPE_SRC = CONSTANTS.slice(ESCAPE_START, ESCAPE_END);
+
+const HOSTILE = ["x'-alert(1)-'.txt", "it's.txt", 'a "b" <i>c</i> & d.txt', "');alert(2);('.txt"];
+const SESSION = 'sess-1';
+
+const dom = new JSDOM(
+  `<div id="fileBrowserPanel" class="visible"></div>
+   <input id="fileBrowserSearch">
+   <div id="fileBrowserStatus"></div>
+   <div id="fileBrowserTree"></div>`,
+  { runScripts: 'dangerously' }
+);
+afterAll(() => dom.window.close());
+const document = dom.window.document;
+const win = dom.window as unknown as Record<string, unknown>;
+const treeEl = () => document.getElementById('fileBrowserTree') as HTMLElement;
+
+interface FakeResponse {
+  ok: boolean;
+  status: number;
+  json: () => Promise<unknown>;
+}
+const reply = (body: unknown, status = 200): FakeResponse => ({
+  ok: status >= 200 && status < 300,
+  status,
+  json: async () => body,
+});
+
+function loadPanel(
+  options: {
+    confirm?: (message: string) => boolean;
+    fetch?: (url: string, init?: { method?: string }) => Promise<FakeResponse>;
+    session?: Record<string, unknown>;
+  } = {}
+) {
+  const CodemanApp = function CodemanApp(this: unknown) {} as unknown as new () => Record<string, any>;
+  const context = vm.createContext({
+    CodemanApp,
+    console,
+    localStorage: { getItem: () => null, setItem: () => {}, removeItem: () => {} },
+    document: { getElementById: () => null, addEventListener: vi.fn() },
+    window: { addEventListener: vi.fn() },
+    // The search debounce, collapsed so the re-run lands on the next turn.
+    setTimeout: (fn: () => void) => setTimeout(fn, 0),
+    clearTimeout,
+    CodemanBase: { url: (p: string) => p },
+    confirm: vi.fn(options.confirm ?? (() => true)),
+    fetch: vi.fn(options.fetch ?? (async () => reply({ success: true, data: {} }))),
+  });
+  vm.runInContext(ESCAPE_SRC, context, { filename: 'constants.js (escapeHtml)' });
+  vm.runInContext(PANELS, context, { filename: 'panels-ui.js' });
+
+  const app = new CodemanApp();
+  app.$ = (id: string) => document.getElementById(id);
+  app.activeSessionId = SESSION;
+  app.sessions = new Map([[SESSION, options.session ?? { id: SESSION }]]);
+  app.fileBrowserExpandedDirs = new Set(['src']);
+  app.fileBrowserShowHidden = false;
+  app.getFileIcon = () => '';
+  app.formatFileSize = () => '';
+  app.openFilePreview = vi.fn();
+  app.showToast = vi.fn();
+  // The sentinel the old inline handler reached: `app.deleteFileFromBrowser(...)` ran in the page.
+  win.app = app;
+  win.alert = vi.fn();
+  return { app, context: context as Record<string, any> };
+}
+
+const fileNode = (name: string) => ({ name, path: `src/${name}`, type: 'file', size: 1, extension: 'txt' });
+const treeEnvelope = (names: string[]) => ({
+  success: true,
+  data: {
+    root: '/repo',
+    tree: [{ name: 'src', path: 'src', type: 'directory', children: names.map(fileNode) }],
+    totalFiles: names.length,
+    totalDirectories: 1,
+    truncated: false,
+  },
+});
+const searchEnvelope = (names: string[]) => ({
+  success: true,
+  data: { mode: 'search', matches: names.map(fileNode), matchCount: names.length, truncated: false },
+});
+
+const rowFor = (path: string) =>
+  [...treeEl().querySelectorAll<HTMLElement>('.file-tree-item')].find((row) => row.dataset.path === path);
+const deleteButtonFor = (path: string) => rowFor(path)?.querySelector<HTMLButtonElement>('.file-tree-delete');
+
+function renderTree(app: Record<string, any>, names: string[]) {
+  app.fileBrowserData = app._validateFileBrowserTreeEnvelope(treeEnvelope(names));
+  app.renderFileBrowserTree(SESSION);
+}
+
+function renderSearch(app: Record<string, any>, names: string[]) {
+  app._renderFileBrowserSearchResults(names.map(fileNode), SESSION, { matchCount: names.length, truncated: false });
+}
+
+describe('Files panel delete button: no inline handler, the exact path', () => {
+  it.each([
+    ['tree', renderTree],
+    ['search results', renderSearch],
+  ])('%s: a click deletes exactly the hostile path and runs nothing', (_label, render) => {
+    const { app } = loadPanel();
+    app.deleteFileFromBrowser = vi.fn();
+    render(app, HOSTILE);
+
+    expect(treeEl().innerHTML).not.toContain('decodeURIComponent');
+    for (const name of HOSTILE) {
+      const button = deleteButtonFor(`src/${name}`);
+      expect(button, name).toBeTruthy();
+      expect(button!.getAttribute('onclick')).toBeNull();
+      expect(button!.type).toBe('button');
+
+      button!.click();
+
+      expect(app.deleteFileFromBrowser).toHaveBeenLastCalledWith(SESSION, `src/${name}`);
+    }
+    expect(app.deleteFileFromBrowser).toHaveBeenCalledTimes(HOSTILE.length);
+    expect(win.alert).not.toHaveBeenCalled();
+    // The click stays on the button: the row behind it does not open the file.
+    expect(app.openFilePreview).not.toHaveBeenCalled();
+    // The row itself still opens it.
+    rowFor(`src/${HOSTILE[0]}`)!.click();
+    expect(app.openFilePreview).toHaveBeenCalledWith(`src/${HOSTILE[0]}`, SESSION);
+  });
+
+  it('labels the button with the escaped name, as text', () => {
+    const { app } = loadPanel();
+    renderTree(app, ['a "b" <i>c</i> & d.txt']);
+    const button = deleteButtonFor('src/a "b" <i>c</i> & d.txt')!;
+    expect(button.getAttribute('aria-label')).toBe('Delete a "b" <i>c</i> & d.txt');
+    expect(rowFor('src/a "b" <i>c</i> & d.txt')!.querySelector('i')).toBeNull();
+  });
+
+  it('offers no delete button on a folder row', () => {
+    const { app } = loadPanel();
+    renderTree(app, ['a.txt']);
+    expect(rowFor('src')!.querySelector('.file-tree-delete')).toBeNull();
+    expect(deleteButtonFor('src/a.txt')).toBeTruthy();
+  });
+
+  it.each([
+    ['a remote (SSH) session', { id: SESSION, remote: { host: 'h' } }],
+    ['an adopted session', { id: SESSION, adopt: { kind: 'local' } }],
+  ])('offers none for %s, which the route refuses', (_label, session) => {
+    const { app } = loadPanel({ session });
+    renderTree(app, ['a.txt']);
+    expect(rowFor('src/a.txt')).toBeTruthy();
+    expect(deleteButtonFor('src/a.txt')).toBeNull();
+    renderSearch(app, ['a.txt']);
+    expect(rowFor('src/a.txt')).toBeTruthy();
+    expect(deleteButtonFor('src/a.txt')).toBeNull();
+  });
+});
+
+describe('deleteFileFromBrowser', () => {
+  it('asks first and sends nothing when the answer is no', async () => {
+    const { app, context } = loadPanel({ confirm: () => false });
+    await app.deleteFileFromBrowser(SESSION, "src/it's.txt");
+    expect(context.confirm).toHaveBeenCalledWith("Delete the file src/it's.txt? This cannot be undone.");
+    expect(context.fetch).not.toHaveBeenCalled();
+  });
+
+  it('sends one DELETE with the encoded path, then reloads keeping the query', async () => {
+    const { app, context } = loadPanel({ fetch: async () => reply({ success: true, data: { path: 'x' } }) });
+    app._reloadFileBrowserKeepingQuery = vi.fn(async () => {});
+    const path = "src/x'-alert(1)-' & #?.txt";
+
+    await app.deleteFileFromBrowser(SESSION, path);
+
+    expect(context.fetch).toHaveBeenCalledTimes(1);
+    expect(context.fetch).toHaveBeenCalledWith(`/api/sessions/${SESSION}/files?path=${encodeURIComponent(path)}`, {
+      method: 'DELETE',
+    });
+    expect(app.showToast).toHaveBeenCalledWith(`File deleted: ${path}`, 'success');
+    expect(app._reloadFileBrowserKeepingQuery).toHaveBeenCalledTimes(1);
+  });
+
+  it('shows the server reason and reloads nothing when the delete is refused', async () => {
+    const { app } = loadPanel({
+      fetch: async () => reply({ success: false, error: 'Symbolic links are not deleted from the Files panel' }, 400),
+    });
+    app._reloadFileBrowserKeepingQuery = vi.fn(async () => {});
+
+    await app.deleteFileFromBrowser(SESSION, 'AGENTS.md');
+
+    expect(app.showToast).toHaveBeenCalledWith(
+      'Delete failed: Symbolic links are not deleted from the Files panel',
+      'error'
+    );
+    expect(app._reloadFileBrowserKeepingQuery).not.toHaveBeenCalled();
+  });
+
+  it('removes the row from the search results it was deleted from', async () => {
+    let files = ['delete-me.txt', 'keep-me.txt', 'other.md'];
+    const { app, context } = loadPanel({
+      fetch: async (url, init) => {
+        const query = new URL(url, 'http://localhost');
+        if (init?.method === 'DELETE') {
+          const gone = query.searchParams.get('path')!.replace(/^src\//, '');
+          files = files.filter((name) => name !== gone);
+          return reply({ success: true, data: { path: query.searchParams.get('path') } });
+        }
+        const q = query.searchParams.get('q');
+        return reply(q ? searchEnvelope(files.filter((name) => name.includes(q))) : treeEnvelope(files));
+      },
+    });
+    await app.loadFileBrowser(SESSION);
+    (document.getElementById('fileBrowserSearch') as HTMLInputElement).value = 'me';
+    app.filterFileBrowser('me');
+    await vi.waitFor(() => expect(rowFor('src/delete-me.txt')).toBeTruthy());
+    expect(rowFor('src/other.md')).toBeUndefined();
+
+    deleteButtonFor('src/delete-me.txt')!.click();
+
+    await vi.waitFor(() => expect(rowFor('src/delete-me.txt')).toBeUndefined());
+    expect(rowFor('src/keep-me.txt')).toBeTruthy();
+    // Still the search view, not the tree behind it.
+    expect(rowFor('src/other.md')).toBeUndefined();
+    expect(document.getElementById('fileBrowserStatus')!.textContent).toBe('1 match');
+    const methods = context.fetch.mock.calls.map(([url, init]: [string, { method?: string }?]) =>
+      init?.method === 'DELETE' ? 'DELETE' : url.includes('&q=') ? 'search' : 'tree'
+    );
+    expect(methods).toEqual(['tree', 'search', 'DELETE', 'tree', 'search']);
+  });
+});
+
+describe('Files panel delete button: touch screens', () => {
+  it('keeps the row buttons visible where there is no hover', () => {
+    const blocks = [...STYLES.matchAll(/@media \(hover: none\) \{([^{}]*\{[^{}]*\})\s*\}/g)].map((m) => m[1]);
+    expect(
+      blocks.some((block) => /\.file-tree-download,\s*\.file-tree-delete\s*\{\s*display: inline;/.test(block))
+    ).toBe(true);
+  });
+});

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

@@ -1938,6 +1938,57 @@ describe('view()', () => {
     await h.service.cancel();
   });
 
+  it('a view whose read began while the job ran shows how the job ended, never paused', async () => {
+    // The window polls every second, so a read of the state file can be under way while the
+    // job writes its last state and lets go. That read returns the old `installing`, and
+    // settling it with no job in this process read it as an interrupted job: the window (and
+    // the e2e test, under CI load) saw `paused` with Resume for one tick instead of `failed`.
+    const slow = {
+      read: undefined as undefined | (() => Promise<LocalModelStateFile>),
+      hold: undefined as undefined | Promise<void>,
+      entered: undefined as undefined | (() => void),
+    };
+    const h = setup({
+      overrides: {
+        readState: async () => {
+          const snapshot = await slow.read!();
+          const hold = slow.hold;
+          slow.hold = undefined;
+          if (hold) {
+            slow.entered?.();
+            await hold;
+          }
+          return snapshot;
+        },
+      },
+    });
+    slow.read = h.store.readState;
+    let failVerify!: () => void;
+    const verifying = new Promise<void>((resolve) => (failVerify = resolve));
+    h.deps.verifyModel.mockImplementationOnce(async () => {
+      await verifying;
+      return { ok: false, code: 'no-tool-call' } as never;
+    });
+
+    await h.service.install(REQUEST, ADMIN);
+    await vi.waitFor(() => expect(h.deps.verifyModel).toHaveBeenCalled());
+
+    // A view starts reading while the job is still in the verify step...
+    let releaseRead!: () => void;
+    slow.hold = new Promise<void>((resolve) => (releaseRead = resolve));
+    const entered = new Promise<void>((resolve) => (slow.entered = resolve));
+    const viewing = h.service.view();
+    await entered;
+    // ...the job fails, writes it and ends while that read is still out...
+    failVerify();
+    await h.service.idle();
+    expect(h.store.get().state).toBe('failed');
+    // ...and only then does the read come back, with the file as it was before.
+    releaseRead();
+    const view = await viewing;
+    expect(view).toMatchObject({ state: 'failed', step: 'verify', error: { code: 'no-tool-call' } });
+  });
+
   it('names the model to try next only when the catalogue still has it', async () => {
     const state: LocalModelStateFile = {
       ...jobAt('verify', 'paused'),

test/routes/file-delete-routes.test.ts

@@ -0,0 +1,322 @@
+/**
+ * @fileoverview `DELETE /api/sessions/:id/files?path=`, the Files panel's delete button (salvaged
+ * from #529).
+ *
+ * Real temp workspace, no fs mock, like test/routes/file-write-routes.test.ts: the thing under
+ * test is what the route does to real files, and the defect it fixes (a delete of
+ * `AGENTS.md -> CLAUDE.md` removed CLAUDE.md, because the confinement check hands back the
+ * realpath) only shows against a real symlink. Each refusal also checks that nothing on disk moved.
+ *
+ * Uses app.inject() — no real HTTP ports needed.
+ * Port: N/A (app.inject doesn't open ports)
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { createRouteTestHarness, type RouteTestHarness } from './_route-test-utils.js';
+import { registerFileRoutes } from '../../src/web/routes/file-routes.js';
+import { SETTINGS_PATH } from '../../src/web/route-helpers.js';
+
+describe('DELETE /api/sessions/:id/files (real fs)', () => {
+  let harness: RouteTestHarness;
+  let base: string;
+  let workDir: string;
+  let outsideDir: string;
+
+  const del = (path: string, h: RouteTestHarness = harness) =>
+    h.app.inject({
+      method: 'DELETE',
+      url: `/api/sessions/${h.ctx._sessionId}/files?path=${encodeURIComponent(path)}`,
+    });
+
+  beforeEach(async () => {
+    harness = await createRouteTestHarness(registerFileRoutes);
+    // realpath: tmpdir() can hold a symlinked component (macOS /tmp), and the fixtures compare paths.
+    base = realpathSync(mkdtempSync(join(tmpdir(), 'codeman-delete-')));
+    workDir = join(base, 'ws');
+    outsideDir = join(base, 'outside');
+    mkdirSync(workDir);
+    mkdirSync(outsideDir);
+    harness.ctx._session.workingDir = workDir;
+  });
+
+  afterEach(async () => {
+    await harness.app.close();
+    rmSync(base, { recursive: true, force: true });
+    rmSync(SETTINGS_PATH, { force: true });
+  });
+
+  it('deletes a regular file and answers the path it was given', async () => {
+    mkdirSync(join(workDir, 'src'));
+    writeFileSync(join(workDir, 'src', 'old.ts'), 'x');
+    writeFileSync(join(workDir, 'keep.ts'), 'y');
+
+    const res = await del('src/old.ts');
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ success: true, data: { path: 'src/old.ts' } });
+    expect(existsSync(join(workDir, 'src', 'old.ts'))).toBe(false);
+    expect(existsSync(join(workDir, 'src'))).toBe(true);
+    expect(readFileSync(join(workDir, 'keep.ts'), 'utf8')).toBe('y');
+  });
+
+  it('deletes a file whose name carries quotes and other characters a shell or a URL cares about', async () => {
+    const name = "x'-alert(1)-' & #?.txt";
+    writeFileSync(join(workDir, name), 'x');
+
+    const res = await del(name);
+
+    expect(res.statusCode).toBe(200);
+    expect(existsSync(join(workDir, name))).toBe(false);
+  });
+
+  describe('symbolic links are refused, never followed', () => {
+    it('leaves both the link and its target when asked to delete AGENTS.md -> CLAUDE.md', async () => {
+      writeFileSync(join(workDir, 'CLAUDE.md'), '# rules');
+      symlinkSync('CLAUDE.md', join(workDir, 'AGENTS.md'));
+
+      const res = await del('AGENTS.md');
+
+      expect(res.statusCode).toBe(400);
+      expect(res.json().success).toBe(false);
+      expect(res.json().error).toMatch(/symbolic link/i);
+      expect(readFileSync(join(workDir, 'CLAUDE.md'), 'utf8')).toBe('# rules');
+      expect(lstatSync(join(workDir, 'AGENTS.md')).isSymbolicLink()).toBe(true);
+    });
+
+    it('refuses a link to a folder, which the listing shows as a file row', async () => {
+      mkdirSync(join(workDir, 'real'));
+      writeFileSync(join(workDir, 'real', 'a.txt'), 'a');
+      symlinkSync('real', join(workDir, 'alias'));
+
+      const res = await del('alias');
+
+      expect(res.statusCode).toBe(400);
+      expect(readFileSync(join(workDir, 'real', 'a.txt'), 'utf8')).toBe('a');
+      expect(lstatSync(join(workDir, 'alias')).isSymbolicLink()).toBe(true);
+    });
+
+    it('answers 404 for a link that leads out of the workspace, and leaves its target', async () => {
+      writeFileSync(join(outsideDir, 'secret.txt'), 'secret');
+      symlinkSync(join(outsideDir, 'secret.txt'), join(workDir, 'leak.txt'));
+
+      const res = await del('leak.txt');
+
+      expect(res.statusCode).toBe(404);
+      expect(readFileSync(join(outsideDir, 'secret.txt'), 'utf8')).toBe('secret');
+    });
+
+    it('deletes a plain file reached through a linked folder inside the workspace', async () => {
+      mkdirSync(join(workDir, 'real'));
+      writeFileSync(join(workDir, 'real', 'b.txt'), 'b');
+      symlinkSync('real', join(workDir, 'alias'));
+
+      const res = await del('alias/b.txt');
+
+      expect(res.statusCode).toBe(200);
+      expect(existsSync(join(workDir, 'real', 'b.txt'))).toBe(false);
+      expect(lstatSync(join(workDir, 'alias')).isSymbolicLink()).toBe(true);
+    });
+  });
+
+  it('refuses a file under .git with 403, also when .git is reached through a linked folder', async () => {
+    mkdirSync(join(workDir, '.git'));
+    writeFileSync(join(workDir, '.git', 'config'), '[core]');
+    symlinkSync('.git', join(workDir, 'gitdir'));
+
+    for (const path of ['.git/config', 'gitdir/config']) {
+      const res = await del(path);
+      expect(res.statusCode).toBe(403);
+      expect(res.json().success).toBe(false);
+    }
+    expect(readFileSync(join(workDir, '.git', 'config'), 'utf8')).toBe('[core]');
+  });
+
+  it('refuses a sensitive file with 403', async () => {
+    writeFileSync(join(workDir, '.env'), 'TOKEN=abc');
+
+    const res = await del('.env');
+
+    expect(res.statusCode).toBe(403);
+    expect(readFileSync(join(workDir, '.env'), 'utf8')).toBe('TOKEN=abc');
+  });
+
+  it('answers 404 for a path that climbs out of the workspace', async () => {
+    writeFileSync(join(outsideDir, 'victim.txt'), 'v');
+
+    for (const path of ['../outside/victim.txt', join(outsideDir, 'victim.txt')]) {
+      const res = await del(path);
+      expect(res.statusCode).toBe(404);
+    }
+    expect(readFileSync(join(outsideDir, 'victim.txt'), 'utf8')).toBe('v');
+  });
+
+  it('answers 404 for a file that does not exist', async () => {
+    expect((await del('nope.txt')).statusCode).toBe(404);
+  });
+
+  it('refuses a directory with 400', async () => {
+    mkdirSync(join(workDir, 'src'));
+    writeFileSync(join(workDir, 'src', 'a.ts'), 'a');
+
+    const res = await del('src');
+
+    expect(res.statusCode).toBe(400);
+    expect(readFileSync(join(workDir, 'src', 'a.ts'), 'utf8')).toBe('a');
+  });
+
+  it('refuses a missing or repeated path parameter with 400', async () => {
+    const missing = await harness.app.inject({
+      method: 'DELETE',
+      url: `/api/sessions/${harness.ctx._sessionId}/files`,
+    });
+    expect(missing.statusCode).toBe(400);
+    writeFileSync(join(workDir, 'a.txt'), 'a');
+    const repeated = await harness.app.inject({
+      method: 'DELETE',
+      url: `/api/sessions/${harness.ctx._sessionId}/files?path=a.txt&path=a.txt`,
+    });
+    expect(repeated.statusCode).toBe(400);
+    expect(existsSync(join(workDir, 'a.txt'))).toBe(true);
+  });
+
+  it('refuses a remote (SSH) session before looking at the local twin of its folder', async () => {
+    // The local folder of the same absolute name is exactly the hazard: validation would resolve
+    // against it and the delete would land here while the user meant the remote file.
+    writeFileSync(join(workDir, 'twin.txt'), 'local');
+    harness.ctx._session.remote = {
+      hostId: 'host-1',
+      label: 'testhost',
+      host: '192.0.2.10',
+      username: 'j',
+      remotePath: workDir,
+    };
+
+    const res = await del('twin.txt');
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error).toMatch(/remote/i);
+    expect(readFileSync(join(workDir, 'twin.txt'), 'utf8')).toBe('local');
+  });
+
+  it('refuses an adopted session, whose folder is not a workspace of ours', async () => {
+    writeFileSync(join(workDir, 'shared.txt'), 'tmp');
+    harness.ctx._session.isAdopted = true;
+
+    const res = await del('shared.txt');
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error).toMatch(/adopted/i);
+    expect(readFileSync(join(workDir, 'shared.txt'), 'utf8')).toBe('tmp');
+  });
+
+  describe('a worktree outside the session folder', () => {
+    let sibling: string;
+
+    beforeEach(() => {
+      sibling = join(base, 'ws-feature');
+      mkdirSync(join(sibling, 'src'), { recursive: true });
+      writeFileSync(join(sibling, 'src', 'feature.ts'), 'feature');
+      Object.assign(harness.ctx._session, {
+        liveWorktree: { name: 'ws-feature', path: sibling, outside: true },
+      });
+    });
+
+    it('deletes an absolute path inside it, as the other file routes serve it', async () => {
+      const res = await del(join(sibling, 'src', 'feature.ts'));
+      expect(res.statusCode).toBe(200);
+      expect(existsSync(join(sibling, 'src', 'feature.ts'))).toBe(false);
+    });
+
+    it('does not reach it with a relative path, which resolves against the session folder only', async () => {
+      const res = await del('../ws-feature/src/feature.ts');
+      expect(res.statusCode).toBe(404);
+      expect(existsSync(join(sibling, 'src', 'feature.ts'))).toBe(true);
+    });
+
+    it('refuses a symlink in it that leads out of it, and leaves the target', async () => {
+      writeFileSync(join(outsideDir, 'key.txt'), 'secret');
+      symlinkSync(join(outsideDir, 'key.txt'), join(sibling, 'leak.txt'));
+
+      const res = await del(join(sibling, 'leak.txt'));
+
+      expect(res.statusCode).toBe(404);
+      expect(readFileSync(join(outsideDir, 'key.txt'), 'utf8')).toBe('secret');
+    });
+
+    it('reaches nothing there once it is no longer an outside worktree', async () => {
+      Object.assign(harness.ctx._session, { liveWorktree: { name: 'ws-feature', path: sibling } });
+      expect((await del(join(sibling, 'src', 'feature.ts'))).statusCode).toBe(404);
+      expect(existsSync(join(sibling, 'src', 'feature.ts'))).toBe(true);
+    });
+
+    it.each([
+      ['workspace confinement is turned on', () => ({ attachmentConfineToWorkspace: true })],
+      ['its parent folder is blocked', () => ({ attachmentBlockedPaths: [base] })],
+    ])('deletes nothing there once %s', async (_label, settings) => {
+      mkdirSync(dirname(SETTINGS_PATH), { recursive: true });
+      writeFileSync(SETTINGS_PATH, JSON.stringify(settings()));
+
+      const res = await del(join(sibling, 'src', 'feature.ts'));
+
+      expect(res.statusCode).toBe(404);
+      expect(readFileSync(join(sibling, 'src', 'feature.ts'), 'utf8')).toBe('feature');
+    });
+  });
+
+  describe('multi-user mode', () => {
+    let prevMultiUser: string | undefined;
+
+    beforeEach(() => {
+      prevMultiUser = process.env.CODEMAN_MULTIUSER;
+      process.env.CODEMAN_MULTIUSER = '1';
+    });
+
+    afterEach(() => {
+      if (prevMultiUser === undefined) delete process.env.CODEMAN_MULTIUSER;
+      else process.env.CODEMAN_MULTIUSER = prevMultiUser;
+    });
+
+    it("answers 404 for another user's session and deletes nothing", async () => {
+      const bob = await createRouteTestHarness(registerFileRoutes, { authUser: { username: 'bob', role: 'user' } });
+      try {
+        bob.ctx._session.workingDir = workDir;
+        (bob.ctx._session as unknown as { owner?: string }).owner = 'alice';
+        writeFileSync(join(workDir, 'alice.txt'), 'mine');
+
+        const res = await del('alice.txt', bob);
+
+        expect(res.statusCode).toBe(404);
+        expect(readFileSync(join(workDir, 'alice.txt'), 'utf8')).toBe('mine');
+      } finally {
+        await bob.app.close();
+      }
+    });
+
+    it('lets the owner delete in their own session', async () => {
+      const bob = await createRouteTestHarness(registerFileRoutes, { authUser: { username: 'bob', role: 'user' } });
+      try {
+        bob.ctx._session.workingDir = workDir;
+        (bob.ctx._session as unknown as { owner?: string }).owner = 'bob';
+        writeFileSync(join(workDir, 'bob.txt'), 'mine');
+
+        expect((await del('bob.txt', bob)).statusCode).toBe(200);
+        expect(existsSync(join(workDir, 'bob.txt'))).toBe(false);
+      } finally {
+        await bob.app.close();
+      }
+    });
+  });
+});