docs(wiki): name the app's Add a Coding Agent menu item as the app shows it

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

CLAUDE.md

@@ -104,7 +104,6 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 - **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)
-- **Never start `git` without `gitSpawnAllowed()`** (`utils/git-availability.ts`): on a Mac without the developer tools `/usr/bin/git` is Apple's placeholder, and running it, even as `git --version`, opens macOS's "install the command line developer tools" window. The server did that on the first page load after a no-admin install (`isGitAvailable()` from `renderIndexHtml`) and would have again at every start. The gate resolves `git` on the PATH itself and, for the placeholder, proves the tools first with `xcode-select -p`, which never opens a window; a refusal is answered as ENOENT (`gitMissingError()`), which every caller already reads as "git is not installed". `test/git-spawn-gate.test.ts` pins the list of spawn sites, so a new one fails until it is gated. `install.sh` follows the same rule for the same reason.
 - **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)
 

README.md

@@ -43,6 +43,8 @@ codeman web
 
 The installer asks before every system change, and re-running the same line updates in place. Full details: [Quick Start - Installation](#quick-start---installation).
 
+On a Mac you can skip the terminal: [download Codeman.dmg](https://github.com/Ark0N/Codeman/releases/latest/download/Codeman.dmg), and the app installs Codeman for you, opens the one already running, or connects to one on another machine. More in [On a Mac: the Codeman app](#on-a-mac-the-codeman-app).
+
 - **One dashboard, ten CLIs** - run [Claude Code, OpenCode, Codex, Antigravity, Gemini, Pi, Grok, DeepSeek, OMP, or GitHub Copilot](#more-features) per session (plus plain shell), locally, [in Docker](#isolated-docker-sessions), or [over SSH](#remote-ssh-sessions), with your own dashboards open as [web tabs](#more-features) beside them
 - **Truly phone-friendly** - a [touch-optimized terminal](#mobile-optimized-web-ui) with instant local echo, QR login, swipe navigation, and push notifications
 - **Runs while you sleep** - [idle detection + respawn cycling](#respawn-controller) and auto-resume when a subscription limit resets, for 24+ hour unattended runs
@@ -97,6 +99,21 @@ bash docker/Start-Codeman.sh
 
 The first run asks three questions (data folder, port, password; Enter takes the default, including a generated password), writes `docker/.env` for you, builds the image and ends on the URL once Codeman answers. The image already includes Claude Code, Codex, Gemini CLI and OpenCode. Codeman runs in a container and spawns Docker cases as sibling containers through the host socket. To update, use **App Settings → Updates**, or `git pull` and run the script again rather than a plain `docker compose up`, so the rebuilt image, refreshed volumes and entrypoint arrive together. See the [Docker deployment guide](docker/README.md) for Unraid, direct Compose commands, storage and networking options.
 
+### On a Mac: the Codeman app
+
+**[Download Codeman.dmg](https://github.com/Ark0N/Codeman/releases/latest/download/Codeman.dmg)** · one universal app for Apple Silicon and Intel · macOS 11.3 or later
+
+A small native app that opens Codeman in its own window. On a Mac without Codeman it installs it for you, with no Terminal and no administrator password, shows the install as a checklist, and offers to install a coding agent if the Mac has none yet. On a Mac that already runs Codeman it finds the server and opens it, or starts it when it is stopped. Under **Another machine** it connects to Codeman on your Mac mini, a home server or your tailnet, with the password kept in the Keychain, and can start an install over there through SSH. On a MacBook Pro with a PROLED XDR display, whose lid logo lights up, **View > Blink Apple Logo** blinks the logo by what your agents are doing, with a style of your own for working, for waiting for you and for needing permission; all three stay off until you choose. The app is Rust around macOS's own WebKit, not a bundled browser, so the download is under 5 MB.
+
+Open `Codeman.dmg`, drag Codeman into Applications and open it from there. macOS asks once whether to open an app downloaded from the internet: click **Open**.
+
+- **Quitting the app doesn't stop Codeman.** An install from the app runs Codeman as a LaunchAgent that starts at login, so your agents keep working with the window closed, and your browser and phone reach it as before.
+- **Codeman's page needs the WebKit of Safari 16.4.** The app starts on macOS 11.3, but Codeman itself needs macOS 13.3 or later, or macOS 11 or 12 with Safari 16.4 or later installed. On an older WebKit the app says so and does not connect.
+- **The install from the app needs macOS 15, or a tmux that is already there.** tmux comes from the tmux project's own builds, which need macOS 15. On an older Mac without tmux the app offers Terminal instead, where Homebrew installs it (that takes an administrator once).
+- **Updating.** The app doesn't update itself yet: download the new `Codeman.dmg` and drag it over the old copy.
+
+First launch, known limits and how to build it yourself: [Installation](https://github.com/Ark0N/Codeman/wiki/Installation#on-a-mac-the-codeman-app) in the wiki and [packages/desktop/README.md](packages/desktop/README.md).
+
 <details>
 <summary><strong>Keep it running in the background</strong></summary>
 

README.zh-CN.md

@@ -45,6 +45,8 @@ codeman web
 
 安装器在每次系统改动前都会先询问；重跑同一条命令即可原地更新。详见[快速开始 — 安装](#快速开始--安装)。
 
+在 Mac 上可以不用终端：[下载 Codeman.dmg](https://github.com/Ark0N/Codeman/releases/latest/download/Codeman.dmg)，这个应用会替你安装 Codeman、打开已在运行的 Codeman，或者连接另一台机器上的 Codeman。详见[在 Mac 上：Codeman 应用](#在-mac-上codeman-应用)。
+
 - **一个仪表盘，十个 CLI**：每个会话可选 [Claude Code、OpenCode、Codex、Antigravity、Gemini、Pi、Grok、DeepSeek、OMP 或 GitHub Copilot](#更多特性)（外加普通 shell），在本机、[Docker 容器](#隔离的-docker-会话)或 [SSH 远程主机](#远程-ssh-会话)上运行，你自己的仪表盘也能作为 [Web 标签页](#更多特性)并排打开
 - **真正的手机友好**：[触控优化的终端](#移动端优化的-web-ui)，即时本地回显、二维码登录、滑动导航与推送通知
 - **睡觉时也在跑**：[空闲检测 + 重生循环](#重生控制器respawn-controller)，订阅限额重置后自动续跑，支持 24 小时以上的无人值守运行
@@ -99,6 +101,21 @@ bash docker/Start-Codeman.sh
 
 详见下文[多用户模式](#多用户模式可选启用)。
 
+### 在 Mac 上：Codeman 应用
+
+**[下载 Codeman.dmg](https://github.com/Ark0N/Codeman/releases/latest/download/Codeman.dmg)** · 同一个通用应用，适用于 Apple 芯片和 Intel · macOS 11.3 或更高版本
+
+一个小巧的原生应用，在它自己的窗口里打开 Codeman。在还没有 Codeman 的 Mac 上，它会替你安装，不用终端，也不需要管理员密码，用一张清单显示安装进度；如果这台 Mac 上还没有编程智能体，它还会提出帮你装一个。在已经运行 Codeman 的 Mac 上，它会找到服务器并打开；服务器停着时则替你启动。在 **Another machine** 下，它可以连接你的 Mac mini、家用服务器或 tailnet 上的 Codeman，密码保存在钥匙串里，还能通过 SSH 在那台机器上开始安装。在配备 PROLED XDR 显示屏、机盖 Apple 标志会发光的 MacBook Pro 上，**View > Blink Apple Logo** 会让标志按智能体在做的事闪烁：工作中、等你回复、需要权限各用一种你自己选的样式；在你选定之前，三种都保持关闭。这个应用用 Rust 写成，套在 macOS 自带的 WebKit 外面，不捆绑浏览器，所以下载不到 5 MB。
+
+打开 `Codeman.dmg`，把 Codeman 拖进「应用程序」文件夹，再从那里打开。macOS 会问一次是否打开这个从互联网下载的应用：点**打开**。
+
+- **退出应用不会停止 Codeman。** 通过应用安装的 Codeman 以 LaunchAgent 的形式运行，登录时自动启动，所以关掉窗口后智能体照样工作，浏览器和手机也和以前一样能访问它。
+- **Codeman 的页面需要 Safari 16.4 的 WebKit。** 应用本身在 macOS 11.3 上就能启动，但 Codeman 需要 macOS 13.3 或更高版本，或者装有 Safari 16.4 或更高版本的 macOS 11 或 12。WebKit 更旧时，应用会说明原因，并且不会连接。
+- **在应用里安装需要 macOS 15，或者机器上已有 tmux。** tmux 来自 tmux 项目自己的构建，而这些构建需要 macOS 15。在没有 tmux 的旧 Mac 上，应用会改为提供终端安装方式，由 Homebrew 在终端里安装 tmux（这需要管理员操作一次）。
+- **更新。** 应用暂时不会自我更新：下载新的 `Codeman.dmg`，拖过去覆盖旧的那份即可。
+
+首次启动、已知限制以及如何自行构建：见 wiki 的 [Installation](https://github.com/Ark0N/Codeman/wiki/Installation#on-a-mac-the-codeman-app)（英文）和 [packages/desktop/README.md](packages/desktop/README.md)（英文）。
+
 <details>
 <summary><strong>让它在后台一直运行</strong></summary>
 

docs/wiki/Installation.md

@@ -25,7 +25,8 @@ curl -fsSL https://getcodeman.com/install | bash
 
 This installs Node.js, tmux and a build toolchain if they are missing (node-pty ships no
 Linux prebuild, so it compiles from source), clones Codeman into `~/.codeman/app`, and
-builds it.
+builds it. On a Mac, the [Codeman app](#on-a-mac-the-codeman-app) can run this installer
+for you, with no Terminal.
 
 It starts by printing what it found (git, Node, tmux, build tools, agent CLIs, Tailscale,
 an existing install), then asks everything it needs up front, then does the work
@@ -216,6 +217,73 @@ image, the refreshed volumes and the entrypoint arrive together. The full guide,
 Unraid, storage and networking options, is
 [`docker/README.md`](https://github.com/Ark0N/Codeman/blob/master/docker/README.md).
 
+## On a Mac: the Codeman app
+
+[Download Codeman.dmg](https://github.com/Ark0N/Codeman/releases/latest/download/Codeman.dmg):
+one universal app for Apple Silicon and Intel, macOS 11.3 or later.
+
+A small native app that opens Codeman in its own window. Its first screen has two tabs:
+
+- **This Mac** looks for Codeman here and offers what fits: *Open Codeman* when it runs,
+  *Start Codeman* when it is installed but stopped, *Install Codeman on this Mac* when it is
+  not there. It also lists the Codeman servers of yours that already run on this Mac (one
+  started by hand in a terminal, say) and offers to connect to those; it never starts a
+  second one next to them. Install runs [the installer](#route-a-the-installer-recommended)
+  for you, with no Terminal and no administrator password: it asks which coding agent to
+  install (only when the Mac has none, and *Skip for now* is there) and who may reach
+  Codeman (this Mac only, or the local network with a password), then shows the install as
+  a checklist. *Add a coding agent* on this tab (*Add a Coding Agent to This Mac…* in the app menu) installs one later.
+- **Another machine** connects to Codeman by address, a tailnet name included, and keeps
+  the password in the Keychain. *Codeman is not installed there yet?* opens Terminal and
+  runs the installer on that machine over SSH.
+
+On a MacBook Pro with a PROLED XDR display, whose lid logo lights up,
+**View > Blink Apple Logo** blinks the logo by what your agents are doing, with a style of
+your own for working, for waiting for you and for needing permission. All three are off
+until you choose, and the menu only exists on such a Mac.
+
+### First launch
+
+1. Open `Codeman.dmg` and drag Codeman into Applications.
+2. Open Codeman from Applications. macOS asks once whether to open an app downloaded from
+   the internet: click **Open**.
+3. On macOS 15 and later, the first connection to an address on your local network (a LAN
+   IP, a `.local` name) makes macOS ask whether Codeman may use the local network, and that
+   first attempt can fail while the question is open: connect again after answering. If
+   you denied it, turn Codeman on in **System Settings > Privacy & Security > Local
+   Network**.
+
+What to know about it:
+
+- **Quitting the app does not stop Codeman.** An install from the app runs Codeman as a
+  LaunchAgent that starts at login, so agents keep working with the window closed, and a
+  browser or phone reaches it as before.
+- **Codeman's page needs the WebKit of Safari 16.4.** The app starts on macOS 11.3, but
+  Codeman itself needs macOS 13.3 or later, or macOS 11 or 12 with Safari 16.4 or later
+  installed. On an older WebKit the app says so and does not connect.
+- **The install from the app needs macOS 15, or a tmux that is already there.** tmux comes
+  from the tmux project's own builds, which need macOS 15. On an older Mac without tmux the
+  app offers Terminal instead, where Homebrew installs it (that takes an administrator once).
+- **The install from the app reaches as far as the local network.** Tailscale needs its own
+  login and setup, which the installer does at a terminal: choose *Install in Terminal
+  instead*, or run `install.sh tailscale` afterwards.
+- **Self-signed HTTPS is refused.** A server started with `codeman web --https` uses a
+  self-signed certificate, which macOS's WebKit rejects. Use `http://127.0.0.1:3000` for a
+  server on this Mac. For another machine, serve Codeman through `tailscale serve`
+  (`https://<machine>.<tailnet>.ts.net` has a real certificate) or a reverse proxy with a
+  real certificate.
+- **The Codeman it installs is an ordinary installer install,** made on the
+  [route without administrator rights](#without-administrator-rights), so
+  [Updating](#updating) and [Uninstalling](#uninstalling) below apply to it.
+- **The app does not update itself yet.** Download the new `Codeman.dmg` and drag it over
+  the old copy.
+- **Deleting the app leaves Codeman running.** The app's own settings are in
+  `~/Library/Application Support/Codeman/`, and its saved passwords in the Keychain under
+  *Codeman Desktop*.
+
+Everything else, including how to build it yourself:
+[`packages/desktop/README.md`](https://github.com/Ark0N/Codeman/blob/master/packages/desktop/README.md).
+
 ## Installing an agent CLI
 
 Codeman drives CLIs, it does not bundle them. Install at least one:

src/git-clone.ts

@@ -54,7 +54,6 @@ import { lstat, readdir, rename, rm } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 import { EXEC_TIMEOUT_MS } from './config/exec-timeout.js';
 import { probePathKind } from './utils/bounded-path-probe.js';
-import { gitMissingError, gitSpawnAllowed } from './utils/git-availability.js';
 
 // ─── Tunables ────────────────────────────────────────────────────────────────
 
@@ -729,17 +728,6 @@ interface GitRun {
  * signal is used rather than `child.kill()`.
  */
 async function runGit(args: string[], timeoutMs: number, maxStdoutBytes: number): Promise<GitRun> {
-  // Never Apple's placeholder git on a Mac without developer tools: answered as a missing git.
-  if (!gitSpawnAllowed()) {
-    return {
-      stdout: '',
-      stderr: '',
-      code: null,
-      timedOut: false,
-      started: false,
-      spawnError: String(gitMissingError()),
-    };
-  }
   // The queue wait spends the SAME deadline as the operation: `timeoutMs` is a
   // promise about the whole call, not about git's runtime after some unbounded
   // wait. A full queue is refused outright rather than queued.
@@ -826,17 +814,10 @@ async function runGit(args: string[], timeoutMs: number, maxStdoutBytes: number)
   }
 }
 
-/**
- * Is a usable `git` on this machine? Memoized: the answer cannot change without a restart. The one
- * exception is a Mac whose only git is Apple's placeholder with no developer tools behind it: running
- * that, even as `git --version`, opens macOS's "install the developer tools" window, so it is never
- * run, and that refusal is not memoized here (the gate keeps its own short memory), so the page finds
- * git once the tools are installed.
- */
+/** Is a usable `git` on this machine? Memoized: the answer cannot change without a restart. */
 let gitAvailable: boolean | null = null;
 export function isGitAvailable(): boolean {
   if (gitAvailable !== null) return gitAvailable;
-  if (!gitSpawnAllowed()) return false;
   try {
     execFileSync('git', ['--version'], {
       encoding: 'utf-8',

src/git-fetch.ts

@@ -65,7 +65,6 @@ import {
   resolveWorkspaceRepos,
   type GitRunner,
 } from './git-workspace-status.js';
-import { gitMissingError, gitSpawnAllowed } from './utils/git-availability.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -206,7 +205,6 @@ export function fetchEnvFor(base: NodeJS.ProcessEnv, repoSshCommand: string | nu
  * add a fifth git process or push a fetch past the user's timeout: it spends part of it.
  */
 export async function readRepoSshCommand(cwd: string, timeoutMs: number): Promise<string | null> {
-  if (!gitSpawnAllowed()) return null;
   try {
     const { stdout } = await execFileAsync('git', ['config', '--get', 'core.sshCommand'], {
       cwd,
@@ -242,8 +240,6 @@ export async function readRepoSshCommand(cwd: string, timeoutMs: number): Promis
  * as a timeout without starting the fetch.
  */
 export const runFetch: GitRunner = async (cwd, args, opts) => {
-  // Never Apple's placeholder git on a Mac without developer tools: answered as GIT_MISSING.
-  if (!gitSpawnAllowed()) throw gitMissingError();
   const timeoutMs = opts?.timeoutMs ?? DEFAULT_GIT_TIMEOUT_MS;
   const startedAt = Date.now();
   const env = fetchEnvFor(process.env, await readRepoSshCommand(cwd, timeoutMs));

src/git-workspace-status.ts

@@ -50,7 +50,6 @@ import { homedir } from 'node:os';
 import { basename, join, relative, sep } from 'node:path';
 import { promisify } from 'node:util';
 import { gitNonInteractiveEnv, redactGitCredentials } from './git-clone.js';
-import { gitMissingError, gitSpawnAllowed } from './utils/git-availability.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -266,8 +265,6 @@ export function parseCommitLog(text: string): GitCommitEntry[] {
 export type GitRunner = (cwd: string, args: string[], opts?: { timeoutMs?: number }) => Promise<string>;
 
 export const runGit: GitRunner = async (cwd, args, opts) => {
-  // Never Apple's placeholder git on a Mac without developer tools (utils/git-availability.ts).
-  if (!gitSpawnAllowed()) throw gitMissingError();
   const { stdout } = await execFileAsync(
     'git',
     // --no-optional-locks: never touch the index just to look. core.fsmonitor=false: do not start or

src/git-worktrees.ts

@@ -62,7 +62,6 @@ import { homedir } from 'node:os';
 import { join, resolve, sep } from 'node:path';
 import { gitNonInteractiveEnv, isSafeGitRef, sanitizeGitOutput } from './git-clone.js';
 import { isInsideAny, isUnrelatedAncestor } from './git-workspace-status.js';
-import { gitMissingError, gitSpawnAllowed } from './utils/git-availability.js';
 
 // ─── Limits ──────────────────────────────────────────────────────────────────
 
@@ -372,11 +371,6 @@ const READ_ONLY_GIT_OPTIONS = ['--no-optional-locks', '-c', 'core.fsmonitor=fals
  */
 export const runWorktreeGit: WorktreeGitRunner = (cwd, args, opts) =>
   new Promise<WorktreeGitResult>((resolveRun) => {
-    // Never Apple's placeholder git on a Mac without developer tools: answered as "git is not installed".
-    if (!gitSpawnAllowed()) {
-      resolveRun({ code: null, stdout: '', stderr: '', timedOut: false, spawnError: String(gitMissingError()) });
-      return;
-    }
     let child: ReturnType<typeof spawn>;
     try {
       child = spawn('git', args, {

src/readmymind-collectors.ts

@@ -21,7 +21,6 @@ import { open, readdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
 import type { PredictionToolCall, WorkspaceSignals } from './readmymind-context.js';
-import { gitMissingError, gitSpawnAllowed } from './utils/git-availability.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -151,8 +150,6 @@ const MAX_STATUS_LINES = 30;
  */
 export async function collectWorkspaceSignals(workingDir: string): Promise<WorkspaceSignals | null> {
   const git = async (args: string[]): Promise<string> => {
-    // Never Apple's placeholder git on a Mac without developer tools (utils/git-availability.ts).
-    if (!gitSpawnAllowed()) throw gitMissingError();
     const { stdout } = await execFileAsync('git', args, {
       cwd: workingDir,
       timeout: GIT_TIMEOUT_MS,

src/utils/git-availability.ts

@@ -1,147 +0,0 @@
-/**
- * @fileoverview The ONE gate in front of every `git` the server starts.
- *
- * macOS ships `/usr/bin/git` as a placeholder. On a Mac without the developer tools (Xcode or the
- * Command Line Tools), running it, even as `git --version`, makes macOS open its "install the command
- * line developer tools" window and exit non-zero. The server used to ask "is git here?" that way on the
- * first page load, so a user who had just installed Codeman without git and without an administrator
- * password got that window one second after the install finished, and again at every login.
- * `install.sh` never runs the placeholder for the same reason.
- *
- * So on macOS, when `git` on the server's PATH resolves to that placeholder, the developer tools are
- * proven first: `xcode-select -p` (a real binary that prints and never opens a window) must name a
- * folder that holds a git of its own. Otherwise git counts as absent and is never started.
- *
- * Every site that starts git calls `gitSpawnAllowed()` first and answers a refusal the way it already
- * answers a machine with no git (`gitMissingError()` carries `code: 'ENOENT'` for that).
- * `test/git-spawn-gate.test.ts` fails on a git spawn in a file that does not go through this gate.
- *
- * The decision is pure (`gitSpawnWouldPrompt`, `findOnPath`); the IO around it is two bounded steps, a
- * PATH scan and one `xcode-select -p` (a few milliseconds, capped at 3 s), and only on macOS. A "yes" is
- * kept for the life of the process; a "no" is asked again after `GIT_GATE_NEGATIVE_TTL_MS`, so
- * installing the developer tools later needs no server restart for the git features (the page's own
- * "git is available" flag stays memoized per process, like every other availability flag there).
- *
- * @module utils/git-availability
- */
-
-import { execFileSync } from 'node:child_process';
-import { realpathSync } from 'node:fs';
-import { delimiter, isAbsolute, join } from 'node:path';
-import { isExecutableRegularFile } from './cli-executable-resolver.js';
-
-/** Apple's placeholder. A real git (Homebrew, MacPorts, Nix) sits elsewhere on the PATH. */
-export const APPLE_GIT_PLACEHOLDER = '/usr/bin/git';
-
-const XCODE_SELECT = '/usr/bin/xcode-select';
-const XCODE_SELECT_TIMEOUT_MS = 3_000;
-
-/** How long a refusal is kept before the machine is looked at again. */
-export const GIT_GATE_NEGATIVE_TTL_MS = 60_000;
-
-/**
- * The first `name` on a PATH-style list that `isExecutable` accepts, or null. Pure.
- * Empty and relative entries are skipped: they mean "the current directory" of whoever runs the
- * command, which this lookup cannot know.
- */
-export function findOnPath(
-  name: string,
-  pathEnv: string | undefined,
-  isExecutable: (path: string) => boolean
-): string | null {
-  for (const dir of (pathEnv ?? '').split(delimiter)) {
-    if (!dir || !isAbsolute(dir)) continue;
-    const candidate = join(dir, name);
-    if (isExecutable(candidate)) return candidate;
-  }
-  return null;
-}
-
-export interface GitGateFacts {
-  platform: NodeJS.Platform;
-  /** What `git` resolves to on the server's PATH (symlinks followed), or null when there is none. */
-  gitPath: string | null;
-  /** Asked only when it decides the answer, so other machines never pay for it. */
-  developerToolsPresent: () => boolean;
-}
-
-/**
- * Would starting `git` open macOS's "install the developer tools" window? Pure.
- * Only Apple's placeholder does that, and only while no developer tools are installed. No git on the
- * PATH at all is not this function's case: the spawn then fails with ENOENT, which every caller handles.
- */
-export function gitSpawnWouldPrompt(facts: GitGateFacts): boolean {
-  if (facts.platform !== 'darwin') return false;
-  if (facts.gitPath !== APPLE_GIT_PLACEHOLDER) return false;
-  return !facts.developerToolsPresent();
-}
-
-/**
- * The developer folder `xcode-select -p` names must hold a git of its own (`usr/bin/git`, true for both
- * Xcode and the Command Line Tools). A selected folder that has since been deleted would otherwise read
- * as "tools present" and the placeholder would open its window after all.
- */
-export function developerDirHoldsGit(developerDir: string, isExecutable: (path: string) => boolean): boolean {
-  const dir = developerDir.trim();
-  if (!dir || !isAbsolute(dir)) return false;
-  return isExecutable(join(dir, 'usr', 'bin', 'git'));
-}
-
-function resolveGitOnPath(): string | null {
-  const found = findOnPath('git', process.env.PATH, isExecutableRegularFile);
-  if (!found) return null;
-  try {
-    return realpathSync(found);
-  } catch {
-    return found;
-  }
-}
-
-function developerToolsPresent(): boolean {
-  try {
-    const out = execFileSync(XCODE_SELECT, ['-p'], {
-      encoding: 'utf8',
-      timeout: XCODE_SELECT_TIMEOUT_MS,
-      stdio: ['ignore', 'pipe', 'ignore'],
-    });
-    return developerDirHoldsGit(out, isExecutableRegularFile);
-  } catch {
-    return false; // exit 2: no developer folder. Never the placeholder's window.
-  }
-}
-
-let allowed: boolean | null = null;
-let refusedAt = 0;
-
-/**
- * May the server start `git` right now? False only on a Mac whose only git is Apple's placeholder with
- * no developer tools behind it. Callers answer false as "git is not installed".
- */
-export function gitSpawnAllowed(): boolean {
-  if (allowed === true) return true;
-  if (allowed === false && Date.now() - refusedAt < GIT_GATE_NEGATIVE_TTL_MS) return false;
-  const platform = process.platform;
-  allowed = !gitSpawnWouldPrompt({
-    platform,
-    gitPath: platform === 'darwin' ? resolveGitOnPath() : null,
-    developerToolsPresent,
-  });
-  if (!allowed) refusedAt = Date.now();
-  return allowed;
-}
-
-/** The error a refused spawn stands in for: what Node raises when there is no `git` to start. */
-export function gitMissingError(): NodeJS.ErrnoException {
-  const err: NodeJS.ErrnoException = new Error('spawn git ENOENT');
-  err.code = 'ENOENT';
-  err.errno = -2;
-  err.syscall = 'spawn git';
-  err.path = 'git';
-  return err;
-}
-
-/** Test seam: forget the remembered answer. */
-export function resetGitGateForTests(): void {
-  allowed = null;
-  refusedAt = 0;
-}

src/web/repo-status.ts

@@ -41,7 +41,6 @@ import { createRequire } from 'node:module';
 import { promisify } from 'node:util';
 import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
 import { gitNonInteractiveEnv, redactGitCredentials } from '../git-clone.js';
-import { gitSpawnAllowed } from '../utils/git-availability.js';
 import { getInstallInfo } from './self-update.js';
 import type { RepoIncomingCommit, RepoRemoteRole, RepoRemoteStatus, RepositoryStatusResult } from '../types/update.js';
 
@@ -243,8 +242,6 @@ interface GitResult {
  * spawn would block the event loop for the whole wait.
  */
 async function runGit(args: string[], cwd: string, timeout = EXEC_TIMEOUT_MS): Promise<GitResult> {
-  // Never Apple's placeholder git on a Mac without developer tools (utils/git-availability.ts).
-  if (!gitSpawnAllowed()) return { ok: false, stdout: '', stderr: 'git is not installed' };
   try {
     const { stdout } = await execFileAsync('git', args, {
       cwd,

src/web/self-update.ts

@@ -41,7 +41,6 @@ import { createRequire } from 'node:module';
 import { dataPath } from '../config/instance.js';
 import { LAUNCHD_LABEL, SYSTEMD_UNIT } from '../config/service-names.js';
 import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
-import { gitSpawnAllowed } from '../utils/git-availability.js';
 import type {
   EnvironmentBlocker,
   EnvironmentGate,
@@ -430,8 +429,6 @@ export function reconcileUpdateOnBoot(now = Date.now()): void {
 
 /** Run a command, returning trimmed stdout, or null on any error. */
 function tryExec(cmd: string, args: string[], cwd?: string, timeout = EXEC_TIMEOUT_MS): string | null {
-  // Never Apple's placeholder git on a Mac without developer tools (utils/git-availability.ts).
-  if (cmd === 'git' && !gitSpawnAllowed()) return null;
   try {
     return execFileSync(cmd, args, { cwd, encoding: 'utf-8', timeout, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
   } catch {

test/git-spawn-gate.test.ts

@@ -1,181 +0,0 @@
-/**
- * @fileoverview The gate in front of every `git` the server starts (src/utils/git-availability.ts).
- *
- * On a Mac without the developer tools, `/usr/bin/git` is Apple's placeholder: running it, even as
- * `git --version`, opens the system's "install the command line developer tools" window. The server did
- * exactly that on the first page load after a no-admin install (found 2026-11-06 on a new MacBook: the
- * system log named the Codeman server as the parent of that `git`).
- *
- * Two halves: the pure decision, and a scan of `src/` that fails when a file starts git without going
- * through the gate, so the next git caller cannot bring the window back.
- */
-
-import { readdirSync, readFileSync } from 'node:fs';
-import { join, relative, sep } from 'node:path';
-import { describe, expect, it } from 'vitest';
-import {
-  APPLE_GIT_PLACEHOLDER,
-  developerDirHoldsGit,
-  findOnPath,
-  gitMissingError,
-  gitSpawnAllowed,
-  gitSpawnWouldPrompt,
-  resetGitGateForTests,
-} from '../src/utils/git-availability.js';
-
-const never = (): boolean => {
-  throw new Error('must not be asked');
-};
-
-describe('gitSpawnWouldPrompt', () => {
-  it('is true only for Apple’s placeholder on a Mac without developer tools', () => {
-    expect(
-      gitSpawnWouldPrompt({ platform: 'darwin', gitPath: APPLE_GIT_PLACEHOLDER, developerToolsPresent: () => false })
-    ).toBe(true);
-  });
-
-  it('lets the placeholder run once the developer tools are there', () => {
-    expect(
-      gitSpawnWouldPrompt({ platform: 'darwin', gitPath: APPLE_GIT_PLACEHOLDER, developerToolsPresent: () => true })
-    ).toBe(false);
-  });
-
-  it('never asks about developer tools for a git that is not the placeholder', () => {
-    for (const gitPath of ['/opt/homebrew/bin/git', '/usr/local/bin/git', '/nix/store/x/bin/git']) {
-      expect(gitSpawnWouldPrompt({ platform: 'darwin', gitPath, developerToolsPresent: never })).toBe(false);
-    }
-  });
-
-  it('leaves a Mac with no git on the PATH to the spawn’s own ENOENT', () => {
-    expect(gitSpawnWouldPrompt({ platform: 'darwin', gitPath: null, developerToolsPresent: never })).toBe(false);
-  });
-
-  it('is never true off macOS, where /usr/bin/git is a real git', () => {
-    for (const platform of ['linux', 'win32', 'freebsd'] as const) {
-      expect(gitSpawnWouldPrompt({ platform, gitPath: APPLE_GIT_PLACEHOLDER, developerToolsPresent: never })).toBe(
-        false
-      );
-    }
-  });
-});
-
-describe('findOnPath', () => {
-  const has =
-    (...paths: string[]) =>
-    (p: string) =>
-      paths.includes(p);
-
-  it('returns the first match in PATH order', () => {
-    const exists = has('/opt/homebrew/bin/git', '/usr/bin/git');
-    expect(findOnPath('git', '/opt/homebrew/bin:/usr/bin', exists)).toBe('/opt/homebrew/bin/git');
-    expect(findOnPath('git', '/usr/bin:/opt/homebrew/bin', exists)).toBe('/usr/bin/git');
-  });
-
-  it('skips empty and relative entries, which mean the current directory', () => {
-    const exists = has('git', 'bin/git', '/usr/bin/git');
-    expect(findOnPath('git', ':.:bin:/usr/bin', exists)).toBe('/usr/bin/git');
-  });
-
-  it('is null when nothing matches or there is no PATH', () => {
-    expect(findOnPath('git', '/a:/b', () => false)).toBeNull();
-    expect(findOnPath('git', undefined, () => true)).toBeNull();
-    expect(findOnPath('git', '', () => true)).toBeNull();
-  });
-});
-
-describe('developerDirHoldsGit', () => {
-  it('needs a git inside the folder xcode-select names', () => {
-    const exists = (p: string) => p === '/Library/Developer/CommandLineTools/usr/bin/git';
-    expect(developerDirHoldsGit('/Library/Developer/CommandLineTools\n', exists)).toBe(true);
-    // A selected Xcode that was deleted since: the placeholder would open its window after all.
-    expect(developerDirHoldsGit('/Applications/Xcode.app/Contents/Developer\n', exists)).toBe(false);
-  });
-
-  it('refuses empty and relative answers', () => {
-    expect(developerDirHoldsGit('', () => true)).toBe(false);
-    expect(developerDirHoldsGit('   \n', () => true)).toBe(false);
-    expect(developerDirHoldsGit('relative/dir', () => true)).toBe(false);
-  });
-});
-
-describe('gitMissingError', () => {
-  it('reads as the ENOENT every caller already answers with "git is not installed"', () => {
-    const err = gitMissingError();
-    expect(err.code).toBe('ENOENT');
-    expect(err.message).toBe('spawn git ENOENT');
-    expect(String(err)).toMatch(/enoent/i); // git-worktrees.ts and git-clone.ts match the string form
-  });
-});
-
-describe('gitSpawnAllowed', () => {
-  it.skipIf(process.platform === 'darwin')('is always true off macOS and does no IO there', () => {
-    resetGitGateForTests();
-    expect(gitSpawnAllowed()).toBe(true);
-    expect(gitSpawnAllowed()).toBe(true);
-  });
-});
-
-// ─── Scan: no git spawn outside the gate ─────────────────────────────────────
-
-const SRC = join(__dirname, '..', 'src');
-
-/** A call that starts `git` as the program (argv form; the server never builds a git shell string). */
-const GIT_SPAWN = /\b(?:spawn|spawnSync|execFile|execFileSync|execFileAsync|exec|execSync|tryExec)\(\s*['"`]git['"`]/g;
-
-/**
- * Files that start git, with how many call sites each has. A new site in one of them, or a new file,
- * fails here on purpose: add `gitSpawnAllowed()` in front of it (see the module's fileoverview), then
- * update this table.
- */
-const GATED: Record<string, number> = {
-  'git-clone.ts': 2,
-  'git-fetch.ts': 2,
-  'git-workspace-status.ts': 1,
-  'git-worktrees.ts': 1,
-  'readmymind-collectors.ts': 1,
-  'web/repo-status.ts': 1,
-  'web/self-update.ts': 8,
-};
-
-function walk(dir: string, out: string[] = []): string[] {
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const full = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      if (entry.name === 'public' || entry.name === 'node_modules') continue;
-      walk(full, out);
-    } else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) {
-      out.push(full);
-    }
-  }
-  return out;
-}
-
-describe('every git the server starts goes through the gate', () => {
-  const found: Record<string, number> = {};
-  const ungated: string[] = [];
-  for (const file of walk(SRC)) {
-    const text = readFileSync(file, 'utf8');
-    const sites = text.match(GIT_SPAWN)?.length ?? 0;
-    if (!sites) continue;
-    const rel = relative(SRC, file).split(sep).join('/');
-    found[rel] = sites;
-    if (!/\bgitSpawnAllowed\(\)/.test(text)) ungated.push(rel);
-  }
-
-  it('finds the spawn sites at all (the pattern still matches the code)', () => {
-    expect(Object.keys(found).length).toBeGreaterThan(0);
-  });
-
-  it('has no file that starts git without calling gitSpawnAllowed()', () => {
-    expect(ungated).toEqual([]);
-  });
-
-  it('matches the reviewed list of sites, so a new one is looked at', () => {
-    expect(found).toEqual(GATED);
-  });
-
-  it('keeps the gate itself free of git', () => {
-    const gate = readFileSync(join(SRC, 'utils', 'git-availability.ts'), 'utf8');
-    expect(gate.match(GIT_SPAWN)).toBeNull();
-  });
-});