@staix/agent-hub 0.12.44 → 0.13.0

package/src/cli/init.ts

@@ -1,9 +1,13 @@
+import { randomUUID } from "node:crypto";
 import { initShadow, repoOf } from "../hub/snapshots.ts";
 import { profileName, projectProfile, resolveProfile, mergeProfileOverrides, type ProfileName } from "../hub/profiles.ts";
 import { JCODE_MCP_FILE } from "./jcode-mcp.ts";
-import { existsSync, lstatSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { hubGitSync } from "../hub/git.ts";
+import { existsSync, lstatSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync, renameSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import type { Stats } from "node:fs";
+import { realPath } from "../hub/project.ts";
+import { hubGitArgv, hubGitEnv, hubGitSync } from "../hub/git.ts";
 import { KIMI_MCP_FILE } from "./kimi-mcp.ts";
 import { AGY_PLUGIN_FILES } from "./agy-mcp.ts";
 
@@ -36,8 +40,70 @@ export interface InitChange {
   managedBlock?: "insert" | "replace" | "remove";
 }
 /** Content is internal to apply, never included in a public preview. */
-interface PlannedWrite extends InitChange { next?: string; shadow?: true; }
-function changes(cwd: string, requested?: ProfileName, shadow = false): PlannedWrite[] {
+interface PlannedWrite extends InitChange { next?: string; shadow?: true; directory?: true; executable?: true; moveFrom?: string; expected?: { dev: number; ino: number }; }
+const RELEASE_BEGIN = "<!-- AGENT_HUB_RELEASE_GUARD:BEGIN (managed by `ahub init --release-guard`) -->";
+const RELEASE_END = "<!-- AGENT_HUB_RELEASE_GUARD:END -->";
+const HOOK_MARKER = "# agent-hub managed release pre-push guard";
+const shellQuote = (value: string) => "'" + value.replace(/'/g, "'\"'\"'") + "'";
+
+function releaseBlock(existing: string): string {
+  const block = `${RELEASE_BEGIN}\n${readFileSync(join(TEMPLATES, "release-guard.block.md"), "utf8").trim()}\n${RELEASE_END}`;
+  const start = existing.indexOf("<!-- AGENT_HUB_RELEASE_GUARD:BEGIN"), end = existing.indexOf(RELEASE_END, Math.max(start, 0));
+  if (start >= 0 && end > start) return existing.slice(0, start) + block + existing.slice(end + RELEASE_END.length);
+  if (start >= 0 || existing.includes(RELEASE_END)) throw new Error("release guard instruction markers are incomplete");
+  return `${existing.trimEnd()}\n\n${block}\n`;
+}
+function regularHook(file: string): Stats | undefined {
+  const info = lstatSync(file, { throwIfNoEntry: false });
+  if (info && (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1)) throw new Error("release guard hook must be an unlinked regular file");
+  return info;
+}
+function releaseHookPlan(cwd: string): PlannedWrite[] {
+  for (const scope of [["--local"], ["--global"], []]) {
+    // Read the actual hooksPath without the hardened override masking it. All
+    // other portable Git hardening stays; `git config --get` executes no hook.
+    const argv = hubGitArgv(["config", ...scope, "--get", "core.hooksPath"]);
+    const override = argv.indexOf("core.hooksPath=/dev/null");
+    if (override < 1 || argv[override - 1] !== "-c") throw new Error("release guard Git hardening unavailable");
+    argv.splice(override - 1, 2);
+    const configured = spawnSync(argv[0]!, argv.slice(1), { cwd, env: hubGitEnv(process.env, { repositoryIsolation: true }), encoding: "utf8", timeout: 3000, maxBuffer: 16 * 1024 });
+    if (configured.status !== 1) throw new Error(configured.status === 0 ? "release guard refuses custom core.hooksPath; no files changed" : "release guard cannot verify core.hooksPath");
+  }
+  const common = hubGitSync(["rev-parse", "--git-common-dir"], { cwd, env: hubGitEnv(process.env, { repositoryIsolation: true }), encoding: "utf8", timeout: 3000 });
+  if (common.status !== 0 || !common.stdout.trim()) throw new Error("release guard requires a Git repository");
+  const raw = isAbsolute(common.stdout.trim()) ? common.stdout.trim() : resolve(cwd, common.stdout.trim());
+  const own = lstatSync(raw);
+  if (!own.isDirectory() || own.isSymbolicLink()) throw new Error("release guard Git directory must not be a link");
+  const commonDir = realPath(raw), hooks = join(commonDir, "hooks");
+  const parent = lstatSync(hooks, { throwIfNoEntry: false });
+  if (parent && (!parent.isDirectory() || parent.isSymbolicLink())) throw new Error("release guard hooks directory must not be a link");
+  const hook = join(hooks, "pre-push"), backup = join(hooks, "pre-push.agent-hub-original");
+  const original = regularHook(hook), saved = regularHook(backup);
+  const current = original ? readFileSync(hook, "utf8") : "";
+  const managed = current.startsWith(`#!/bin/sh\n${HOOK_MARKER}\n`);
+  if (!managed && saved) throw new Error("release guard backup is occupied; no files changed");
+  const wrapper = `#!/bin/sh
+${HOOK_MARKER}
+guard_input=$(umask 077; mktemp "\${TMPDIR:-/tmp}/ahub-release-guard.XXXXXX") || exit 1
+trap 'rm -f "$guard_input"' 0
+trap 'exit 1' 1 2 15
+${shellQuote(process.execPath)} ${shellQuote(join(import.meta.dir, "main.ts"))} sdlc release-guard-hook "$1" "$2" >"$guard_input" || exit "$?"
+if [ -x ${shellQuote(backup)} ]; then
+  ${shellQuote(backup)} "$@" <"$guard_input"
+else
+  exit 0
+fi
+`;
+  const plan: PlannedWrite[] = [];
+  if (!parent) plan.push({ action: "create", path: hooks, reason: "create default Git hooks directory", directory: true });
+  if (original && !managed) plan.push({ action: "create", path: backup, reason: "preserve original pre-push hook inode and mode", moveFrom: hook, expected: { dev: original.dev, ino: original.ino } });
+  if (current !== wrapper || original && !(original.mode & 0o111)) plan.push({ action: original ? "modify" : "create", path: hook, reason: "install release authorization pre-push guard", next: wrapper, executable: true });
+  return plan;
+}
+function changes(cwd: string, requested?: ProfileName, shadow = false, releaseGuard = false): PlannedWrite[] {
+  const originalAgents = existsSync(join(cwd, "AGENTS.md")) ? readFileSync(join(cwd, "AGENTS.md"), "utf8") : "";
+  const guarded = releaseGuard || originalAgents.includes("<!-- AGENT_HUB_RELEASE_GUARD:BEGIN");
+  const hooks = guarded ? releaseHookPlan(cwd) : [];
   const repository = shadow ? repoOf(cwd) : undefined;
   if (shadow && repository && !repository.shadow) throw new Error("project already has a Git work tree; shadow mode is for non-git folders");
   if (shadow) {
@@ -80,7 +146,8 @@ function changes(cwd: string, requested?: ProfileName, shadow = false): PlannedW
   }
   const agents = join(cwd, "AGENTS.md");
   const existing = existsSync(agents) ? readFileSync(agents, "utf8") : "";
-  write(agents, upsertBlock(existing, overrides && Object.hasOwn(overrides as object, "agents") ? profile.agents : profile.agents || readFileSync(join(TEMPLATES, "AGENTS.block.md"), "utf8")), "refresh hub instructions; preserve surrounding text", existing.includes("<!-- AGENT_HUB:BEGIN") ? "replace" : "insert");
+  const instructions = upsertBlock(existing, overrides && Object.hasOwn(overrides as object, "agents") ? profile.agents : profile.agents || readFileSync(join(TEMPLATES, "AGENTS.block.md"), "utf8"));
+  write(agents, guarded ? releaseBlock(instructions) : instructions, "refresh hub instructions; preserve surrounding text", existing.includes("<!-- AGENT_HUB:BEGIN") ? "replace" : "insert");
   const claude = join(cwd, "CLAUDE.md");
   const own = lstatSync(claude, { throwIfNoEntry: false });
   // The write preserves an existing inode, including AGENTS.md -> CLAUDE.md and hard links.
@@ -105,19 +172,50 @@ function changes(cwd: string, requested?: ProfileName, shadow = false): PlannedW
   }
   if (existsSync(join(cwd, JCODE_MCP_FILE)) && hubGitSync(["ls-files", "--error-unmatch", "--", JCODE_MCP_FILE], { cwd, encoding: "utf8", timeout: 3000 }).status !== 0 && !lines.split("\n").includes(JCODE_MCP_FILE)) lines = `${lines}${lines && !lines.endsWith("\n") ? "\n" : ""}${JCODE_MCP_FILE}\n`;
   write(ignore, lines, "ignore runtime state and machine-local configuration");
-  return changed;
+  return [...hooks, ...changed];
 }
 /** Read-only metadata, deliberately omitting project/user file contents. */
-export function planInit(cwd: string, profile?: ProfileName, shadow = false): InitChange[] {
-  return changes(cwd, profile, shadow).map(({ next, shadow: _shadow, ...change }) => change);
+export function planInit(cwd: string, profile?: ProfileName, shadow = false, releaseGuard = false): InitChange[] {
+  return changes(cwd, profile, shadow, releaseGuard).map(({ next, shadow: _shadow, directory, executable, moveFrom, expected, ...change }) => change);
 }
 /** Returns the paths it changed, applying the same plan as the preview. */
-export function init(cwd: string, profile?: ProfileName, shadow = false): string[] {
-  const plan = changes(cwd, profile, shadow);
+export function init(cwd: string, profile?: ProfileName, shadow = false, releaseGuard = false): string[] {
+  const plan = changes(cwd, profile, shadow, releaseGuard);
+  // Recheck hook parents and rename identities before any project write.
+  for (const change of plan.filter(change => change.executable || change.moveFrom)) {
+    const parent = lstatSync(dirname(change.path), { throwIfNoEntry: false });
+    if (parent && (!parent.isDirectory() || parent.isSymbolicLink())) throw new Error("release guard hook parent changed before installation");
+    if (change.moveFrom) {
+      const source = regularHook(change.moveFrom);
+      if (!source || source.dev !== change.expected?.dev || source.ino !== change.expected.ino || lstatSync(change.path, { throwIfNoEntry: false })) throw new Error("release guard hook changed before installation");
+    } else regularHook(change.path);
+  }
   mkdirSync(join(cwd, ".agenthub"), { recursive: true });
   for (const change of plan) {
     if (change.shadow) initShadow(cwd);
+    else if (change.directory) mkdirSync(change.path);
+    else if (change.moveFrom) continue; // Applied atomically with its prepared wrapper below.
     else if (change.action === "delete") unlinkSync(change.path);
+    else if (change.executable) {
+      const parent = lstatSync(dirname(change.path));
+      if (!parent.isDirectory() || parent.isSymbolicLink()) throw new Error("release guard hook parent changed before installation");
+      const current = regularHook(change.path), move = plan.find(row => row.moveFrom === change.path);
+      const temporary = join(dirname(change.path), `.pre-push.${randomUUID()}.tmp`);
+      let moved = false;
+      try {
+        // Prepare bytes before disturbing any existing gate. Refreshing our own
+        // managed hook is one atomic rename, so a failed write leaves it intact.
+        writeFileSync(temporary, change.next!, { mode: 0o755, flag: "wx" });
+        if (move) {
+          if (!current || current.dev !== move.expected?.dev || current.ino !== move.expected.ino || lstatSync(move.path, { throwIfNoEntry: false })) throw new Error("release guard hook changed before installation");
+          renameSync(change.path, move.path); moved = true;
+        }
+        renameSync(temporary, change.path);
+      } catch (error) {
+        if (moved && !lstatSync(change.path, { throwIfNoEntry: false })) renameSync(move!.path, change.path);
+        throw error;
+      } finally { if (lstatSync(temporary, { throwIfNoEntry: false })) unlinkSync(temporary); }
+    }
     else writeFileSync(change.path, change.next!);
   }
   return plan.map(change => change.path);

package/src/cli/main.ts

@@ -1,8 +1,14 @@
 #!/usr/bin/env bun
+import { hubGitSync, hubGitEnv } from "../hub/git.ts";
+import { parseReleaseGuardArgv, parseReleasePushUpdates } from "./sdlc-release-guard.ts";
+import { validReleaseVersion } from "../hub/sdlc-release-authorization.ts";
+import { agentVersions, runAgents } from "./agents.ts";
+import { assessVersion, COMPAT, configuredCommands } from "../adapters/compat.ts";
 import { claudePeer as defaultChannelPeer } from "../hub/claude-state.ts";
 import { effectiveInstanceRoles } from "../hub/instances.ts";
 import { resolveInstanceExecutionCwd } from "../hub/instance-execution.ts";
 import { readInstanceRoleConfig, readInstanceConfig, type InstanceRoleConfig } from "../hub/instance-config.ts";
+import { staleInstanceKey } from "../hub/roster.ts";
 import { parseConfiguredAcpArguments, runConfiguredAcpEntry, requireActiveConfiguredAcp } from "./configured-acp-entry.ts";
 import type { NativeCliEntryContext } from "../adapters/definitions/native-cli-entry-types.ts";
 import { BUILTIN_CLI_ENTRIES, createProjectAdapterCatalog, definitionOf, DOCTOR_TOOL_PROBES, DOCTOR_MEMORY_CAPTURE_PEERS, DOCTOR_PLUGIN_PROBE, nativeDoctorCheck, nativeDoctorRecoveryIdentity, nativeDoctorOptionalProbes } from "../adapters/registry.ts";
@@ -73,14 +79,17 @@ import { selectedMemoryProfile } from "../hub/memory-profile.ts";
 import { checkMemoryProfiles, formatMemoryProfileCheck } from "../hub/memory-profile-check.ts";
 import { addonReport, appendRecords, formatAddons, formatResearch, LABELS, labelTarget, RESEARCH_SCHEMA, projectKey, readStores, researchReport, taskRecords, toCsv, type Label, type TaskRecord } from "../hub/research.ts";
 import { summarize, summarizeByTask } from "../hub/report.ts";
+import { readDogfood } from "../hub/dogfood-read.ts";
+import { dogfoodSince, formatDogfood } from "../hub/dogfood.ts";
+import { USAGE_GROUPS, LIMITS_MAX } from "../hub/usage-rollup.ts";
 import { hasTree, planUndo, repoOf, restore, Turns } from "../hub/snapshots.ts";
 import { pathWarnings } from "../hub/conflicts.ts";
 import { COMPLETION_SHELLS, completionScript } from "./completion.ts";
-import { classifyPeerCommand, cliCommandLabel, detectCliIdentity, LIVE_TEST_PERSON_REFUSAL, liveTestRefusal, peerCommandRefusal } from "./identity.ts";
+import { agentShellCause, classifyPeerCommand, cliCommandLabel, detectCliIdentity, LIVE_TEST_PERSON_REFUSAL, liveTestRefusal, peerCommandRefusal } from "./identity.ts";
 import { recordCliAudit, recordDelegatedCliAudit } from "./identity-audit.ts";
 import { runConsole } from "./console.ts";
 import { paint, permissionBoundary, resolveColor, wrap, type Span } from "./console-state.ts";
-import { outputWidth, renderRoster, renderStatus, renderBoard, renderBoardColumns, boardColumnModel, renderBudget, renderDoctor, renderProjects, renderQueue, renderTurns, renderOrphans, renderQueueShow, renderModelsStatus, renderExecutionBudgetStatus, renderReport, type DoctorCheck } from "./output.ts";
+import { outputWidth, renderRoster, renderStatus, renderBoard, renderBoardColumns, boardColumnModel, renderBudget, renderDoctor, renderProjects, renderQueue, renderTurns, renderOrphans, renderQueueShow, renderModelsStatus, renderExecutionBudgetStatus, renderReport, renderUsage, renderLimits, renderTotal, type DoctorCheck } from "./output.ts";
 import { renderHelp, configuredAcpHelp } from "./help.ts";
 import { renderTailEvent } from "./tail-render.ts";
 import { archiveProblem, archiveState, damagedState, failureText, MANIFEST, planReset, resetLines, resetRuntime, startState, type ResetPlan } from "./reset.ts";
@@ -443,7 +452,14 @@ async function taskOp(op: string, a: Record<string, unknown>, throwOnError = fal
   try {
     if (op === "hub_task_cancel" && !hub.features.includes("task_cancel")) fail("this daemon does not support task cancellation; upgrade it first");
     const res = await hub.request({ t: "task", op, args: a }, timeoutMs ?? (op === "github_import" ? 60_000 : 30_000));
-    if (!res.ok) { if (throwOnError) throw new Error(res.error); audit("refused"); fail(res.error); }
+    if (!res.ok) {
+      if (throwOnError) throw new Error(res.error);
+      audit("refused");
+      // #711: an agent shell refused something only the person may do is told why it counts as an agent. The refusal and the authority stay as they were.
+      const cause = agentShellCause(identity, String(res.error));
+      if (cause) console.error(`ahub: ${res.error}\n${cause}`), process.exit(1);
+      fail(res.error);
+    }
     return res.text;
   } finally { if (!connection) hub.close(); }
 }
@@ -884,15 +900,15 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   init: () => {
-    const flags = takeFlags(args.filter(arg => arg !== "--dry-run" && arg !== "--json" && arg !== "--shadow"), ["--profile"], []);
-    if (flags.rest.length) fail("usage: ahub init [--profile dev|research|writing|general] [--shadow] [--dry-run --json]");
+    const flags = takeFlags(args.filter(arg => arg !== "--dry-run" && arg !== "--json" && arg !== "--shadow" && arg !== "--release-guard"), ["--profile"], []);
+    if (flags.rest.length) fail("usage: ahub init [--profile dev|research|writing|general] [--shadow] [--release-guard] [--dry-run --json]");
     const requestedProfile = flags.one["--profile"] === undefined ? undefined : profileName(flags.one["--profile"]);
     if (args.includes("--dry-run")) {
-      const plan = planInit(cwd, requestedProfile, args.includes("--shadow"));
+      const plan = planInit(cwd, requestedProfile, args.includes("--shadow"), args.includes("--release-guard"));
       return console.log(args.includes("--json") ? JSON.stringify(plan, null, 2) : plan.map(change => `${change.action} ${change.path}: ${change.reason}${change.managedBlock ? ` (managed block: ${change.managedBlock})` : ""}`).join("\n") || "already up to date");
     }
     assertLifecycleAvailable();
-    const changed = init(cwd, requestedProfile, args.includes("--shadow"));
+    const changed = init(cwd, requestedProfile, args.includes("--shadow"), args.includes("--release-guard"));
     registeredProject();
     console.log(changed.length ? changed.map((p) => `${existsSync(p) ? "wrote" : "removed"} ${p}`).join("\n") : "already up to date");
     const config = projectConfig(), examples = resolveProfile(config.profile, config.profile_overrides).example_checks;
@@ -1005,8 +1021,21 @@ const commands: Record<string, () => Promise<void> | void> = {
         printOutput(renderQueue(result.deliveries, options.columns, Date.now()), options.color);
         return;
       }
+      if (operation === "discard") {
+        // #713: the person's bulk clear of one peer's queue. Without --yes it only says how many it would discard.
+        const yes = rest.includes("--yes");
+        const { one, rest: others } = takeFlags(rest.filter((word) => word !== "--yes"), ["--peer", "--reason", "--state"], []);
+        if (others.length || !one["--peer"] || (one["--state"] !== undefined && !["queued", "needs_review"].includes(one["--state"]))) fail("usage: ahub queue discard --peer <id> --reason <text> [--state queued|needs_review] [--yes]");
+        if (yes && !one["--reason"]?.trim()) fail("ahub queue discard needs --reason <text> with --yes: it is recorded on every discarded delivery");
+        const result = await hub.request({ t: "queue", op: "discard", peer: one["--peer"], ...(one["--state"] ? { state: one["--state"] } : {}), ...(yes ? { confirmed: true, reason: one["--reason"] } : {}) }, 60_000);
+        if (!result.ok) fail(result.error);
+        if (options.json) return console.log(JSON.stringify(result, null, 2));
+        if (!yes) return console.log(`${result.count} ${result.state} deliver${result.count === 1 ? "y" : "ies"} for ${result.peer}; nothing discarded. Run again with --reason <text> --yes to discard them.`);
+        console.log(`discarded ${result.discarded} of ${result.count} ${result.state} deliver${result.count === 1 ? "y" : "ies"} for ${result.peer}${result.refused ? `; ${result.refused} refused (${Object.entries(result.refusedBy ?? {}).map(([why, n]) => `${why} ${n}`).join(", ")})` : ""}`);
+        return;
+      }
       const [id, ...flags] = rest;
-      if (!id || !["show", "resolve"].includes(operation)) fail("usage: ahub queue show <id> | resolve <id> --action completed|retry|discard --reason <text> [--revision N]");
+      if (!id || !["show", "resolve"].includes(operation)) fail("usage: ahub queue show <id> | resolve <id> --action completed|retry|discard --reason <text> [--revision N] | discard --peer <id> --reason <text> [--state queued|needs_review] [--yes]");
       if (operation === "show") {
         if (flags.length) fail("usage: ahub queue show <id>");
         const shown = await hub.request({ t: "queue", op: "show", id });
@@ -1191,6 +1220,50 @@ const commands: Record<string, () => Promise<void> | void> = {
 
   sdlc: async () => {
     const sub = args[0], id = args[1] === undefined ? undefined : Number(args[1]);
+    if (sub === "authorize-release") {
+      if (args.length !== 2 || !validReleaseVersion(args[1])) fail("usage: ahub sdlc authorize-release <version>");
+      const result = hubGitSync(["rev-parse", "--verify", "HEAD"], { cwd, env: hubGitEnv(process.env, { repositoryIsolation: true }), encoding: "utf8", timeout: 2000 });
+      const commit = result.stdout?.trim();
+      if (result.status !== 0 || !commit || !/^[a-f0-9]{40}$/.test(commit)) fail("candidate commit unavailable");
+      const hub = await connect();
+      try { const reply = await hub.request({ t: "sdlc", op: sub, version: args[1], commit }, 30_000); if (!reply.ok) fail(reply.error); console.log(JSON.stringify(reply.authorization, null, 2)); }
+      finally { hub.close(); }
+      return;
+    }
+    if (sub === "release-guard" || sub === "release-guard-hook") {
+      let original: Buffer | undefined;
+      let request: Record<string, unknown>;
+      if (sub === "release-guard-hook") {
+        if (args.length !== 3) fail("release hook needs its remote name and URL");
+        const chunks: Buffer[] = []; let size = 0;
+        for await (const chunk of process.stdin) { const bytes = Buffer.from(chunk); size += bytes.length; if (size > 128 * 1024) fail("release push inventory exceeds the guard bound"); chunks.push(bytes); }
+        original = Buffer.concat(chunks);
+        let input: string;
+        try { input = new TextDecoder("utf-8", { fatal: true }).decode(original); } catch { fail("release push inventory is not UTF-8"); }
+        const parsed = parseReleasePushUpdates(args[1]!, args[2]!, input);
+        if (!parsed.ok) fail(parsed.reason);
+        // Ordinary branch pushes keep working with the daemon offline.
+        if (!parsed.updates.length) { process.stdout.write(original); return; }
+        request = { t: "sdlc", op: sub, remoteName: parsed.remoteName, remoteUrl: parsed.remoteUrl, stdin: input };
+      } else {
+        if (args[1] !== "--") fail("usage: ahub sdlc release-guard -- git push origin v<version> | gh release create v<version> | npm publish");
+        const argv = args.slice(2), parsed = parseReleaseGuardArgv(argv);
+        if (!parsed.ok) fail(parsed.reason);
+        // Literal preflights cannot attest a command redirected by ambient target selectors.
+        const selectors = ["GIT_DIR", "GIT_WORK_TREE", "GIT_COMMON_DIR", ...(parsed.request.kind === "gh-release" ? ["GH_REPO", "GH_HOST"] : []), ...(parsed.request.kind === "npm-publish" ? Object.keys(process.env).filter(key => /^npm_config_(?:prefix|workspace|workspaces|userconfig|globalconfig|registry)$/i.test(key)) : [])];
+        if (selectors.some(key => process.env[key] !== undefined)) fail("release guard refuses ambient target selectors");
+        request = { t: "sdlc", op: sub, argv };
+      }
+      let hub: ControlClient | undefined;
+      try {
+        hub = await connect();
+        const reply = await hub.request(request, 30_000);
+        if (!reply.ok) fail(reply.error ?? "release authorization refused");
+        if (original) process.stdout.write(original); else console.log("release authorization matched");
+      } catch { fail("release authorization unavailable; the daemon must be reachable with a matching person approval"); }
+      finally { hub?.close(); }
+      return;
+    }
     if (sub === "queue" || sub === "release") {
       const repo = args[1], liveIssues = args.slice(2).map(Number);
       if (!repo || args.length > 34 || (sub === "queue" && args.length !== 2) || liveIssues.some(id => !Number.isSafeInteger(id) || id <= 0)) fail("usage: ahub sdlc queue <owner/repository> | release <owner/repository> [live-issue...]");
@@ -1230,6 +1303,17 @@ const commands: Record<string, () => Promise<void> | void> = {
       if (!flags.rest.length || (scope === undefined) !== (reviewers === undefined)) fail("plan-review needs a reason and both --review and --reviewers when supplying review scope");
       return console.log(await taskOp("hub_plan_review", { id, revision, reason: flags.rest.join(" "), ...(scope !== undefined ? { review: { scope, reviewers: Number(reviewers) } } : {}), ...(flags.one["--ci"] !== undefined ? { ci: flags.one["--ci"] } : {}) }));
     }
+    if (sub === "accept-departure") {
+      const head = args[2], rawReason = args.slice(3).join(" "), reason = rawReason.trim();
+      if (!Number.isSafeInteger(id) || id! <= 0 || typeof head !== "string" || !/^[a-f0-9]{40}$/.test(head) || !reason || rawReason.length > 2048) fail("usage: ahub sdlc accept-departure <task> <head> <reason...>");
+      const hub = await connect();
+      try {
+        const reply = await hub.request({ t: "sdlc", op: "accept-departure", id, head, reason }, 30_000);
+        if (!reply.ok) fail(reply.error);
+        console.log(`task #${id}: plan departure accepted for the reviewed head`);
+      } finally { hub.close(); }
+      return;
+    }
     if (sub === "accept") {
       // #481 S1: the person accepts the task's spec issue at its current body; agent shells are refused before this runs.
       const flags = takeFlags(args.slice(2), ["--issue", "--repo"], []);
@@ -1315,10 +1399,15 @@ const commands: Record<string, () => Promise<void> | void> = {
       if (args.length !== 2 || !/^\d+$/.test(args[1]!)) fail("usage: ahub review brief <task id>");
       return console.log(await taskOp("review_brief", { id: Number(args[1]) }));
     }
-    const { one, many, rest } = takeFlags(args, ["--head"], ["--unmet"]);
+    const { one, many, rest } = takeFlags(args, ["--head", "--findings"], ["--unmet"]);
     const [id, verdict, ...note] = rest;
-    if (!id || !verdict) fail("usage: ahub review <id> approved|changes_requested [note...] [--unmet <item>]... | ahub review brief <id>");
-    console.log(await taskOp("hub_review", { id: Number(id), verdict, ...(one["--head"] ? { head: one["--head"] } : {}), note: note.join(" "), ...(many["--unmet"]?.length ? { unmet: many["--unmet"] } : {}) }));
+    if (!id || !verdict) fail("usage: ahub review <id> approved|changes_requested [note...] [--unmet <item>]... [--head <sha>] [--findings <json>] | ahub review brief <id>");
+    let findings: unknown;
+    if (one["--findings"] !== undefined) {
+      try { findings = JSON.parse(one["--findings"]); } catch { fail("--findings must be a JSON array"); }
+      if (!Array.isArray(findings)) fail("--findings must be a JSON array");
+    }
+    console.log(await taskOp("hub_review", { id: Number(id), verdict, ...(one["--head"] ? { head: one["--head"] } : {}), note: note.join(" "), ...(findings === undefined ? {} : { findings }), ...(many["--unmet"]?.length ? { unmet: many["--unmet"] } : {}) }));
   },
 
   remember: async () => console.log(await taskOp("hub_remember", { text: freeText(args, "ahub remember <text>") })),
@@ -1390,7 +1479,7 @@ const commands: Record<string, () => Promise<void> | void> = {
   roster: async () => {
     const options = outputOptions(), flags = args.filter(arg => arg.startsWith("--")), positional = outputArguments().filter(arg => arg !== "--yes" && arg !== "--now");
     const [sub = "list", peer, ...extra] = positional;
-    if (!["list", "add", "remove"].includes(sub) || extra.length || (sub === "list" ? peer !== undefined : !peerDefinition(peer)) || flags.some(flag => !["--json", "--full", "--yes", "--now"].includes(flag) && !flag.startsWith("--color=")) || (sub !== "list" && options.json) || (sub !== "remove" && flags.some(flag => ["--yes", "--now"].includes(flag)))) fail("usage: ahub roster [--json] | add <peer> | remove <peer> [--yes] [--now]");
+    if (!["list", "add", "remove"].includes(sub) || extra.length || (sub === "list" ? peer !== undefined : !peerDefinition(peer) && !(sub === "remove" && typeof peer === "string" && staleInstanceKey(peer, projectCatalog))) || flags.some(flag => !["--json", "--full", "--yes", "--now"].includes(flag) && !flag.startsWith("--color=")) || (sub !== "list" && options.json) || (sub !== "remove" && flags.some(flag => ["--yes", "--now"].includes(flag)))) fail("usage: ahub roster [--json] | add <peer> | remove <peer> [--yes] [--now]");
     const hub = await connect();
     try {
       requireNamedPeerFeature(hub, peer);
@@ -1400,7 +1489,8 @@ const commands: Record<string, () => Promise<void> | void> = {
         if (!Array.isArray(view.roster)) fail("upgrade the running hub to use ahub roster");
         return options.json ? console.log(JSON.stringify(view.roster, null, 2)) : printOutput(renderRoster(view.roster, options.columns), options.color);
       }
-      const key = `roster.${peer}`, value = sub === "add";
+      // A key whose instance is no longer declared is deleted (null), never set to false: there is no peer left for it to switch off (#225).
+      const key = `roster.${peer}`, stale = sub === "remove" && !peerDefinition(peer) && staleInstanceKey(peer!, projectCatalog), value = stale ? null : sub === "add";
       const preview = await request({ t: "settings_preview", key, value });
       printOutput((preview.lines ?? []).map((text: string) => [{ text }]), options.color);
       if (sub === "remove" && !flags.includes("--yes")) {
@@ -1685,8 +1775,15 @@ const commands: Record<string, () => Promise<void> | void> = {
     const r = researchReport(records, from);
     console.log(args.includes("--json") ? JSON.stringify(r, null, 2) : formatResearch(r).join("\n"));
   },
-  report: () => {
+  report: async () => {
     const options = outputOptions();
+    if (args.includes("--dogfood")) {
+      let from: number;
+      try { from = dogfoodSince(args.filter(arg => !arg.startsWith("--color="))); }
+      catch { return fail("usage: ahub report --dogfood [--since 7d|<iso>] [--json]"); }
+      const scorecard = await readDogfood(cwd, stateDir, from);
+      return console.log(options.json ? JSON.stringify(scorecard, null, 2) : formatDogfood(scorecard).join("\n"));
+    }
     const by = args.indexOf("--by");
     if (by >= 0 && args[by + 1] !== "task") return fail("--by takes task");
     const events = readEvents(join(stateDir, "events.jsonl"), since());
@@ -1694,6 +1791,32 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (options.json) return console.log(JSON.stringify(data, null, 2));
     printOutput(renderReport(data, options.columns, Date.now(), by >= 0), options.color);
   },
+  usage: async () => {
+    const options = outputOptions();
+    const rest = outputArguments();
+    const sub = rest[0] !== undefined && !rest[0].startsWith("--") ? rest[0] : undefined;
+    if (sub !== undefined && !["limits", "total"].includes(sub)) fail("usage: ahub usage [--since 7d|<iso>] [--by peer|task|issue|pr|release|day|model] [--json] | limits [--peer <id>] [--limit <n>] [--json] | total [--json]");
+    const flags = sub === undefined ? rest : rest.slice(1);
+    const valueFlags = sub === "limits" ? ["--peer", "--limit"] : sub === undefined ? ["--since", "--by"] : [];
+    for (let i = 0; i < flags.length; i++) {
+      if (!valueFlags.includes(flags[i]!)) fail(`unknown argument ${JSON.stringify(flags[i]!.slice(0, 40))}; run ahub help`);
+      if (flags[++i] === undefined || flags[i]!.startsWith("--")) fail(`${flags[i - 1]} needs a value`);
+    }
+    const value = (flag: string) => { const at = args.indexOf(flag); return at >= 0 ? args[at + 1] : undefined; };
+    const by = value("--by"), peer = value("--peer"), limitText = value("--limit");
+    const limit = limitText === undefined ? undefined : /^\d+$/.test(limitText) ? Number(limitText) : NaN;
+    if (limit !== undefined && !(limit >= 1 && limit <= LIMITS_MAX)) fail(`--limit takes a whole number from 1 to ${LIMITS_MAX}`);
+    if (by !== undefined && !(USAGE_GROUPS as readonly string[]).includes(by)) fail(`--by takes ${USAGE_GROUPS.join(", ")}`);
+    const from = since();
+    const hub = await connect();
+    const reply = await hub.request(sub === "limits" ? { t: "usage", op: "limits", ...(peer ? { peer } : {}), ...(limit !== undefined ? { limit } : {}) } : sub === "total" ? { t: "usage", op: "total" }
+      : { t: "usage", op: "query", by: by ?? "peer", ...(from ? { since: from } : {}) }, 35_000);
+    hub.close();
+    if (!reply.ok) return fail(String(reply.error ?? "usage refused"));
+    if (reply.behind) process.stderr.write("ahub: the usage roll-up is still catching up with the event log: these numbers are partial; run it again in a few seconds\n");
+    if (options.json) return console.log(JSON.stringify(sub === "limits" ? { limits: reply.limits, current: reply.current } : sub === "total" ? reply.total : reply.usage, null, 2));
+    printOutput(sub === "limits" ? renderLimits(reply.limits, reply.current, options.columns) : sub === "total" ? renderTotal(reply.total, options.columns) : renderUsage(reply.usage, options.columns), options.color);
+  },
   facts: async () => {
     if (!args.includes("--hook")) return fail("usage: ahub facts --hook (a Claude Code PreToolUse, PostToolUse and Stop hook)");
     try {
@@ -1931,6 +2054,8 @@ const commands: Record<string, () => Promise<void> | void> = {
     }
     fail("usage: ahub role list [--group <group>] | show <id> | assign <peer> <id> | clear <peer> [<id>]");
   },
+  agents: () => runAgents(args, configuredCommands(loadConfig(cwd)), fail),
+
   doctor: async () => {
     const options = outputOptions();
     if (args.includes("--orphans")) return orphanDoctor(args.includes("--kill"), options);
@@ -1983,10 +2108,14 @@ const commands: Record<string, () => Promise<void> | void> = {
             [servers.length ? `${servers.length} besides the hub's own would load in the hub-owned jcode (${servers.join(", ")}); jcode has no switch to choose them, so remove them from its config or use another JCODE_HOME` : "",
               unreadable.length ? `unreadable or unsafe, not listed: ${unreadable.join(", ")}` : ""].filter(Boolean).join("; ") || "none besides the hub's own");
         } else {
-          const v = version(probe.command[0]!);
-          row(v === probe.expected, probe.name, v === probe.expected ? probe.confirmed : probe.unconfirmed);
+          const verdict = assessVersion(probe.compat, COMPAT[probe.compat].parse(version(probe.command[0]!) ?? ""));
+          row(verdict.ok ? verdict.state === "verified" || undefined : false, probe.name, verdict.ok ? verdict.note ?? probe.confirmed : `${probe.unconfirmed}: ${verdict.reason}`);
         }
       }
+      // #691: one line for each installed gated CLI that is not on a verified version.
+      for (const agent of agentVersions(configuredCommands(config))) {
+        if (agent.executable && !(agent.verdict.ok && agent.verdict.state === "verified")) row(agent.verdict.ok ? undefined : false, `${agent.id} version`, agent.verdict.ok ? agent.verdict.note ?? agent.verdict.state : agent.verdict.reason);
+      }
       const omni = new OmniRoute(config.omniroute);
       const gateway = await omni.base();
       row(gateway ? true : config.omniroute.urls.length || process.env.AGENTHUB_OMNIROUTE_URL ? false : undefined, "omniroute", gateway ? `${new URL(gateway).host} healthy` : config.omniroute.urls.length || process.env.AGENTHUB_OMNIROUTE_URL ? "no candidate reachable (VPN off?); ahub local cannot run" : "not configured: set omniroute.urls in .agenthub/config.local.json (any OpenAI-compatible gateway); ahub local cannot run");

package/src/cli/output.ts

@@ -5,6 +5,7 @@ import { cells, TABLES, table, fitLine, wrap, duration, relative, plural, termin
 import { taskProgress } from "../ui/task-progress.ts";
 import { backendLabel } from "./status-lines.ts";
 import { formatReport, formatTaskReport, type Report, type TaskReport } from "../hub/report.ts";
+import type { Counter, LimitsResult, TotalResult, UsageResult } from "../hub/usage-rollup.ts";
 
 export interface DoctorCheck { section: "Tools" | "Hub" | "Config" | "Models" | "Memory"; level: "ok" | "warn" | "fail" | "unknown"; name: string; detail: string }
 export interface StatusOutput {
@@ -17,7 +18,7 @@ export interface StatusOutput {
   isolatedChecks?: { pending?: number; orphans?: string[]; unknownReceipts?: readonly string[]; maintenanceUnavailable?: boolean };
   memoryProfile?: { profile?: string; generation?: string; state?: string; agentMemVersion?: string; skippedRows?: number; error?: string };
   taskWip?: Record<string, { wip: number; wipLimit: number }>;
-  pid?: number; controlPort?: number; cwd?: string; version?: string; peers: Record<string, any>; roleInfo?: Record<string, any>; budget?: Record<string, any>; planner?: { peers?: string[]; source?: string };
+  pid?: number; controlPort?: number; cwd?: string; version?: string; peers: Record<string, any>; roleInfo?: Record<string, any>; actionPolicyInfo?: Record<string, { note: string; enforceable: boolean }>; budget?: Record<string, any>; planner?: { peers?: string[]; source?: string };
   tasks?: Record<string, number>; models?: { backends?: any[] }; permissionDefaults?: any[]; deliveryError?: string; crash?: string[];
 }
 export interface BudgetOutput { budget: Record<string, any>; gate?: number }
@@ -245,9 +246,12 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
     }
     if (p.toolsOnly) out.push(...detail(definitionOf(id)?.attach?.pullOnlyForms?.includes("tui") && p.pullOnly ? "pull-only" : "tools-only", flat(p.toolsOnly).replace(/^(?:tools-only|pull-only):\s*/, ""), columns, "attention"));
     if (p.pullOnly && definitionOf(id)?.attach?.pullOnlyForms?.includes("tui")) out.push(...detail(`${id} last read`, typeof p.lastInboxAt === "number" ? relative(p.lastInboxAt, now) : "never", columns, "muted"));
+    const actionPolicy = data.actionPolicyInfo?.[id];
+    if (actionPolicy?.note) out.push(...detail(`${id} action policy`, actionPolicy.note, columns, actionPolicy.enforceable ? "muted" : "attention"));
     if (p.permissionNote) out.push(...detail("permission", p.permissionNote, columns, "muted"));
     if (typeof p.statusNotice?.message === "string" && p.statusNotice.message) out.push(...detail("status notice", p.statusNotice.message, columns, "attention"));
     if (p.requestedModel && p.servedBy && p.requestedModel !== p.servedBy) out.push(...detail("requested model", p.requestedModel, columns));
+    if (typeof p.modelSource === "string" && p.modelSource) out.push(...detail("model source", flat(p.modelSource), columns, "muted")); // an extra Jcode instance (#685): names only, never a URL or token
     if (typeof p.importantWaitingSince === "number" && p.importantWaitingNote) out.push(...detail("important waiting", `${p.importantWaitingNote.replace(/^\d+ important messages? waiting/, "important messages waiting")}`, columns, "attention"));
     if (typeof p.oldestQueuedAt === "number") out.push(...detail(`${id} oldest queued`, relative(p.oldestQueuedAt, now), columns, "muted"));
     return out;
@@ -431,3 +435,42 @@ export function renderReport(report: Report | TaskReport, columns?: number, now
   }
   return out;
 }
+
+// ---- ahub usage (#683 U2): every number names its source; an unknown number prints `unknown`, never 0 ----------------------------------------------
+const SOURCE_NAME: Record<Counter["source"], string> = { native: "native", count: "hub count", manual: "manual", partial: "partial, at least", unknown: "unknown" };
+/** `1234 (native)`, `1234 (hub count)`, or `unknown`: a missing counter is never shown as zero. */
+export const usageNumber = (c: Counter): string => c.value === null ? "unknown" : `${c.value} (${SOURCE_NAME[c.source]})`;
+const usageCell = (c: Counter): OutputCell => c.value === null ? span("unknown", "muted") : span(usageNumber(c), "number");
+
+export function renderUsage(result: UsageResult, columns?: number): Span[][] {
+  const out = lines(`usage by ${result.by}: ${result.coverage.records} records, ${result.coverage.withUsage} with provider counters, ${result.coverage.withoutUsage} without`, columns, "muted");
+  const header = ["KEY", "TOTAL", "WITHOUT CACHE", "CACHE READ", "INPUT", "OUTPUT", "REASONING", "HUB COUNT"];
+  const row = (r: UsageResult["rows"][number]) => [span(r.pii ? `${r.key} [pii]` : r.key), usageCell(r.total), usageCell(r.totalWithoutCache), usageCell(r.cacheRead), usageCell(r.input), usageCell(r.output), usageCell(r.reasoning), usageCell(r.counted)];
+  const all = [...result.rows, ...(result.unattributed ? [result.unattributed] : [])];
+  if (!all.length) return [...out, ...lines("no usage recorded in this period", columns)];
+  return [...out, [], ...rows(header, all.map(row), columns, undefined, true),
+    ...lines("TOTAL is the provider's own total, cache reads included; WITHOUT CACHE removes them. HUB COUNT is what the hub counted itself and covers peers that report no usage record. unknown is never zero.", columns, "muted")];
+}
+
+export function renderLimits(result: LimitsResult, current: unknown, columns?: number): Span[][] {
+  const out = lines(`limit history: ${result.truncated ? `the newest ${result.shown} of ${result.total}` : `${result.total}`} events, ${result.open.length} open pause${result.open.length === 1 ? "" : "s"}`, columns, "muted");
+  if (result.truncated) out.push(...lines(`${result.omitted} older events are not shown: use --limit <n> (up to ${result.maxLimit}) for more`, columns, "attention"));
+  for (const o of result.open) out.push(...lines(`open pause: ${o.peer} ${o.window} since ${o.since}, resets ${new Date(o.resetsAt).toISOString()}`, columns, "attention"));
+  for (const o of result.endedUnknown) out.push(...lines(`pause ended, end unknown: ${o.peer} ${o.window} since ${o.since} (the hub no longer holds it, for example after ahub reset; no resume was recorded)`, columns, "muted"));
+  const windows = current && typeof current === "object" ? Object.entries(current as Record<string, { windows?: { id: string; used: number; resetsAt?: number }[] }>) : [];
+  const live = windows.flatMap(([peer, b]) => (b?.windows ?? []).map(w => [span(peer), span(w.id), span(`${Math.round(w.used * 100)}%`, "number"), span(w.resetsAt ? new Date(w.resetsAt).toISOString() : "unknown", w.resetsAt ? undefined : "muted")]));
+  if (live.length) out.push([], ...lines("current windows", columns, "strong"), ...rows(["PEER", "WINDOW", "USED", "RESETS"], live, columns, undefined, true));
+  const hist = result.history.map(h => [span(h.at), span(h.type.replace("budget_", "").replace("quota_reset", "reset")), span(h.peer), span(h.window), span(Object.entries(h.detail).map(([k, v]) => `${k} ${v}`).join(", "), "muted")]);
+  if (hist.length) out.push([], ...lines("history", columns, "strong"), ...rows(["AT", "EVENT", "PEER", "WINDOW", "DETAIL"], hist, columns, undefined, true));
+  return out;
+}
+
+export function renderTotal(result: TotalResult, columns?: number): Span[][] {
+  const out = lines(`lifetime development tokens since ${result.since ?? "the first event"}`, columns, "muted");
+  const table = result.peers.map(p => [span(p.peer), usageCell(p.tokens), usageCell(p.withoutCache), usageCell(p.cacheRead)]);
+  table.push([span("ALL PEERS", "strong"), usageCell(result.overall.tokens), usageCell(result.overall.withoutCache), usageCell(result.overall.cacheRead)]);
+  const left = (label: string, peers: string[]) => peers.length ? lines(`${label} leaves out ${peers.join(", ")} (unknown, not counted as 0): a lower bound`, columns, "attention") : [];
+  return [...out, [], ...rows(["PEER", "TOTAL", "WITHOUT CACHE", "CACHE READ"], table, columns, undefined, true),
+    ...left("ALL PEERS TOTAL", result.overall.tokens.source === "partial" ? result.unknownPeers.tokens : []), ...left("ALL PEERS CACHE READ", result.overall.cacheRead.source === "partial" ? result.unknownPeers.cacheRead : []),
+    ...lines("A peer with no provider counters (for example jcode, kimi) shows the hub's own count where one exists, otherwise unknown. The overall WITHOUT CACHE is unknown unless every peer's cache split is known.", columns, "muted")];
+}

package/src/cli/preview.ts

@@ -21,7 +21,7 @@ export function launcherPreview(tool: "claude" | "codex" | "kimi" | "pi" | "qwen
     if (mode >= 0 && args[mode + 1] !== "headless") throw new Error("extra instances require headless mode");
     if (mode < 0 && !args.includes("--headless")) args.push("--mode", "headless");
   }
-  const result = preview({ tool, args, cwd, stateDir, cliDir: import.meta.dir, unattended, config, definition,
+  const result = preview({ tool, args, cwd, stateDir, cliDir: import.meta.dir, unattended, config, definition, ...(selected.instance ? { instance: selected.instance } : {}),
     baseEnvNames: Object.keys(childEnv()).concat(["AGENTHUB_STATE_DIR", "AGENTHUB_PROJECT_DIR"]),
     helpers: { buildLaunch: (native, argv, ctx) => buildLaunch(native, argv, { ...ctx, ...(selected.instance ? { instance: selected.instance } : {}) }), claudeObservationHooks, buildKimiLaunch, buildKimiTuiLaunch, nativeLaunchEnv, childEnv,
       startModeOf, kimiMcpPlan, jcodeCommand, jcodeTuiCommand, qwenSessionId, relayModelIds, buildPiLaunch },

package/src/cli/sdlc-release-guard.ts

@@ -0,0 +1,82 @@
+/** Literal release targets only. Parsing never executes a command or reads the repository. */
+export type ReleaseGuardRequest =
+  | { kind: "tag-push"; version: string; tag: string; sourceRef: string; remote: string }
+  | { kind: "gh-release"; version: string; tag: string; target?: string }
+  | { kind: "npm-publish" };
+export interface ReleasePushUpdate { localRef: string; localOid: string; remoteRef: string; remoteOid: string; version: string; }
+type Refusal = { ok: false; reason: string };
+export type ReleaseGuardParse = { ok: true; request: ReleaseGuardRequest } | Refusal;
+export type ReleasePushParse = { ok: true; remoteName: string; remoteUrl: string; updates: ReleasePushUpdate[]; stdin: string } | Refusal;
+const refuse = (): Refusal => ({ ok: false, reason: "release target is ambiguous, unsupported or invalid" });
+const SEMVER = /^(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)(?:-[0-9A-Za-z.-]+)?(?:[+][0-9A-Za-z.-]+)?$/;
+const oid = (value: string) => /^[0-9a-f]{40}$/.test(value);
+const zero = (value: string) => /^0{40}$/.test(value);
+const literal = (value: string) => value.length > 0 && value.length <= 4096 && !/[\s\0-\x1f\x7f$`*?\\]/.test(value);
+const ref = (value: string) => literal(value) && !value.startsWith("-") && !value.includes("..") && !value.includes("@{") && !value.includes("//") && !value.endsWith("/") && !value.endsWith(".") && !value.endsWith(".lock") && !"~^:[]()".split("").some(char => value.includes(char));
+const versionOf = (tag: string): string | undefined => tag.startsWith("v") && SEMVER.test(tag.slice(1)) ? tag.slice(1) : undefined;
+
+// Hook values are opaque Git data, not shell source. Unicode and shell-looking
+// characters are valid in refs; only Git's forbidden ref syntax is rejected.
+const hookText = (value: string) => value.length > 0 && value.length <= 4096 && !/[\p{Cc}]/u.test(value);
+const hookRef = (value: string) => hookText(value) && !/[\0-\x20\x7f]/.test(value) && !"~^:?*[\\".split("").some(char => value.includes(char)) && !value.includes("..") && !value.includes("@{") && !value.includes("//") && !value.endsWith("/") && !value.endsWith(".") && !value.split("/").some(part => !part || part.startsWith(".") || part.endsWith(".lock"));
+
+export function parseReleaseGuardArgv(argv: readonly string[]): ReleaseGuardParse {
+  if (!Array.isArray(argv) || !argv.length || argv.length > 128 || !argv.every(word => typeof word === "string" && word.length <= 4096 && !/[\0-\x1f\x7f]/.test(word)) || Buffer.byteLength(argv.join("\0")) > 16 * 1024) return refuse();
+  const [program, ...args] = argv;
+  if (program === "git" && args[0] === "push") {
+    if (args.length !== 3 || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(args[1] ?? "")) return refuse();
+    const spec = args[2]!, parts = spec.split(":");
+    if (parts.length > 2 || spec.startsWith("+")) return refuse();
+    const destination = parts.length === 2 ? parts[1]! : parts[0]!;
+    const tag = destination.startsWith("refs/tags/") ? destination.slice(10) : destination;
+    const version = versionOf(tag), sourceRef = parts[0]!;
+    if (!version || !ref(sourceRef) || parts.length === 2 && !destination.startsWith("refs/tags/")) return refuse();
+    return { ok: true, request: { kind: "tag-push", version, tag, sourceRef, remote: args[1]! } };
+  }
+  if (program === "gh" && args[0] === "release" && args[1] === "create") {
+    const tag = args[2] ?? "", version = versionOf(tag);
+    if (!version) return refuse();
+    let target: string | undefined;
+    const valued = new Set(["--title", "-t", "--notes", "-n", "--notes-file", "-F", "--notes-start-tag", "--target"]);
+    const flags = new Set(["--verify-tag", "--generate-notes", "--draft", "-d", "--prerelease", "-p", "--fail-on-no-commits"]);
+    for (let i = 3; i < args.length; i++) {
+      const flag = args[i]!;
+      if (flags.has(flag)) continue;
+      if (!valued.has(flag) || args[i + 1] === undefined) return refuse();
+      const value = args[++i]!;
+      if (flag === "--target") { if (target !== undefined || !ref(value)) return refuse(); target = value; }
+    }
+    return { ok: true, request: { kind: "gh-release", version, tag, ...(target === undefined ? {} : { target }) } };
+  }
+  if (program === "npm" && args[0] === "publish") {
+    const flags = new Set(["--provenance", "--ignore-scripts", "--dry-run"]);
+    for (let i = 1; i < args.length; i++) {
+      if (flags.has(args[i]!)) continue;
+      if (args[i] === "--access" && ["public", "restricted"].includes(args[i + 1] ?? "")) { i++; continue; }
+      if (args[i] === "--tag" && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(args[i + 1] ?? "")) { i++; continue; }
+      return refuse();
+    }
+    return { ok: true, request: { kind: "npm-publish" } };
+  }
+  return refuse();
+}
+
+/** Validate every hook row before selecting version-tag updates. Preserve the exact original input. */
+export function parseReleasePushUpdates(remoteName: string, remoteUrl: string, stdin: string): ReleasePushParse {
+  if (typeof remoteName !== "string" || typeof remoteUrl !== "string" || typeof stdin !== "string" || !hookText(remoteName) || !hookText(remoteUrl) || Buffer.byteLength(stdin) > 128 * 1024) return refuse();
+  const lines = stdin.endsWith("\n") ? stdin.slice(0, -1).split("\n") : stdin.split("\n");
+  if (stdin === "") lines.length = 0;
+  if (lines.length > 128) return refuse();
+  const updates: ReleasePushUpdate[] = [];
+  for (const line of lines) {
+    const fields = line.split(" ");
+    if (fields.length !== 4) return refuse();
+    const [localRef, localOid, remoteRef, remoteOid] = fields as [string, string, string, string];
+    if ((!hookRef(localRef) && localRef !== "(delete)") || !hookRef(remoteRef) || !remoteRef.startsWith("refs/") || !oid(localOid) || !oid(remoteOid)) return refuse();
+    if (!remoteRef.startsWith("refs/tags/v")) continue;
+    const version = versionOf(remoteRef.slice(10));
+    if (!version || zero(localOid) || localRef === "(delete)") return refuse();
+    updates.push({ localRef, localOid, remoteRef, remoteOid, version });
+  }
+  return { ok: true, remoteName, remoteUrl, updates, stdin };
+}