@cldmv/gh-broker 0.9.0 → 0.10.0

package/deploy/install.mjs

@@ -17,8 +17,14 @@
 /**
  * gh-broker installer — one command for first install AND upgrade.
  *
- *   sudo npx @cldmv/gh-broker [agent-user] [flags]   (from npm)
- *   sudo node deploy/install.mjs [agent-user] [flags] (from a checkout)
+ *   sudo gh-broker install [agent-user] [flags]            (global npm install)
+ *   sudo npx @cldmv/gh-broker install [agent-user] [flags] (one-off, from npm)
+ *   sudo node deploy/install.mjs [agent-user] [flags]      (from a checkout)
+ *
+ * The documented path is a global install (`sudo npm install -g --prefix /usr/local
+ * --ignore-scripts @cldmv/gh-broker`, then `sudo gh-broker install`); the package bin is
+ * deploy/cli.mjs, which hands `install` to this file. Agents, OTP and the `gh-broker` admin
+ * commands are in deploy/cli.mjs and lib/.
  *
  * Prerequisite: node >= 20. Idempotent: re-run to upgrade (config regenerated by
  * layering, existing secrets kept). Interactive by default; pass flags plus
@@ -30,24 +36,26 @@ import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import {
 	run, has, isRoot, userExists, requireGid,
-	ensureServiceUser, createAgentUser, addUserToGroup,
+	ensureServiceUser, createAgentUser,
 	pointNodeSymlinks, currentNodeBin, ensureDirs, installUnit,
-	enableService, restartService, serviceActive, deployDist, writeConfigFile,
+	enableService, restartService, serviceActive, deployDist, writeConfigFile, ensureAgentGroup,
 	trySystemdCredDecrypt, systemdCredsEncrypt, ensureCredsDir, writeCredsDropin, removeCredsDropin, ensureDropDir
 } from "./lib/system.mjs";
 import { promptLine, promptHidden, confirm, choose } from "./lib/prompt.mjs";
 import { buildConfig, readOperatorConfig, secretsBlock } from "./lib/config-merge.mjs";
 import { writeSecretsFile, readSecretsFile, removeSecretsFile, referencedCredNames, optionalCredNames, detectSecretsProvider } from "./lib/secret-store.mjs";
-import { parseArgs, NPM_SCOPE } from "./lib/install-args.mjs";
+import { parseArgs, NPM_SCOPE, envSecretKey } from "./lib/install-args.mjs";
+import { generateSeed, seedCredName, seedExists, showSeed, writeFileAtomic } from "./lib/otp.mjs";
 import { credentialPlan } from "./lib/credentials.mjs";
-import { smokeTest } from "./lib/smoke.mjs";
 import { createNpmToken } from "./lib/npm-setup.mjs";
 import { hostname } from "node:os";
+import { assertAgentName, classifyInstall, migrationPlan, NPM_INSTALL_COMMAND, parseGroups, registeredAgents, LEGACY_CLIENTS_GROUP } from "./lib/agents.mjs";
+import { configureMcp, smokeAgent } from "./lib/agent-cli.mjs";
+import { realDeps } from "./real-deps.mjs";
 
 const REPO = dirname(dirname(fileURLToPath(import.meta.url)));
 const SVC_USER = "gh-broker";
 const SVC_GROUP = "gh-broker";
-const CLIENTS_GROUP = "gh-broker-clients";
 const APP_DIR = "/opt/gh-broker";
 const DIST = join(REPO, "dist");
 const DIST_ENTRY = join(DIST, "index.mjs");
@@ -69,12 +77,18 @@ function readJson(path) {
 
 const HELP = `gh-broker installer — install and upgrade in one command.
 
-Usage: sudo npx @cldmv/gh-broker [agent-user] [flags]     (from npm)
-       sudo node deploy/install.mjs [agent-user] [flags]   (from a checkout)
+Usage: sudo gh-broker install [agent-user] [flags]           (global npm install)
+       sudo npx @cldmv/gh-broker install [agent-user] [flags] (one-off, from npm)
+       sudo node deploy/install.mjs [agent-user] [flags]      (from a checkout)
+Global install: ${NPM_INSTALL_COMMAND}
+After install: sudo gh-broker agent add|remove|list|sync, sudo gh-broker otp status|unlock|rotate
 
 Flags:
-  --agent-user <name>     the unprivileged user the agent runs as
-                          (also positional; defaults to $SUDO_USER)
+  --agent-user <name>     an unprivileged agent user to register (also positional).
+                          Each agent gets its own socket and MCP config. Optional on an
+                          upgrade (registered agents are kept); a first install with none
+                          asks (never $SUDO_USER)
+  --no-mcp-config         do not write any agent's ~/.claude.json; print the entry instead
   --secrets-provider <p>  systemd-creds | file   (skips the prompt)
   --secrets-file <path>   JSON { "<cred-name>": "<token>" } to import tokens from
   --secret <name>=<tok>   one token on the command line (repeatable). Visible in
@@ -101,7 +115,7 @@ these flags). An upgrade run with none of them keeps the deployed owners and ghc
                           GitHub App installation id for an owner (repeatable)
   --default-owner <org>   owner whose read token serves calls that name no owner
                           (a first install with a single owner defaults to it)
-  --listen <unix:path>    socket the broker listens on
+  --listen <agents:dir>   directory holding the per-agent sockets (default agents:/run/gh-broker/agents)
   --upstream <url>        GitHub hosted MCP base URL
   --app-id <n>            GitHub App id (App-token-only verbs)
   --app-private-key <cred-name>
@@ -170,22 +184,47 @@ async function main() {
 	for (const cmd of ["systemctl", "useradd", "getent", "sudo"]) if (!has(cmd)) die(`missing required command: ${cmd}`);
 	for (const cmd of ["socat", "rsync"]) if (!has(cmd)) log(`  note: '${cmd}' not found — ${cmd === "socat" ? "the agent socket bridge needs it" : "will fall back to a plain copy"}`);
 
-	// --- agent user ---
-	step("agent user");
-	let agentUser = opts.agentUser || opts.positional[0] || process.env.SUDO_USER || "";
-	if (!agentUser) {
+	// --- agent users ---
+	// An agent is registered by the group gh-broker-agent-<user>. Upgrades keep the registered ones,
+	// migrate members of the old shared gh-broker-clients group, and add the one named on the
+	// command line. A first install with none asks. It never defaults to $SUDO_USER: that is the
+	// admin running sudo, and an agent must be a plain user without it.
+	step("agent users");
+	const groupFile = "/etc/group";
+	const groups = parseGroups(existsSync(groupFile) ? readFileSync(groupFile, "utf8") : "");
+	const registered = registeredAgents(groups);
+	const migration = migrationPlan(groups, registered);
+	for (const name of migration.skipped) log(`  skipping ${LEGACY_CLIENTS_GROUP} member "${name}": not a valid agent user name`);
+	let requested = opts.agentUser || opts.positional[0] || "";
+	if (!requested && registered.length === 0 && migration.add.length === 0) {
 		if (opts.nonInteractive) die("no agent user — pass --agent-user <name>");
-		agentUser = await promptLine("Which unprivileged user does the agent run as? ");
+		requested = await promptLine("Which unprivileged user does the agent run as? ");
+		if (!requested) die("no agent user given");
 	}
-	if (!agentUser) die("no agent user given");
-	if (!userExists(agentUser)) {
-		const create = opts.createAgentUser || (!opts.nonInteractive && (await confirm(`User "${agentUser}" does not exist. Create it (plain, no sudo)?`)));
-		if (!create) die(`agent user "${agentUser}" missing — create it first or pass --create-agent-user`);
-		createAgentUser(agentUser);
-		log(`  created "${agentUser}"`);
-	} else {
-		log(`  "${agentUser}" exists`);
+	if (requested) {
+		try {
+			assertAgentName(requested);
+		} catch (err) {
+			die(err.message);
+		}
+		if (!userExists(requested)) {
+			const create = opts.createAgentUser || (!opts.nonInteractive && (await confirm(`User "${requested}" does not exist. Create it (plain, no sudo)?`)));
+			if (!create) die(`agent user "${requested}" missing — create it first or pass --create-agent-user`);
+			createAgentUser(requested);
+			log(`  created "${requested}"`);
+		}
 	}
+	const agents = [...new Set([...registered.map((a) => a.user), ...migration.add.filter(userExists), ...(requested ? [requested] : [])])].sort();
+	for (const name of migration.add) log(userExists(name) ? `  migrating ${LEGACY_CLIENTS_GROUP} member "${name}" to a registered agent` : `  skipping ${LEGACY_CLIENTS_GROUP} member "${name}": no such user`);
+	log(`  agents: ${agents.join(", ")}`);
+	// The GHCR drop dir belongs to one agent. A new one goes to the agent named now, else the
+	// first registered; an existing one keeps its owner (see ensureDropDir).
+	const dropOwner = requested || agents[0];
+
+	// --- where this copy of the package lives ---
+	const where = classifyInstall(REPO);
+	if (where === "nvm") log(`  warning: this package is installed under an nvm Node version folder; that copy breaks when Node is upgraded. Reinstall it globally: ${NPM_INSTALL_COMMAND}`);
+	else if (where === "checkout" && !existsSync("/usr/local/bin/gh-broker")) log(`  note: no global gh-broker command found. Get one with: ${NPM_INSTALL_COMMAND}`);
 
 	// --- build if needed ---
 	// This installer requires root, but dist/ and node_modules/ are generated INSIDE
@@ -226,8 +265,8 @@ async function main() {
 
 	// --- users, groups, dirs, node symlink ---
 	step("service user, groups, directories");
-	ensureServiceUser(SVC_USER, SVC_GROUP, CLIENTS_GROUP);
-	addUserToGroup(agentUser, CLIENTS_GROUP);
+	ensureServiceUser(SVC_USER, SVC_GROUP);
+	for (const name of agents) ensureAgentGroup(name, SVC_USER);
 	ensureDirs(configDir, APP_DIR, SVC_USER, SVC_GROUP);
 	const linked = pointNodeSymlinks(currentNodeBin());
 	log(`  node symlink -> ${currentNodeBin()} (${linked.join(", ")})`);
@@ -246,8 +285,8 @@ async function main() {
 		die(err.message);
 	}
 	if (merged.ghcr?.dropDir) {
-		ensureDropDir(merged.ghcr.dropDir, agentUser, SVC_GROUP);
-		log(`  ghcr drop dir: ${merged.ghcr.dropDir} (2750 ${agentUser}:${SVC_GROUP})`);
+		const { created } = ensureDropDir(merged.ghcr.dropDir, dropOwner, SVC_GROUP);
+		log(`  ghcr drop dir: ${merged.ghcr.dropDir} (2750 ${created ? dropOwner : "existing owner"}:${SVC_GROUP})`);
 	}
 
 	// --- npm integration (npm_scaffold): opt-in ---
@@ -322,13 +361,32 @@ async function main() {
 	// single-line prompt can't accept — it must be supplied out-of-band.
 	const appKeyName = merged.app?.privateKey?.startsWith("cred:") ? merged.app.privateKey.slice("cred:".length) : undefined;
 
+	// OTP seed (#143): generated on a first install and whenever none is stored, never over an
+	// existing one (that is `gh-broker otp rotate`). An operator-supplied seed is used as is and
+	// not shown again. The generated one rides in as an explicit value so the normal storage path
+	// (either backend) writes it. It is shown before it is stored: if a later step fails after the
+	// store, the next run finds a seed and won't make (or show) a new one, so showing it last
+	// could leave a seed nobody has.
+	const seedName = seedCredName(merged);
+	let generatedSeed;
+	if (seedName) {
+		const supplied = opts.cliSecrets[seedName] || importTokens?.[seedName] || process.env[envSecretKey(seedName)];
+		const stored = seedExists({ name: seedName, existingFile, credFileExists: (n) => existsSync(join(credsDir, `${n}.cred`)) });
+		if (!supplied && !stored) generatedSeed = generateSeed();
+	}
+	if (generatedSeed) {
+		step("OTP seed");
+		await showSeed({ seed: generatedSeed, host: hostname(), log });
+		log("  If this install fails and the next run shows a different key, use that one instead.");
+	}
+
 	let plan;
 	try {
 		plan = credentialPlan({
 			needed,
 			optional,
 			cliSecrets: opts.cliSecrets,
-			imported: importTokens ?? {},
+			imported: { ...(importTokens ?? {}), ...(generatedSeed ? { [seedName]: generatedSeed } : {}) },
 			env: process.env,
 			existingFile,
 			decrypt: (name) => trySystemdCredDecrypt(name, join(credsDir, `${name}.cred`)),
@@ -390,22 +448,21 @@ async function main() {
 	installUnit(join(REPO, "deploy", "gh-broker.service"));
 	enableService();
 	deployDist(DIST, APP_DIR, SVC_USER, SVC_GROUP);
+	// `gh-broker otp status` / `agent list` compare it with the package. /opt/gh-broker belongs to
+	// the service user, so root writes it without following anything planted there.
+	writeFileAtomic(join(APP_DIR, "version"), `${readJson(join(REPO, "package.json"))?.version ?? ""}\n`, { uid: 0, gid: 0, mode: 0o644 });
 	restartService();
 	log(`  service: ${serviceActive()}`);
 
-	// --- smoke test ---
-	step("smoke test");
-	const sock = merged.listen.replace(/^unix:/, "");
-	try {
-		const r = await smokeTest(sock);
-		log(`  ✅ broker answered — ${r.tools.length} tools advertised${r.roundTrip ? `; ${r.roundTrip}` : ""}`);
-	} catch (e) {
-		die(`smoke test failed: ${e.message}\n  check: journalctl -u gh-broker -n 30 --no-pager`);
-	}
+	// --- each agent's MCP config, then a smoke test over its own socket ---
+	step("agents");
+	const dep = realDeps();
+	for (const name of agents) configureMcp(name, merged, dep, { noMcp: opts.noMcpConfig });
+	let smokeFailed = false;
+	for (const name of agents) if (!(await smokeAgent(name, merged, dep))) smokeFailed = true;
+	if (smokeFailed) die("smoke test failed (see above)");
 
-	log(`\n✅ gh-broker installed. Point the agent's MCP client at the socket:`);
-	log(`   "github": { "type": "stdio", "command": "socat", "args": ["STDIO", "UNIX-CONNECT:${sock}"] }`);
-	log(`   (re-login as "${agentUser}" so its ${CLIENTS_GROUP} membership is active)`);
+	log(`\n✅ gh-broker installed. Manage agents with: sudo gh-broker agent add|remove|list|sync, OTP with: sudo gh-broker otp status|unlock|rotate`);
 }
 
 main().catch((e) => die(e.message));

package/deploy/lib/agent-cli.mjs

@@ -0,0 +1,166 @@
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /deploy/lib/agent-cli.mjs
+ *	@Date: 2026-11-02T09:12:00-08:00 (1793639520)
+ *	@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-02T09:12:00-08:00 (1793639520)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ *
+ */
+
+/**
+ * `gh-broker agent add | remove | list | sync` (#143, contract v2). An agent is a Linux group
+ * `gh-broker-agent-<u>` (the registry), one socket per agent in the daemon's agents directory,
+ * and an entry in the agent user's Claude Code MCP config. Every effect is injected.
+ */
+import { agentGroup, agentsDir, assertAgentName, registeredAgents, socketPath, versionWarning } from "./agents.mjs";
+import { applyMcpConfig, mcpEntry, mcpFileStatus, removeMcpConfig, MCP_BACKUP, MCP_FILE } from "./mcp-config.mjs";
+import { statePathOf } from "./otp-cli.mjs";
+import { spendRecentCodes, withoutUser } from "./otp.mjs";
+
+/** Run one `agent` subcommand. Returns the exit code; throws on a failure the dispatcher reports. */
+export async function agentCommand(command, rest, config, d) {
+	const flags = rest.filter((a) => a.startsWith("-"));
+	const names = rest.filter((a) => !a.startsWith("-"));
+	const noMcp = flags.includes("--no-mcp-config");
+	if (command === "list") return list(config, d);
+	if (command === "sync") return sync(config, names[0], noMcp, d);
+	if (names.length !== 1) throw new Error(`name the agent user: sudo gh-broker agent ${command} <user>`);
+	return command === "add" ? add(config, names[0], noMcp, d) : remove(config, names[0], d);
+}
+
+const registry = (d) => registeredAgents(d.groups());
+
+/**
+ * Write (or, with `noMcp`, just print) one agent's MCP config and explain the restart. Shared with
+ * the installer. Returns the lines it logged through `d.log`.
+ */
+export function configureMcp(user, config, d, { noMcp = false } = {}) {
+	const dir = agentsDir(config.listen);
+	const entry = mcpEntry(user, dir);
+	const info = d.userInfo(user);
+	if (noMcp || !info) {
+		d.log(`${user}: not writing the MCP config${info ? " (--no-mcp-config)" : " (no such user)"}. Add this under "mcpServers" in the user's ~/.claude.json:`);
+		d.log(JSON.stringify({ github: entry }, null, "\t"));
+		return "skipped";
+	}
+	let r;
+	try {
+		r = applyMcpConfig({ home: info.home, user, dir, owner: { uid: info.uid, gid: info.gid } }, d.mcpIO);
+	} catch (err) {
+		// The home directory is the agent's, so a write there can fail on anything it puts in the
+		// way (a directory where the backup goes, say). Report it; it must not stop the caller.
+		d.error(`${user}: could not write the MCP config: ${err.message}. Add this under "mcpServers" in the user's ~/.claude.json by hand:`);
+		d.log(JSON.stringify({ github: entry }, null, "\t"));
+		return "failed";
+	}
+	if (r.status === "unsafe") {
+		d.error(`${user}: ${r.reason}, so it was left alone (root won't read or replace it). Make it a plain file the user owns and run "sudo gh-broker agent sync ${user}", or add this under "mcpServers" by hand:`);
+		d.log(JSON.stringify({ github: entry }, null, "\t"));
+		return "unsafe";
+	}
+	if (r.status === "unreadable") {
+		d.log(`${user}: ${r.path} is not valid JSON, so it was left alone. Add this under "mcpServers" by hand:`);
+		d.log(JSON.stringify({ github: entry }, null, "\t"));
+		return "unreadable";
+	}
+	d.log(`${user}: MCP config ${r.status === "unchanged" ? "already up to date" : r.status} in ${r.path} (entry "${r.key}")${r.status === "written" ? `; previous file saved as ${MCP_BACKUP}` : ""}`);
+	d.log(`${user}: restart the user's running Claude sessions to pick it up. If a running session overwrites the file, "sudo gh-broker agent sync ${user}" puts it back.`);
+	return r.status;
+}
+
+/** Smoke-test one agent's socket; logs the result and returns whether it answered. */
+export async function smokeAgent(user, config, d) {
+	const sock = socketPath(agentsDir(config.listen), user);
+	try {
+		const r = await d.smoke(sock);
+		d.log(`${user}: broker answered on ${sock} (${r.tools.length} tools)`);
+		return true;
+	} catch (err) {
+		d.error(`${user}: smoke test failed on ${sock}: ${err.message}\n  check: journalctl -u gh-broker -n 30 --no-pager`);
+		return false;
+	}
+}
+
+async function add(config, user, noMcp, d) {
+	assertAgentName(user);
+	if (!d.userInfo(user)) throw new Error(`user "${user}" does not exist; create it first (the installer can: sudo gh-broker install --agent-user ${user} --create-agent-user)`);
+	d.ensureGroup(user);
+	d.log(`${user}: registered (group ${agentGroup(user)})`);
+	configureMcp(user, config, d, { noMcp });
+	d.restart();
+	return (await smokeAgent(user, config, d)) ? 0 : 1;
+}
+
+function remove(config, user, d) {
+	assertAgentName(user);
+	if (!registry(d).some((a) => a.user === user)) throw new Error(`"${user}" is not a registered agent`);
+	// The group and the restart go first: they are what close the agent's socket, so nothing the
+	// agent can do to its own home directory (which the MCP cleanup below edits) can stop that.
+	d.removeGroup(user);
+	d.log(`${user}: unregistered (group ${agentGroup(user)} emptied; it is kept so its id is never given to another agent)`);
+	d.restart();
+	d.log("service restarted");
+	const info = d.userInfo(user);
+	if (info) {
+		try {
+			const r = removeMcpConfig({ home: info.home, dir: agentsDir(config.listen), uid: info.uid }, d.mcpIO);
+			const what = { removed: `removed the broker entry from ${r.path} (backup: ${MCP_BACKUP})`, absent: `no broker entry in ${r.path}`, "no-file": `no ${MCP_FILE} to edit`, unreadable: `${r.path} is not valid JSON, so it was left alone`, unsafe: `${r.reason}, so it was left alone` };
+			d.log(`${user}: ${what[r.status]}`);
+		} catch (err) {
+			d.error(`${user}: could not remove the broker entry from ${info.home}/${MCP_FILE}: ${err.message}. The agent is unregistered anyway; remove the entry by hand.`);
+		}
+	}
+	try {
+		const statePath = statePathOf(config);
+		const read = d.readState(statePath);
+		if (read.status === "ok" && Object.hasOwn(read.state.users, user)) {
+			d.writeState(statePath, spendRecentCodes(withoutUser(read.state, user), d.now()));
+			d.log(`${user}: cleared from ${statePath}`);
+		} else if (read.status === "corrupt") {
+			d.error(`${statePath} is corrupt, so ${user}'s entry was not cleared; run "sudo gh-broker otp unlock --all"`);
+		}
+	} catch (err) {
+		// The agent is already unregistered and its socket closed; a leftover entry is harmless.
+		d.error(`${user}: lock state not cleared: ${err.message}. "sudo gh-broker otp unlock ${user}" clears it later.`);
+	}
+	return 0;
+}
+
+function list(config, d) {
+	const dir = agentsDir(config.listen);
+	const agents = registry(d);
+	if (agents.length === 0) d.log("no agents registered (add one with: sudo gh-broker agent add <user>)");
+	for (const a of agents) {
+		const sock = socketPath(dir, a.user);
+		const info = d.userInfo(a.user);
+		let mcp = "no such user";
+		if (info) {
+			try {
+				mcp = mcpFileStatus({ home: info.home, user: a.user, dir, uid: info.uid }, d.mcpIO);
+			} catch (err) {
+				mcp = `can't read (${err.message})`; // one agent's file must not hide the others
+			}
+		}
+		d.log(`${a.user}  ${sock}  socket: ${d.socketExists(sock) ? "yes" : "no"}  mcp: ${mcp}${a.complete ? "" : "  (group members incomplete; run agent add)"}`);
+	}
+	const warn = versionWarning(d.versions().pkg, d.versions().deployed);
+	if (warn) d.error(warn);
+	return 0;
+}
+
+function sync(config, only, noMcp, d) {
+	const agents = registry(d).map((a) => a.user);
+	if (only) {
+		assertAgentName(only);
+		if (!agents.includes(only)) throw new Error(`"${only}" is not a registered agent`);
+	}
+	let ok = true;
+	for (const user of only ? [only] : agents) if (["failed", "unsafe", "unreadable"].includes(configureMcp(user, config, d, { noMcp }))) ok = false;
+	return ok ? 0 : 1;
+}

package/deploy/lib/agents.mjs

@@ -0,0 +1,128 @@
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /deploy/lib/agents.mjs
+ *	@Date: 2026-11-02T09:12:00-08:00 (1793639520)
+ *	@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-02T09:12:00-08:00 (1793639520)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ *
+ */
+
+/**
+ * The agent registry and the small pure helpers around it (#143, contract v2). An agent user `<u>`
+ * is registered when the group `gh-broker-agent-<u>` exists with exactly `gh-broker` and `<u>` as
+ * members; the daemon listens on one socket per registered agent. Everything here works on text
+ * (the contents of /etc/group, a `getent passwd` line), so it is testable without a host.
+ */
+import { join } from "node:path";
+
+export const SVC_USER = "gh-broker";
+export const AGENT_GROUP_PREFIX = "gh-broker-agent-";
+export const LEGACY_CLIENTS_GROUP = "gh-broker-clients";
+export const DEFAULT_AGENTS_DIR = "/run/gh-broker/agents";
+export const DEFAULT_LISTEN = `agents:${DEFAULT_AGENTS_DIR}`;
+/** Keeps `gh-broker-agent-<u>` within the 32-character group name limit. */
+export const AGENT_NAME = /^[a-z_][a-z0-9_-]{0,15}$/;
+
+/** Names that fit the pattern but are refused, as the daemon refuses them (src/agents.ts): a special JS key, root, and the service user. */
+export const RESERVED_AGENT_NAMES = ["__proto__", "root", SVC_USER];
+
+/** Whether `name` may be registered as an agent user. */
+export function validAgentName(name) {
+	return typeof name === "string" && AGENT_NAME.test(name) && !RESERVED_AGENT_NAMES.includes(name);
+}
+
+/** Throws a clear error for an invalid agent user name. */
+export function assertAgentName(name) {
+	if (!validAgentName(name)) throw new Error(`"${name}" is not a valid agent user name (lowercase letters, digits, "_" and "-", starting with a letter or "_", at most 16 characters)`);
+	return name;
+}
+
+export const agentGroup = (user) => `${AGENT_GROUP_PREFIX}${user}`;
+
+/** The directory the agents' sockets live in, from `listen` ("agents:<abs dir>"). */
+export function agentsDir(listen) {
+	return typeof listen === "string" && /^agents:\/.+/.test(listen) ? listen.slice("agents:".length) : DEFAULT_AGENTS_DIR;
+}
+
+export const socketPath = (dir, user) => join(dir, `${user}.sock`);
+
+/** Parse the contents of /etc/group (or `getent group` output) into { name, gid, members }. */
+export function parseGroups(text) {
+	const groups = [];
+	for (const line of text.split("\n")) {
+		const parts = line.split(":");
+		if (parts.length < 4 || !parts[0]) continue;
+		groups.push({ name: parts[0], gid: Number(parts[2]), members: parts[3] ? parts[3].split(",").filter(Boolean) : [] });
+	}
+	return groups;
+}
+
+/**
+ * Every `gh-broker-agent-<u>` group, with whether it is complete: its members are exactly the
+ * service user and `<u>`, the same test the daemon uses (it ignores a group that isn't). A group
+ * with no members is a removed agent (see removeAgentGroup) and isn't listed.
+ * @returns {Array<{ user: string, gid: number, complete: boolean }>} sorted by user
+ */
+export function registeredAgents(groups) {
+	const out = [];
+	for (const g of groups) {
+		if (!g.name.startsWith(AGENT_GROUP_PREFIX)) continue;
+		const user = g.name.slice(AGENT_GROUP_PREFIX.length);
+		if (!validAgentName(user) || g.members.length === 0) continue;
+		const members = new Set(g.members);
+		out.push({ user, gid: g.gid, complete: members.size === 2 && members.has(SVC_USER) && members.has(user) });
+	}
+	return out.sort((a, b) => a.user.localeCompare(b.user));
+}
+
+/**
+ * The agents to register on upgrade: members of the old shared `gh-broker-clients` group (other
+ * than the service user) that are not registered yet. Members with an invalid name are returned
+ * separately, to be reported and skipped.
+ */
+export function migrationPlan(groups, registered) {
+	const clients = groups.find((g) => g.name === LEGACY_CLIENTS_GROUP);
+	const have = new Set(registered.map((a) => a.user));
+	const add = [];
+	const skipped = [];
+	for (const m of clients?.members ?? []) {
+		if (m === SVC_USER || have.has(m)) continue;
+		(validAgentName(m) ? add : skipped).push(m);
+	}
+	return { add, skipped };
+}
+
+/** Parse one `getent passwd` line into { uid, gid, home }, or undefined. */
+export function parsePasswd(line) {
+	const f = line.trim().split(":");
+	if (f.length < 6) return undefined;
+	const uid = Number(f[2]);
+	const gid = Number(f[3]);
+	if (!Number.isInteger(uid) || !Number.isInteger(gid) || !f[5]) return undefined;
+	return { uid, gid, home: f[5] };
+}
+
+/**
+ * Where the installed package stands: a global install under /usr/local survives a Node upgrade,
+ * one under an nvm version folder does not.
+ * @returns {"global" | "nvm" | "checkout"}
+ */
+export function classifyInstall(packageDir) {
+	if (/nvm\/versions\//.test(packageDir)) return "nvm";
+	if (packageDir.startsWith("/usr/local/lib/node_modules/")) return "global";
+	return "checkout";
+}
+
+/** A warning when the npm package and the deployed /opt copy differ, else undefined. */
+export function versionWarning(pkgVersion, deployedVersion) {
+	if (!deployedVersion || !pkgVersion || pkgVersion === deployedVersion) return undefined;
+	return `warning: the installed package is ${pkgVersion} but the deployed service is ${deployedVersion}; run "sudo gh-broker install"`;
+}
+
+export const NPM_INSTALL_COMMAND = "sudo npm install -g --prefix /usr/local --ignore-scripts @cldmv/gh-broker@latest";

package/deploy/lib/cli.mjs

@@ -0,0 +1,72 @@
+/**
+ *
+ *	@Project: @cldmv/gh-broker
+ *	@Filename: /deploy/lib/cli.mjs
+ *	@Date: 2026-11-02T09:12:00-08:00 (1793639520)
+ *	@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-02T09:12:00-08:00 (1793639520)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ *
+ */
+
+/**
+ * The `gh-broker` command's dispatcher: `otp ...` and `agent ...` (and `install`, which
+ * deploy/cli.mjs hands to the installer before it gets here). Root check, config read and error
+ * reporting live here; the commands are in otp-cli.mjs and agent-cli.mjs.
+ */
+import { otpCommand } from "./otp-cli.mjs";
+import { agentCommand } from "./agent-cli.mjs";
+
+export const USAGE = `Usage: sudo gh-broker <command>
+
+Commands:
+  install [flags]            install or upgrade the broker (see: gh-broker install --help)
+  agent add <user>           register an agent user: group, MCP config, restart, smoke test (--no-mcp-config to skip the config)
+  agent remove <user>        unregister an agent: empty its group, restart, MCP entry, lock state
+  agent list                 each agent, its socket, and whether its MCP config points at it
+  agent sync [<user>]        re-apply the MCP config for one agent or all
+  otp status [<user>] [--json]
+                             lock state per agent
+  otp list [--json]          who is locked out now, and the command that clears each
+  otp unlock <user>|--all    clear an agent's lockout and hard lock (--all: everyone)
+  otp rotate                 make a new OTP seed, store it, show it once, restart the service`;
+
+const COMMANDS = { otp: ["unlock", "status", "list", "rotate"], agent: ["add", "remove", "list", "sync"] };
+
+/**
+ * @param {string[]} argv  arguments after the program name, e.g. ["otp", "unlock", "repo"]
+ * @param {object} d       injected effects (see deploy/cli.mjs realDeps)
+ * @returns {Promise<number>} the process exit code
+ */
+export async function runCli(argv, d) {
+	const [group, command, ...rest] = argv;
+	if (group === undefined || group === "-h" || group === "--help" || group === "help") {
+		d.log(USAGE);
+		return 0;
+	}
+	if (!COMMANDS[group]?.includes(command)) {
+		d.error(`gh-broker: unknown command "${argv.join(" ")}"\n${USAGE}`);
+		return 2;
+	}
+	if (!d.isRoot()) {
+		d.error(`gh-broker ${group} ${command}: must run as root: sudo gh-broker ${group} ${command}`);
+		return 1;
+	}
+	let config;
+	try {
+		config = d.readConfig();
+	} catch (err) {
+		d.error(`gh-broker ${group} ${command}: cannot read the broker config: ${err.message}`);
+		return 1;
+	}
+	try {
+		return await (group === "otp" ? otpCommand : agentCommand)(command, rest, config, d);
+	} catch (err) {
+		d.error(`gh-broker ${group} ${command}: ${err.message}`);
+		return 1;
+	}
+}