feat(cli-registry): CLI management write API + Settings UI (Phases 1-6)

[opticon454]

Summary

Completes docs/cli-enable-disable-plan.md — "PR C" from the original #343 review, which deliberately split the trust-model decision (settings UI + write endpoints + auto-install) out of that PR to be decided on its own merits rather than inside a 100-file diff. That decision is now made and implemented in phases.

~/.codeman/clis.json has been read-only since the registry existed. This adds the write side: a Settings UI section to enable/disable a CLI, install one that's missing, or add a custom one — without hand-editing the file.

• Phase 1 — cliManagementEnabled master feature flag (synced, default OFF). Every write endpoint refuses with 403 FORBIDDEN when it's off.
• Phase 2 — GET /api/clis: every registry entry (stock + custom, enabled or not), admin-gated to an empty list (never a 403) for a non-admin in multi-user mode.
• Phase 3 — PUT /api/clis/:id: toggles enabled for any existing entry, stock or custom. shell is structurally un-disableable (several code paths assume a raw-terminal fallback always exists); claude is a normal toggleable entry like any other CLI — internal session creation resolves a CLI via getCli(), which doesn't check enabled at all, so disabling it only affects the Run menu and new-session requests through the API, identical in kind to disabling grok/codex/etc.
• Phase 4 — POST /api/clis/:id/install: runs a stock entry's already-vetted install command (bounded by timeout, process-group killed on expiry, output captured, audit-logged). A custom entry's id is refused outright, independent of anything Phase 5 does — a custom entry's install text stays display-only, never executed.
• Phase 5 — POST /api/clis (create) / PUT /api/clis/custom/:id (update) / DELETE /api/clis/:id (custom only): a deliberately minimal request shape (id/label/shortBadge/binaries/a simple launch variant), assembled into a full CliEntry with conservative capability defaults and re-validated through the same CliEntrySchema every stock entry goes through — no relaxed path for UI-originated entries. Stock-id collisions and edits/deletes against a stock id are rejected explicitly.
• Phase 6 — Settings UI (App Settings → Agents & CLIs), gated independently on the flag AND admin-in-multi-user-mode, so it's hidden entirely for a non-admin rather than shown-empty. The Installed CLIs list sorts installed-first, then alphabetically within each group. shell's row shows no toggle at all ("Always available") rather than a permanently-greyed switch that read as broken.

registry-writer.ts is a new, deliberately separate module so registry.ts itself stays import-side-effect-free (its own header documents that property), same tmp+rename+0600 write shape as custom-model-hosts.ts.

Test plan

• 27 new/updated route tests covering every gate (flag off, admin, unknown id), collision (stock-id reuse, duplicate custom id), and cleanup path
• Merged against current upstream master (56 commits ahead of the branch point) in an isolated worktree; 3 conflicts, all independent non-contradicting additions at the same insertion point (upstream's watching-badge feature / our disabled-CLI hiding fix; two test files each expecting a different newly-added strip), resolved by keeping both sides
• Full CI gate on the merged tree, fresh clone: 426/427 test files, 8198 tests, 0 failures
• npm run typecheck && npm run lint && npm run check:frontend-syntax && npm run check:public-assets && npm run format:check all clean
• Live-verified end-to-end against a real deployment: flag gate, stock toggle, shell un-disableable guard, claude toggle, custom-entry create/list/delete, auth enforcement

🤖 Generated with Claude Code

[opticon454]

@Ark0N This is the last piece of #343
Please review in full and let me know if you have any questions or things to fix

[Ark0N]

Thanks @opticon454 for finishing the last piece of #343. This adds the write side of the CLI registry: an opt-in cliManagementEnabled flag, /api/clis endpoints to toggle, install and add custom CLIs, a Settings section for it, and a catalogue-driven Run menu and welcome screen. The gating and the re-validation of custom entries through CliEntrySchema are exactly the shape I wanted, and the full gate is green here.

A few things need fixing before merge, mostly in the new writer:

Must fix

1. src/config/cli-registry/registry-writer.ts:29: an unparseable clis.json is treated as missing, so the next toggle overwrites it. The registry is memoized, so a hand-edit with a typo made while the server runs is never quarantined; one Settings click then replaces the user's file with a one-key file (I reproduced this). Please refuse the write, or quarantine the file the way readRegistryFile() does, and only start fresh on ENOENT. A test for it would be great.
2. registry-writer.ts:50: every write uses the same clis.json.<pid>.tmp name and the routes do an unserialized read-modify-write. Three parallel PUT /api/clis/:id calls gave me two 500s (ENOENT on rename) and lost two of the three toggles. Please serialize registry mutations through one promise chain and use a unique tmp suffix.
3. registry-writer.ts:29: the reader ignores clis.json when it has any group/world permission bit, but the writer reads it anyway and rewrites it 0600, which turns a refused file into trusted config. Please apply the same isUnsafePermissions() check before writing and refuse with a chmod hint.
4. Docs: CLAUDE.md (CLI registry paragraph) and docs/architecture-invariants.md:116 still say clis.json is read-only, docs/api-reference.md has none of the six new routes (they are public under /api/v1), and docs/cli-registry.md does not mention the Settings UI.
5. Please drop DEPLOYMENT_PLAN.md (the repo root is kept to tool-required files, and it carries your local paths and session notes) and docs/copilot-integration-plan.md (unrelated parked work). docs/cli-enable-disable-plan.md can stay.

Smaller things (same round if you can)

• src/web/routes/cli-registry-routes.ts:171: editing a disabled custom CLI re-enables it, since the form never sends enabled and the builder defaults to true. Default to the existing entry's value on update.
• src/web/public/session-ui.js:4605: with claude disabled, the runMode setter still falls back to 'claude', so the Run button posts a mode the server rejects. Fall back to the first enabled catalogue entry.
• cli-registry-routes.ts:81 and :135, plus UNTOGGLEABLE in settings-ui.js and the label === 'Claude' rewrites in session-ui.js / mobile-overview.js: these are id (or label) branches the registry rule asks us to avoid. kind === 'shell' covers the un-disableable case, and the stock probe map could be shared with server.ts rather than duplicated.
• src/web/public/settings-ui.js:1343: the generated welcome buttons are data-i18n-skip and read Run Claude instead of Run Claude Code, so zh-CN loses its existing translations. They also add new Codex and Shell welcome buttons; fine if intended, just say so in the description.
• cli-registry-routes.ts:397: please add a per-id in-flight guard for install (409 on a second request) and strip CODEMAN_* from the env you hand to the install script.
• The fileoverview and the CliEnableSchema comment still describe PUT /api/clis/:id as stock-only.
• The test/setup.ts env strip and the quick-start port move are fine, but would be easier to land as their own small PR.

Once the five must-fix items are in, I'm happy to merge; I can pick up any of the smaller ones at merge time if you run out of time.

[opticon454]

@Ark0N thanks for the thorough review. Everything is addressed in 2776ae0, must-fix and smaller items alike.

Must fix

1. Unparseable clis.json. The writer now starts fresh only on ENOENT. For a file that doesn't parse, or has no clis object, the write is refused with a 409 naming the fix, and the file is left byte-for-byte untouched. There's a test with a trailing-comma hand-edit.
2. Lost parallel toggles. Every mutation goes through mutateRegistryFile(), one promise chain. The existence and duplicate checks run inside the same serialized step as the write, and the registry is reloaded before the next mutation starts. The temp file is clis.json.<pid>.<uuid>.tmp, and it's cleaned up if the rename fails. There's a test firing four parallel PUT /api/clis/:id: all 200, all four on disk.
3. Permissions. isUnsafePermissions() is now exported from registry.ts, and the writer refuses (409) with the chmod 600 <path> hint. There's a POSIX test that the file keeps its 0644 mode rather than being rewritten as trusted 0600.
4. Docs. Updated the CLAUDE.md CLI registry paragraph and architecture-invariants.md (the writer, the serialization, the refusals). api-reference.md gains a CLI management section with all six routes, and cli-registry.md gains a Managing CLIs from Settings section. Also fixed a stale claim I found on the way: shortBadge was still listed as declared-for-later, but the Settings list reads it now.
5. Stray files. Removed DEPLOYMENT_PLAN.md and docs/copilot-integration-plan.md.

Smaller items

• Editing a custom CLI. An absent enabled now keeps the entry's current state (tested).
• runMode setter. A disabled mode now falls back to the first enabled agent in the catalogue, then any enabled entry, and never a hardcoded 'claude' (tested).
• Id and label branches. The shell guard is kind === 'shell' on both the server and in Settings; UNDISABLEABLE_IDS and UNTOGGLEABLE are gone. The stock probe map now lives in one place, src/utils/cli-installed-probes.ts, which both server.ts and GET /api/clis use. For the label === 'Claude' rewrites, I changed the stock label itself to Claude Code and dropped the rewrites. That regenerates config/clis.stock.json and the install.sh block. The codeman doctor row keeps its historical "Claude CLI" spelling via its existing override map. The phone Run button now reads "Claude Code", the same width as the "Antigravity" it already shows.
• Welcome buttons. They're translatable again, reading "Run Claude Code" / "Run Shell", which are the existing i18n keys. I added zh-CN entries for "Run Codex" and "Run OMP". The Codex and Shell welcome buttons are intended: the welcome screen now offers every enabled, available registry entry, custom ones included.
• Install. There's a per-id in-flight guard (a second request gets 409 CONFLICT), and the install script gets the environment with every CODEMAN_* variable removed. Both are tested.
• Comments. The fileoverview and the CliEnableSchema comment now describe the toggle as covering stock and custom entries.
• Test-env changes. Split out into test: strip every inherited CODEMAN_* var from the suite (split from #476) #479 and reverted here, so this PR no longer touches test/setup.ts or the quick-start port.

Full gate on Linux: typecheck, lint, format:check, check:frontend-syntax and generate:cli-catalog --check are all clean, and npm test gives 427 files and 8217 tests passing.

[Ark0N]

Merged and shipped in 1.33.0 (https://github.com/Ark0N/Codeman/releases/tag/codeman@1.33.0). Thanks @opticon454, this closes out the CLI registry work you started in #343. The fix round was one of the cleanest I've had: every must-fix came back with a test that pins it (the trailing-comma hand-edit, the four parallel toggles, the 0644 file that stays 0644), and moving the probe map into cli-installed-probes.ts and relabelling the stock entry "Claude Code" got rid of the id branches properly instead of just hiding them. I ran the full gate on it merged with current master before landing (427 files, 8223 tests green). It's the headline of this release.