fix(cases): serialize every write to linked-cases.json

Five routes changed the linked-cases registry: link, unlink, rename, and a
create or clone into a custom folder. Each read the file, checked it and wrote
it back on its own, so two requests that both read before either wrote lost
an entry. Two clones that claimed one name and finished together both passed
the name check, both answered success, and the later write replaced the
earlier entry. The same race made "a name linked while the clone ran is a
409" in test/routes/case-clone-custom-folder.test.ts fail about half the time.

- New src/web/linked-cases-writer.ts, mutateLinkedCases(), shaped like
  mutateSettingsFile(): mutations run one at a time, each write is a temp
  file renamed over the registry (through a symlink, keeping its mode), and
  a file that is not a JSON object is refused (409 CONFLICT) instead of being
  read as {} and overwritten.
- All five writers go through it, with their name checks inside the
  callback, so exactly one of two requests for one name wins. Rename also
  re-checks that the old name still points at the old folder, and drops its
  manual registry undo, since a failed write no longer changes the file.
- Tests: test/linked-cases-writer.test.ts (writer behaviour, and concurrent
  link/unlink through the routes with slowed writes, which fail on the old
  code). Tests that forced a failed registry write with chmod 444 or a
  directory now inject the failure at the rename, or expect the refusal.

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

.github/workflows/ci.yml

@@ -151,61 +151,6 @@ jobs:
             RECONFIGURE=0; parse_flags --port 4001; [[ "$RECONFIGURE" == "1" ]]
             echo "bash $BASH_VERSION: question phase (flags, launch default, occupied :443, rename opt-in, kept password, start line) ok"
           '
-          # No-admin route: the helpers that decide what gets downloaded and whether it is
-          # trusted (the Node.js checksum pick, the tmux digest table, the verify step), the
-          # stop-before-download check, and an archive install plus its replacement, all
-          # in bash 3.2. This image is Alpine, so it is also the one place the musl branch
-          # runs for real: a machine the route cannot serve must stop BEFORE a download.
-          docker run --rm -v "$PWD":/w -w /w -e CODEMAN_INSTALL_SH_LIB=1 -e HOME=/tmp/h bash:3.2 bash -c '
-            set -euo pipefail
-            mkdir -p /tmp/h /tmp/src/Codeman-1/src
-            . /w/install.sh
-            sha=$(printf "%064d" 7)
-            sums=$(printf "%s  node-v22.1.0-linux-x64.tar.gz\nnothex  node-v22.1.0-linux-arm64.tar.gz\n" "$sha")
-            [[ "$(printf "%s\n" "$sums" | pick_node_tarball linux-x64)" == "$sha node-v22.1.0-linux-x64.tar.gz" ]]
-            if printf "%s\n" "$sums" | pick_node_tarball linux-arm64 >/dev/null; then
-              echo "accepted a checksum that is not 64 hex digits" >&2; exit 1
-            fi
-            for p in linux-x86_64 linux-arm64 macos-arm64 macos-x86_64; do
-              d=$(tmux_build_sha256 "$p"); [[ ${#d} -eq 64 ]]
-            done
-            printf codeman > /tmp/f; good=$(sha256_file /tmp/f); [[ ${#good} -eq 64 ]]
-            verify_sha256 /tmp/f "$good"
-            if verify_sha256 /tmp/f "${good%?}x" || verify_sha256 /tmp/f ""; then
-              echo "accepted a wrong or empty checksum" >&2; exit 1
-            fi
-            is_musl_libc
-            NO_ADMIN=1; NONINTERACTIVE=1
-            download() { echo DOWNLOADED; }; download_to_stdout() { echo DOWNLOADED; }
-            check_node() { return 1; }; check_tmux() { return 1; }; check_git() { return 1; }
-            check_build_tools() { return 0; }
-            if out=$( (ask_dependencies_no_admin linux) 2>&1 ); then
-              echo "did not stop on a musl system" >&2; exit 1
-            fi
-            case "$out" in
-              *DOWNLOADED*) echo "downloaded before stopping: $out" >&2; exit 1 ;;
-              *musl*) ;;
-              *) echo "stopped for the wrong reason: $out" >&2; exit 1 ;;
-            esac
-            # An archive install, then its replacement beside it (busybox tar, bash 3.2).
-            printf "{ \"version\": \"1.0.0\" }\n" > /tmp/src/Codeman-1/package.json
-            tar -czf /tmp/one.tar.gz -C /tmp/src Codeman-1
-            printf "{ \"version\": \"2.0.0\" }\n" > /tmp/src/Codeman-1/package.json
-            tar -czf /tmp/two.tar.gz -C /tmp/src Codeman-1
-            INSTALL_DIR=/tmp/h/app; LOG_FILE=/dev/null
-            download() { cp "${1#file://}" "$2"; }; run_step() { shift; "$@"; }
-            CODEMAN_TARBALL_URL=file:///tmp/one.tar.gz; install_or_update_repo >/dev/null 2>&1; finish_source_swap
-            [[ -f "$INSTALL_DIR/$SOURCE_MARKER" && -z "$SOURCE_STAGING" ]]
-            grep -q 1.0.0 "$INSTALL_DIR/package.json"
-            touch "$INSTALL_DIR/from-the-old-build"
-            CODEMAN_TARBALL_URL=file:///tmp/two.tar.gz; install_or_update_repo >/dev/null 2>&1
-            [[ "$SOURCE_STAGING" == "$INSTALL_DIR.new" ]] && grep -q 1.0.0 "$INSTALL_DIR/package.json"
-            finish_source_swap
-            grep -q 2.0.0 "$INSTALL_DIR/package.json"
-            [[ ! -e "$INSTALL_DIR/from-the-old-build" && ! -e "$INSTALL_DIR.new" && ! -e "$INSTALL_DIR.old" ]]
-            NO_ADMIN=""; resolve_admin_mode; [[ "$NO_ADMIN" == "0" ]]
-            echo "bash $BASH_VERSION: no-admin route (checksums, stop before download, archive install and swap) ok"
-          '
 
       - name: CLI catalogue artifacts are in sync with stock.ts
         run: npm run generate:cli-catalog -- --check

CLAUDE.md

@@ -103,7 +103,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 - **Default bind is loopback-only; non-loopback without a password starts but warns** — the server defaults to `--host 127.0.0.1`. Binding non-loopback (`--host`/`-H`/`CODEMAN_HOST`) without `CODEMAN_PASSWORD` starts anyway but prints a loud warning; `--allow-unauthenticated-network` / `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` acknowledges it. ⚠️ The production systemd unit passes no `--host`, so prod binds **localhost only**: reach it via `tailscale serve`/tunnel to `127.0.0.1`. A loopback bind is reachable through a same-host tunnel but NOT by a browser hitting the box's LAN IP. `install.sh` is separate and prompts for the binding (defaulting to LAN + a password), and preserves the existing binding on re-runs. → [architecture-invariants#default-bind-and-the-non-loopback-warning-path](docs/architecture-invariants.md#default-bind-and-the-non-loopback-warning-path), `docs/security-architecture.md`
 - **Instance isolation / multi-instance attach danger** — the data dir (`~/.codeman`) and tmux socket (`tmux -L codeman`) are PROCESS-WIDE and shared by every Codeman on the machine, derived from `CODEMAN_INSTANCE` via `src/config/instance.ts`. ⚠️ A 2nd instance on the SAME socket **discovers and attaches PTYs to the first instance's live sessions**, resizing and mutating them. `$HOME` isolation is NOT enough because tmux is system-global. To run two instances, give each a distinct `CODEMAN_INSTANCE` (scopes dir + socket together), or set `CODEMAN_TMUX_SOCKET` + `CODEMAN_DATA_DIR` individually; `scripts/run-beta.sh` does this for a beta alongside prod. **Any new `~/.codeman/...` path MUST go through `dataPath()`**, never `join(homedir(), '.codeman', …)`, and **any new `tmux -L` caller through `resolveTmuxSocketName()`** (both in `config/instance.ts`): the TUI shells out to tmux from a second process, and a hardcoded `codeman` there would point a beta instance at prod's panes. → [architecture-invariants#instance-isolation-and-the-multi-instance-attach-danger](docs/architecture-invariants.md#instance-isolation-and-the-multi-instance-attach-danger)
 - **The prefix table on Codeman's socket holds only `<prefix> send-prefix`** — browser tabs are tmux attach clients, and tmux's stock bindings let Ctrl+B `)`/`s` move a tab onto another session. `createSession` resets the table, and `reconcileSessions()` at boot for sessions that survived an upgrade (`src/tmux-prefix-table.ts`); `root` and `C-<letter> detach-client` (the TUI attach's way out) are left alone, so F1 and that alias reach browser tabs for the length of an attach. Alt+1..9 are `if-shell` bindings that `switch-client` only for the TUI's own client (`client_tty` plus a one-shot pid hook), so a browser tab's Esc-then-digit does not move it. Docker and owned-remote nested servers get the same reduction (`C-q send-prefix` only) in their create chain. ⚠️ So `Ctrl+B d` does not exist there: anything attaching a user's terminal claims its own detach key (F1 in `root`, as `codeman tui` and `scripts/tmux-manager.sh` do). → [architecture-invariants#the-prefix-table-on-codemans-socket-holds-only-send-prefix](docs/architecture-invariants.md#the-prefix-table-on-codemans-socket-holds-only-send-prefix)
-- **node-pty's macOS `spawn-helper` ships without `+x`** (issues #6, #204): `node-pty@1.1.0` publishes `prebuilds/darwin-<arch>/spawn-helper` as mode 0644, and macOS launches every PTY through it, so a stock macOS install fails every session start with `Error: posix_spawnp failed.` **Linux can never reproduce it**: `spawn-helper` is an `OS=="mac"` gyp target and node-pty ships no Linux prebuild, so node-gyp always emits an executable helper there. ⚠️ The flip side of that: since Linux has no prebuild, `npm install` **needs a C/C++ toolchain there** (`make`, `g++`, `python3`), so `install.sh` checks for and installs one alongside Node/tmux/git — a stock Ubuntu 24 server has none and died inside node-gyp with `not found: make`. Do not drop that step. (The installer's no-admin route cannot install one, so there it stops before downloading anything and names what is missing.) ⚠️ Look in **`prebuilds/<platform>-<arch>/`**, not just `build/Release/`, which does not exist on macOS. Repair is a chmod, never a mandatory rebuild (that would require Xcode CLI tools and deletes `prebuilds/` before compiling): `npm run fix:node-pty` chmods every helper then proves it by really opening a PTY. `spawnPtyWithHelperRepair()` (`utils/node-pty-repair.ts`) wraps every `pty.spawn()` in `session.ts` and self-heals a broken install on the first failure. → [architecture-invariants#node-ptys-macos-spawn-helper-must-be-executable](docs/architecture-invariants.md#node-ptys-macos-spawn-helper-must-be-executable)
+- **node-pty's macOS `spawn-helper` ships without `+x`** (issues #6, #204): `node-pty@1.1.0` publishes `prebuilds/darwin-<arch>/spawn-helper` as mode 0644, and macOS launches every PTY through it, so a stock macOS install fails every session start with `Error: posix_spawnp failed.` **Linux can never reproduce it**: `spawn-helper` is an `OS=="mac"` gyp target and node-pty ships no Linux prebuild, so node-gyp always emits an executable helper there. ⚠️ The flip side of that: since Linux has no prebuild, `npm install` **needs a C/C++ toolchain there** (`make`, `g++`, `python3`), so `install.sh` checks for and installs one alongside Node/tmux/git — a stock Ubuntu 24 server has none and died inside node-gyp with `not found: make`. Do not drop that step. ⚠️ Look in **`prebuilds/<platform>-<arch>/`**, not just `build/Release/`, which does not exist on macOS. Repair is a chmod, never a mandatory rebuild (that would require Xcode CLI tools and deletes `prebuilds/` before compiling): `npm run fix:node-pty` chmods every helper then proves it by really opening a PTY. `spawnPtyWithHelperRepair()` (`utils/node-pty-repair.ts`) wraps every `pty.spawn()` in `session.ts` and self-heals a broken install on the first failure. → [architecture-invariants#node-ptys-macos-spawn-helper-must-be-executable](docs/architecture-invariants.md#node-ptys-macos-spawn-helper-must-be-executable)
 - **User-chosen paths are probed BOUNDED, never with `existsSync`/`statSync`** (#516): a linked case or a `workingDir` can sit on a network mount that stopped answering. A synchronous check there freezes the whole server, and an unbounded async `stat`/`lstat`/`readFile` holds one of libuv's threadpool workers (4 by default, shared with every `fs`, `dns.lookup` and `crypto` call) until the mount returns. On a request or spawn path use `probePath()`/`probePathKind()` (`utils/bounded-path-probe.ts`, read its `@fileoverview`). ⚠️ `unknown` is NEVER `absent`: nothing is created, scaffolded or 404'd on it. Bulk scans keep the stall cap; a request for ONE path the user named may pass `{ pastCap: true }`, which still stops at the ceiling that keeps one worker free; and a helper that would otherwise touch the path skips whatever is still `unknown`. User-facing errors for it go through `describeUnknownPath()`, so a refused probe is not reported as a broken folder.
 - **Headless screenshots: `deviceScaleFactor` MUST be 1, and write unique filenames** — under DSF=2 xterm's WebGL renderer draws glyphs at ~2× nominal size while still *reporting* nominal cell dims, so only the pixels reveal it and only the terminal font looks wrong. And overwriting a fixed output path leaves OS image viewers showing the old render, which reads as "the fix didn't work"; `scripts/capture-real-overview.mjs` mints a timestamped filename per run. Seed the per-device `localStorage` keys (`codeman:skin`, `codeman-font-size`, `codeman-app-settings`) so the capture matches a real device. → [architecture-invariants#headless-screenshot-capture](docs/architecture-invariants.md#headless-screenshot-capture)
 
@@ -183,7 +183,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **DeepSeek web UI** (`POST`/`GET`/`DELETE /api/deepseek/web`, `deepseek-web-server.ts`): the Run menu's "DeepSeek web UI..." entry supervises ONE background `dsh web` child process, deliberately **NOT a shell session**. ⚠️ Every piece is load-bearing: exactly one server (a second click REUSES it), restarted when the browser authority changes (`--trusted-host`, last asker wins), killed on shutdown via `stopDeepSeekWeb()` (the detached child would otherwise outlive Codeman and hold its port), and failures returned to the caller. ⚠️ Never hardcode the port: search from 3080 across 40, detect free ports by BINDING, then wait for the server to really answer. ⚠️ Both `POST` and `DELETE` must stay behind `canUsernameRunPrivilegedCommands` (booting a profile runs its plugin code; the server is shared). → [architecture-invariants#deepseek-web-ui](docs/architecture-invariants.md#deepseek-web-ui)
 
-**Case rename** (`POST /api/cases/:name/rename`, `src/case-rename.ts`; `docs/wiki/Core-Concepts.md#case`): a case under the cases dir is its folder name and always moves; a linked case renames its alias and moves its real folder only with `renameFolder`; remote and Docker cases are refused. ⚠️ A folder that sessions have open is the hazard: live sessions at or under it make the route answer `409 requiresStop` with their names, and only `stopSessions: true` ends them (via `ctx.cleanupSession`: closed like a tab close, uploads included, nothing is restarted); the free-target pre-check runs before that and refuses a dangling symlink too (`lstat`, as `moveCaseFolder` does), so no session is ended for a move that cannot happen. `withCaseLock` holds the old and new paths for the whole operation (`isCasePathLocked`; the `Session` constructor throws for a working directory inside a held path, so nothing is constructed mid-move). ⚠️ A create awaits the owner's layout lock and a settings read between `new Session` and the server's map, where the rename looks for open sessions, so the constructor also records the session (`noteCaseSessionStarting`) until `registerSessionWithLayout()` or `stop()` settles it (30 s TTL for one that never registers), and a folder move refuses `409` with `renameCode: "BUSY"` while one is recorded at or under the folder (`isCaseSessionStarting`, checked in the same tick that takes the lock); an alias-only rename is not refused. A create whose path was validated before the move but whose `Session` is constructed after it is not covered (the plain check-then-use race of any create path), `moveCaseFolder` refuses an existing target itself (POSIX `rename` would silently replace an EMPTY directory) and retries `EBUSY`/`EPERM`/`EACCES` before answering `423 LOCKED`. If the registries (`linked-cases.json`, `caseOrder`, `lastUsedCase`) fail after the move, `settings.json` and the folder are put back (a failed move-back says the folder is now at the new path), and an error after `stopSessions` carries `stoppedSessions`. Claude Code keys history by path (`claudeProjectDirName`: every non-alphanumeric becomes `-`), so `<claude config>/projects/<old>` is renamed too, or merged entry by entry, never overwriting, into one already at the new key (case delete never removes history, so an earlier case of the new name leaves one); other CLIs' history, Docker bind mounts, `git worktree` links, cron jobs' `workingDir`, Claude history of subfolder sessions and Claude Code's per-project entry in `~/.claude.json` (local-scope `mcpServers`, `allowedTools`, trust; writing another CLI's config is the opt-in MCP sync's job) are NOT migrated. The history scanner prefers the decoded project key over a transcript's `cwd` that no longer exists, so Resume follows a rename. Only an admin's rename touches the server-wide `settings.json` (`caseOrder`, `lastUsedCase`); the owner's default session group is carried across with `TabLayoutService`. `settings.json` is written before `linked-cases.json`, and both are restored if the registry write fails.
+**Case rename** (`POST /api/cases/:name/rename`, `src/case-rename.ts`; `docs/wiki/Core-Concepts.md#case`): a case under the cases dir is its folder name and always moves; a linked case renames its alias and moves its real folder only with `renameFolder`; remote and Docker cases are refused. ⚠️ A folder that sessions have open is the hazard: live sessions at or under it make the route answer `409 requiresStop` with their names, and only `stopSessions: true` ends them (via `ctx.cleanupSession`: closed like a tab close, uploads included, nothing is restarted); the free-target pre-check runs before that and refuses a dangling symlink too (`lstat`, as `moveCaseFolder` does), so no session is ended for a move that cannot happen. `withCaseLock` holds the old and new paths for the whole operation (`isCasePathLocked`; the `Session` constructor throws for a working directory inside a held path, so nothing is constructed mid-move). ⚠️ A create awaits the owner's layout lock and a settings read between `new Session` and the server's map, where the rename looks for open sessions, so the constructor also records the session (`noteCaseSessionStarting`) until `registerSessionWithLayout()` or `stop()` settles it (30 s TTL for one that never registers), and a folder move refuses `409` with `renameCode: "BUSY"` while one is recorded at or under the folder (`isCaseSessionStarting`, checked in the same tick that takes the lock); an alias-only rename is not refused. A create whose path was validated before the move but whose `Session` is constructed after it is not covered (the plain check-then-use race of any create path), `moveCaseFolder` refuses an existing target itself (POSIX `rename` would silently replace an EMPTY directory) and retries `EBUSY`/`EPERM`/`EACCES` before answering `423 LOCKED`. If the registries (`linked-cases.json`, `caseOrder`, `lastUsedCase`) fail after the move, `settings.json` and the folder are put back (a failed move-back says the folder is now at the new path), and an error after `stopSessions` carries `stoppedSessions`. Claude Code keys history by path (`claudeProjectDirName`: every non-alphanumeric becomes `-`), so `<claude config>/projects/<old>` is renamed too, or merged entry by entry, never overwriting, into one already at the new key (case delete never removes history, so an earlier case of the new name leaves one); other CLIs' history, Docker bind mounts, `git worktree` links, cron jobs' `workingDir`, Claude history of subfolder sessions and Claude Code's per-project entry in `~/.claude.json` (local-scope `mcpServers`, `allowedTools`, trust; writing another CLI's config is the opt-in MCP sync's job) are NOT migrated. The history scanner prefers the decoded project key over a transcript's `cwd` that no longer exists, so Resume follows a rename. Only an admin's rename touches the server-wide `settings.json` (`caseOrder`, `lastUsedCase`); the owner's default session group is carried across with `TabLayoutService`. `settings.json` is written before `linked-cases.json`, and both are restored if the registry write fails. ⚠️ Every write to `linked-cases.json` (link, unlink, rename, and a create or clone into a custom folder) goes through `mutateLinkedCases()` (`src/web/linked-cases-writer.ts`: serialized, temp file + rename, and a file that does not parse is refused, never read as `{}`), and a check that must still hold when the entry is written (the name is free) runs INSIDE its callback: two clones that claimed one name used to both pass a re-read made outside it and both answer success. Pinned by `test/linked-cases-writer.test.ts`.
 
 **Custom Model Endpoint Profiles** (opt-in, `customModelEndpointsEnabled`, SYNCED, default OFF; `docs/custom-model-endpoints.md`): points a session at a user-configured OpenAI-compatible endpoint (store `custom-model-hosts.ts`, `~/.codeman/custom-model-hosts.json`, 0600). `authStyle` is `bearer` or `api-key`, never both headers (hangs the server). The per-CLI redirect is registry data, `capabilities.customModelInjection` (`env` / `configContentEnv` / `configDir` / `unsupported`), computed by the pure `custom-model-injection.ts`; ⚠️ `configDir` writes an isolated per-session config, NEVER the user's real `~/.codex`/`~/.pi`/`~/.omp`/grok config; the one exception is a recipe's `linkFromRealHome` (deepseek's `profiles`, `sessions`, `settings.yaml`), which symlinks those named entries back out of the real home so they survive the redirect. ⚠️ Claude applies via `Session.restartCli()` (a relaunch in the existing pane, so the conversation is pinned as `resumeSessionId`), the rest one-shot at launch; retired env keys must also be `setenv -u`'d (`_pendingEnvUnsets`), since tmux env survives `respawn-pane`. ⚠️ Remote/Docker sessions are refused (400). ⚠️ Persist only KEYS (`__customModel`), never values (they carry the API key). ⚠️ Every redirectable var must be in that CLI's `privilegedEnvKeys`, and `ANTHROPIC_*` stays out of claude's `allowedPrefixes`. ⚠️ The Run-menu picker builds entries from `window.__codemanCustomModelClis` (escaped via `escapeScriptJson()`), never a hardcoded CLI id list, and launches through `run()` via a temporary `_runMode` swap, never `setRunMode()`. → [architecture-invariants#custom-model-endpoint-profiles](docs/architecture-invariants.md#custom-model-endpoint-profiles)
 
@@ -220,7 +220,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 **Terminal scrollback strip + wheel/touch forwarding**: codex/claude/gemini get the FULL strip (alt-screen, `3J`, mouse DECSETs); tmux-backed opencode and copilot get the MIDDLE strip (alt-screen toggles + mouse DECSETs, `3J` kept); every other tmux-backed mode (shell/antigravity/pi/grok/deepseek/omp) gets the NARROW strip (alt-screen toggles only). Table: `CliCapabilities.altScreen` JSDoc, pinned in test/claude-scrollback-strip.test.ts. ⚠️ Gated on `useMux`: direct-PTY sessions must keep the alt screen. Wheel and touch forward only with observed `cliMouseTracking`: **Claude ≥ 2.1.187, tracked Codex, or tracked Copilot**. Codex 0.163.0 fullscreen was measured with `alternate_on=1`, `mouse_any_flag=1`: one SGR report moves one transcript row; see the fresh measurement in architecture-invariants. Inline/untracked Codex retains local history or the capability-gated paging fallback. Copilot has no version gate; a stale/false tracking flag falls back to PageUp/PageDown. Touch alone has one more branch (`_shouldForwardTouchToApp`): in any mode, a drag also forwards as SGR wheel reports while xterm ITSELF tracks the mouse with SGR encoding (an app in the pane asked for it; a tracking mode other than `x10` and `coreMouseService.activeEncoding === 'SGR'`, so DEFAULT, X10 and SGR-pixel apps fail closed), because xterm encodes a wheel there but the touch listeners consume the drag. ⚠️ `getClaudeCliVersion()` must never cache a FAILED probe. ⚠️ Hand-report clicks only while the CLI has mouse tracking on: `_shouldReportMouseToCli()` gates all three report sites on `cliMouseTracking` (from `_recordStrippedMouseMode()`, session.ts), or a plain shell prints the reports as literal text. ⚠️ A `TerminalTile` (grid tile, split Pane B) forwards the wheel as SGR reports, pages it and reports clicks through these SAME gates with itself as the target (its terminal, its session, never `activeSessionId`), and scrolls Shift+wheel itself (xterm makes it a horizontal no-op); never copy the mode lists into terminal-tile.js. ⚠️ The hollow-buffer PageUp/PageDown fallback (`_maybePageCliTranscript`) stands down when the last capture reported tmux scrollback (`paneHistoryLines` > 0: a tail replayed after a server restart carries only the attach repaint), so the gesture scrolls locally and the scroll-to-top pull loads `full=1`; 0 and unknown keep paging. Read `_logScrollRouting()` before diagnosing a scroll report. → [architecture-invariants#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding](docs/architecture-invariants.md#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding)
 **Detached start + service install**: `codeman web -d` relaunches the same entry script `detached:true` (setsid); `nohup` is not what makes it survive. ⚠️ Both `-d` and `service install` must REFUSE when a server is already up on this data dir (pidfile + `/api/status` probe), or a second instance attaches to the first one's live sessions. ⚠️ Never report success not observed: poll `/api/status` until the child answers or dies. `--stop` must verify the pid still looks like Codeman (`ps -o command=`) before signalling. Unit/label names live only in `config/service-names.ts`. `service install` bakes the installing shell's PATH into the unit and never writes `CODEMAN_PASSWORD` into it. → [architecture-invariants#detached-start-and-service-install](docs/architecture-invariants.md#detached-start-and-service-install)
 
-**Self-update** (App Settings → System → Updates): in-app updater for git-clone installs under a supervisor (`systemd`, `launchd`, `launchd-daemon`, `docker-compose`, else `none`). The work runs in a DETACHED `scripts/self-update.sh` writing `update-status.json`, polled across the restart; pure helpers in `src/web/self-update.ts`. ⚠️ Compose: the restart kills the script, so nothing may be appended after the `restarting` marker; the repo must stay a host bind mount over `/opt/codeman` and the image must keep devDependencies + toolchain. ⚠️ `evaluateEnvironmentGate()` refuses releases that change `server.Dockerfile`/`docker-compose.yaml` or add `.env.example` keys, re-evaluated on `POST /api/system/update`; unknowns fail OPEN, but the exit-to-restart needs `--restart-by-exit 1` (`CODEMAN_RESTART_BY_EXIT=1` only in the Compose file). ⚠️ An install with no git checkout (`install.sh` on a machine without a working git leaves the marker `.install-source`) is kind `archive`: it cannot update in place, and both the check and the UI tell it to re-run the installer, never the npm line. ⚠️ Keep the agent CLIs in `server.Dockerfile` pinned. → [docs/docker-self-update.md](docs/docker-self-update.md), [architecture-invariants#self-update](docs/architecture-invariants.md#self-update)
+**Self-update** (App Settings → System → Updates): in-app updater for git-clone installs under a supervisor (`systemd`, `launchd`, `launchd-daemon`, `docker-compose`, else `none`). The work runs in a DETACHED `scripts/self-update.sh` writing `update-status.json`, polled across the restart; pure helpers in `src/web/self-update.ts`. ⚠️ Compose: the restart kills the script, so nothing may be appended after the `restarting` marker; the repo must stay a host bind mount over `/opt/codeman` and the image must keep devDependencies + toolchain. ⚠️ `evaluateEnvironmentGate()` refuses releases that change `server.Dockerfile`/`docker-compose.yaml` or add `.env.example` keys, re-evaluated on `POST /api/system/update`; unknowns fail OPEN, but the exit-to-restart needs `--restart-by-exit 1` (`CODEMAN_RESTART_BY_EXIT=1` only in the Compose file). ⚠️ Keep the agent CLIs in `server.Dockerfile` pinned. → [docs/docker-self-update.md](docs/docker-self-update.md), [architecture-invariants#self-update](docs/architecture-invariants.md#self-update)
 
 **Reverse-proxy base path** (`--base-url` / `CODEMAN_BASE_URL`, default `/`; pure single source `src/config/base-path.ts`, normalized to `''` or `/foo`): mounts Codeman under a sub-path behind a proxy that forwards the prefix unchanged. Few choke points: `stripBasePath()` in Fastify's `rewriteUrl` (routes stay prefix-agnostic; unprefixed requests still answer), one `onSend` hook rebasing `Location`, `renderIndexHtml` rewriting `<base href>` + injecting `window.__CODEMAN_BASE__`, and `CodemanBase.url()` (constants.js) for runtime URLs. ⚠️ Keep template asset refs RELATIVE, and route every root-absolute frontend URL (EventSource/WebSocket/`window.open`/src) through `CodemanBase.url()`. ⚠️ Web-tab proxy egress goes through `proxyPrefixFor(cap, basePath)`; ingress parsers stay base-agnostic. ⚠️ `--base-url` must ride `buildWebArgs` and `resolveServicePlan`. Tests: `test/base-path.test.ts`. → [architecture-invariants#reverse-proxy-base-path](docs/architecture-invariants.md#reverse-proxy-base-path)
 
@@ -319,7 +319,7 @@ One module per domain in `src/web/routes/` (plus a barrel; `ls src/web/routes/`
 
 ## State Files
 
-All in `~/.codeman/`: `state.json` (sessions, settings, respawn, orchestrator, cron jobs/runs, owner tab layouts, case default groups), `mux-sessions.json` (tmux recovery), `settings.json` (user prefs), `push-keys.json` + `push-subscriptions.json`, `session-lifecycle.jsonl` (audit log), `update-status.json` (self-updater progress, polled across the service restart), `docker-env-applied.json` (Compose deployment only: sha256 of the Dockerfile + compose file the running container was built from, written by `Start-Codeman.sh`, read by the self-updater's environment gate), `docker-build-source.json` (Compose deployment only: the checkout's HEAD commit and `package-lock.json` hash the `codeman-node-modules`/`codeman-dist` volumes currently reflect, written by both `Start-Codeman.sh` and a successful in-place self-update, compared to detect and refresh a volume left stale by an externally-triggered rebuild), `linked-cases.json`, `webviews.json` (saved web-tab dashboard URLs), `remote-hosts.json` + `remote-cases.json`, `docker-hosts.json` + `docker-cases.json` + `docker-exports/`, `subagent-window-states.json` + `subagent-parents.json` (subagent window layout, GET/PUT `/api/subagent-window-states`/`-parents`), `hook-secret` (per-instance), `users.json` (multi-user, mode 0600) + `admin-audit.jsonl`, `intents.json` (Read My Mind intent profiles, mode 0600), `agent-inbox.json` (agent inbox snapshot, only while `agentInboxPersistEnabled` is on, mode 0600), `edit-history/<id>.json` (Edit history panel, one store per session, every diff an agent wrote, mode 0600), `webhook.json` (webhook notifications: enabled/service/scope plus the ntfy/Slack/Discord URL, a bearer secret, so mode 0600, kept out of `settings.json` and never returned by `/api/webhook`, which is admin-only in multi-user mode), `discord.json` (Discord bridge: bot token, a bearer secret, so mode 0600, never returned by `/api/discord`, admin-only in multi-user mode) + `discord-bridge.json` (sessionId to Discord thread id), `config-backup-id` (the random id config backups record as each manifest's `origin`, so instances sharing a backup folder keep to their own snapshots; mode 0600, never tracked or restored, and deleting it unlists this instance's earlier snapshots), `backups/config/` (the default config-backup folder, moved by `configBackupDir`: `cfg-YYYYMMDD-HHMMSS/` snapshots, 0700 with 0600 files, each with a `manifest.json` of SHA-256s, the origin and the retention in force (`keepCount`/`keepDays`), which a pass falls back to when `settings.json` lacks a retention key), `certs/` (self-signed TLS for `--https`), `.env` (CODEMAN_USERNAME/PASSWORD fallback for the `codeman attach` CLI), `install.log` (installer step output, written by `install.sh`'s `run_step`) `tailscale-rename` (the node name before `install.sh` renamed it, so uninstall can offer it back) and `runtime/` (the Node.js and tmux `install.sh` downloaded on its no-admin route, linked from `~/.local/bin`; all three installer-route only). Transient: `self-update-runner.sh`. Multi-user case spaces live OUTSIDE the data dir at `~/codeman-users/<username>/cases` (shared across instances like `~/codeman-cases`, override `CODEMAN_USER_SPACES_DIR`).
+All in `~/.codeman/`: `state.json` (sessions, settings, respawn, orchestrator, cron jobs/runs, owner tab layouts, case default groups), `mux-sessions.json` (tmux recovery), `settings.json` (user prefs), `push-keys.json` + `push-subscriptions.json`, `session-lifecycle.jsonl` (audit log), `update-status.json` (self-updater progress, polled across the service restart), `docker-env-applied.json` (Compose deployment only: sha256 of the Dockerfile + compose file the running container was built from, written by `Start-Codeman.sh`, read by the self-updater's environment gate), `docker-build-source.json` (Compose deployment only: the checkout's HEAD commit and `package-lock.json` hash the `codeman-node-modules`/`codeman-dist` volumes currently reflect, written by both `Start-Codeman.sh` and a successful in-place self-update, compared to detect and refresh a volume left stale by an externally-triggered rebuild), `linked-cases.json`, `webviews.json` (saved web-tab dashboard URLs), `remote-hosts.json` + `remote-cases.json`, `docker-hosts.json` + `docker-cases.json` + `docker-exports/`, `subagent-window-states.json` + `subagent-parents.json` (subagent window layout, GET/PUT `/api/subagent-window-states`/`-parents`), `hook-secret` (per-instance), `users.json` (multi-user, mode 0600) + `admin-audit.jsonl`, `intents.json` (Read My Mind intent profiles, mode 0600), `agent-inbox.json` (agent inbox snapshot, only while `agentInboxPersistEnabled` is on, mode 0600), `edit-history/<id>.json` (Edit history panel, one store per session, every diff an agent wrote, mode 0600), `webhook.json` (webhook notifications: enabled/service/scope plus the ntfy/Slack/Discord URL, a bearer secret, so mode 0600, kept out of `settings.json` and never returned by `/api/webhook`, which is admin-only in multi-user mode), `discord.json` (Discord bridge: bot token, a bearer secret, so mode 0600, never returned by `/api/discord`, admin-only in multi-user mode) + `discord-bridge.json` (sessionId to Discord thread id), `config-backup-id` (the random id config backups record as each manifest's `origin`, so instances sharing a backup folder keep to their own snapshots; mode 0600, never tracked or restored, and deleting it unlists this instance's earlier snapshots), `backups/config/` (the default config-backup folder, moved by `configBackupDir`: `cfg-YYYYMMDD-HHMMSS/` snapshots, 0700 with 0600 files, each with a `manifest.json` of SHA-256s, the origin and the retention in force (`keepCount`/`keepDays`), which a pass falls back to when `settings.json` lacks a retention key), `certs/` (self-signed TLS for `--https`), `.env` (CODEMAN_USERNAME/PASSWORD fallback for the `codeman attach` CLI), `install.log` (installer step output, written by `install.sh`'s `run_step`) and `tailscale-rename` (the node name before `install.sh` renamed it, so uninstall can offer it back; both installer-route only). Transient: `self-update-runner.sh`. Multi-user case spaces live OUTSIDE the data dir at `~/codeman-users/<username>/cases` (shared across instances like `~/codeman-cases`, override `CODEMAN_USER_SPACES_DIR`).
 
 **Generated top-level dirs** (all gitignored — don't edit or commit): `dist/` (esbuild output), `out/`, `coverage/`, `test-results/`, `tmp/`, `screenshots-echo-diag/`. The committed gesture bundle (`src/web/public/gesture/gesture-codeman.js`) IS tracked, but its runtime wasm/model assets (`src/web/public/gesture/wasm/`, `*.task`) are fetched and gitignored.
 
@@ -384,6 +384,6 @@ Two constraints worth knowing before you touch them: the env-derived PTY buffer
 
 ## Scripts & Tunnel
 
-**`install.sh`** (repo root) is the public `curl | bash` installer: it installs Node/tmux/git/build tools, clones to `~/.codeman/app`, builds, and offers a systemd/launchd service, asking every question BEFORE the unattended build (log in `~/.codeman/install.log`). Network access is Tailscale / LAN / local-only; re-runs preserve the existing binding AND password (`read_existing_binding()`). ⚠️ Compose the hand-start env only in `start_command_hint`/`export_bind_env`, and call `stop_background_helpers` before `exec`. ⚠️ Tailscale rename is opt-in (default NO, never under `--yes`/non-interactive); NEVER `tailscale serve reset`, touch a mapping it did not create, run `tailscale funnel` or advertise a Service (`test/install-sh-invariants.test.ts`). ⚠️ **No-admin route** (`--no-admin` / `CODEMAN_NO_ADMIN`, taken by itself when the account has no administrator rights): Node.js (nodejs.org, checked against `SHASUMS256.txt`) and tmux (`tmux/tmux-builds`, digests pinned in `tmux_build_sha256`: bump `TMUX_BUILD_VERSION` and all four together) go into `~/.codeman/runtime`, and without a working git the source is an archive that updates by a re-run (built beside the old tree, swapped in after the build). Nothing in that section may run `sudo`, Homebrew or `xcode-select --install`, a download is verified before it is unpacked, the route is never decided by `sudo -v`, `/usr/bin/git` on a Mac is never executed before `xcode-select -p` proves the developer tools, and `no_admin_blocker` stops BEFORE the first download for what it cannot supply (a Linux toolchain, macOS below 15). ⚠️ Stay **bash 3.2** clean (no `declare -A`, `mapfile`, namerefs, `${x,,}`, here-strings, empty-array expansion under `set -u`). ⚠️ Execute only commands from the generated CLI block (`CLI_INSTALL_CMD_TRUSTED`, `npm run generate:cli-catalog`). → [architecture-invariants#installsh-the-public-installer](docs/architecture-invariants.md#installsh-the-public-installer)
+**`install.sh`** (repo root) is the public `curl | bash` installer: it installs Node/tmux/git/build tools, clones to `~/.codeman/app`, builds, and offers a systemd/launchd service, asking every question BEFORE the unattended build (log in `~/.codeman/install.log`). Network access is Tailscale / LAN / local-only; re-runs preserve the existing binding AND password (`read_existing_binding()`). ⚠️ Compose the hand-start env only in `start_command_hint`/`export_bind_env`, and call `stop_background_helpers` before `exec`. ⚠️ Tailscale rename is opt-in (default NO, never under `--yes`/non-interactive); NEVER `tailscale serve reset`, touch a mapping it did not create, run `tailscale funnel` or advertise a Service (`test/install-sh-invariants.test.ts`). ⚠️ Stay **bash 3.2** clean (no `declare -A`, `mapfile`, namerefs, `${x,,}`, here-strings, empty-array expansion under `set -u`). ⚠️ Execute only commands from the generated CLI block (`CLI_INSTALL_CMD_TRUSTED`, `npm run generate:cli-catalog`). → [architecture-invariants#installsh-the-public-installer](docs/architecture-invariants.md#installsh-the-public-installer)
 
 Other key scripts: `scripts/tmux-manager.sh` (safe tmux mgmt), `scripts/tunnel.sh [quick|named] start|stop|status|url` (quick = random trycloudflare URL, default; `named setup|enable` = fixed-hostname tunnel via `scripts/codeman-tunnel-named.service`; bare `start|stop|url` still means quick), `scripts/run-beta.sh` (isolated beta instance), `scripts/build-agent-image.mjs` (docker base image), `scripts/self-update.sh` (detached updater). Production services: `scripts/codeman-web.service`, `scripts/codeman-tunnel.service`. **Always set `CODEMAN_PASSWORD`** before exposing via tunnel.

README.md

@@ -69,7 +69,6 @@ This installs Node.js, tmux and a build toolchain if missing (node-pty ships no
 - **How it's reachable, your choice.** **Tailscale** (loopback bind fronted by `tailscale serve`, so you get `https://<machine>.<tailnet>.ts.net` with a real certificate and your tailnet as the login, no password needed), **any device on your network** (`0.0.0.0`, with a strongly recommended password prompt), or **this machine only** (`127.0.0.1`, safest). Skipping the password on a network bind requires an explicit confirmation and ends with a loud warning. The highlighted default reflects what is already on the machine (Tailscale when it is already connected, your existing binding on a re-run), and a bare Enter never pulls in new software. If another app already owns `:443` on your node, Codeman goes under `https://<machine>.<tailnet>.ts.net/codeman` or on a second port instead of replacing it. A bare `codeman web` started by hand still defaults to loopback.
 - **The name is yours to choose.** By default the URL uses the machine's existing tailnet name. Answering yes to the second question renames the machine to `codeman-<hostname>` (which also renames it for SSH, so the default is no); `install.sh name` does it later.
 - **Re-run to update.** The same one-liner updates a finished install in place: local changes in `~/.codeman/app` are stashed (never discarded), and a running service is restarted and verified. If a first install was interrupted, re-running resumes the full setup instead. `install.sh status` prints the URLs and the QR code again; `install.sh update`, `install.sh tailscale` and `install.sh uninstall` also exist.
-- **No administrator rights needed.** On an account without `sudo` (or a Mac account that is not an administrator), the installer downloads Node.js from nodejs.org and the tmux project's own build into `~/.codeman/runtime`, each checked against its SHA-256, and takes the source as an archive when there is no working git. `--no-admin` forces that route. Two limits: Linux needs make, a C++ compiler and python3 to be there already, and the tmux download needs macOS 15 or newer. Details in the [wiki](https://github.com/Ark0N/Codeman/wiki/Installation#without-administrator-rights).
 - **Flags for the impatient.** `curl -fsSL https://getcodeman.com/install | bash -s -- --tailscale --service` answers the questions from the command line (`--lan`, `--local`, `--run`, `--no-start`, `--name <n>`, `--port <n>`, `--yes` too). **CI / headless:** without a terminal attached, steps that would change your system abort with instructions instead of running silently; set `CODEMAN_NONINTERACTIVE=1` to approve them for automation.
 
 You'll need at least one AI coding CLI installed — [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenCode](https://opencode.ai), [Codex](https://developers.openai.com/codex/cli), [Antigravity](https://antigravity.google), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Pi](https://pi.dev), [Grok Build](https://github.com/xai-org/grok-build), [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), [OMP](https://github.com/can1357/oh-my-pi), or [GitHub Copilot CLI](https://github.com/github/copilot-cli) (any combination works; Gemini CLI is enterprise-only since Google's consumer cutover, and Antigravity is its successor). The installer detects whichever of the ten is present; if none is found, it offers to install any of them from a menu (DeepSeek excepted, since its npm package installs only a launcher with no runnable profile), or you can skip and install one yourself later. After install:

docs/architecture-invariants.md

@@ -474,7 +474,7 @@ Tests: `test/file-preview-markdown.test.ts` (jsdom-in-vm, pins every rule above)
 
 ### Clone a repository as a case
 
-**Clone Repo tab** (issue #236, proposed by @DodgyBadger): `POST /api/cases/clone` clones a public repository into the caller's case space and registers it as a normal local case; `POST /api/cases/clone-preflight` answers "can this be cloned anonymously, and what refs does it have?" while the user is still typing. Core in `src/git-clone.ts`, split into a PURE half (URL parse, argv/env, `ls-remote` parse, stderr classification) and a thin IO half (`probeGitRemote`, `cloneRepository`). An optional `path` (the **Clone into a custom folder** checkbox) is the folder the repository is cloned INTO, exactly as given (the case name adds no subfolder), and it registers a LINKED case, the same way `POST /api/cases` with a `path` does: it is judged by `prepareNewCasePath()` (`web/case-path.ts`: blocked trees, symlinks, parent must exist), is admin-only in multi-user mode (it writes an absolute path into the shared linked-cases registry), and must be empty or not exist yet. An existing empty folder is cloned into directly (`CloneOptions.intoEmptyDir`: no temporary sibling and no rename, so a mount point works; a failed attempt empties it again but never removes it); a folder with anything in it is refused. Deleting such a case unlinks it and never removes the files. If the registry write fails after git finished, the folder is kept and the error says where it is.
+**Clone Repo tab** (issue #236, proposed by @DodgyBadger): `POST /api/cases/clone` clones a public repository into the caller's case space and registers it as a normal local case; `POST /api/cases/clone-preflight` answers "can this be cloned anonymously, and what refs does it have?" while the user is still typing. Core in `src/git-clone.ts`, split into a PURE half (URL parse, argv/env, `ls-remote` parse, stderr classification) and a thin IO half (`probeGitRemote`, `cloneRepository`). An optional `path` (the **Clone into a custom folder** checkbox) is the folder the repository is cloned INTO, exactly as given (the case name adds no subfolder), and it registers a LINKED case, the same way `POST /api/cases` with a `path` does: it is judged by `prepareNewCasePath()` (`web/case-path.ts`: blocked trees, symlinks, parent must exist), is admin-only in multi-user mode (it writes an absolute path into the shared linked-cases registry), and must be empty or not exist yet. An existing empty folder is cloned into directly (`CloneOptions.intoEmptyDir`: no temporary sibling and no rename, so a mount point works; a failed attempt empties it again but never removes it); a folder with anything in it is refused. Deleting such a case unlinks it and never removes the files. If the registry write fails after git finished, the folder is kept and the error says where it is. The name is checked again inside `mutateLinkedCases()` when the entry is written, so of two clones that claim one name only the first to finish links it; the other answers 409 `ALREADY_EXISTS` and keeps its folder.
 
 - ⚠️ **The URL is a code-execution surface, which is why it is parsed rather than forwarded.** `ext::sh -c <cmd>` makes git run an arbitrary command as its transport, and ANY `<name>::<payload>` dispatches to a `git-remote-<name>` helper, so every `::` form is refused outright. A repository starting with `-` is read by git as a flag; that is rejected AND every spawn puts `--` before the operands, because either defence alone is one edit away from being a hole. Spawns are argv arrays, never a shell (unlike `remote-hosts.ts`, which does build a shell line and must `shellescape`). The Zod schema deliberately only length-bounds `repository` — a weaker regex duplicate of `parseGitRepositoryUrl` would be the copy that drifts.
 - ⚠️ **Non-interactive or it hangs the request.** The clone is synchronous by design (no job store, no polling, no cancellation surface), so an invisible credential prompt would pin an open HTTP request until the timeout. `gitNonInteractiveEnv()` closes all four prompt paths at once: `GIT_TERMINAL_PROMPT=0`, empty `GIT_ASKPASS`/`SSH_ASKPASS` + `SSH_ASKPASS_REQUIRE=never` + empty `DISPLAY`, `GCM_INTERACTIVE=never`, and `ssh -oBatchMode=yes`. `HOME`/`PATH` are inherited on purpose — a user whose own agent or credential helper already works keeps working (so a private repo may well clone; Codeman just never collects or stores credentials, and refuses a `user:password@` URL). ⚠️ In multi-user mode a NON-ADMIN's clone and preflight run with `git -c credential.helper=` (`cloneWithoutCredentialHelpers`), because the helpers belong to the one server account every user shares; admins and single-user mode keep them. The Docker server image relies on exactly this: when built with the opt-in `CODEMAN_INSTALL_GH`/`CODEMAN_INSTALL_AZ` args it configures `gh` (github.com) and an `az`-backed helper (`docker/git-credential-azure-cli`, Azure DevOps) in its SYSTEM gitconfig, both silent until the user signs the CLI in, so a private clone there still fails fast rather than prompting.
@@ -1297,14 +1297,6 @@ Its CLI knowledge is a GENERATED block (`npm run generate:cli-catalog`, markers
 
 ⚠️ It executes ONLY commands from the embedded block (`CLI_INSTALL_CMD_TRUSTED`) — there is no network fetch of the catalogue at install time to worry about at all.
 
-**No-admin route** (`--no-admin` / `CODEMAN_NO_ADMIN`, 2026-11-05). Everything Codeman writes was always under `$HOME`; administrator rights were only ever spent on prerequisites. `resolve_admin_mode` decides once per run whether those rights may be asked for: root yes; a Mac account outside the `admin` group no (unless a Homebrew it can write to exists); on Linux no without a `sudo` binary, or when the account is outside `sudo`/`wheel`/`admin` AND `sudo -n true` fails. ⚠️ It is never decided by `sudo -v`: that prompts, and a refused password from an account outside sudoers is reported to the administrator. A refused password on the system route offers this route instead of ending the run (`sudo_session_try`).
-
-On this route Node.js comes from nodejs.org (`latest-v<major>.x/SHASUMS256.txt` names the tarball AND carries its checksum, one fetch, no JSON parsing) into `~/.codeman/runtime/node`, and tmux from the tmux project's `tmux-builds` release into `~/.codeman/runtime/bin`. ⚠️ `tmux-builds` publishes no checksum file, so `tmux_build_sha256` pins all four digests of `TMUX_BUILD_VERSION`; bump the version and the digests together (the GitHub release API returns them as `digest`). ⚠️ A download is verified BEFORE it is unpacked or run, and an empty expected digest never passes. `node`, `npm`, `npx` and `tmux` are linked from `~/.local/bin` (`link_into_local_bin` refuses to replace a file that does not already point into the runtime, and uninstall removes only such links): the `codeman` launcher is `#!/usr/bin/env node`, and a non-interactive shell never reads the PATH line written to an interactive profile. The runtime's `node/bin` also goes on PATH and on the LaunchAgent's `svc_path`, since `npm install -g` puts AI CLIs beside that Node.js.
-
-⚠️ `no_admin_blocker` runs before the first download and stops for what this route cannot supply: a C/C++ toolchain on Linux (node-pty 1.1.0 compiles there; a node-pty with Linux prebuilds is what would lift this, and it is a dependency decision, not an installer one), musl, a platform nodejs.org or tmux-builds has no build for, and macOS below 15 (the tmux build's deployment target). ⚠️ Nothing between the "No-admin route" header and "End of the no-admin route" may run `sudo`, `ensure_sudo`, `run_as_root`, Homebrew or `xcode-select --install`; `run_as_root` itself refuses while `NO_ADMIN=1`, so a missed call site fails instead of prompting.
-
-⚠️ **git is judged by whether it works, never by `command -v`.** On a Mac without the Xcode Command Line Tools `/usr/bin/git` is a stub that opens Apple's install dialog, so `check_git` judges that path by `xcode-select -p` and never executes it; any other git is asked for `--version`. `scripts/git-hooks.mjs` has the matching guard (no `.git`, no `git` call), because postinstall runs it on every `npm install`. Without a working git the source is an archive (`fetch_source_archive`, GitHub's `archive/<ref>.tar.gz` or `CODEMAN_TARBALL_URL`) and the install directory carries the marker `.install-source`, which `detectInstallKind` reads as `archive` (the name is pinned across both files by `test/install-sh-invariants.test.ts`). ⚠️ An archive install is replaced as a WHOLE, never patched in place: nothing says which files a newer version dropped, and a stale `src/*.ts` would be compiled. The new tree is fetched and built in `<install dir>.new` and `finish_source_swap` moves it into place only after `npm run build` succeeded, so a failed update leaves the running install untouched; a re-run on a machine that has gained a working git stages a clone instead, which turns the install back into a git one. ⚠️ `download`/`download_to_stdout` resolve `DOWNLOADER` themselves (`require_downloader`): only `main()` used to set it, so a subcommand that downloads died on `set -u` with the message swallowed by the step log.
-
 ## Agent inspection and guarded submission
 
 These three operations are experimental across both CLI and HTTP, including the

docs/wiki/Installation.md

@@ -102,49 +102,6 @@ installs Tailscale itself non-interactively; a non-interactive run never renames
 machine and never starts a service. Everything the unattended steps print goes to
 `~/.codeman/install.log`, and the last lines of it are shown when a step fails.
 
-### Without administrator rights
-
-Codeman itself always lived in your home directory. What used `sudo` (or Homebrew on a
-Mac) were the things it needs first. On an account that has no administrator rights the
-installer says so in its summary (`Admin  not used (...)`) and gets those another way:
-
-| Needed                  | With administrator rights    | Without                                                                                                                             |
-| ----------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| Node.js 22              | system package or Homebrew   | The official tarball from nodejs.org, checked against the `SHASUMS256.txt` published beside it, unpacked to `~/.codeman/runtime/node`. |
-| tmux                    | system package or Homebrew   | The tmux project's own build ([tmux-builds](https://github.com/tmux/tmux-builds)), checked against a SHA-256 pinned in the installer, in `~/.codeman/runtime/bin`. |
-| git                     | system package or Xcode tools | Not installed. Without a working git, the source is downloaded as an archive instead of cloned.                                     |
-| Build toolchain (Linux) | system package               | Cannot be supplied. See below.                                                                                                      |
-
-This route is taken by itself when `sudo` is not installed, when the account is outside the
-`sudo`, `wheel` and `admin` groups and `sudo` will not run without a password, when the
-`sudo` password is refused, and on a Mac for an account that is not an administrator.
-`--no-admin` (or `CODEMAN_NO_ADMIN=1`) forces it on an account that does have the rights;
-`CODEMAN_NO_ADMIN=0` switches the detection off. Nothing on this route runs `sudo`,
-Homebrew or the Xcode tools installer.
-
-What to know about it:
-
-- **Linux needs make, a C++ compiler and python3 to be there already.** node-pty compiles
-  from source on Linux, and a compiler is a system package. The installer checks this
-  before it downloads anything and names what is missing. macOS needs no compiler.
-- **The tmux download needs macOS 15 or newer** (and x86_64 or arm64 on either system).
-  On an older Mac an administrator has to install tmux once (`brew install tmux`); the
-  rest then works without one.
-- **An install without git updates by re-running the install line**, not from App
-  Settings. The re-run builds the new version beside the old one and swaps it in only
-  after the build succeeded, so a failed download or build leaves the install as it was.
-  Once the machine has a working git, the next re-run turns the install into a normal
-  clone and in-app updates work again. On a Mac, "a working git" means the Xcode Command
-  Line Tools are installed: without them `/usr/bin/git` only opens Apple's install dialog,
-  and the installer never runs it.
-- **Tailscale works where it is already installed and your account may configure it.** On
-  Linux, installing it, logging in and granting serve rights each need an administrator
-  (`sudo tailscale set --operator=$USER`, once). Local network and this-machine access
-  need nothing, and `install.sh cloudflared` puts `cloudflared` in `~/.local/bin`.
-- `node`, `npm`, `npx` and `tmux` are linked from `~/.local/bin`, and
-  `~/.codeman/runtime/node/bin` is added to your PATH, so a CLI installed with
-  `npm install -g` is found as well.
-
 ## Route B: npm
 
 ```bash
@@ -237,7 +194,6 @@ If the dashboard loads and **+ New Session** opens, you are done. Continue to
 | Path                    | What                                                                                             |
 | ----------------------- | ------------------------------------------------------------------------------------------------ |
 | `~/.codeman/app`        | The installed code (installer route only).                                                        |
-| `~/.codeman/runtime`    | Node.js and tmux, when the installer downloaded them instead of using system packages ([no administrator rights](#without-administrator-rights)). |
 | `~/.codeman/`           | All state: `state.json`, settings, session history, push keys, TLS certs. See [Core Concepts](Core-Concepts). |
 | `~/codeman-cases/`      | Cases created from scratch. Linked cases stay wherever they already are.                          |
 | `~/.codeman/web.log`    | Log for a detached (`-d`) server.                                                                 |
@@ -261,7 +217,6 @@ Full detail, including logs and the self-updater, is in
 | Install route | How to update                                                     |
 | ------------- | ----------------------------------------------------------------- |
 | Installer     | Re-run the one-liner, or **App Settings → System → Updates** in the UI. |
-| Installer, without git | Re-run the one-liner. The in-app updater says so instead of offering an update. |
 | npm           | `npm update -g aicodeman`                                          |
 | git clone     | `git pull && npm install && npm run build`, then restart.          |
 | Docker Compose | Re-run `Start-Codeman.sh`. The in-app updater works too, and refuses a release that changes the container definition until you re-run the script. |
@@ -277,9 +232,7 @@ install.sh uninstall            # installer route
 npm uninstall -g aicodeman      # npm route
 ```
 
-The installer route asks before it removes `~/.codeman/runtime` (the Node.js and tmux it
-downloaded, if any), and keeps it by default when you installed CLIs there with
-`npm install -g`. Neither removes `~/.codeman/` or `~/codeman-cases/`. Delete those by hand if you want the
+Neither removes `~/.codeman/` or `~/codeman-cases/`. Delete those by hand if you want the
 state and your case folders gone as well, and check `~/codeman-cases/` first: linked cases
 point at directories you already had, but cases created from scratch have their only copy
 there.

package-lock.json

@@ -63,7 +63,7 @@
         "exceljs": "4.4.0",
         "fflate": "0.8.3",
         "pixelmatch": "^6.0.0",
-        "playwright": "^1.64.1",
+        "playwright": "^1.58.0",
         "pngjs": "^7.0.0",
         "postcss": "^8.5.15",
         "prettier": "^3.4.0",
@@ -9736,32 +9736,50 @@
       }
     },
     "node_modules/playwright": {
-      "version": "1.64.1",
-      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.64.1.tgz",
-      "integrity": "sha512-HCrVhHr5QQuwYoswEUGTb7gGp522yflbv/ST8nF4sFWGuLjQCt17Q/EubpGGSNKYn1tsTCPZxqHhHCfVURu7UA==",
+      "version": "1.60.0",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.60.0.tgz",
+      "integrity": "sha512-hheHdokM8cdqCb0lcE3s+zT4t4W+vvjpGxsZlDnikarzx8tSzMebh3UiFtgqwFwnTnjYQcsyMF8ei2mCO/tpeA==",
       "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
-        "playwright-core": "1.64.1"
+        "playwright-core": "1.60.0"
       },
       "bin": {
         "playwright": "cli.js"
       },
       "engines": {
-        "node": ">=20"
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "fsevents": "2.3.2"
       }
     },
     "node_modules/playwright-core": {
-      "version": "1.64.1",
-      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.64.1.tgz",
-      "integrity": "sha512-BC4s8y6SEVA6Q1rSxZTto8hI1KUI3xXlHGZgvGqP4IqPdI/a6FX9H29IDNz7vKo9l21b6LfYosScPL6M3xxyDQ==",
+      "version": "1.60.0",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.60.0.tgz",
+      "integrity": "sha512-9bW6zvX/m0lEbgTKJ6YppOKx8H3VOPBMOCFh2irXFOT4BbHgrx5hPjwJYLT40Lu+4qtD36qKc/Hn56StUW57IA==",
       "dev": true,
       "license": "Apache-2.0",
       "bin": {
         "playwright-core": "cli.js"
       },
       "engines": {
-        "node": ">=20"
+        "node": ">=18"
+      }
+    },
+    "node_modules/playwright/node_modules/fsevents": {
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
+      "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
       }
     },
     "node_modules/pngjs": {

package.json

@@ -133,7 +133,7 @@
     "exceljs": "4.4.0",
     "fflate": "0.8.3",
     "pixelmatch": "^6.0.0",
-    "playwright": "^1.64.1",
+    "playwright": "^1.58.0",
     "pngjs": "^7.0.0",
     "postcss": "^8.5.15",
     "prettier": "^3.4.0",

scripts/git-hooks.mjs

@@ -218,11 +218,6 @@ function canonicalPath(path) {
  * @returns {string | null}
  */
 export function resolveGitHooksDir(repoRoot) {
-  // Not a checkout at all (a source-archive or npm install): answer without running
-  // git. On a Mac without the Xcode Command Line Tools `/usr/bin/git` is a stub that
-  // opens Apple's "install the developer tools" dialog, and this runs on every
-  // `npm install`. `.git` is a directory in a clone and a file in a worktree.
-  if (!existsSync(join(repoRoot, '.git'))) return null;
   try {
     const top = git(repoRoot, ['rev-parse', '--show-toplevel']);
     if (!top || realpathSync(top) !== realpathSync(repoRoot)) return null;

src/types/update.ts

@@ -31,11 +31,8 @@ export type SupervisorKind = 'systemd' | 'launchd' | 'launchd-daemon' | 'docker-
  * How Codeman was installed. `git` and `docker-compose` can self-update in
  * place; `docker-compose` is a git checkout bind-mounted into the container, so
  * the pull/build happen on the host filesystem and survive container recreation.
- * `archive` is what `install.sh` leaves on a machine with no working git (its
- * no-admin route): the source unpacked from an archive, with nothing for the
- * in-app updater to pull into, so it updates by re-running the installer.
  */
-export type InstallKind = 'git' | 'docker-compose' | 'npm' | 'archive' | 'unknown';
+export type InstallKind = 'git' | 'docker-compose' | 'npm' | 'unknown';
 
 /**
  * Why an in-place container update is refused. Each is derived mechanically from

src/web/linked-cases-writer.ts

@@ -0,0 +1,117 @@
+/**
+ * @fileoverview The writer of the linked-cases registry (`linked-cases.json` in the data dir): case
+ * name to the absolute folder it stands for.
+ *
+ * Every read-modify-write of that file goes through `mutateLinkedCases()`, the same shape as
+ * `mutateSettingsFile()` (settings-writer.ts). The one direct writer is config-backup restore
+ * (`restoreConfigBackup()`), which must work on a file that does not parse. Readers keep reading the
+ * file directly; a write is atomic, so they never see half of one.
+ *
+ * - **Serialized.** Mutations run one at a time on a single promise chain, each one reading, changing
+ *   and writing before the next starts. Link, unlink, rename, a create in a custom folder and a clone
+ *   into one each used to read the file, check it and write it back on their own. Two clones that
+ *   claimed one name and finished together both passed the check, both answered success, and the
+ *   later write replaced the earlier one's entry. Any two writers could lose an entry the same way.
+ *   A check that must hold when the entry is written belongs inside `fn`: throwing there rejects that
+ *   caller only, and nothing is written.
+ * - **Atomic.** Each write goes to its own temp file beside the target and is renamed over it, so a
+ *   reader never sees a half-written file (quick-start would read one as an empty registry and resolve
+ *   a linked case to the cases dir instead), and a failed write leaves the previous file in place.
+ * - **Refuses a file it must not trust.** Only a missing (or empty) file starts from `{}`. A file that
+ *   cannot be read or is not a JSON object is left alone and the write throws
+ *   `LinkedCasesWriteRefusedError`: read as `{}`, the next link would write back its own entry alone
+ *   and unlink every other case.
+ */
+
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { dataPath } from '../config/instance.js';
+import { getErrorMessage } from '../types.js';
+
+export type LinkedCases = Record<string, string>;
+
+/** Resolved at call time, like every other `dataPath()` caller that tests point at a temp HOME. */
+export function linkedCasesPath(): string {
+  return dataPath('linked-cases.json');
+}
+
+/** A write refused because the existing registry must not be overwritten. The message is user-facing. */
+export class LinkedCasesWriteRefusedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'LinkedCasesWriteRefusedError';
+  }
+}
+
+async function readLinkedCasesForWrite(path: string): Promise<LinkedCases> {
+  let raw: string;
+  try {
+    raw = await fs.readFile(path, 'utf-8');
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return {};
+    throw new LinkedCasesWriteRefusedError(
+      `Cannot read ${path} (${(err as Error).message}), so the linked cases were not changed.`
+    );
+  }
+  if (raw.trim() === '') return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    parsed = undefined;
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new LinkedCasesWriteRefusedError(
+      `${path} is not a valid JSON object, so the linked cases were not changed (saving would have unlinked every other case). Fix or delete the file, or restore it from a config backup, then try again.`
+    );
+  }
+  return parsed as LinkedCases;
+}
+
+async function writeLinkedCasesFile(path: string, linked: LinkedCases): Promise<void> {
+  // Through a symlink, as the plain writeFile this replaces did: the rename lands on the real file.
+  const target = await fs.realpath(path).catch(() => path);
+  await fs.mkdir(dirname(target), { recursive: true });
+  // A plain writeFile kept the file's permissions; a rename would not, so the temp file takes them.
+  const mode = await fs.stat(target).then(
+    (s) => s.mode & 0o777,
+    () => undefined
+  );
+  const tmp = `${target}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(tmp, JSON.stringify(linked, null, 2), mode === undefined ? undefined : { mode });
+    // The creation mode is masked by the umask; the existing file's bits are put back as they were.
+    if (mode !== undefined) await fs.chmod(tmp, mode);
+    await fs.rename(tmp, target);
+  } catch (err) {
+    await fs.rm(tmp, { force: true }).catch(() => {});
+    throw err;
+  }
+}
+
+let mutationChain: Promise<unknown> = Promise.resolve();
+
+/**
+ * Run one change to the linked-cases registry. `fn` receives a copy of the current registry and
+ * returns the registry to write, or `undefined` to write nothing; it may throw to refuse the change
+ * (its error rejects this call as thrown). Resolves with the registry before and after the change
+ * (`after` is `undefined` when nothing was written). A refused or failed mutation rejects its own
+ * caller only; the chain keeps going.
+ */
+export function mutateLinkedCases(
+  fn: (current: LinkedCases) => LinkedCases | undefined
+): Promise<{ before: LinkedCases; after: LinkedCases | undefined }> {
+  const run = mutationChain.then(async () => {
+    const path = linkedCasesPath();
+    const before = await readLinkedCasesForWrite(path).catch((err: unknown) => {
+      console.warn(`[linked-cases] write refused: ${getErrorMessage(err)}`);
+      throw err;
+    });
+    const after = fn({ ...before });
+    if (after) await writeLinkedCasesFile(path, after);
+    return { before, after };
+  });
+  mutationChain = run.catch(() => {});
+  return run;
+}

src/web/public/settings-ui.js

@@ -1940,14 +1940,10 @@ Object.assign(CodemanApp.prototype, {
     // `docker-compose` self-updates in place like `git` does — the container
     // restarts itself. Anything else cannot.
     if (data.installKind && data.installKind !== 'git' && data.installKind !== 'docker-compose') {
-      // `archive` = installed by install.sh on a machine with no working git: the
-      // installer replaces it with a fresh build, so point there, not at npm.
       const hint =
         data.supervisor === 'docker-compose'
           ? 'Update from the Docker host with <code>docker/Start-Codeman.sh</code>.'
-          : data.installKind === 'archive'
-            ? 'It was installed without git. Re-run the installer to update: <code>curl -fsSL https://getcodeman.com/install | bash</code>'
-            : 'Update with <code>npm i -g aicodeman@latest</code>.';
+          : 'Update with <code>npm i -g aicodeman@latest</code>.';
       this._setUpdateResult(`This install can't update itself (${escapeHtml(data.installKind)}). ${hint}`);
       return;
     }

src/web/routes/case-routes.ts

@@ -86,6 +86,7 @@ import {
   SettingsWriteRefusedError,
   settingsWriteErrorResponse,
 } from '../settings-writer.js';
+import { LinkedCasesWriteRefusedError, linkedCasesPath, mutateLinkedCases } from '../linked-cases-writer.js';
 import { isMultiUserMode } from '../../config/multiuser.js';
 import type { AuthUser } from '../../types.js';
 import { SseEvent } from '../sse-events.js';
@@ -126,7 +127,6 @@ import {
   writeRemoteHosts,
 } from '../../remote-hosts.js';
 
-const LINKED_CASES_FILE = dataPath('linked-cases.json');
 const CODEMAN_CONFIG_DIR = getDataDir();
 const SAFE_CASE_NAME = /^[a-zA-Z0-9_-]+$/;
 const DOCKER_EXPORTS_DIR = dataPath('docker-exports');
@@ -212,11 +212,21 @@ function agentCreatedInfo(marker: AgentCaseMarker): NonNullable<CaseInfo['agentC
   };
 }
 
-/** Read and parse linked-cases.json, returning empty object on missing/invalid file. */
+/**
+ * Read and parse linked-cases.json, returning empty object on missing/invalid file. For reads only:
+ * every write goes through `mutateLinkedCases()`, which re-reads the file inside its own critical
+ * section and refuses one that does not parse.
+ */
 async function readLinkedCases(): Promise<Record<string, string>> {
-  return readJsonConfig<Record<string, string>>(LINKED_CASES_FILE, 'linked cases', {});
+  return readJsonConfig<Record<string, string>>(linkedCasesPath(), 'linked cases', {});
 }
 
+/** A conflict thrown from inside a `mutateLinkedCases()` callback: answered 409, nothing written. */
+function linkedConflict(message: string): Error {
+  return Object.assign(new Error(message), { conflict: true });
+}
+const isLinkedConflict = (err: unknown): boolean => (err as { conflict?: boolean }).conflict === true;
+
 /**
  * Resolve a case name to its directory path, checking linked cases first, then the
  * user's case space (per-user in multi-user mode, the shared CASES_DIR otherwise).
@@ -553,15 +563,11 @@ export function registerCaseRoutes(
       made.push(join(casePath, '.claude')); // before the write, so a half-written one is undone too
       await writeHooksConfig(casePath);
 
-      const codemanDir = getDataDir();
-      if (!existsSync(codemanDir)) mkdirSync(codemanDir, { recursive: true });
-      // Re-read right before writing, so a case linked since the check above is not dropped. This only
-      // narrows the window: like POST /api/cases/link, the registry write is not serialized, and two
-      // requests that both read before either writes can still lose one entry.
-      const fresh = await readLinkedCases();
-      if (fresh[name]) throw Object.assign(new Error(`Case "${name}" was just linked`), { conflict: true });
-      fresh[name] = casePath;
-      await fs.writeFile(LINKED_CASES_FILE, JSON.stringify(fresh, null, 2));
+      // The check above ran before the scaffold; a case linked since then wins and this call is undone.
+      await mutateLinkedCases((current) => {
+        if (current[name]) throw linkedConflict(`Case "${name}" was just linked`);
+        return { ...current, [name]: casePath };
+      });
 
       ctx.broadcast(SseEvent.CaseCreated, { name, path: casePath });
       return { success: true, data: { case: { name, path: casePath } } };
@@ -569,10 +575,14 @@ export function registerCaseRoutes(
       // Undo only what this call made. The whole folder if we created it, otherwise the scaffold
       // entries inside the empty folder the user picked; never anything else.
       for (const p of made.reverse()) await fs.rm(p, { recursive: true, force: true }).catch(() => undefined);
-      if ((err as { conflict?: boolean }).conflict) {
+      if (isLinkedConflict(err)) {
         reply.code(409);
         return createErrorResponse(ApiErrorCode.ALREADY_EXISTS, getErrorMessage(err));
       }
+      if (err instanceof LinkedCasesWriteRefusedError) {
+        reply.code(409);
+        return createErrorResponse(ApiErrorCode.CONFLICT, err.message);
+      }
       reply.code(500);
       return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
     }
@@ -890,20 +900,20 @@ export function registerCaseRoutes(
       }
 
       if (customPath !== undefined) {
-        // Re-read right before writing so a case linked while git ran is not dropped. Like
-        // POST /api/cases/link the write is not serialized, so this only narrows the window.
+        // The name was checked before git ran, which can take minutes. Checked again where the entry is
+        // written, so of two clones that claimed one name only the first to finish links it.
         try {
-          const fresh = await readLinkedCases();
-          if (fresh[name])
-            throw Object.assign(new Error(`Case "${name}" was linked while the clone ran`), { conflict: true });
-          fresh[name] = casePath;
-          await fs.writeFile(LINKED_CASES_FILE, JSON.stringify(fresh, null, 2));
+          await mutateLinkedCases((current) => {
+            if (current[name]) throw linkedConflict(`Case "${name}" was linked while the clone ran`);
+            return { ...current, [name]: casePath };
+          });
         } catch (err) {
           // The clone itself succeeded: keep the folder (the user waited for it) and say where it is.
-          const conflict = (err as { conflict?: boolean }).conflict;
-          reply.code(conflict ? 409 : 500);
+          const conflict = isLinkedConflict(err);
+          const refused = err instanceof LinkedCasesWriteRefusedError;
+          reply.code(conflict || refused ? 409 : 500);
           return createErrorResponse(
-            conflict ? ApiErrorCode.ALREADY_EXISTS : ApiErrorCode.OPERATION_FAILED,
+            conflict ? ApiErrorCode.ALREADY_EXISTS : refused ? ApiErrorCode.CONFLICT : ApiErrorCode.OPERATION_FAILED,
             `Cloned into ${casePath} but could not register the case (${getErrorMessage(err)}). Use Link Existing to add it.`
           );
         }
@@ -1713,28 +1723,17 @@ export function registerCaseRoutes(
       return createErrorResponse(ApiErrorCode.ALREADY_EXISTS, 'A case with this name already exists in codeman-cases.');
     }
 
-    // Load existing linked cases
-    const linkedCases = await readLinkedCases();
-
-    // Check if name is already linked
-    if (linkedCases[name]) {
-      return createErrorResponse(
-        ApiErrorCode.ALREADY_EXISTS,
-        `Case "${name}" is already linked to ${linkedCases[name]}`
-      );
-    }
-
-    // Save the linked case
-    linkedCases[name] = expandedPath;
+    // The name check and the write are one step, so two links of one name cannot both succeed.
     try {
-      const codemanDir = getDataDir();
-      if (!existsSync(codemanDir)) {
-        mkdirSync(codemanDir, { recursive: true });
-      }
-      await fs.writeFile(LINKED_CASES_FILE, JSON.stringify(linkedCases, null, 2));
+      await mutateLinkedCases((current) => {
+        if (current[name]) throw linkedConflict(`Case "${name}" is already linked to ${current[name]}`);
+        return { ...current, [name]: expandedPath };
+      });
       ctx.broadcast(SseEvent.CaseLinked, { name, path: expandedPath });
       return { success: true, data: { case: { name, path: expandedPath } } };
     } catch (err) {
+      if (isLinkedConflict(err)) return createErrorResponse(ApiErrorCode.ALREADY_EXISTS, getErrorMessage(err));
+      if (err instanceof LinkedCasesWriteRefusedError) return createErrorResponse(ApiErrorCode.CONFLICT, err.message);
       return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
     }
   });
@@ -1815,13 +1814,19 @@ export function registerCaseRoutes(
     // must not unlink one either; skip so control falls through to their local delete.
     const linkedCases = await readLinkedCases();
     if (linkedCases[name] && (!isMultiUserMode() || isAdmin(req))) {
-      delete linkedCases[name];
       try {
-        await fs.writeFile(LINKED_CASES_FILE, JSON.stringify(linkedCases, null, 2));
+        // Removes this one entry from the registry as it is now, keeping any linked since the read above.
+        await mutateLinkedCases((current) => {
+          if (!Object.hasOwn(current, name)) return undefined;
+          const next = { ...current };
+          delete next[name];
+          return next;
+        });
         ctx.broadcast(SseEvent.CaseDeleted, { name, type: 'unlinked' });
         await forgetCaseDefault();
         return { success: true, data: { name } };
       } catch (err) {
+        if (err instanceof LinkedCasesWriteRefusedError) return createErrorResponse(ApiErrorCode.CONFLICT, err.message);
         return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
       }
     }
@@ -2007,7 +2012,6 @@ export function registerCaseRoutes(
           stopped++;
         }
         if (moveFolder) await moveCaseFolder(oldPath, newPath);
-        const originalLinks = isLinked ? await readLinkedCases() : undefined;
         // The settings.json values this rename replaced, set only once it wrote them. A failure puts back
         // these keys alone, so a settings save that landed in between is kept.
         let settingsUndo: Record<string, unknown> | undefined;
@@ -2027,16 +2031,19 @@ export function registerCaseRoutes(
               settingsUndo = Object.fromEntries(keys.map((k) => [k, before[k]]));
             }
           }
-          if (originalLinks) {
-            const links = { ...originalLinks };
-            delete links[name];
-            links[newName] = newPath;
-            try {
-              await fs.writeFile(LINKED_CASES_FILE, JSON.stringify(links, null, 2));
-            } catch (err) {
-              await fs.writeFile(LINKED_CASES_FILE, JSON.stringify(originalLinks, null, 2)).catch(() => {});
-              throw err;
-            }
+          if (isLinked) {
+            // Checked again where the entry is written: the checks above ran before the sessions were
+            // stopped and the folder moved. A failed write leaves the registry as it was.
+            await mutateLinkedCases((current) => {
+              if (current[newName]) throw new CaseRenameError('EXISTS', `A case named "${newName}" already exists`);
+              if (current[name] !== oldPath) {
+                throw new CaseRenameError('BUSY', `Case "${name}" was changed while it was being renamed`);
+              }
+              const links = { ...current };
+              delete links[name];
+              links[newName] = newPath;
+              return links;
+            });
           }
         } catch (err) {
           // The folder moved but the registries did not follow: put settings.json and the folder back
@@ -2081,6 +2088,9 @@ export function registerCaseRoutes(
               : ApiErrorCode.OPERATION_FAILED;
         return fail(status, code, err.message, { renameCode: err.code, stoppedSessions: stopped });
       }
+      if (err instanceof LinkedCasesWriteRefusedError) {
+        return fail(409, ApiErrorCode.CONFLICT, err.message, { stoppedSessions: stopped });
+      }
       return fail(500, ApiErrorCode.OPERATION_FAILED, getErrorMessage(err), { stoppedSessions: stopped });
     }
   });

src/web/self-update.ts

@@ -462,26 +462,12 @@ export function isRunningInContainer(): boolean {
   return process.env.CODEMAN_IN_CONTAINER === '1' || existsSync('/.dockerenv');
 }
 
-/**
- * Marker `install.sh` writes into an install directory whose source came from an
- * archive instead of a git clone (`SOURCE_MARKER` there; the two names are pinned
- * to each other by `test/install-sh-invariants.test.ts`).
- */
-export const ARCHIVE_INSTALL_MARKER = '.install-source';
-
-/** How an `archive` install updates: the installer replaces it with a fresh build. */
-export const ARCHIVE_UPDATE_HINT =
-  'This install has no git checkout, so it cannot update in place. Re-run the installer to update: ' +
-  'curl -fsSL https://getcodeman.com/install | bash';
-
-export function detectInstallKind(dir: string): InstallKind {
+function detectInstallKind(dir: string): InstallKind {
   // A container whose code is a bind-mounted checkout updates in place (the pull
   // and build land on the host filesystem and survive container recreation). A
   // container WITHOUT that mount runs a baked image copy — a pull there would go
   // to the writable layer and vanish on the next `up`, so it is not updatable.
   if (existsSync(join(dir, '.git'))) return isRunningInContainer() ? 'docker-compose' : 'git';
-  // install.sh on a machine with no working git: the source from an archive.
-  if (existsSync(join(dir, ARCHIVE_INSTALL_MARKER))) return 'archive';
   // Global npm install ships only dist/ (no src/, no .git).
   if (!existsSync(join(dir, 'src'))) return 'npm';
   return 'unknown';
@@ -719,9 +705,7 @@ export async function checkForUpdate(): Promise<UpdateCheckResult> {
       error:
         info.installKind === 'unknown' && isRunningInContainer()
           ? 'This container runs a baked image copy with no repository mounted — self-update is unavailable. See docs/docker-self-update.md.'
-          : info.installKind === 'archive'
-            ? ARCHIVE_UPDATE_HINT
-            : 'Not a git install — self-update is unavailable.',
+          : 'Not a git install — self-update is unavailable.',
     };
   }
 
@@ -845,9 +829,7 @@ export async function startUpdate(): Promise<StartUpdateResult> {
       code: 'not-git',
       message: isRunningInContainer()
         ? 'This container has no repository mounted. Update from the host with docker/Start-Codeman.sh.'
-        : info.installKind === 'archive'
-          ? ARCHIVE_UPDATE_HINT
-          : 'This is not a git install. Update with: npm i -g aicodeman@latest',
+        : 'This is not a git install. Update with: npm i -g aicodeman@latest',
     };
   }
   const existing = readCurrentUpdateStatus();

test/edit-history-sync.test.ts

@@ -428,20 +428,14 @@ describe('EditHistorySync', () => {
     host.append('main', editLine('t1', T0, '/w/a.ts'));
     const orig = host.read;
     let first = true;
-    let inRead!: () => void;
-    const reachedRead = new Promise<void>((r) => (inRead = r));
     host.read = async (...a) => {
       if (first) {
         first = false;
-        inRead();
         await gate;
       }
       return orig(...a);
     };
     const slow = sync.sync(local);
-    // Only once s1 holds the gate: the sessions load their stores independently, so a later one
-    // could reach the read first, take the gate and hang the loop below before `release()`.
-    await reachedRead;
     for (let i = 1; i <= MAX_LOADED_STORES + 1; i++) await sync.sync({ ...local, id: `s1-${i}` });
     release();
     expect(await slow).toEqual({ state: 'ok' });

test/git-hooks.test.ts

@@ -18,7 +18,6 @@ import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 import { execFileSync, spawnSync } from 'node:child_process';
 import {
   chmodSync,
-  existsSync,
   mkdirSync,
   mkdtempSync,
   readFileSync,
@@ -172,26 +171,6 @@ describe('resolveGitHooksDir (temp repos)', () => {
     expect(resolveGitHooksDir(dir)).toBeNull();
   });
 
-  it('never runs git for a directory that has no .git', () => {
-    // A source-archive or npm install. On a Mac without the Xcode Command Line Tools
-    // /usr/bin/git is a stub that opens Apple's install dialog, and postinstall calls this
-    // on every `npm install`, so "not a checkout" must be answered without spawning git.
-    const dir = join(scratch, `plain-${++counter}`);
-    const bin = join(scratch, `fakebin-${counter}`);
-    const ran = join(scratch, `git-ran-${counter}`);
-    mkdirSync(dir);
-    mkdirSync(bin);
-    writeFileSync(join(bin, 'git'), `#!/bin/sh\necho ran > "${ran}"\nexit 1\n`, { mode: 0o755 });
-    const path = process.env.PATH;
-    process.env.PATH = `${bin}:${path}`;
-    try {
-      expect(resolveGitHooksDir(dir)).toBeNull();
-    } finally {
-      process.env.PATH = path;
-    }
-    expect(existsSync(ran), 'git was executed for a directory with no .git').toBe(false);
-  });
-
   it('returns null when a repo-local core.hooksPath points outside the repo', () => {
     const repo = newRepo();
     const outside = join(scratch, `shared-hooks-${counter}`);

test/install-sh-invariants.test.ts

@@ -12,12 +12,9 @@
 
 import { describe, expect, it } from 'vitest';
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { STOCK_CLIS } from '../src/config/cli-registry/stock.js';
-import { ARCHIVE_INSTALL_MARKER } from '../src/web/self-update.js';
 
 const INSTALL_SH = fileURLToPath(new URL('../install.sh', import.meta.url));
 const SOURCE = readFileSync(INSTALL_SH, 'utf-8');
@@ -539,410 +536,3 @@ it('install.sh never contains the unauthenticated tunnel opt-in', () => {
   expect(SOURCE).not.toContain('CODEMAN_ALLOW_UNAUTHENTICATED_TUNNEL');
   expect(SOURCE).not.toContain('--allow-unauthenticated-tunnel');
 });
-
-describe('install.sh no-admin route', () => {
-  // The route that installs without administrator rights: Node.js and tmux are downloaded
-  // into the home folder, and a machine with no working git gets the source as an archive.
-  // What can go wrong here is quiet: a sudo prompt that cannot succeed, a binary unpacked
-  // before its checksum was checked, Apple's git stub opening a dialog. So each is pinned.
-  const fn = (name: string, until: string) => {
-    const start = SOURCE.indexOf(`${name}() {`);
-    expect(start, `${name}() missing`).toBeGreaterThan(-1);
-    const end = SOURCE.indexOf(until, start);
-    expect(end, `${until} missing after ${name}()`).toBeGreaterThan(start);
-    return SOURCE.slice(start, end);
-  };
-  const sectionStart = SOURCE.indexOf('# No-admin route: everything into the home folder');
-  const sectionEnd = SOURCE.indexOf('# ---- End of the no-admin route');
-  const section = SOURCE.slice(sectionStart, sectionEnd);
-  const sectionCode = section.split('\n').filter((line) => !/^\s*#/.test(line));
-
-  /** Run a snippet with install.sh sourced as a library, in a real bash. */
-  const drive = (script: string, env: NodeJS.ProcessEnv = {}) => {
-    const clean = { ...process.env, ...env };
-    for (const key of ['CODEMAN_NO_ADMIN', 'CODEMAN_TARBALL_URL', 'CODEMAN_REPO_URL', 'CODEMAN_BRANCH']) {
-      if (!(key in env)) delete clean[key];
-    }
-    const full = `set -euo pipefail\nexport CODEMAN_INSTALL_SH_LIB=1\n. "$1"\n${script}`;
-    return spawnSync('bash', ['-c', full, 'bash', INSTALL_SH], { encoding: 'utf-8', timeout: 30_000, env: clean });
-  };
-
-  it('has its section markers, in order', () => {
-    expect(sectionStart).toBeGreaterThan(-1);
-    expect(sectionEnd).toBeGreaterThan(sectionStart);
-    expect(sectionCode.length).toBeGreaterThan(100);
-  });
-
-  it('never runs sudo, Homebrew or the Xcode tools installer', () => {
-    // Command position only: the messages in this section name `brew install tmux` and
-    // `apt-get install` as things an administrator can run, which is prose.
-    const banned =
-      /(?:^|[;&|]|\b(?:if|then|else|do|while|until)\s|!\s)\s*(?:sudo|brew|ensure_sudo|run_as_root|ensure_homebrew|sudo_session_start|sudo_session_try)\b/;
-    const offenders = sectionCode.filter((line) => banned.test(line) || /xcode-select\s+--install/.test(line));
-    expect(offenders, `privileged call on the no-admin route:\n  ${offenders.join('\n  ')}`).toEqual([]);
-  });
-
-  it('pins a SHA-256 for every tmux build it can download', () => {
-    const digests = fn('tmux_build_sha256', '\n}\n');
-    for (const platform of ['linux-x86_64', 'linux-arm64', 'macos-arm64', 'macos-x86_64']) {
-      expect(digests, `no digest for ${platform}`).toMatch(new RegExp(`${platform}\\)\\s+printf '[0-9a-f]{64}'`));
-      // Every platform the name mapper can produce has a digest, and nothing else does.
-      expect(fn('userspace_tmux_platform', '\n}\n')).toContain(`printf '${platform}'`);
-    }
-    expect(digests.match(/[0-9a-f]{64}/g)?.length).toBe(4);
-    // The asset name and URL are built from the same version the digests were taken for.
-    const install = fn('install_tmux_userspace', '\n}\n');
-    expect(install).toContain('name="tmux-$TMUX_BUILD_VERSION-$platform.tar.gz"');
-    expect(install).toContain('tmux-builds/releases/download/v$TMUX_BUILD_VERSION/$name');
-  });
-
-  it('checks a download before unpacking or running it', () => {
-    for (const name of ['install_node_userspace', 'install_tmux_userspace']) {
-      const body = fn(name, '\n}\n');
-      const verify = body.indexOf('verify_sha256 "$tmp/$name" "$sha"');
-      expect(verify, `${name} never verifies its download`).toBeGreaterThan(-1);
-      expect(body.indexOf('tar -xzf'), `${name} unpacks before verifying`).toBeGreaterThan(verify);
-    }
-    // An empty expected digest must never pass (a lookup that came back with nothing).
-    expect(fn('verify_sha256', '\n}\n')).toContain('[[ -n "$want" ]] || return 1');
-  });
-
-  it('never executes /usr/bin/git on a Mac before the developer tools are proven', () => {
-    // Without the Command Line Tools that path is a stub that opens Apple's install dialog.
-    const body = fn('check_git', '\n}\n');
-    const apple = body.indexOf('"$git_bin" == "/usr/bin/git"');
-    const gate = body.indexOf('xcode-select -p');
-    const run = body.indexOf('"$git_bin" --version');
-    expect(apple).toBeGreaterThan(-1);
-    expect(gate).toBeGreaterThan(apple);
-    // The Apple branch returns on its own evidence; only other gits are executed.
-    expect(body.slice(gate, run)).toMatch(/\n\s+return 1\n\s+fi\n/);
-  });
-
-  it('judges git by whether it runs', () => {
-    const result = drive(`
-      bin=$(mktemp -d); trap 'rm -rf "$bin"' EXIT
-      printf '#!/bin/sh\\nexit 127\\n' > "$bin/git"; chmod +x "$bin/git"
-      PATH="$bin:$PATH"; hash -r
-      check_git && echo "broken=present" || echo "broken=missing"
-      printf '#!/bin/sh\\nexit 0\\n' > "$bin/git"
-      check_git && echo "working=present" || echo "working=missing"
-      # A Mac whose only git is Apple's stub, with and without the developer tools.
-      uname() { echo Darwin; }
-      command() { if [[ "$1" == "-v" && "$2" == "git" ]]; then echo /usr/bin/git; else builtin command "$@"; fi; }
-      xcode-select() { return 2; }
-      check_git && echo "stub=present" || echo "stub=missing"
-      mkdir -p "$bin/dev/usr/bin"; cp "$bin/git" "$bin/dev/usr/bin/git"
-      xcode-select() { echo "$bin/dev"; }
-      check_git && echo "tools=present" || echo "tools=missing"
-    `);
-    expect(result.status, result.stderr).toBe(0);
-    expect(result.stdout).toContain('broken=missing');
-    expect(result.stdout).toContain('working=present');
-    expect(result.stdout).toContain('stub=missing');
-    expect(result.stdout).toContain('tools=present');
-  });
-
-  it('decides the route from what the account may do, without asking for a password', () => {
-    // `sudo -v` would prompt, and a refused password is reported to the administrator.
-    expect(fn('resolve_admin_mode', '\n}\n')).not.toMatch(/sudo -v/);
-    const result = drive(`
-      [[ $EUID -ne 0 ]] || { echo "skipped=root"; exit 0; }
-      has_sudo=1
-      command() { if [[ "$1" == "-v" && "$2" == "sudo" ]]; then [[ "$has_sudo" == "1" ]]; elif [[ "$1" == "-v" && "$2" == "brew" ]]; then return 1; else builtin command "$@"; fi; }
-      groups="users"; id() { echo "$groups"; }
-      sudo_ok=1; sudo() { return "$sudo_ok"; }
-      probe() { NO_ADMIN="$1"; NO_ADMIN_REASON=""; resolve_admin_mode; echo "$2=$NO_ADMIN"; }
-      uname() { echo Linux; }
-      has_sudo=0; probe "" linux_no_sudo; has_sudo=1
-      probe "" linux_not_in_group
-      groups="users sudo"; probe "" linux_sudo_group
-      groups="users wheel"; probe "" linux_wheel_group
-      groups="users"; sudo_ok=0; probe "" linux_passwordless; sudo_ok=1
-      probe 0 forced_off
-      groups="users sudo"; probe 1 forced_on
-      uname() { echo Darwin; }
-      groups="staff everyone"; probe "" mac_standard
-      groups="staff admin"; probe "" mac_admin
-    `);
-    expect(result.status, result.stderr).toBe(0);
-    if (result.stdout.includes('skipped=root')) return;
-    for (const expected of [
-      'linux_no_sudo=1',
-      'linux_not_in_group=1',
-      'linux_sudo_group=0',
-      'linux_wheel_group=0',
-      'linux_passwordless=0',
-      'forced_off=0',
-      'forced_on=1',
-      'mac_standard=1',
-      'mac_admin=0',
-    ]) {
-      expect(result.stdout, result.stdout).toContain(expected);
-    }
-  });
-
-  it('stops before the first download when the machine cannot finish the install', () => {
-    // No compiler on Linux, or a Mac older than the tmux build supports: say so while it
-    // costs nothing, not after 50 MB of Node.js.
-    const stop = (env: Record<string, string>) => {
-      const r = drive(
-        `
-        NONINTERACTIVE=1; NO_ADMIN=1; NO_ADMIN_REASON=test
-        download() { echo "DOWNLOAD $1"; }
-        download_to_stdout() { echo "DOWNLOAD $1"; }
-        check_node() { return 1; }; check_tmux() { return 1; }; check_git() { return 0; }
-        detect_arch() { echo "$DRIVE_ARCH"; }
-        check_build_tools() { [[ "$DRIVE_TOOLS" == "1" ]]; }; missing_build_tools() { printf 'make, g++'; }
-        macos_major_version() { printf '%s' "$DRIVE_MACOS"; }
-        is_musl_libc() { [[ "$DRIVE_MUSL" == "1" ]]; }
-        ask_dependencies_no_admin "$DRIVE_OS"
-      `,
-        { DRIVE_ARCH: 'x64', DRIVE_TOOLS: '1', DRIVE_MACOS: '26', DRIVE_MUSL: '0', ...env }
-      );
-      expect(r.status, 'the installer must stop').toBe(1);
-      expect(r.stdout + r.stderr, 'something was downloaded before the stop').not.toContain('DOWNLOAD');
-      return r.stderr;
-    };
-    expect(stop({ DRIVE_OS: 'linux', DRIVE_TOOLS: '0' })).toMatch(/make, g\+\+[\s\S]*administrator/);
-    expect(stop({ DRIVE_OS: 'macos', DRIVE_ARCH: 'arm64', DRIVE_MACOS: '14' })).toMatch(/macOS 15 or newer/);
-    expect(stop({ DRIVE_OS: 'linux', DRIVE_MUSL: '1' })).toMatch(/musl/);
-    expect(stop({ DRIVE_OS: 'linux', DRIVE_ARCH: 'armv7' })).toMatch(/no Node\.js download/);
-  });
-
-  it('picks the right Node.js tarball out of SHASUMS256.txt', () => {
-    const sha = (c: string) => c.repeat(64);
-    const sums = [
-      `${sha('a')}  node-v22.23.4-aix-ppc64.tar.gz`,
-      `${sha('b')}  node-v22.23.4-darwin-arm64.tar.gz`,
-      `${sha('c')}  node-v22.23.4-darwin-arm64.tar.xz`,
-      `${sha('d')}  node-v22.23.4-linux-x64-musl.tar.gz`,
-      `${sha('e')}  node-v22.23.4-linux-x64.tar.gz`,
-      `nothex  node-v22.23.4-linux-arm64.tar.gz`,
-    ].join('\n');
-    const result = drive(
-      `
-      printf '%s\\n' "$SUMS" | pick_node_tarball linux-x64
-      printf '%s\\n' "$SUMS" | pick_node_tarball darwin-arm64
-      printf '%s\\n' "$SUMS" | pick_node_tarball linux-arm64 || echo "arm64=refused"
-      printf '%s\\n' "$SUMS" | pick_node_tarball linux-s390x || echo "s390x=none"
-    `,
-      { SUMS: sums }
-    );
-    expect(result.status, result.stderr).toBe(0);
-    expect(result.stdout).toContain(`${sha('e')} node-v22.23.4-linux-x64.tar.gz`);
-    expect(result.stdout).toContain(`${sha('b')} node-v22.23.4-darwin-arm64.tar.gz`);
-    expect(result.stdout).not.toContain('musl');
-    // A line whose checksum is not 64 hex digits is not a checksum to trust.
-    expect(result.stdout).toContain('arm64=refused');
-    expect(result.stdout).toContain('s390x=none');
-  });
-
-  it('refuses a download whose checksum does not match', () => {
-    const result = drive(`
-      f=$(mktemp); trap 'rm -f "$f"' EXIT
-      printf 'codeman' > "$f"
-      good=$(sha256_file "$f")
-      echo "len=\${#good}"
-      verify_sha256 "$f" "$good" && echo "match=ok"
-      verify_sha256 "$f" "\${good%?}x" && echo "tampered=accepted" || echo "tampered=refused"
-      verify_sha256 "$f" "" && echo "empty=accepted" || echo "empty=refused"
-    `);
-    expect(result.status, result.stderr).toBe(0);
-    expect(result.stdout).toContain('len=64');
-    expect(result.stdout).toContain('match=ok');
-    expect(result.stdout).toContain('empty=refused');
-    // The last digit swapped for a character no digest contains.
-    expect(result.stdout).toContain('tampered=refused');
-  });
-
-  it('installs from an archive without git, then replaces that install beside itself', () => {
-    const scratch = mkdtempSync(join(tmpdir(), 'codeman-archive-install-'));
-    try {
-      const make = (version: string) => {
-        const tree = join(scratch, `src-${version}`, `Codeman-${version}`);
-        mkdirSync(join(tree, 'src'), { recursive: true });
-        writeFileSync(join(tree, 'package.json'), `{ "version": "${version}" }\n`);
-        writeFileSync(join(tree, 'src', `only-in-${version}.ts`), '');
-        const tarball = join(scratch, `${version}.tar.gz`);
-        const tar = spawnSync('tar', ['-czf', tarball, '-C', join(scratch, `src-${version}`), `Codeman-${version}`]);
-        expect(tar.status, String(tar.stderr)).toBe(0);
-        return tarball;
-      };
-      const first = make('1.0.0');
-      const second = make('2.0.0');
-      const app = join(scratch, 'app');
-      const script = `
-        LOG_FILE=/dev/null
-        check_git() { return 1; }
-        download() { cp "\${1#file://}" "$2"; }
-        run_step() { shift; "$@"; }
-        install_or_update_repo
-        echo "staging=[$SOURCE_STAGING] cwd=$(pwd)"
-        finish_source_swap
-        echo "after=$(pwd)"
-      `;
-      const run = (tarball: string) =>
-        drive(script, { CODEMAN_INSTALL_DIR: app, CODEMAN_TARBALL_URL: `file://${tarball}`, HOME: scratch });
-
-      // First install: straight into the install directory, marked as an archive install.
-      const fresh = run(first);
-      expect(fresh.status, fresh.stderr).toBe(0);
-      expect(fresh.stdout).toContain('staging=[]');
-      expect(readFileSync(join(app, 'package.json'), 'utf-8')).toContain('1.0.0');
-      expect(existsSync(join(app, ARCHIVE_INSTALL_MARKER))).toBe(true);
-
-      // Second run: the new tree is built BESIDE the old one, which stays whole until the swap.
-      writeFileSync(join(app, 'built-by-1.0.0'), '');
-      const update = run(second);
-      expect(update.status, update.stderr).toBe(0);
-      expect(update.stdout).toContain(`staging=[${app}.new] cwd=${app}.new`);
-      expect(update.stdout).toContain(`after=${app}`);
-      expect(readFileSync(join(app, 'package.json'), 'utf-8')).toContain('2.0.0');
-      // A whole replacement: what the old version had and the new one dropped is gone.
-      expect(existsSync(join(app, 'src', 'only-in-1.0.0.ts'))).toBe(false);
-      expect(existsSync(join(app, 'built-by-1.0.0'))).toBe(false);
-      expect(existsSync(join(app, ARCHIVE_INSTALL_MARKER))).toBe(true);
-      expect(existsSync(`${app}.new`)).toBe(false);
-      expect(existsSync(`${app}.old`)).toBe(false);
-
-      // A folder that is neither a checkout nor one of ours is never written into.
-      const foreign = join(scratch, 'foreign');
-      mkdirSync(foreign);
-      writeFileSync(join(foreign, 'notes.txt'), 'mine');
-      const refused = drive(script, {
-        CODEMAN_INSTALL_DIR: foreign,
-        CODEMAN_TARBALL_URL: `file://${first}`,
-        HOME: scratch,
-      });
-      expect(refused.status).toBe(1);
-      expect(refused.stderr).toContain('is not a Codeman install');
-      expect(readFileSync(join(foreign, 'notes.txt'), 'utf-8')).toBe('mine');
-    } finally {
-      rmSync(scratch, { recursive: true, force: true });
-    }
-  });
-
-  it('downloads from a subcommand that never ran the full flow', () => {
-    // DOWNLOADER used to be set only by main(), so `install.sh cloudflared` (and now the
-    // update of an archive install) died inside download() on an unbound variable.
-    const result = drive(`
-      unset DOWNLOADER
-      curl() { echo "FETCH $*"; }
-      wget() { echo "FETCH $*"; }
-      download https://example.invalid/a /tmp/never-written
-      unset DOWNLOADER
-      download_to_stdout https://example.invalid/b
-    `);
-    expect(result.status, result.stderr).toBe(0);
-    expect(result.stdout).toMatch(/FETCH .*example\.invalid\/a/);
-    expect(result.stdout).toMatch(/FETCH .*example\.invalid\/b/);
-  });
-
-  it('builds the archive URL from the repository and branch, on GitHub only', () => {
-    const url = (env: NodeJS.ProcessEnv) => drive('source_tarball_url || echo REFUSED', env).stdout.trim();
-    expect(url({})).toBe('https://github.com/Ark0N/Codeman/archive/master.tar.gz');
-    expect(url({ CODEMAN_REPO_URL: 'https://github.com/someone/fork.git', CODEMAN_BRANCH: 'feat/x' })).toBe(
-      'https://github.com/someone/fork/archive/feat/x.tar.gz'
-    );
-    expect(url({ CODEMAN_REPO_URL: 'https://gitlab.com/someone/fork.git' })).toBe('REFUSED');
-    expect(url({ CODEMAN_REPO_URL: 'git@github.com:someone/fork.git' })).toBe('REFUSED');
-    expect(url({ CODEMAN_TARBALL_URL: 'https://mirror.example/codeman.tar.gz' })).toBe(
-      'https://mirror.example/codeman.tar.gz'
-    );
-  });
-
-  it('shares the archive marker name with the in-app updater', () => {
-    // install.sh writes it, src/web/self-update.ts reads it to tell such an install how to
-    // update. A rename on one side would send archive installs back to the npm advice.
-    expect(SOURCE).toContain(`SOURCE_MARKER="${ARCHIVE_INSTALL_MARKER}"`);
-  });
-
-  it('treats a completed archive install as an install: quiet update on a re-run', () => {
-    const dispatch = SOURCE.slice(SOURCE.indexOf('\nparse_flags "$@"'));
-    expect(dispatch).toMatch(
-      /-f "\$INSTALL_DIR\/\.install-complete" \]\] && \[\[ -d "\$INSTALL_DIR\/\.git" \|\| -f "\$INSTALL_DIR\/\$SOURCE_MARKER" \]\]/
-    );
-    const update = fn('update', '\nuninstall() {');
-    expect(update).toContain('! -f "$INSTALL_DIR/$SOURCE_MARKER"');
-    // The swap happens only after the build has succeeded.
-    expect(update.indexOf('finish_source_swap')).toBeGreaterThan(update.indexOf('npm run build'));
-    const main = fn(
-      'main',
-      '\n# ----------------------------------------------------------------------------\n# Phase 0'
-    );
-    expect(main.indexOf('finish_source_swap')).toBeGreaterThan(main.indexOf('npm run build'));
-    expect(main.indexOf('finish_source_swap')).toBeLessThan(main.indexOf('install_symlink'));
-  });
-
-  it('documents --no-admin where people look for flags, and resolves the route before any work', () => {
-    expect(fn('usage', '\n}\n')).toContain('--no-admin');
-    const dispatch = SOURCE.slice(SOURCE.indexOf('\nparse_flags "$@"'));
-    expect(dispatch.indexOf('resolve_admin_mode')).toBeGreaterThan(-1);
-    expect(dispatch.indexOf('resolve_admin_mode')).toBeLessThan(dispatch.lastIndexOf('case "$SUBCOMMAND" in'));
-    expect(dispatch.indexOf('adopt_userspace_runtime')).toBeLessThan(dispatch.indexOf('resolve_admin_mode'));
-  });
-
-  it('puts the downloaded runtime on the LaunchAgent PATH', () => {
-    // The agent's PATH is a fixed list (Homebrew, /usr/local, ~/.local/bin, the system). A
-    // Node.js in the home folder is outside it, and so is everything `npm install -g` puts
-    // beside that Node.js: the AI CLIs, whose launchers start with `#!/usr/bin/env node`.
-    // A machine with a real LaunchDaemon makes the function stand down, so skip there.
-    if (existsSync('/Library/LaunchDaemons/com.codeman.web.plist')) return;
-    const home = mkdtempSync(join(tmpdir(), 'codeman-agent-path-'));
-    const result = drive(
-      `
-      mkdir -p "$RUNTIME_DIR/node/bin" "$RUNTIME_DIR/bin" "$HOME/.local/bin"
-      printf '#!/bin/sh\n' > "$RUNTIME_DIR/node/bin/node"; chmod +x "$RUNTIME_DIR/node/bin/node"
-      printf '#!/bin/sh\n' > "$RUNTIME_DIR/bin/tmux"; chmod +x "$RUNTIME_DIR/bin/tmux"
-      ln -s "$RUNTIME_DIR/node/bin/node" "$HOME/.local/bin/node"
-      PATH="$HOME/.local/bin:$PATH"; hash -r
-      launchctl() { return 0; }
-      sleep() { :; }
-      BIND_HOST=127.0.0.1
-      setup_launchd_service >/dev/null 2>&1
-      cat "$HOME/Library/LaunchAgents/com.codeman.web.plist"
-    `,
-      { HOME: home }
-    );
-    rmSync(home, { recursive: true, force: true });
-    expect(result.status, result.stderr).toBe(0);
-    const path = /<key>PATH<\/key>\s*<string>([^<]*)<\/string>/.exec(result.stdout)?.[1] ?? '';
-    const dirs = path.split(':');
-    expect(dirs).toContain(`${home}/.codeman/runtime/node/bin`);
-    expect(dirs).toContain(`${home}/.codeman/runtime/bin`);
-    expect(dirs).toContain(`${home}/.local/bin`);
-    expect(dirs).toContain('/usr/bin');
-    expect(new Set(dirs).size, `duplicate PATH entries: ${path}`).toBe(dirs.length);
-    expect(result.stdout).toContain(`<string>${home}/.local/bin/node</string>`);
-  });
-
-  it('links only into its own runtime, and removes only its own links', () => {
-    // ~/.local/bin is the user's folder: a tmux or node they put there is never replaced on
-    // install and never deleted on uninstall.
-    const home = mkdtempSync(join(tmpdir(), 'codeman-links-'));
-    const result = drive(
-      `
-      mkdir -p "$HOME/.local/bin" "$RUNTIME_DIR/bin"
-      touch "$RUNTIME_DIR/bin/tmux" "$RUNTIME_DIR/bin/node"
-      printf 'mine' > "$HOME/.local/bin/tmux"
-      link_into_local_bin "$RUNTIME_DIR/bin/tmux" tmux && echo "foreign=replaced" || echo "foreign=kept"
-      link_into_local_bin "$RUNTIME_DIR/bin/node" node && echo "fresh=linked"
-      link_into_local_bin "$RUNTIME_DIR/bin/node" node && echo "ours=relinked"
-      echo "tmux=$(cat "$HOME/.local/bin/tmux") node=$(readlink "$HOME/.local/bin/node")"
-    `,
-      { HOME: home }
-    );
-    rmSync(home, { recursive: true, force: true });
-    expect(result.status, result.stderr).toBe(0);
-    expect(result.stdout).toContain('foreign=kept');
-    expect(result.stdout).toContain('fresh=linked');
-    expect(result.stdout).toContain('ours=relinked');
-    expect(result.stdout).toMatch(/tmux=mine node=.*\/\.codeman\/runtime\/bin\/node/);
-
-    const body = fn('uninstall', '\nusage() {');
-    const rm = body.indexOf('rm -f "$symlink_dir/$runtime_tool"');
-    expect(rm).toBeGreaterThan(-1);
-    expect(body.slice(body.lastIndexOf('if [[', rm), rm)).toContain('== "$RUNTIME_DIR/"*');
-  });
-});

test/linked-cases-writer.test.ts

@@ -0,0 +1,198 @@
+/**
+ * @fileoverview Every writer of the linked-cases registry is serialized, atomic, and refuses to
+ * overwrite a file that does not parse (`mutateLinkedCases()`, src/web/linked-cases-writer.ts). Real
+ * filesystem under test/setup.ts's temp HOME. Port: N/A (app.inject()).
+ *
+ * The CI flake this fixes was "a name linked while the clone ran is a 409" in
+ * test/routes/case-clone-custom-folder.test.ts: two clones claiming one name both re-read the
+ * registry before either wrote it, so both answered success and the later write replaced the
+ * earlier entry. Writes to the registry (and its temp files) are slowed down here, so two writers
+ * that both read before either writes lose an entry every time instead of once in a while.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import fs from 'node:fs/promises';
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  readlinkSync,
+  realpathSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { createRouteTestHarness } from './routes/_route-test-utils.js';
+import { registerCaseRoutes } from '../src/web/routes/case-routes.js';
+import { LinkedCasesWriteRefusedError, linkedCasesPath, mutateLinkedCases } from '../src/web/linked-cases-writer.js';
+import { isSandboxedHome, safeRmHomeTree } from './mocks/index.js';
+
+const LINKED = () => linkedCasesPath();
+const linked = (): Record<string, string> => JSON.parse(readFileSync(LINKED(), 'utf8'));
+/** Temp files the writer left beside the registry (there must never be any). */
+const leftovers = () =>
+  readdirSync(dirname(LINKED())).filter((n) => n.startsWith(`${basename(LINKED())}.`) && n.endsWith('.tmp'));
+/** The bytes of a registry torn by two overlapping truncate-then-write calls. */
+const TORN = '{\n  "kept": "/srv/kept"\n}' + 'ept-2"\n}';
+
+/** How long every write to the registry (or a temp file beside it) is held before it starts. */
+const SLOW_WRITE_MS = 60;
+const realWriteFile = fs.writeFile.bind(fs);
+
+let workDir = '';
+
+beforeEach(() => {
+  if (!isSandboxedHome()) {
+    throw new Error('linked-cases-writer.test.ts rewrites the linked-cases registry: run it via npm test');
+  }
+  safeRmHomeTree(LINKED());
+  mkdirSync(dirname(LINKED()), { recursive: true });
+  workDir = realpathSync(mkdtempSync(join(homedir(), 'linked-cases-writer-')));
+  vi.spyOn(fs, 'writeFile').mockImplementation((async (file: unknown, data: unknown, options?: unknown) => {
+    if (typeof file === 'string' && file.startsWith(LINKED())) {
+      await new Promise((resolve) => setTimeout(resolve, SLOW_WRITE_MS));
+    }
+    return realWriteFile(file as string, data as string, options as undefined);
+  }) as typeof fs.writeFile);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  if (workDir) safeRmHomeTree(workDir);
+  workDir = '';
+  if (isSandboxedHome()) safeRmHomeTree(LINKED());
+});
+
+describe('mutateLinkedCases()', () => {
+  it('runs concurrent mutations one at a time, so none loses another one’s entry', async () => {
+    writeFileSync(LINKED(), JSON.stringify({ kept: '/srv/kept' }));
+    await Promise.all(
+      Array.from({ length: 8 }, (_, i) => mutateLinkedCases((current) => ({ ...current, [`c${i}`]: `/srv/c${i}` })))
+    );
+    expect(Object.keys(linked()).sort()).toEqual(['c0', 'c1', 'c2', 'c3', 'c4', 'c5', 'c6', 'c7', 'kept']);
+    expect(leftovers()).toEqual([]);
+  });
+
+  it('a check that throws inside the mutation rejects that caller only and writes nothing', async () => {
+    const claim = (name: string, path: string) =>
+      mutateLinkedCases((current) => {
+        if (current[name]) throw Object.assign(new Error(`${name} is taken`), { conflict: true });
+        return { ...current, [name]: path };
+      });
+    const results = await Promise.allSettled([
+      claim('twin', '/srv/a'),
+      claim('twin', '/srv/b'),
+      claim('solo', '/srv/s'),
+    ]);
+    expect(results.map((r) => r.status)).toEqual(['fulfilled', 'rejected', 'fulfilled']);
+    expect((results[1] as PromiseRejectedResult).reason.message).toBe('twin is taken');
+    expect(linked()).toEqual({ twin: '/srv/a', solo: '/srv/s' });
+  });
+
+  it('starts from an empty registry when the file is missing or empty, and writes nothing for undefined', async () => {
+    const { before, after } = await mutateLinkedCases((current) => ({ ...current, a: '/srv/a' }));
+    expect(before).toEqual({});
+    expect(after).toEqual({ a: '/srv/a' });
+    writeFileSync(LINKED(), '  \n');
+    await mutateLinkedCases((current) => ({ ...current, b: '/srv/b' }));
+    expect(linked()).toEqual({ b: '/srv/b' });
+    const untouched = readFileSync(LINKED(), 'utf8');
+    expect((await mutateLinkedCases(() => undefined)).after).toBeUndefined();
+    expect(readFileSync(LINKED(), 'utf8')).toBe(untouched);
+  });
+
+  it('refuses a registry that is not a JSON object and leaves it byte for byte', async () => {
+    for (const content of [TORN, '[]', 'null', '"text"']) {
+      writeFileSync(LINKED(), content);
+      const fn = vi.fn((current: Record<string, string>) => ({ ...current, a: '/srv/a' }));
+      await expect(mutateLinkedCases(fn)).rejects.toBeInstanceOf(LinkedCasesWriteRefusedError);
+      expect(fn).not.toHaveBeenCalled();
+      expect(readFileSync(LINKED(), 'utf8')).toBe(content);
+    }
+    // The chain keeps going after a refusal.
+    writeFileSync(LINKED(), '{}');
+    await mutateLinkedCases((current) => ({ ...current, a: '/srv/a' }));
+    expect(linked()).toEqual({ a: '/srv/a' });
+  });
+
+  it('leaves the previous registry and no temp file when the write fails', async () => {
+    writeFileSync(LINKED(), JSON.stringify({ kept: '/srv/kept' }));
+    const realRename = fs.rename.bind(fs);
+    vi.spyOn(fs, 'rename').mockImplementation(async (from, to) => {
+      if (to === LINKED()) throw Object.assign(new Error('no space left on device'), { code: 'ENOSPC' });
+      return realRename(from, to);
+    });
+    await expect(mutateLinkedCases((current) => ({ ...current, a: '/srv/a' }))).rejects.toThrow('no space left');
+    expect(linked()).toEqual({ kept: '/srv/kept' });
+    expect(leftovers()).toEqual([]);
+  });
+
+  it('writes through a symlinked registry onto its target and keeps the file’s permissions', async () => {
+    const real = join(workDir, 'linked-cases.json');
+    writeFileSync(real, JSON.stringify({ kept: '/srv/kept' }), { mode: 0o600 });
+    safeRmHomeTree(LINKED());
+    symlinkSync(real, LINKED());
+    await mutateLinkedCases((current) => ({ ...current, a: '/srv/a' }));
+    expect(lstatSync(LINKED()).isSymbolicLink()).toBe(true);
+    expect(readlinkSync(LINKED())).toBe(real);
+    expect(JSON.parse(readFileSync(real, 'utf8'))).toEqual({ kept: '/srv/kept', a: '/srv/a' });
+    expect(statSync(real).mode & 0o777).toBe(0o600);
+    expect(readdirSync(workDir).filter((n) => n.endsWith('.tmp'))).toEqual([]);
+  });
+});
+
+describe('the case routes share the writer', () => {
+  const folder = (name: string) => {
+    const dir = join(workDir, name);
+    mkdirSync(dir);
+    return dir;
+  };
+
+  it('two links of different names at once both survive', async () => {
+    const { app } = await createRouteTestHarness(registerCaseRoutes);
+    const [a, b] = await Promise.all([
+      app.inject({ method: 'POST', url: '/api/cases/link', payload: { name: 'one', path: folder('one') } }),
+      app.inject({ method: 'POST', url: '/api/cases/link', payload: { name: 'two', path: folder('two') } }),
+    ]);
+    expect([a.json().success, b.json().success]).toEqual([true, true]);
+    expect(linked()).toEqual({ one: join(workDir, 'one'), two: join(workDir, 'two') });
+  });
+
+  it('two links of one name at once: exactly one wins and the other is told the name is taken', async () => {
+    const { app } = await createRouteTestHarness(registerCaseRoutes);
+    const [a, b] = await Promise.all([
+      app.inject({ method: 'POST', url: '/api/cases/link', payload: { name: 'twin', path: folder('twin-a') } }),
+      app.inject({ method: 'POST', url: '/api/cases/link', payload: { name: 'twin', path: folder('twin-b') } }),
+    ]);
+    expect([a.json().success, b.json().success].filter(Boolean)).toHaveLength(1);
+    const loser = a.json().success ? b : a;
+    expect(loser.json().errorCode).toBe('ALREADY_EXISTS');
+    expect(Object.keys(linked())).toEqual(['twin']);
+  });
+
+  it('an unlink at the same time as a link keeps the new link', async () => {
+    writeFileSync(LINKED(), JSON.stringify({ old: folder('old') }));
+    const { app } = await createRouteTestHarness(registerCaseRoutes);
+    const [unlink, link] = await Promise.all([
+      app.inject({ method: 'DELETE', url: '/api/cases/old' }),
+      app.inject({ method: 'POST', url: '/api/cases/link', payload: { name: 'fresh', path: folder('fresh') } }),
+    ]);
+    expect([unlink.json().success, link.json().success]).toEqual([true, true]);
+    expect(linked()).toEqual({ fresh: join(workDir, 'fresh') });
+    expect(existsSync(join(workDir, 'old'))).toBe(true);
+  });
+
+  it('a link refuses a registry that does not parse instead of replacing it', async () => {
+    writeFileSync(LINKED(), TORN);
+    const { app } = await createRouteTestHarness(registerCaseRoutes);
+    const res = await app.inject({ method: 'POST', url: '/api/cases/link', payload: { name: 'n', path: folder('n') } });
+    expect(res.json()).toMatchObject({ success: false, errorCode: 'CONFLICT' });
+    expect(res.json().error).toContain('is not a valid JSON object');
+    expect(readFileSync(LINKED(), 'utf8')).toBe(TORN);
+  });
+});

test/routes/case-custom-path-routes.test.ts

@@ -8,7 +8,7 @@
  * to start there. Each test's folders sit in a fresh mkdtemp dir, and everything is removed through
  * safeRmHomeTree, so a run can only ever delete what it created.
  */
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import {
   existsSync,
   mkdirSync,
@@ -19,6 +19,7 @@ import {
   symlinkSync,
   writeFileSync,
 } from 'node:fs';
+import fs from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { basename, join } from 'node:path';
 import { createRouteTestHarness } from './_route-test-utils.js';
@@ -40,7 +41,7 @@ beforeEach(() => {
   if (!sandboxed()) {
     throw new Error('case-custom-path-routes.test.ts deletes the linked-cases registry: run it via npm test');
   }
-  // Recursive: the rollback tests turn the registry into a directory.
+  // Recursive, so a test that left anything at the registry's path cannot leak into the next one.
   safeRmHomeTree(LINKED());
   // Resolved, because the server answers with the symlink-resolved folder (macOS temp is under /private).
   workDir = realpathSync(mkdtempSync(join(homedir(), 'case-custom-path-')));
@@ -134,20 +135,36 @@ describe('POST /api/cases with a custom path', () => {
 
   it('undoes what it created when registering fails (a new folder is removed entirely)', async () => {
     const { app } = await createRouteTestHarness(registerCaseRoutes);
-    mkdirSync(LINKED(), { recursive: true }); // writeFile onto a directory fails
-    const res = await create(app, { name: 'doomed', path: join(work(), 'doomed') });
+    // The registry is replaced by renaming a temp file over it: fail that rename.
+    const realRename = fs.rename;
+    const spy = vi.spyOn(fs, 'rename').mockImplementation(async (from, to) => {
+      if (to === LINKED()) throw Object.assign(new Error('permission denied'), { code: 'EACCES' });
+      return realRename(from, to);
+    });
+    let res;
+    try {
+      res = await create(app, { name: 'doomed', path: join(work(), 'doomed') });
+    } finally {
+      spy.mockRestore();
+    }
     expect(res.statusCode).toBe(500);
     expect(existsSync(join(work(), 'doomed'))).toBe(false);
+    expect(linked()).toEqual({});
   });
 
-  it('undoes only the scaffold inside an empty folder the user picked, leaving the folder', async () => {
+  it('undoes only the scaffold inside an empty folder the user picked when the registry is refused', async () => {
     const { app } = await createRouteTestHarness(registerCaseRoutes);
     mkdirSync(join(work(), 'picked'));
-    mkdirSync(LINKED(), { recursive: true });
+    // A registry that does not parse is never written over (that would unlink every other case).
+    const torn = '{\n  "kept": "/somewhere"\n}tail"\n}';
+    writeFileSync(LINKED(), torn);
     const res = await create(app, { name: 'picked', path: join(work(), 'picked') });
-    expect(res.statusCode).toBe(500);
+    expect(res.statusCode).toBe(409);
+    expect(res.json().errorCode).toBe('CONFLICT');
+    expect(res.json().error).toContain('is not a valid JSON object');
     expect(existsSync(join(work(), 'picked'))).toBe(true);
     expect(readdirSync(join(work(), 'picked'))).toEqual([]);
+    expect(readFileSync(LINKED(), 'utf8')).toBe(torn);
   });
 
   it('a request without a path still creates under the cases directory, as before', async () => {

test/routes/case-rename-routes.test.ts

@@ -6,7 +6,6 @@
  */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import {
-  chmodSync,
   existsSync,
   mkdirSync,
   mkdtempSync,
@@ -36,6 +35,21 @@ let claudeCfg = '';
 const made: string[] = [];
 
 const linked = (): Record<string, string> => (existsSync(LINKED()) ? JSON.parse(readFileSync(LINKED(), 'utf8')) : {});
+/**
+ * The registry is replaced by renaming a temp file over it, which a read-only file does not stop, so a
+ * failed registry write is injected at that rename. `before` runs first (another writer landing then).
+ */
+const failRegistryWrite = (before?: () => Promise<unknown>, alsoFail?: (from: string) => boolean) => {
+  const realRename = fs.rename;
+  return vi.spyOn(fs, 'rename').mockImplementation(async (from, to) => {
+    if (to === LINKED()) {
+      if (before) await before();
+      throw Object.assign(new Error('permission denied'), { code: 'EACCES' });
+    }
+    if (alsoFail?.(String(from))) throw Object.assign(new Error('resource busy'), { code: 'EBUSY' });
+    return realRename(from, to);
+  });
+};
 const settings = (): Record<string, unknown> => JSON.parse(readFileSync(SETTINGS_PATH, 'utf8'));
 const rename = (app: Awaited<ReturnType<typeof createRouteTestHarness>>['app'], name: string, payload: object) =>
   app.inject({ method: 'POST', url: `/api/cases/${name}/rename`, payload });
@@ -278,8 +292,13 @@ describe('POST /api/cases/:name/rename (a linked case)', () => {
     writeFileSync(LINKED(), JSON.stringify({ proj: real }));
     writeFileSync(SETTINGS_PATH, JSON.stringify({ caseOrder: ['a', 'proj', 'b'], lastUsedCase: 'proj' }));
     // the registry reads fine but cannot be written: the rename must undo the folder move
-    chmodSync(LINKED(), 0o444);
-    const res = await rename(app, 'proj', { newName: 'renamed', renameFolder: true });
+    const spy = failRegistryWrite();
+    let res;
+    try {
+      res = await rename(app, 'proj', { newName: 'renamed', renameFolder: true });
+    } finally {
+      spy.mockRestore();
+    }
     expect(res.statusCode).toBe(500);
     expect(existsSync(real)).toBe(true);
     expect(linked()).toEqual({ proj: real });
@@ -294,14 +313,9 @@ describe('POST /api/cases/:name/rename (a linked case)', () => {
     mkdirSync(real);
     writeFileSync(LINKED(), JSON.stringify({ proj: real }));
     writeFileSync(SETTINGS_PATH, JSON.stringify({ caseOrder: ['a', 'proj', 'b'], lastUsedCase: 'proj' }));
-    chmodSync(LINKED(), 0o444);
     // Another writer (a settings save) lands after the rename wrote settings.json and before the
     // registry write fails.
-    const realWriteFile = fs.writeFile;
-    const spy = vi.spyOn(fs, 'writeFile').mockImplementation(async (file, data, options) => {
-      if (file === LINKED()) await mutateSettingsFile((current) => ({ ...current, agentSkillEnabled: true }));
-      return realWriteFile(file, data, options);
-    });
+    const spy = failRegistryWrite(() => mutateSettingsFile((current) => ({ ...current, agentSkillEnabled: true })));
     try {
       const res = await rename(app, 'proj', { newName: 'renamed', renameFolder: true });
       expect(res.statusCode).toBe(500);
@@ -351,13 +365,8 @@ describe('POST /api/cases/:name/rename (a linked case)', () => {
     const real = join(work, 'my-project');
     mkdirSync(real);
     writeFileSync(LINKED(), JSON.stringify({ proj: real }));
-    chmodSync(LINKED(), 0o444);
     const moved = join(work, 'renamed');
-    const realRename = fs.rename;
-    const spy = vi.spyOn(fs, 'rename').mockImplementation(async (from, to) => {
-      if (from === moved) throw Object.assign(new Error('resource busy'), { code: 'EBUSY' });
-      return realRename(from, to);
-    });
+    const spy = failRegistryWrite(undefined, (from) => from === moved);
     try {
       const res = await rename(app, 'proj', { newName: 'renamed', renameFolder: true });
       expect(res.statusCode).toBe(500);
@@ -373,9 +382,14 @@ describe('POST /api/cases/:name/rename (a linked case)', () => {
     const real = join(work, 'my-project');
     mkdirSync(real);
     writeFileSync(LINKED(), JSON.stringify({ proj: real }));
-    chmodSync(LINKED(), 0o444);
     (ctx.sessions as Map<string, unknown>).set('s1', { id: 's1', name: 'w1', workingDir: real });
-    const res = await rename(app, 'proj', { newName: 'renamed', renameFolder: true, stopSessions: true });
+    const spy = failRegistryWrite();
+    let res;
+    try {
+      res = await rename(app, 'proj', { newName: 'renamed', renameFolder: true, stopSessions: true });
+    } finally {
+      spy.mockRestore();
+    }
     expect(res.statusCode).toBe(500);
     expect(res.json().stoppedSessions).toBe(1);
     expect(ctx.cleanupSession).toHaveBeenCalledWith('s1', true, 'case_rename');

test/routes/case-routes.test.ts

@@ -54,6 +54,12 @@ vi.mock('node:fs/promises', () => ({
       throw err;
     }),
     writeFile: vi.fn(async () => {}),
+    // What the linked-cases writer needs to replace the registry atomically (temp file + rename).
+    realpath: vi.fn(async (p: string) => p),
+    mkdir: vi.fn(async () => undefined),
+    chmod: vi.fn(async () => {}),
+    rename: vi.fn(async () => {}),
+    rm: vi.fn(async () => {}),
   },
 }));
 
@@ -704,6 +710,7 @@ describe('case-routes', () => {
       });
       // linked-cases.json doesn't exist yet
       mockedReadFile.mockRejectedValue(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
+      mockedStat.mockRejectedValue(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
 
       const res = await harness.app.inject({
         method: 'POST',

test/self-update.test.ts

@@ -6,16 +6,8 @@
  *   npm test -- test/self-update.test.ts
  */
 
-import { describe, it, expect, afterAll } from 'vitest';
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { describe, it, expect } from 'vitest';
 import {
-  ARCHIVE_INSTALL_MARKER,
-  ARCHIVE_UPDATE_HINT,
-  canSelfUpdateInPlace,
-  detectInstallKind,
-  isRunningInContainer,
   parseVersionFromTag,
   compareVersions,
   isNewerStableVersion,
@@ -213,39 +205,3 @@ describe('expireStalledStatus (runtime staleness backstop)', () => {
     expect(expireStalledStatus(base({ phase: 'failed', updatedAt: NOW - 60 * MIN }), NOW)).toBeNull();
   });
 });
-
-describe('detectInstallKind', () => {
-  const scratch = mkdtempSync(join(tmpdir(), 'codeman-install-kind-'));
-  afterAll(() => rmSync(scratch, { recursive: true, force: true }));
-  let n = 0;
-  const tree = (entries: string[]) => {
-    const dir = join(scratch, `install-${++n}`);
-    mkdirSync(dir);
-    for (const entry of entries) {
-      if (entry.endsWith('/')) mkdirSync(join(dir, entry));
-      else writeFileSync(join(dir, entry), 'archive\n');
-    }
-    return dir;
-  };
-
-  it('reads a source-archive install (install.sh without a working git) as archive', () => {
-    const dir = tree(['src/', 'dist/', ARCHIVE_INSTALL_MARKER]);
-    expect(detectInstallKind(dir)).toBe('archive');
-    // Nothing to pull into, so it never self-updates in place; the hint names the installer.
-    expect(canSelfUpdateInPlace('archive')).toBe(false);
-    expect(ARCHIVE_UPDATE_HINT).toContain('getcodeman.com/install');
-    expect(ARCHIVE_UPDATE_HINT).not.toContain('npm i -g');
-  });
-
-  it('lets a real checkout win over a leftover marker', () => {
-    // A re-run of the installer on a machine that gained git replaces the archive tree with
-    // a clone; were a marker ever left beside .git, the checkout is still what counts.
-    const dir = tree(['.git/', 'src/', ARCHIVE_INSTALL_MARKER]);
-    expect(detectInstallKind(dir)).toBe(isRunningInContainer() ? 'docker-compose' : 'git');
-  });
-
-  it('keeps npm and unknown as they were', () => {
-    expect(detectInstallKind(tree(['dist/']))).toBe('npm');
-    expect(detectInstallKind(tree(['dist/', 'src/']))).toBe('unknown');
-  });
-});