fix(macos): scrub parent-session env, survive node upgrades and reboots, store lanes by real path (#22)

What broke (code audit, untested on a Mac):
- Without systemd the server is always spawned from inside a Claude Code
  session, so it inherited CLAUDECODE, CLAUDE_CODE_SESSION_ID,
  CLAUDE_PLUGIN_ROOT, ... and tmux handed them to every lane pane (a codex
  pane even resolved as `claude` in `agenthub`'s harness check).
- The ~/.local/bin/agenthub launcher pinned a versioned node path that
  `brew upgrade`/nvm deletes, leaving the CLI dead until the next bootstrap.
- A discovery entry left over from before a reboot could name a recycled pid,
  so the bootstrap's fast path believed a dashboard was live and
  stopDashboard could signal an unrelated process.
- Lanes were stored under the typed cwd; macOS reports /private/tmp and the
  on-disk case, so sessions never bound to a /tmp or differently-cased lane.

What changed:
- server/index.js deletes a DENYLIST of parent-session variables at startup;
  user config (CLAUDE_CONFIG_DIR, CLAUDE_CODE_USE_BEDROCK, ANTHROPIC_*) stays.
- linkCli's launcher falls back to `node` on PATH when the pinned one is gone.
- liveServers ignores entries whose startedAt predates this boot (60 s margin).
- createLane and POST /api/lanes/ensure store/look up fs.realpathSync.native
  of an existing cwd; the liveness reaper also tries the realpath. Existing
  rows are untouched.
- session-liveness gains an exec seam so the darwin ps+lsof branch is tested.
- plugin-doctor names ~/.zshrc on darwin; INSTALL.md gains a macOS section
  with the Mac verification checklist, mirrored in both READMEs and PLUGINS.md.
No launchd, no macOptionIsMeta, engines stays >=20.
This commit is contained in:
2026-09-23 12:09:28 +07:00
parent aff79a787c
commit 478418f602
18 changed files with 288 additions and 15 deletions
+48
View File
@@ -86,6 +86,54 @@ Detaching is `Ctrl-b d` — it leaves the run alive, which is the whole point:
the browser terminal and your local terminal are two clients on one pane, and
restarting the dashboard never stops a run.
### macOS
Status: **code-audited, untested on a Mac.** The Mac-specific paths below are
covered by Linux-side unit tests only; the checklist at the end of this section
is what a Mac user runs to confirm them.
```bash
brew install node git tmux # Node >= 22.5 for the plugin install (nvm works too)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc # where the plugin puts `agenthub`
```
- **Node:** a plugin install needs **>= 22.5** (it stores data through
`node:sqlite`); a checkout still runs on Node 20. The `agenthub` launcher
pins the node that installed it and falls back to `node` on `PATH` when a
`brew upgrade` or `nvm` switch deletes that binary.
- **No systemd, so no auto-start on boot.** The server is a detached process
that runs until logout or reboot. It comes back at the next Claude Code
session start (within about 10 s), or by hand with `agenthub start`. A
discovery entry left over from before the reboot is ignored, so a recycled
pid can never pass for a live dashboard.
- **Started from a Claude Code session.** The server drops the variables that
describe that session (`CLAUDECODE`, `CLAUDE_CODE_SESSION_ID`,
`CLAUDE_PLUGIN_ROOT`, …) before anything else runs, so lane panes do not
inherit them. Your own configuration (`CLAUDE_CONFIG_DIR`,
`CLAUDE_CODE_USE_BEDROCK`, `ANTHROPIC_*`) passes through. A tmux server that
an older build started keeps its dirty global env until it exits
(`tmux kill-server` once, with no run you care about open).
- **Paths.** A lane's directory is stored by its real path, so a typed `/tmp/x`
becomes `/private/tmp/x` and a differently-cased path on a case-insensitive
volume becomes the one on disk — that is what sessions report, so they bind.
Lanes created before this change keep the string they were created with.
- **Account switching** uses the login Keychain item `Claude Code-credentials`;
macOS may ask once for permission the first time.
- **Option key** in the browser terminal types special characters (it is not
sent as Meta).
**Mac checklist** — please run it and report the result on issue #22:
1. Fresh plugin install from a Terminal `claude` session: `/agenthub-doctor` is all OK (the systemd row says not available) and the dashboard answers on `http://localhost:4820`.
2. `tmux show-environment -g | grep -i claude` prints nothing.
3. Add a Repo lane by typing its path in a different case: sessions bind to it, and `agenthub stage plan` inside it moves the map.
4. **Start Run** in the browser: the terminal attaches, typing works, an image paste into `claude` works, and `exit` returns to the run form.
5. Changes panel: diff, stage and commit on a lane.
6. Switch profile and check `claude /status` shows the new account. Repeat with a non-default `CLAUDE_HOME`, which also checks the Keychain service name.
7. `brew upgrade node && brew cleanup`, then `agenthub status` still works.
8. Reboot, open `claude`, and the dashboard comes back within about 10 s.
9. `/agenthub-update` completes and the server restarts on the new version.
---
## Step 1 — Clone the repository