feat: multi-instance management (#109) (#118)

Closes #109. Sub-issues #110, #111, #112, #113, #114, #115 all closed.

## Summary

Refactor `@forgeplan/web` for multi-instance use:

1. **citty-based CLI** — `bin/forgeplan-web.mjs` shrinks 367→5 lines;
subcommands live in `bin/commands/{init,update,start}.mjs`; helpers in
`bin/lib/`. Single allow-listed dep (`citty@0.2.2`) per amended rule 23.
2. **`--scope user|project` flag** — init writes to
`<cwd>/.forgeplan-web/` or `~/.forgeplan-web/`. `init -y` keeps
defaulting to project (compat); interactive prompt picks user as the new
default. Non-TTY without flag fails clearly.
3. **`start` resolution chain** — project → user → prompt-init. Explicit
`--scope` short-circuits the chain.
4. **Global instance registry** at `~/.forgeplan-web/instances.json` —
incremental ports, pid + heartbeat liveness, atomic tmp+rename writes,
stale sweep on every start. New `/api/instances` readonly endpoint
mirrors the registry to the UI.
5. **Combobox primitive** in `template/src/shared/ui/combobox/` (bits-ui
2.18.1; default + mono variants × sm/md sizes; showcased on /playground;
rule-24 clean).
6. **HealthBar instance switcher** — when ≥2 instances are running, the
project label becomes a Combobox; selecting another instance navigates
the browser to `http://host:port`. Single-instance behavior unchanged.

## Why

Original issue: install `forgeplan-web` once per user (not per project),
run several instances simultaneously, switch between them from any
instance's UI. Refined plan keeps backwards compat (`--scope project` is
still the `init -y` default) so existing setups don't break.

## Forgeplan artifacts (all `active`, R_eff > 0)

- ADR-003 — amend rule 23 to permit citty in `bin/`
- ADR-004 — registry path + JSON format + atomic writes
- PRD-024 + RFC-020 — citty integration
- PRD-025 + RFC-021 — `--scope` flag + user-scope path
- PRD-026 + RFC-022 — start resolution chain
- PRD-027 + RFC-023 + SPEC-003 — instance registry
- PRD-028 + RFC-024 — Combobox primitive
- PRD-029 + RFC-025 — HealthBar switcher
- EVID-029..034 — smoke + svelte-check + manual scenarios per PRD

Rules touched (each via dedicated PRD/ADR):
- `.claude/rules/20-init-host-isolation.md` — user-scope writes are
gitignore-silent (PRD-025)
- `.claude/rules/22-readonly-proxy.md` — `/api/instances` allow-list
extension (PRD-027)
- `.claude/rules/23-bin-zero-deps.md` — citty named exception (ADR-003)

## Test plan

- [x] `npm run smoke` — PASS at every wave (citty refactor, scope
wiring, registry, HealthBar)
- [x] `npm run build` — svelte-check 1056 files / 0 errors / 0 warnings
- [x] Manual: `init -y --scope user` writes only to `~/.forgeplan-web/`,
host `.gitignore` untouched
- [x] Manual: `init -y` (no flag) defaults to project (compat preserved)
- [x] Manual: Two instances on 5174 + 5175 (or first free pair); both
register; SIGKILL on one swept on next start; heartbeat ticks at ~30s;
deregister within 2s of SIGTERM
- [x] Manual: HealthBar shows Combobox when ≥2 instances;
single-instance fallback verified
- [x] Manual: `/api/instances` returns standard envelope `{ ok, data: {
instances }, cmd: "registry:read" }`
- [x] `forgeplan health` clean post-Wave-7
- [x] Rule 23 verifier exits 0 (only `citty` + `node:*` + relative
siblings in `bin/`)
- [x] Rule 24 grep clean (no upper-layer `:global()` reaches into
Combobox internals)
- [ ] CI matrix (ubuntu/macos/windows × Node 22) — runs on PR open

## Out of scope (deferred follow-ups)

- Cross-host federation (talking to instances on other machines)
- Auth / per-instance access control
- Migration tool for existing project-scope `.forgeplan-web/` →
user-scope
- Full XDG compliance (`XDG_CONFIG_HOME` etc.) — RFC-021 keeps
`~/.forgeplan-web/` for predictability
- Smoke coverage for `--scope user` path + multi-instance scenario
(current smoke covers single project-scope instance only)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: fedorovvvv

.claude/rules/20-init-host-isolation.md

@@ -1,27 +1,47 @@
 # `init` host isolation
 
-`bin/forgeplan-web.mjs init` runs in the user's project directory. It
-MUST write only inside `<cwd>/.forgeplan-web/`, with **one** narrow
-exception: appending an ignore rule for `.forgeplan-web/` to the host's
-`.gitignore` (see ADR-001). Every other host write is forbidden.
+`bin/forgeplan-web.mjs init` runs in the user's project directory. Its
+write boundary depends on the resolved scope (PRD-025 / RFC-021):
 
-## Forbidden writes from `init`
+- **Project scope** (`--scope project`, or `-y` without `--scope`, or the
+  user picks "project" interactively): writes only inside
+  `<cwd>/.forgeplan-web/`, with **one** narrow exception — appending an
+  ignore rule for `.forgeplan-web/` to the host's `.gitignore` (see
+  ADR-001). Every other host write is forbidden.
+- **User scope** (`--scope user`, or the user picks "user" interactively):
+  writes only inside `~/.forgeplan-web/` (resolved from `os.homedir()`,
+  per RFC-021 / ADR-004). The host project's `.gitignore` MUST NOT be
+  touched — the home directory is workspace-agnostic and the user-scope
+  scaffold is shared across projects, so an "ignore" hint in any
+  individual project would be misleading. User scope likewise does NOT
+  require a `.forgeplan/` workspace in the cwd at install time; the
+  workspace is bound at `start` time via `FORGEPLAN_CWD`.
+
+## Forbidden writes from `init` (both scopes)
 
 - The host's `package.json`, `pnpm-lock.yaml`, `package-lock.json`,
   `yarn.lock`.
 - The host's `.npmrc`, `.editorconfig`, or any other root config.
 - The host's `node_modules/`.
 - The host's `.forgeplan/` (the workspace is *read* via the bundled
   `forgeplan` CLI; never written by us).
-- Any file outside `<cwd>/.forgeplan-web/` other than the single
-  `.gitignore` exception below.
+- Under `--scope user`: the host's `.gitignore` MUST NOT be created,
+  read-then-rewritten, or appended. User scope is gitignore-silent.
+- Any file outside the resolved target directory (project: `<cwd>/.forgeplan-web/`,
+  user: `~/.forgeplan-web/`) other than the single `.gitignore`
+  exception below — and that exception applies to project scope only.
 
 ## Allowed writes
 
-- Anything inside `<cwd>/.forgeplan-web/`.
-- `<cwd>/.forgeplan-web/forgeplan-web.json` (workspace pointer the
-  SvelteKit server reads at runtime).
-- `<cwd>/.gitignore` — **append-only**, with these constraints:
+- **Project scope** only: anything inside `<cwd>/.forgeplan-web/`,
+  including `<cwd>/.forgeplan-web/forgeplan-web.json` (workspace pointer
+  the SvelteKit server reads at runtime).
+- **User scope** only: anything inside `~/.forgeplan-web/`, including
+  `~/.forgeplan-web/forgeplan-web.json`. The `workspaceRoot` field in
+  the user-scope config is `null` at init-time (the user-scope dist is
+  workspace-agnostic; `start` binds the workspace from cwd or
+  `FORGEPLAN_CWD` at runtime).
+- **Project scope** only: `<cwd>/.gitignore` — **append-only**, with these constraints:
   - Add at most one ignore line: `.forgeplan-web/`.
   - The append is idempotent. Detection regex per line:
     `^[ \t]*\.forgeplan-web\/?[ \t]*$`. If a matching line is already
@@ -46,13 +66,18 @@ idempotent, reversible, and opt-out — see ADR-001.
 
 ## Verification
 
-- `git status` in the host project after `init` must show changes only
-  inside `.forgeplan-web/` and (at most) a single appended block at the
-  end of `.gitignore`.
-- The `init()` function in `bin/forgeplan-web.mjs` must not call
-  `writeFileSync` / `copyFileSync` / `mkdirSync` with any path that
-  does not resolve under `target` (`.forgeplan-web/`) or under the
-  host's `.gitignore`.
-- Running `init` twice must not duplicate the `.gitignore` entry.
+- After `init -y` or `init --scope project`: `git status` in the host
+  project must show changes only inside `.forgeplan-web/` and (at most)
+  a single appended block at the end of `.gitignore`.
+- After `init --scope user`: `git status` in the cwd must show **no**
+  changes at all. All writes land under `~/.forgeplan-web/`.
+- `runInit()` in `bin/commands/init.mjs` must not call `writeFileSync`
+  / `copyFileSync` / `mkdirSync` with any path that does not resolve
+  under the resolved scope target (`<cwd>/.forgeplan-web/` or
+  `~/.forgeplan-web/`) — and, only under project scope, the host's
+  `.gitignore`.
+- Running `init -y` twice must not duplicate the `.gitignore` entry.
 - Running `init -y --no-gitignore` must not touch `.gitignore` at all
   (no create, no append, no read-then-rewrite).
+- `ensureGitignore` is called from `runInit` only when `scope ===
+  "project"`; user-scope code paths must not even invoke it.

.claude/rules/22-readonly-proxy.md

@@ -29,7 +29,7 @@ revision of this rule. See PRD-012 / RFC-011.
 
 ## Allow-list extension: `/api/update-check` (non-forgeplan)
 
-`/api/update-check` is the **single** non-forgeplan endpoint permitted from
+`/api/update-check` is one of the non-forgeplan endpoints permitted from
 `/api/*`. It probes the npm registry for the latest published version of
 `@forgeplan/web` so the UI can surface an "Update available" affordance.
 
@@ -52,6 +52,40 @@ Any additional non-forgeplan endpoint (whether it hits npm, GitHub,
 crates.io, or anything else) requires a new Forgeplan artifact and a fresh
 amendment to this rule. See PRD-013 / RFC-012.
 
+## Allow-list extension: `/api/instances` (non-forgeplan)
+
+`/api/instances` is the second non-forgeplan endpoint permitted from
+`/api/*`. It exposes a read-only mirror of the global instance registry at
+`~/.forgeplan-web/instances.json` (PRD-027 / RFC-023 / SPEC-003 / ADR-004) so
+the UI can surface an instance switcher (PRD-029, Wave 6).
+
+Constraints (every one of these is enforceable from the diff):
+
+- Method: `GET` only.
+- File path: the registry file is resolved as
+  `path.join(os.homedir(), ".forgeplan-web", "instances.json")` —
+  **no interpolation, no env override, no user input** on the path.
+- **No spawn, no `fs.write*` / `fs.mkdir*` / `fs.rename*` / `fs.unlink*`**.
+  The endpoint MUST NOT mutate the registry; mutations live exclusively in
+  `bin/lib/registry.mjs`. The endpoint reads via `node:fs.readFileSync`
+  only and applies an in-process liveness sweep (`process.kill(pid, 0)` +
+  heartbeat freshness ≤ 60 s) before returning.
+- No Forgeplan invocation, no network call, no host filesystem mutation.
+  The only side-effect is a process-local in-memory cache (2 s TTL, single
+  inflight promise) inside
+  `template/src/shared/server/registry.ts#readInstances`.
+- Response shape mirrors the standard envelope: `{ ok, data: { instances },
+  cmd: "registry:read", error? }`. `instances` MUST conform to the
+  SPEC-003 v1 row shape (id / host / port / pid / scope / workspaceRoot /
+  projectName / startedAt / heartbeatAt / webVersion / forgeplanCli);
+  malformed rows are silently dropped from the live view.
+- Errors (file read, JSON parse) MUST fall back to `{ ok: false, error,
+  data: { instances: [] } }` — never throw.
+
+Any additional non-forgeplan endpoint (whether it hits npm, GitHub,
+crates.io, the local filesystem outside the registry, or anything else)
+requires a new Forgeplan artifact and a fresh amendment to this rule.
+
 ## Forbidden `forgeplan` subcommands from any `/api/*` endpoint
 
 Any subcommand that mutates the workspace:
@@ -97,3 +131,8 @@ browser invalidates that.
 - `grep -RIn "fetch(" template/src/routes/api/` must show external URLs
   only inside `update-check/+server.ts`, and the URL must appear as a
   string literal (`https://registry.npmjs.org/@forgeplan/web/latest`).
+- `template/src/routes/api/instances/+server.ts` MUST NOT contain any
+  `spawn`, `execFile`, `writeFileSync`, `renameSync`, or `mkdirSync`
+  call (read-only constraint above). The reader
+  `template/src/shared/server/registry.ts` MAY only call
+  `existsSync` + `readFileSync` against `~/.forgeplan-web/instances.json`.

.claude/rules/23-bin-zero-deps.md

@@ -1,31 +1,50 @@
-# `bin/` zero runtime dependencies
+# `bin/` near-zero runtime dependencies (amended by ADR-003)
 
-`bin/forgeplan-web.mjs` is invoked by `npx @forgeplan/web init` and
-`npx @forgeplan/web start`. The bin script itself MUST run with Node
-built-ins only — it does its job (copy `dist/` into `.forgeplan-web/`,
-spawn `node .forgeplan-web/index.js`) without needing any third-party
-import.
+`bin/forgeplan-web.mjs` is invoked by `npx @forgeplan/web init`,
+`npx @forgeplan/web update`, and `npx @forgeplan/web start`. The bin
+script does its job (copy `dist/` into `.forgeplan-web/`, spawn
+`node .forgeplan-web/index.js`) with Node built-ins plus exactly **one**
+allow-listed CLI library: `citty` (per ADR-003).
 
-## Allowed in `bin/`
+ADR-003 amended the historical "zero-dep" rule to a **named-allowlist**
+rule: `citty` (and any of its transitive deps) is the **only** named
+exception. Adding any other third-party import to `bin/` requires a new
+ADR — not an amendment to this one.
+
+## Allowed in `bin/` (amended by ADR-003)
 
 - `node:*` modules (`node:fs`, `node:child_process`, `node:path`,
   `node:url`, `node:os`, `node:crypto`, `node:util`).
-- Relative imports of sibling `.mjs` files **inside `bin/`** (e.g.
-  `import { … } from "./banner.mjs"`). These are first-party code that
-  ships in the `bin/` folder of the published tarball; they introduce
-  no third-party resolution at `npx` time. Each such sibling file is
-  itself bound by this rule (zero `node_modules/` imports, `node:*`-only).
+- Relative imports of sibling `.mjs` files inside `bin/` (e.g.
+  `import { … } from "./banner.mjs"`, `from "./lib/config.mjs"`,
+  `from "./commands/init.mjs"`). These are first-party code that ships
+  in the `bin/` folder of the published tarball; they introduce no
+  third-party resolution at `npx` time. Each such sibling file is
+  itself bound by this rule (`node:*` + `citty` only, plus relative
+  siblings).
+- **`citty`** — CLI framework providing `defineCommand`, `runMain`,
+  `parseArgs`, typed args, auto-help, and subcommand routing. Pinned
+  to `^0.2.2` (caret-minor). Bumping major/minor requires re-evaluating
+  ADR-003. As of `citty@0.2.2` the package has zero runtime
+  `dependencies` (it bundles its own helpers and uses
+  `node:util.parseArgs`); should a future version reintroduce
+  transitive deps, those are covered by this rule too as long as they
+  are pulled by `citty` and not declared at the root.
 - Synchronous I/O (`mkdirSync`, `cpSync`, …) — the script is short and
   CLI-bound; readability beats event-loop nicety.
 
 ## Forbidden in `bin/`
 
-- Any `import` from a third-party package.
-- Any `require()` from `node_modules/` at the package root.
-- Spawning `node_modules/.bin/*` binaries from the package root (root
-  has no `node_modules`).
-- Adding entries to the root `package.json#dependencies` to support the
-  bin script.
+- Any third-party import OTHER than `citty` (and any transitive deps
+  it pulls). E.g. `chalk`, `commander`, `yargs`, `figlet`, `prompts`,
+  `ora`, `kleur` are all forbidden. If you think one is needed, open a
+  new ADR.
+- Any `require()` from `node_modules/` at the package root that is not
+  resolved through citty.
+- Spawning `node_modules/.bin/*` binaries from the package root.
+- Adding any other entry to root `package.json#dependencies` to support
+  the bin script. Currently allowed: `{ "citty": "^0.2.2" }` — and
+  nothing else.
 
 ## Note on `dist/` and `dist-experimental/`
 
@@ -43,8 +62,8 @@ The published tarball ships **two** pre-built artifacts (PRD-014 / RFC-013):
 
 In both cases the bin script only `spawn()`s `node` against the
 artifact's `index.js` — it never imports anything from the artifact's
-internals. This rule is about the bin script itself staying zero-dep;
-the artifacts are governed by rule 21.
+internals. This rule is about the bin script itself staying bound to
+the citty + node:* allow-list; the artifacts are governed by rule 21.
 
 After the bundled shape graduates from `--experimental` (see
 `TODO(rfc-013-graduation)` in `bin/forgeplan-web.mjs` and
@@ -53,10 +72,13 @@ tarball and this section will collapse to one paragraph.
 
 ## Required
 
-- The root `package.json` must keep `dependencies` empty (or absent). It
-  may have `devDependencies` for repo tooling (currently: `esbuild` for
-  building `dist-experimental/`). The published tarball ships `bin/`
-  (zero-dep), `dist/` (with its own `node_modules/`),
+- The root `package.json` must keep `dependencies` to **exactly** the
+  citty entry: `{ "citty": "^0.2.2" }` (caret-minor pin per ADR-003).
+  No other runtime deps allowed at the root. `devDependencies` for
+  repo tooling are unconstrained by this rule (currently: `esbuild`).
+- The published tarball ships `bin/` (incl. `bin/cli.mjs`,
+  `bin/commands/*.mjs`, `bin/lib/*.mjs`, `bin/banner.mjs`,
+  `bin/forgeplan-web.mjs`), `dist/` (with its own `node_modules/`),
   `dist-experimental/` (single bundle, no `node_modules/`), and
   `README.md`.
 - `package.json#engines` pins Node ≥ `^20.19.0 || >=22.12.0`. Any change
@@ -67,31 +89,51 @@ tarball and this section will collapse to one paragraph.
 `npx @forgeplan/web init` is the user's first contact with the package.
 The package itself is pre-built — `init` is a `cp -r` of `dist/` into
 `.forgeplan-web/`, and `start` is a `spawn(node, dist/index.js)`. The bin
-must not pull in third-party code that npm would have to resolve before
-invocation; doing so would re-introduce the exact latency we removed by
-shipping a pre-built artifact.
+must not pull in arbitrary third-party code that npm would have to
+resolve before invocation; doing so would re-introduce the exact latency
+we removed by shipping a pre-built artifact. The citty exception is
+ADR-003's deliberate trade-off: ~5KB / ~50ms for subcommand routing,
+typed args, auto-help, and a future prompt hook (#111).
 
 ## Verification
 
 ```bash
-# bin/* must only import node:* modules or relative sibling .mjs files.
-# Allowed:   from 'node:fs', from "./banner.mjs", from "../bin/x.mjs"
-# Forbidden: from 'chalk', from 'figlet', from any bare specifier.
+# bin/* must only import node:* modules, citty, or relative sibling .mjs files.
+# Allowed:   from 'node:fs', from 'citty', from "./banner.mjs",
+#            from "./lib/config.mjs", from "./commands/init.mjs"
+# Forbidden: from 'chalk', from 'commander', from any other bare specifier.
 # Also handles multi-line `import { … } from "node:fs";` because we match
 # the `from "…"` line itself, regardless of where the `import` keyword sits.
-for f in bin/*.mjs; do
+fail=0
+for f in $(find bin -name '*.mjs' -type f); do
   hits=$(grep -E "(from|require\()\s*['\"]" "$f" \
-    | grep -vE "(from|require\()\s*['\"]node:" \
+    | grep -vE "(from|require\()\s*['\"](node:|citty['\"])" \
     | grep -vE "(from|require\()\s*['\"]\\.{1,2}/" || true)
   if [ -z "$hits" ]; then
-    echo "OK ($f): no third-party deps"
+    echo "OK ($f): bin allow-list (node:*, citty, relative)"
   else
-    echo "FAIL ($f): third-party imports found:"
+    echo "FAIL ($f): non-allow-listed imports found:"
     echo "$hits"
-    exit 1
+    fail=1
   fi
 done
-
-# root package must not declare runtime deps
-node -e "const p=require('./package.json'); if (p.dependencies && Object.keys(p.dependencies).length) { console.error('FAIL: runtime deps present', p.dependencies); process.exit(1)} else { console.log('OK: no runtime deps') }"
+[ "$fail" -eq 0 ] || exit 1
+
+# root package may declare ONLY citty as runtime dep
+node -e "
+const p = require('./package.json');
+const deps = p.dependencies || {};
+const keys = Object.keys(deps).sort();
+const allowed = ['citty'];
+const extra = keys.filter((k) => !allowed.includes(k));
+if (extra.length) {
+  console.error('FAIL: unexpected runtime deps', extra);
+  process.exit(1);
+}
+if (!deps.citty) {
+  console.error('FAIL: citty missing from dependencies (ADR-003 invariant I3)');
+  process.exit(1);
+}
+console.log('OK: root deps = { citty:', deps.citty, '}');
+"
 ```