@cldmv/gh-broker 0.9.0 → 0.10.1

package/README.md

@@ -19,19 +19,18 @@ It runs as a dedicated `gh-broker` system user, holds a read-scoped and a write-
 
 ## ✨ What's New
 
-### Latest: v0.9.0 (November 2026)
+### Latest: v0.10.1 (November 2026)
 
-- **Three report verbs for the release and fleet skills.** `report_alert_status` buckets each open Dependabot alert by where its fix stands (released but still open, fixed on `next`, open PR, closed PR, nothing). `report_release_changes` returns the PRs a release actually ships, grouped by changelog section, with the net `package.json` and dependency deltas. `report_dependents` finds every repo that declares an npm package, including dev-trunk repos on `dev`, and skips a `dev` that has fallen behind the default branch.
-- **`ciVerbosity` on `list_pull_requests`.** The same opt-in CI detail as `pull_request_read`, across a whole PR list with one shared call budget.
-- **Install from npm.** `sudo npx @cldmv/gh-broker <agent-user>` runs the installer from the prebuilt package. The tarball now ships only runtime files.
-- [View full v0.9.0 Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.9.0.md)
+- **The OTP gate says why it refused a code.** A wrong code now reads "not accepted", with the bad-code count and the lockout length, and a reused code says it's spent, so the agent can tell you what happened instead of just asking again.
+- **`report_dependents` lists dev branches on large orgs.** The GraphQL listing pages at 25 repos and backs off when GitHub times out, instead of failing with a raw 502.
+- [View full v0.10.1 Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.10.1.md)
 
 ### Recent Releases
 
+- **v0.10.0** (November 2026) — OTP gate for risky write tools, one socket per agent with the `gh-broker` command, eleven new write tools and a built-in deny list ([Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.10.0.md))
+- **v0.9.0** (November 2026) — `report_alert_status`, `report_release_changes` and `report_dependents` for the release and fleet skills, `ciVerbosity` on `list_pull_requests`, and install from npm ([Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.9.0.md))
 - **v0.8.0** (November 2026) — `npm_scaffold` creates an npm package and its trusted publisher, `ghcr_push` pushes images without an agent-held token, and optional credentials hide their tools ([Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.8.0.md))
 - **v0.7.0** (October 2026) — `issue_labels` adds, removes or swaps single labels without replacing the set, and `issue_write` warns that its `labels` does ([Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.7.0.md))
-- **v0.6.1** (October 2026) — MCP SDK 1.32.0 (same-origin redirects only) and a refreshed vitest toolchain; no broker source changes ([Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.6.1.md))
-- **v0.6.0** (October 2026) — Compact per-repo roll-up, filters and flow tier for `report_security_alerts`, and release-readiness analysis for `report_release_prs` ([Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.6.0.md))
 
 📚 For the complete version history, see the [docs/changelog/](https://github.com/CLDMV/gh-broker/tree/master/docs/changelog/) folder.
 
@@ -133,7 +132,7 @@ The broker presents its **own** MCP contract to the agent — a proxied tool's s
 
 ### 📦 **One-Command Install & Upgrade**
 
-`sudo node deploy/install.mjs` handles first install and every upgrade: builds under the checkout's own owner (no `chown`, ever), merges shipped config defaults over the deployed config, lets you choose how PATs are stored at rest, and runs a post-deploy smoke test.
+`sudo gh-broker install` (or `sudo node deploy/install.mjs` from a checkout) handles first install and every upgrade: builds under the checkout's own owner (no `chown`, ever), merges shipped config defaults over the deployed config, lets you choose how PATs are stored at rest, and runs a post-deploy smoke test.
 
 📦 **Full prerequisites, PAT scopes, and flags: [deploy/README.md](deploy/README.md)**
 
@@ -152,10 +151,11 @@ The broker presents its **own** MCP contract to the agent — a proxied tool's s
 
 gh-broker is a system service, not a library. The installer handles both the first install and every upgrade, and you can run it from npm or from a checkout.
 
-From npm ([`@cldmv/gh-broker`](https://www.npmjs.com/package/@cldmv/gh-broker)), with the prebuilt bundle:
+From npm ([`@cldmv/gh-broker`](https://www.npmjs.com/package/@cldmv/gh-broker)), with the prebuilt bundle, as a global install (upgrade with the same command, then `gh-broker install` again):
 
 ```sh
-sudo npx @cldmv/gh-broker <agent-user>
+sudo npm install -g --prefix /usr/local --ignore-scripts @cldmv/gh-broker
+sudo gh-broker install <agent-user>
 ```
 
 From a checkout:
@@ -166,13 +166,13 @@ cd gh-broker
 sudo node deploy/install.mjs <agent-user>
 ```
 
-Both take the same flags. The installer creates the service user and the socket group, builds as the checkout's owner when there's no bundle yet, merges the shipped defaults with the deployed config, stores the PATs in the backend you pick, installs the unit and runs a smoke test. Prerequisites, PAT scopes, unattended installs and every flag: [deploy/README.md](deploy/README.md).
+Both take the same flags. The installer creates the service user, registers each agent user (its own group, socket and MCP config; see `gh-broker agent`), builds as the checkout's owner when there's no bundle yet, merges the shipped defaults with the deployed config, stores the PATs in the backend you pick, installs the unit and runs a smoke test. Prerequisites, PAT scopes, unattended installs and every flag: [deploy/README.md](deploy/README.md).
 
 ---
 
 ## 🚀 Quick Start
 
-Point the agent's MCP client at the socket ([deploy/README.md § 3](deploy/README.md#3-point-claude-at-the-broker)). From then on the client sees an ordinary `tools/call`, and the broker resolves the credential, routes it, and (for custom/augmented tools) does the extra work in between:
+The installer writes each agent's MCP config for its own socket ([deploy/README.md § 3](deploy/README.md#3-agents-one-socket-and-one-mcp-config-each)). From then on the client sees an ordinary `tools/call`, and the broker resolves the credential, routes it, and (for custom/augmented tools) does the extra work in between:
 
 ```json
 // tools/call
@@ -201,6 +201,7 @@ src/
   catalog.ts        build the advertised tool list (real upstream schemas + custom + augmented)
   server.ts         Unix-socket MCP server toward the agent (StdioServerTransport)
   audit.ts          structured audit log (never tokens)
+  denylist.ts       tools refused at config load, gated or not (file writes, repo deletion, repo configuration)
   verbs/
     report_unlabeled.ts  issues/PRs with no labels, one repo or org-wide
     report_security_alerts.ts  open Dependabot/CodeQL/secret alerts, one repo or org-wide
@@ -216,6 +217,9 @@ src/
     npm-registry.ts      the npm registry requests npm_scaffold makes
     npm-tarball.ts       minimal npm tarball builder for the placeholder
     review_thread.ts     resolve/reply PR review threads (write PAT)
+    minimize_comment.ts  hide or show a comment (write PAT)
+    delete_branch.ts     delete a branch, refusing flow branches and open-PR heads/bases (write PAT, gated)
+    dismiss_alert.ts     dismiss or reopen a code scanning, Dependabot or secret scanning alert (write PAT, gated)
     ghcr_push.ts         ghcr_push / ghcr_push_status / ghcr_tags (GHCR classic PAT)
     ghcr/                config policy, tar + image-archive reader, OCI registry client, push, job queue
     link_issue.ts         addClosingIssueReference (App token) — DEFERRED, not wired in
@@ -238,7 +242,7 @@ config.sample.json   a full config with placeholder values, for reference only
 
 ## 📚 Documentation
 
-- **[Tools Reference](docs/TOOLS.md)** — every custom and augmented tool: `report_unlabeled`, `report_security_alerts`, `report_alert_status`, `report_release_prs`, `report_release_changes`, `report_dependents`, `report_ci_status`, the `pull_request_read` and `list_pull_requests` `ciVerbosity` extensions, `issue_labels`, `npm_scaffold`, `resolve_review_thread`/`reply_review_thread`, `ghcr_push`/`ghcr_push_status`/`ghcr_tags`, and how to add a new one
+- **[Tools Reference](docs/TOOLS.md)** — every custom and augmented tool: `report_unlabeled`, `report_security_alerts`, `report_alert_status`, `report_release_prs`, `report_release_changes`, `report_dependents`, `report_ci_status`, the `pull_request_read` and `list_pull_requests` `ciVerbosity` extensions, `issue_labels`, `npm_scaffold`, `resolve_review_thread`/`reply_review_thread`, `minimize_comment`, `delete_branch`, `dismiss_alert`, `ghcr_push`/`ghcr_push_status`/`ghcr_tags`, `otp_status`, the OTP gate and the deny list, and how to add a new one
 - **[Agent-as-Separate-User Model](docs/agent-user-model.md)** — the isolation model behind "use ≠ possession": users, groups, filesystem permissions, verified against a real host
 - **[Deploy Architecture](docs/deploy-architecture.md)** — config merge, secret store backends, node handling, the installer's full flow
 - **[Install Guide](deploy/README.md)** — prerequisites, PAT scopes, install/upgrade command, flags

package/config.example.json

@@ -1,5 +1,5 @@
 {
-	"listen": "unix:/run/gh-broker/gh-broker.sock",
+	"listen": "agents:/run/gh-broker/agents",
 	"upstream": "https://api.githubcopilot.com/mcp/x/all",
 	"tools": [
 		{
@@ -256,6 +256,65 @@
 			"mode": "write",
 			"custom": true
 		},
+		{
+			"name": "update_pull_request_branch",
+			"mode": "write"
+		},
+		{
+			"name": "request_copilot_review",
+			"mode": "write"
+		},
+		{
+			"name": "minimize_comment",
+			"mode": "write",
+			"custom": true
+		},
+		{
+			"name": "create_repository",
+			"mode": "write"
+		},
+		{
+			"name": "fork_repository",
+			"mode": "write"
+		},
+		{
+			"name": "merge_pull_request",
+			"mode": "write"
+		},
+		{
+			"name": "pull_request_review_write",
+			"mode": "write"
+		},
+		{
+			"name": "actions_run_trigger",
+			"mode": "write"
+		},
+		{
+			"name": "label_write",
+			"mode": "write"
+		},
+		{
+			"name": "delete_branch",
+			"mode": "write",
+			"custom": true
+		},
+		{
+			"name": "dismiss_alert",
+			"mode": "write",
+			"custom": true
+		},
+		{
+			"name": "create_pull_request_with_copilot",
+			"mode": "write"
+		},
+		{
+			"name": "assign_copilot_to_issue",
+			"mode": "write"
+		},
+		{
+			"name": "assign_copilot_to_issue_with_intent",
+			"mode": "write"
+		},
 		{
 			"name": "report_unlabeled",
 			"mode": "read",
@@ -305,6 +364,14 @@
 			"name": "ghcr_tags",
 			"mode": "read",
 			"custom": true
+		},
+		{
+			"name": "otp_status",
+			"mode": "read",
+			"custom": true
 		}
-	]
+	],
+	"otp": {
+		"seed": "cred:otp-seed"
+	}
 }

package/config.sample.json

@@ -1,5 +1,5 @@
 {
-	"listen": "unix:/run/gh-broker/gh-broker.sock",
+	"listen": "agents:/run/gh-broker/agents",
 	"upstream": "https://api.githubcopilot.com/mcp/x/all",
 	"defaultOwner": "your-org",
 	"owners": {

package/deploy/README.md

@@ -4,7 +4,7 @@ One interactive installer does first-install and upgrade. Design and rationale:
 
 ## 0. Host prerequisites
 
-- **Node ≥ 20** — the only real prerequisite; the installer runs under it (`sudo node deploy/install.mjs`). If node isn't installed yet, the optional Linux bootstrap `sudo ./deploy/install.sh` sets up a system-wide nvm + node + the `/usr/local/bin/node` symlink, then hands off to the Node installer.
+- **Node ≥ 20** — the only real prerequisite; the installer runs under it (`sudo gh-broker install`, or `sudo node deploy/install.mjs` from a checkout). If node isn't installed yet, the optional Linux bootstrap `sudo ./deploy/install.sh` sets up a system-wide nvm + node + the `/usr/local/bin/node` symlink, then hands off to the Node installer.
 - **`socat`** — the agent's stdio↔socket bridge. **`rsync`** — used to sync the build (falls back to a plain copy if absent). **`systemd`** with `systemctl`. **`sudo`** — used internally to build as the checkout's own owner (see step 5 below), not just to invoke the installer itself. Install what's missing (`apt install socat rsync sudo` etc.).
 
 The installer maintains `/usr/local/bin/node` as the single node indirection (CLI and service resolve the same link). Bumping node is re-pointing that symlink — which the installer does on every run.
@@ -14,9 +14,9 @@ The installer maintains `/usr/local/bin/node` as the single node indirection (CL
 For each GitHub owner (user or org) the broker serves, `<org>`: GitHub → Settings → Developer settings → **Fine-grained tokens** → Generate new token, **twice**. Resource owner: `<org>`. Repository access: **All repositories**.
 
 **`<org>-read`** — Issues: Read, Pull requests: Read, Contents: Read, Metadata: Read (auto).
-**`<org>-write`** — Issues: R/W, Pull requests: R/W, Contents: R/W, Metadata: Read (auto).
+**`<org>-write`** — Issues: R/W, Pull requests: R/W, Contents: R/W, Metadata: Read (auto). For the tools added in #146, also: Administration: R/W (`create_repository`, `fork_repository`), Actions: R/W (`actions_run_trigger`), Workflows: R/W (`merge_pull_request` and `update_pull_request_branch` on a PR that changes `.github/workflows/`), Code scanning alerts: R/W, Dependabot alerts: R/W and Secret scanning alerts: R/W (`dismiss_alert`). The Copilot coding-agent tools ship disabled and need nothing extra beyond Issues and Pull requests: R/W, plus Copilot coding agent on the account. The installer ships every tool on each run, so a scope left off doesn't hide its tools: the calls are advertised and GitHub refuses them. Administration: R/W is broad: on its own it also lets the token delete repos and change their settings. The broker never offers those, but the token itself can do them, so treat the write PAT accordingly.
 
-No organization or admin permissions. If the org requires approval for fine-grained PATs, approve them in Org → Settings → Personal access tokens. The two-PAT split (read vs write) is a deliberate least-privilege control — see the design doc.
+No organization permissions. If the org requires approval for fine-grained PATs, approve them in Org → Settings → Personal access tokens. The two-PAT split (read vs write) is a deliberate least-privilege control — see the design doc.
 
 ### GHCR pushes: one classic PAT (`<org>-packages`)
 
@@ -27,23 +27,25 @@ The installer also creates the drop directory from `ghcr.dropDir` (default `/srv
 ## 2. Install (first install AND upgrade — same command)
 
 ```sh
-sudo npx @cldmv/gh-broker [agent-user]      # from npm
-sudo node deploy/install.mjs [agent-user]   # from a checkout
+sudo npm install -g --prefix /usr/local --ignore-scripts @cldmv/gh-broker   # install, or upgrade with @latest
+sudo gh-broker install [agent-user]
 ```
 
-Both run the same installer and take the same flags; the npm package ships a prebuilt `dist/`, so step 5 has nothing to build. `agent-user` defaults to `$SUDO_USER` (the account you ran `sudo` from). The installer walks the whole thing and is idempotent:
+`--prefix /usr/local` puts the package in `/usr/local/lib/node_modules/@cldmv/gh-broker` and the command at `/usr/local/bin/gh-broker`, independent of the Node version and on `sudo`'s PATH. `--ignore-scripts` because a global install runs as root on the box that holds the tokens. The package ships a prebuilt `dist/`, so there is nothing to build. A copy installed under an nvm version folder breaks when Node is upgraded; `gh-broker install` warns if it finds one. One-offs still work: `sudo npx @cldmv/gh-broker install [agent-user]`, and from a checkout `sudo node deploy/install.mjs [agent-user]`.
+
+`gh-broker install` takes the same flags either way. `agent-user` registers that user as an agent (see [Agents](#3-agents-one-socket-and-one-mcp-config-each)); on an upgrade with agents already registered it is optional and adds nobody. A first install with no agent asks for one (`--non-interactive` needs `--agent-user`); it never takes `$SUDO_USER`, the admin running sudo. The installer walks the whole thing and is idempotent:
 
 1. checks prerequisites,
-2. **creates or confirms the agent user** (stops if it can't — no silent half-install),
-3. creates the `gh-broker` service user + `gh-broker-clients` bridge group, adds the agent user to it (and, when the config has a `ghcr` block, creates the GHCR drop directory),
+2. **registers the agents**: members of the old shared `gh-broker-clients` group become registered agents (the group itself is left alone), the user named on the command line is added (and created if missing), and each one gets its own group `gh-broker-agent-<user>`,
+3. creates the `gh-broker` service user and, when the config has a `ghcr` block, the GHCR drop directory (owned by the agent named on the command line, else the first registered one),
 4. points `/usr/local/bin/node` at the running node,
 5. builds `dist/` if it isn't already built, or rebuilds it if a prior run left it (or `node_modules/`) owned by someone other than the checkout's owner — the build itself runs via `sudo -u '#<uid>'` as whoever owns `deploy/install.mjs`, not as root, so the installer never leaves root-owned files behind in your checkout,
-6. regenerates the config by layering `config.example.json`, whatever is deployed, your `--config` file and your flags (your data is preserved; allowlist changes from the repo arrive; see [Configuring the install](#configuring-the-install)); a first install with no owner asks for one,
+6. regenerates the config (replacing an old `unix:` `listen` with `agents:/run/gh-broker/agents`) by layering `config.example.json`, whatever is deployed, your `--config` file and your flags (your data is preserved; allowlist changes from the repo arrive; see [Configuring the install](#configuring-the-install)); a first install with no owner asks for one,
 7. sets up the optional **npm integration** when asked (offered on a first install, or `--npm`): an npm web login it waits on, then the token it creates for `npm_scaffold` (see [npm integration](#npm-integration-npm_scaffold)),
-8. **asks how to store the credentials** — `systemd-creds` (encrypted at rest, host-bound; recommended) or a plaintext `file` (`0640 root:gh-broker`; portable) — then stores the tokens in the chosen backend: it keeps existing creds, decrypts a legacy `systemd-creds` token when you switch to `file`, and **prompts only for what it can't find** (input hidden),
+8. **asks how to store the credentials** — `systemd-creds` (encrypted at rest, host-bound; recommended) or a plaintext `file` (`0640 root:gh-broker`; portable) — then stores the tokens in the chosen backend: it keeps existing creds, decrypts a legacy `systemd-creds` token when you switch to `file`, and **prompts only for what it can't find** (input hidden); when no OTP seed is stored it also generates one and shows it once (see [OTP gate](#otp-gate-gh-broker-otp)),
 9. validates the config with the real loader (`--check`),
-10. installs the unit, deploys `dist/`, restarts, and
-11. runs a **smoke test** (MCP handshake + a real read over the socket) → ✅/❌.
+10. installs the unit, deploys `dist/` to `/opt/gh-broker`, restarts, writes every agent's MCP config (`--no-mcp-config` prints the entry instead), and
+11. runs a **smoke test** over each agent's own socket (MCP handshake + a real read) → ✅/❌.
 
 ### Unattended (single non-interactive command)
 
@@ -59,6 +61,28 @@ Re-running on an existing install needs no `--owner`: the deployed owners are ke
 
 **Upgrade** is just re-running it: config merged (edits kept), your previously-chosen storage backend pre-selected, existing tokens kept. You can **switch backends** on any run — pick `file` and it decrypts the existing `systemd-creds` tokens into the file (no re-entry); pick `systemd-creds` and it encrypts the tokens into `.cred` files. `launch.sh` is no longer used — remove it after a successful run: `sudo rm -f /opt/gh-broker/launch.sh` (and `sudo rm -rf /etc/gh-broker/creds` only if you've moved fully to the `file` backend).
 
+## OTP gate (`gh-broker otp`)
+
+Tools marked `"otp": true` in `/etc/gh-broker/config.json` (an upgrade keeps each tool's `otp` and `enabled` settings) only run when the call carries a current code from an authenticator app, so a code is something only you can supply. The seed behind those codes is generated by the installer and stored next to the PATs, where the agent can't read it.
+
+**Setup.** On a first install, and on any later run that finds no stored `otp-seed`, the installer generates a seed, prints it, then stores it in the chosen backend (an encrypted `otp-seed.cred` delivered by the unit drop-in under `systemd-creds`, or the `otp-seed` key in `secrets.json` under `file`). It is printed once, before it is stored, so a run that fails later can't leave a stored seed nobody saw: a QR code of the `otpauth://` URI, the base32 key as text, and the URI itself. If a run fails and the next one prints a different key, use the newer one. Scan the QR code with an authenticator app, or enter the key by hand. `--non-interactive` does the same, so capture the output of an unattended run. An existing seed is never overwritten by the installer. To supply your own, pass `--secret otp-seed=<base32>`, `--secrets-file` or env `GH_BROKER_SECRET_OTP_SEED`; it is then used as is and not printed.
+
+**The `gh-broker` command.** The global npm install puts `gh-broker` on root's PATH (`/usr/local/bin/gh-broker`). It needs root, because the state directory is `0700 gh-broker`:
+
+```sh
+sudo gh-broker otp status [<user>] [--json]   # per agent: bad codes so far, short lockouts in the last 24 h, hard lock, state file health
+sudo gh-broker otp list [--json]              # who is locked out now, and the command that clears each
+sudo gh-broker otp unlock <user>              # clear one agent's lockout and hard lock
+sudo gh-broker otp unlock --all               # clear everyone
+sudo gh-broker otp rotate                     # new seed: stored, shown once, service restarted
+```
+
+`unlock <user>` drops that user's entry from the state file and leaves the others alone, rewriting the file atomically as `0600 gh-broker:gh-broker`. Every write from the command also counts each code up to the next 30-second step as spent, so a write that races the daemon can't hand a code back that the daemon just accepted. After an unlock the current code and the one after it are refused (they don't count as bad codes); the command says how many seconds to wait for a fresh one, up to a minute. If the broker writes the state file while the command runs (a lockout, an accepted code), the command changes nothing and asks you to run it again, so it can't undo what the broker just recorded. Each unlock is logged to the journal as `gh-broker`, next to the daemon's audit log, with the sudo user who ran it. If the state file is corrupt the broker treats every user as hard-locked; `status` and `list` report that, `unlock <user>` refuses (clearing one user would not fix the file), and `unlock --all` rewrites it clean. `rotate` replaces the stored seed and restarts the service, which closes every open window; remove the old entry from your authenticator.
+
+**State file.** The lock counters live in `/var/lib/gh-broker/otp-state.json` (`otp.statePath` to change it): `version`, a global `lastAcceptedStep`, and a `users` object with `failures`, `lockedUntil`, `lockouts` and `hardLock` per agent user. A user with no entry is all zero. The unit sets `StateDirectory=gh-broker` with `StateDirectoryMode=0700`, which makes the directory writable under `ProtectSystem=strict` and owned by the service user. It survives restarts, so a hard lock does too. The broker re-reads it whenever it changes, so `unlock` takes effect on the next call with no restart.
+
+**Config.** `config.example.json` ships `"otp": { "seed": "cred:otp-seed" }`. An upgrade adds it to a deployed config that lacks it; an `otp` block you already have (`maxFailures`, `lockoutSeconds`, `maxLockouts`, `windowSeconds`, `statePath`) wins field by field, and a `--config` file may hold one too.
+
 ## Credential storage — your choice
 
 The installer asks which backend holds the tokens at rest:
@@ -101,23 +125,38 @@ Flags that build a single GHCR owner do so for one owner per run; use `--config`
 
 With no owner anywhere (a first install with no flags and no `--config`), an interactive run asks for the GitHub owner name and then for its two tokens; `--non-interactive` fails and names `--owner` / `--config`.
 
-## 3. Point Claude at the broker
+## 3. Agents: one socket and one MCP config each
+
+The broker knows which agent is calling from the socket the call arrives on: there is one Unix socket per agent user, `/run/gh-broker/agents/<user>.sock`, reachable only by that user. An agent is registered when the group `gh-broker-agent-<user>` exists with exactly `gh-broker` and `<user>` as members (user names are lowercase, up to 16 characters: `^[a-z_][a-z0-9_-]{0,15}$`). There is no shared socket, so a locked-out agent can't keep using the broker through another door.
 
-The installer prints this; add it to the agent user's `~/.claude.json` `mcpServers`:
+```sh
+sudo gh-broker agent add <user>      # group, MCP config, restart, smoke test over the user's socket
+sudo gh-broker agent remove <user>   # empty the group, restart (closes the socket), then the MCP entry (backup first) and the user's lock state
+sudo gh-broker agent list            # socket path, whether it exists, and whether the MCP config points at it (ok / missing / points elsewhere)
+sudo gh-broker agent sync [<user>]   # re-apply the MCP config for one agent or all
+```
+
+`agent remove` empties the agent's group rather than deleting it. Processes the user already has running keep that group's id, so deleting it would let a later `agent add` reuse the id and give those processes the new agent's socket. An empty group isn't an agent; `agent add` for the same user fills it again.
+
+**The MCP config.** The broker writes the entry into the top-level `mcpServers` of `<home>/.claude.json`, using `sg` so the new group is effective without a re-login:
 
 ```json
 "github": {
 	"type": "stdio",
-	"command": "socat",
-	"args": ["STDIO", "UNIX-CONNECT:/run/gh-broker/gh-broker.sock"]
+	"command": "sg",
+	"args": ["gh-broker-agent-<user>", "-c", "exec socat STDIO UNIX-CONNECT:/run/gh-broker/agents/<user>.sock"]
 }
 ```
 
-Re-login as the agent user first, so its `gh-broker-clients` membership is active.
+If an existing entry already mentions `/run/gh-broker/` (the old shared socket or the new one) that entry is updated in place and keeps its name; otherwise the entry is added as `github`, or `gh-broker` when that name is taken. Nothing else in the file changes. The file is parsed, edited, written to a temp file in the same directory and renamed, keeping its owner and mode, and `~/.claude.json.gh-broker.bak` keeps the previous copy (overwritten each time). A missing file is created `0600`; a file that doesn't parse is left alone and the entry is printed to add by hand. The home directory belongs to the agent user and the command runs as root, so it reads the file without following a symlink and only touches a plain file the user owns with a single link; anything else (a symlink, a hard link, someone else's file) is left alone with a warning, and the temp file is created with a random name that can't be pre-planted. Running Claude sessions for that user must be restarted to pick the change up, and `agent sync <user>` puts the entry back if a running session overwrote the file. `--no-mcp-config` (on `install`, `agent add` and `agent sync`) skips the write and prints the entry.
+
+**Upgrading from the shared socket.** The first `gh-broker install` after the change registers every member of `gh-broker-clients` (other than `gh-broker`) as an agent, writes the new `listen` (`agents:/run/gh-broker/agents`), rewrites each agent's MCP config to its own socket and smoke-tests every socket. `gh-broker-clients` is left in place; nothing depends on it any more. Agents added later need a service restart, which `agent add` does.
+
+**Versions.** The service runs from `/opt/gh-broker`, which `gh-broker install` deploys. `gh-broker otp status` and `gh-broker agent list` warn when the installed package and the deployed copy differ; run `sudo gh-broker install` again.
 
 ## Adding an org later
 
-Re-run the installer with `--owner <org>` (repeatable). The deployed owners stay, the new one is added with `cred:<org>-read` / `cred:<org>-write`, and the installer prompts for its two tokens. No code change.
+Re-run `sudo gh-broker install` with `--owner <org>` (repeatable). The deployed owners stay, the new one is added with `cred:<org>-read` / `cred:<org>-write`, and the installer prompts for its two tokens. No code change.
 
 ## npm integration (`npm_scaffold`)
 
@@ -148,4 +187,4 @@ Without the `npm` block nothing changes: the installer says "not enabled", and t
 - The agent user cannot read `/etc/gh-broker/` — the dir is `0750 root:gh-broker`; the config (`0640`) and, whichever backend is used, the tokens (systemd-creds `.cred` files `0400 root`, or the `file` backend's `secrets.json` `0640 root:gh-broker`) are unreadable to a non-member.
 - The config file holds **no tokens** — only `cred:` references; the tokens live in the separate secret store.
 - The socket carries MCP frames only.
-- `journalctl -u gh-broker` shows the audit log (tool, owner, mode, repo, result) — never tokens.
+- `journalctl -t gh-broker` shows the audit log (tool, user, owner, mode, repo, result, OTP outcome, lockouts and unlocks) — never tokens, codes or the seed.

package/deploy/cli.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /deploy/cli.mjs
+ *	@Date: 2026-11-01T20:43:03-08:00 (1793594583)
+ *	@Author: Nate Corcoran <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-11-01T20:43:03-08:00 (1793594583)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ *
+ */
+
+/**
+ * The `gh-broker` command (the package `bin`): `gh-broker install`, `gh-broker otp ...` and
+ * `gh-broker agent ...`. `install` hands over to the installer (deploy/install.mjs); the rest is
+ * lib/cli.mjs with the real effects from real-deps.mjs.
+ */
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { runCli } from "./lib/cli.mjs";
+import { realDeps } from "./real-deps.mjs";
+
+/** Run the CLI with the real effects and set the exit code. `install` is the installer. */
+export async function main(argv = process.argv.slice(2)) {
+	if (argv[0] === "install") {
+		process.argv.splice(2, 1); // the installer reads its flags from argv[2..]
+		await import("./install.mjs");
+		return;
+	}
+	process.exitCode = await runCli(argv, realDeps());
+}
+
+// npm links the bin as a symlink, so compare real paths.
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) await main();

package/deploy/gh-broker.service

@@ -15,8 +15,9 @@ Group=gh-broker
 # See secrets.ts / docs/deploy-architecture.md.
 
 # Socket dir /run/gh-broker (traversable), owned by the service user; the daemon
-# creates the socket there and sets it 0660 group=gh-broker-clients so the agent
-# user (a member of that group) can connect, while the token stays server-side.
+# creates one socket per agent under /run/gh-broker/agents, each 0660 with group
+# gh-broker-agent-<user>, so only that agent can connect and the broker knows who
+# is calling. The token stays server-side.
 RuntimeDirectory=gh-broker
 RuntimeDirectoryMode=0755
 
@@ -24,6 +25,8 @@ RuntimeDirectoryMode=0755
 # it at the chosen node and re-points it on a bump), so no node version is pinned
 # here and there is no nvm resolution at start. The symlink is the single source of
 # truth, so CLI node == service node by construction. See docs/deploy-architecture.md.
+# The audit log (stdout) and `gh-broker otp unlock` both log as gh-broker: journalctl -t gh-broker
+SyslogIdentifier=gh-broker
 ExecStart=/usr/local/bin/node /opt/gh-broker/dist/index.mjs --config /etc/gh-broker/config.json
 Restart=on-failure
 RestartSec=2
@@ -48,6 +51,10 @@ SystemCallArchitectures=native
 SystemCallFilter=@system-service
 SystemCallErrorNumber=EPERM
 ReadWritePaths=/run/gh-broker
+# OTP gate state (lock counters, hard lock): /var/lib/gh-broker, created 0700 gh-broker:gh-broker.
+# StateDirectory= makes it writable under ProtectSystem=strict; `sudo gh-broker otp unlock` edits it.
+StateDirectory=gh-broker
+StateDirectoryMode=0700
 UMask=0077
 # Optional egress lockdown once GitHub ranges are pinned:
 # IPAddressDeny=any