@staix/agent-hub 0.12.20 → 0.12.21

package/src/cli/identity.ts

@@ -26,6 +26,7 @@ export type PeerCommandAccess = "allowed" | "conductor" | "console";
 
 /** A closed list: unknown commands cannot acquire console authority through an agent shell. */
 export function classifyPeerCommand(command: string, args: readonly string[]): PeerCommandAccess {
+  if (command === "permission") return "console";
   if (args.some((arg) => arg === "--as-user" || arg.startsWith("--as-user="))) return "console";
   if (command === "task") {
     if (["propose", "show"].includes(args[0] ?? "")) return "allowed";
@@ -33,6 +34,11 @@ export function classifyPeerCommand(command: string, args: readonly string[]): P
     return "console";
   }
   if (command === "route") return args[0] === "explain" ? "allowed" : "console";
+  // #247: reading the research measures and records is harmless (ids and counts only); writing them is a person's.
+  if (command === "research") return args[0] === "backfill" ? "console" : "allowed";
+  // #251: a run resets the bench project's tree and proposes work; reading results is harmless.
+  // The subcommand is the first argument that is not --json, which the command accepts anywhere.
+  if (command === "bench") return args.find((arg) => arg !== "--json") === "run" ? "console" : "allowed";
   if (command === "budget") return !args.length || args.every((arg) => arg === "--json") ? "allowed" : "console";
   if (["claude", "codex", "kimi", "pi", "local", "pause", "resume"].includes(command)) return "conductor";
   if (["help", "version", "--version", "say", "status", "board", "report", "turns", "review", "remember", "facts", "check-path"].includes(command)) return "allowed";
@@ -41,10 +47,10 @@ export function classifyPeerCommand(command: string, args: readonly string[]): P
 
 /** No argument text is included: notices and refusal logs must not copy task text or credentials. */
 export function cliCommandLabel(command: string, args: readonly string[]): string {
-  if (!["upgrade", "restart", "recovery", "recovery-run", "help", "--help", "--version", "version", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "claude", "codex", "kimi", "pi", "local", "models", "say", "queue", "tail", "budget", "board", "task", "review", "remember", "ask", "route", "pause", "resume", "permit", "status", "logs", "export", "report", "facts", "check-path", "turns", "undo", "kill", "reset", "doctor"].includes(command)) return "unknown";
-  if (["task", "queue", "budget", "route", "recovery", "models", "projects"].includes(command)) {
-    const sub = args[0];
-    if (sub && ["propose", "show", "assign", "escalate", "list", "resolve", "resume", "set", "execution", "explain", "status", "abort", "dispose", "setup", "start", "stop", "remove"].includes(sub)) return `${command} ${sub}`;
+  if (!["upgrade", "restart", "recovery", "recovery-run", "help", "--help", "--version", "version", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "claude", "codex", "kimi", "pi", "local", "models", "say", "queue", "tail", "budget", "board", "task", "review", "remember", "ask", "route", "pause", "resume", "permit", "permission", "status", "logs", "export", "report", "research", "bench", "facts", "check-path", "turns", "undo", "kill", "reset", "doctor"].includes(command)) return "unknown";
+  if (["task", "queue", "budget", "route", "recovery", "models", "projects", "research", "bench"].includes(command)) {
+    const sub = command === "bench" ? args.find((arg) => arg !== "--json") : args[0];
+    if (sub && ["propose", "show", "assign", "escalate", "label", "list", "resolve", "resume", "set", "execution", "explain", "status", "abort", "dispose", "setup", "start", "stop", "remove", "export", "backfill", "run", "report", "compare"].includes(sub)) return `${command} ${sub}`;
   }
   return (/^[a-z][a-z0-9-]*$/.test(command) && !/\s/.test(command)) || ["--help", "--version"].includes(command) ? command : "unknown";
 }

package/src/cli/launch.ts

@@ -1,6 +1,9 @@
 // Launchers inject only the flags the hub owns and refuse user-supplied duplicates.
-import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { mkdirSync, writeFileSync, renameSync, unlinkSync, lstatSync, readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { resolve, join, basename, dirname, isAbsolute } from "node:path";
+import { processLiveness, processSignature } from "../pi/process-signature.ts";
+import { realPath } from "../hub/project.ts";
 import { peerChildEnv } from "../hub/child-process.ts";
 export const CLAUDE_CHANNEL = "plugin:agent-hub@agent-hub";
 
@@ -40,6 +43,36 @@ export interface Launch {
   cmd: string;
   args: string[];
   warning?: string;
+  permissionHook?: boolean;
+  hookPurpose?: FactsHook["purpose"];
+  settingsFile?: string;
+  unattended?: boolean;
+}
+
+/** Retire only our prior private Claude settings file, after the replacement launch record is committed. */
+export function cleanupClaudeSettings(stateDir: string, previous: unknown): void {
+  if (typeof previous !== "string" || !isAbsolute(previous) || !/^claude-settings-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\.json$/.test(basename(previous))) return;
+  try {
+    const root = realPath(stateDir);
+    if (realPath(dirname(previous)) !== root) return;
+    const stat = lstatSync(previous);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || (stat.mode & 0o777) !== 0o600 || !process.getuid || stat.uid !== process.getuid()) return;
+    if (realPath(previous) !== join(root, basename(previous))) return;
+    unlinkSync(previous);
+  } catch { /* Missing or unverifiable files remain untouched. */ }
+}
+
+/** Crash fallback only: an absent/unreadable owner identity never certifies that its native launch ended. */
+export function cleanupStaleClaudeSettings(stateDir: string, previous: unknown, identity = processSignature): void {
+  if (!previous || typeof previous !== "object" || Array.isArray(previous)) return;
+  const record = previous as Record<string, unknown>;
+  if (typeof record.launcherSignature !== "string" || !record.launcherSignature) return;
+  if (processLiveness(record.launcherPid, record.launcherSignature, identity) !== "gone") return;
+  // ponytail: spawnSync launch records have no independent native identity, so crash-left settings are retained.
+  // Upgrade path: record the native child's PID and processSignature before admitting crash fallback cleanup.
+  if (typeof record.nativePid !== "number" || !Number.isSafeInteger(record.nativePid) || record.nativePid <= 0 || record.nativePid === record.launcherPid || typeof record.nativeSignature !== "string" || !record.nativeSignature) return;
+  if (processLiveness(record.nativePid, record.nativeSignature, identity) !== "gone") return;
+  cleanupClaudeSettings(stateDir, record.settingsFile);
 }
 
 export interface StatusLineTee {
@@ -61,22 +94,22 @@ export function statusLineSettings(tee: StatusLineTee): string {
   return JSON.stringify({ statusLine: { type: "command", command, refreshInterval: tee.original?.refreshInterval ?? 10, ...(tee.original?.padding !== undefined ? { padding: tee.original.padding } : {}) } });
 }
 
-/** The turn-free facts hook (issue #108): absolute path of src/cli/facts-hook.ts and the hub's state dir. */
+/** Shared facts, native observation and permission hook transport. */
 export interface FactsHook {
   script: string;
   stateDir: string;
   /** The same hook transport can observe native turns without injecting facts. */
-  purpose?: "facts" | "idle" | "facts-and-idle";
+  purpose?: "facts" | "idle" | "facts-and-idle" | "permission";
   /** Observe native sessions/turns for every enabled facts, idle or conductor hook configuration. */
   observeNative?: boolean;
 }
 
-/** Shared by actual launch and read-only preview; advisory facts remain disabled. */
-export function claudeObservationHooks(config: { coordination?: string; task_sweep?: { enabled: boolean }; roles?: Record<string, string[]> }, paths: Pick<FactsHook, "script" | "stateDir">): FactsHook | undefined {
+/** Shared by actual launch and preview; permissions are always enabled, advisory facts remain disabled. */
+export function claudeObservationHooks(config: { coordination?: string; task_sweep?: { enabled: boolean }; roles?: Record<string, string[]> }, paths: Pick<FactsHook, "script" | "stateDir">): FactsHook {
   const facts = config.coordination === "turn-free";
   const idle = config.task_sweep?.enabled === true;
   const observeNative = facts || idle || config.roles?.claude?.includes("conductor") === true;
-  return facts || idle || observeNative ? { ...paths, purpose: facts ? (idle ? "facts-and-idle" : "facts") : "idle", ...(observeNative ? { observeNative: true } : {}) } : undefined;
+  return { ...paths, purpose: facts ? (idle ? "facts-and-idle" : "facts") : idle || observeNative ? "idle" : "permission", ...(observeNative ? { observeNative: true } : {}) };
 }
 
 /**
@@ -84,11 +117,11 @@ export function claudeObservationHooks(config: { coordination?: string; task_swe
  * facts hook before and after every tool call and at the end of each turn (issue #108; the turn end is the quiescence
  * evidence of issue #107).
  */
-export function sessionSettings(tee: StatusLineTee, facts?: FactsHook): string {
-  const settings = JSON.parse(statusLineSettings(tee)) as Record<string, unknown>;
+export function sessionSettings(tee?: StatusLineTee, facts?: FactsHook): string {
+  const settings = (tee ? JSON.parse(statusLineSettings(tee)) : {}) as Record<string, unknown>;
   if (facts) {
-    const hooks = [{ type: "command", command: `AGENTHUB_STATE_DIR=${sh(facts.stateDir)} bun ${sh(facts.script)}`, timeout: 5 }];
-    settings.hooks = { PreToolUse: [{ matcher: "*", hooks }], PostToolUse: [{ matcher: "*", hooks }], Stop: [{ hooks }] };
+    const hooks = [{ type: "command", command: `AGENTHUB_STATE_DIR=${sh(facts.stateDir)} AGENTHUB_HOOK_PURPOSE=${sh(facts.purpose ?? "facts")} bun ${sh(facts.script)}`, timeout: 5 }];
+    settings.hooks = { PreToolUse: [{ matcher: "*", hooks }], ...(facts.purpose !== "permission" ? { PostToolUse: [{ matcher: "*", hooks }], Stop: [{ hooks }] } : {}) };
     if (facts.observeNative) Object.assign(settings.hooks as object, { SessionStart: [{ matcher: "*", hooks }], UserPromptSubmit: [{ hooks }] });
   }
   return JSON.stringify(settings);
@@ -97,7 +130,7 @@ export function sessionSettings(tee: StatusLineTee, facts?: FactsHook): string {
 export function buildLaunch(
   tool: "claude" | "codex",
   userArgs: string[],
-  ctx: { unattended: boolean; proxyUrl?: string; codexBin?: string; statusLine?: StatusLineTee; facts?: FactsHook },
+  ctx: { unattended: boolean; proxyUrl?: string; codexBin?: string; statusLine?: StatusLineTee; facts?: FactsHook; preview?: boolean },
 ): Launch {
   // Hub-level switches are consumed here; everything else passes through to the tool.
   const passthrough = userArgs.filter((a) => !["--unattended", "--safe", "--new"].includes(a));
@@ -109,17 +142,62 @@ export function buildLaunch(
   if (tool === "claude") {
     // `--settings` takes one value, so a user-supplied one wins and Claude has no quota source for that session.
     const own = passthrough.some((a) => a === "--settings" || a.startsWith("--settings="));
-    const tee = ctx.statusLine && !own ? ["--settings", sessionSettings(ctx.statusLine, ctx.facts)] : [];
+    let settingsArgs = ctx.statusLine && !own ? ["--settings", sessionSettings(ctx.statusLine, ctx.facts)] : [];
+    let nativeArgs = passthrough;
+    let settingsFile: string | undefined;
+    if (own) {
+      if (passthrough.filter(a => a === "--settings" || a.startsWith("--settings=")).length > 1) throw new Error("pass --settings only once so the hub permission hook stays installed");
+      const index = passthrough.findIndex(a => a === "--settings" || a.startsWith("--settings="));
+      const arg = passthrough[index]!;
+      const value = arg === "--settings" ? passthrough[index + 1] : arg.slice("--settings=".length);
+      if (!value) throw new Error("--settings requires a JSON object or readable file so the hub permission hook can be installed");
+      let caller: Record<string, unknown>;
+      try {
+        caller = JSON.parse(value.trim().startsWith("{") ? value : readFileSync(resolve(value), "utf8"));
+        if (!caller || typeof caller !== "object" || Array.isArray(caller)) throw new Error("not an object");
+      } catch { throw new Error("cannot read --settings as a JSON object; the hub permission hook must be installed"); }
+      if (ctx.facts && caller.disableAllHooks === true) throw new Error("--settings disableAllHooks prevents the required hub permission hook; enable hooks to launch");
+      const injected = JSON.parse(sessionSettings(undefined, ctx.facts));
+      const callerHooks = caller.hooks;
+      if (callerHooks !== undefined && (!callerHooks || typeof callerHooks !== "object" || Array.isArray(callerHooks))) throw new Error("--settings hooks must be an object");
+      const hooks = { ...(callerHooks as Record<string, unknown> | undefined) };
+      for (const [event, entries] of Object.entries(injected.hooks ?? {})) {
+        const existing = hooks[event];
+        if (existing !== undefined && !Array.isArray(existing)) throw new Error(`--settings ${event} hooks must be an array`);
+        hooks[event] = [...(existing as unknown[] | undefined ?? []), ...(entries as unknown[])];
+      }
+      settingsArgs = ["--settings", JSON.stringify({ ...caller, ...(ctx.facts ? { hooks } : {}) })];
+      nativeArgs = passthrough.filter((_, i) => i !== index && (arg !== "--settings" || i !== index + 1));
+    } else if (ctx.facts && !ctx.statusLine) {
+      const injected = JSON.parse(sessionSettings(undefined, ctx.facts));
+      settingsArgs = ["--settings", JSON.stringify({ hooks: injected.hooks })];
+    }
+    if (settingsArgs.length && !ctx.preview) {
+      const stateDir = ctx.facts?.stateDir ?? ctx.statusLine?.stateDir;
+      if (!stateDir) throw new Error("Claude session settings require the hub state directory");
+      const file = join(stateDir, `claude-settings-${randomUUID()}.json`);
+      try {
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        writeFileSync(`${file}.tmp`, settingsArgs[1]!, { mode: 0o600, flag: "wx" });
+        renameSync(`${file}.tmp`, file);
+      } catch {
+        try { unlinkSync(`${file}.tmp`); } catch { /* no temp file was written */ }
+        throw new Error("cannot write private Claude session settings in the hub state directory");
+      }
+      settingsArgs[1] = file;
+      settingsFile = file;
+    }
     const notes = [
       unattended ? UNATTENDED_WARNING : "",
       ctx.statusLine && own ? "note: you passed --settings, so the hub's status line tee is off and the budget coordinator cannot see Claude's quota (ahub budget set claude <0..1> still works)." : "",
-      ctx.facts && own && ctx.facts.purpose !== "idle" ? "note: you passed --settings, so the hub's turn-free facts hooks are off for this session: Claude will not see the other agents' changes at its tool calls." : "",
-      ctx.facts && own && (ctx.facts.purpose === "idle" || ctx.facts.purpose === "facts-and-idle") ? "note: you passed --settings, so native idle observation hooks are off for this session: task idle sweeps cannot verify Claude between turns." : "",
-      ctx.facts?.observeNative && own ? "note: you passed --settings, so native session/turn observation hooks are off: completed turns and supervision tokens may be unavailable." : "",
     ].filter(Boolean);
     return {
       cmd: "claude",
-      args: ["--dangerously-load-development-channels", claudeChannel(passthrough), ...(unattended ? ["--dangerously-skip-permissions"] : []), ...tee, ...passthrough],
+      args: ["--dangerously-load-development-channels", claudeChannel(passthrough), ...(unattended ? ["--dangerously-skip-permissions"] : []), ...settingsArgs, ...nativeArgs],
+      ...(settingsFile ? { settingsFile } : {}),
+      permissionHook: !!ctx.facts,
+      ...(ctx.facts ? { hookPurpose: ctx.facts.purpose ?? "facts" } : {}),
+      unattended,
       ...(notes.length ? { warning: notes.join("\n") } : {}),
     };
   }
@@ -127,6 +205,7 @@ export function buildLaunch(
   return {
     cmd: ctx.codexBin ?? "codex",
     args: ["--enable", "tui_app_server", "--remote", ctx.proxyUrl, ...(unattended ? ["--dangerously-bypass-approvals-and-sandbox"] : []), ...passthrough],
+    unattended,
     ...warning,
   };
 }

package/src/cli/main.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import { isPermissionMode } from "../hub/permission-mode.ts";
 import { currentRouting } from "../hub/routing.ts";
 import { spawn, spawnSync } from "node:child_process";
 import { chmodSync, existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
@@ -10,13 +11,14 @@ import { loadConfig } from "../hub/daemon.ts";
 import { factsHook } from "./facts-hook.ts";
 import { projectContext, realPath } from "../hub/project.ts";
 import { Registry, type Project } from "../hub/registry.ts";
-import { inspectProject, processAlive, startProject, stopProject, runProjectDaemon } from "../hub/lifecycle.ts";
+import { inspectProject, startProject, stopProject, runProjectDaemon } from "../hub/lifecycle.ts";
+import { processLiveness, processSignature } from "../pi/process-signature.ts";
 import { openManager, startManager, stopManager } from "../hub/manager.ts";
 import { OmniRoute } from "../omniroute/client.ts";
 import { MemoryClient } from "../memory/client.ts";
 import { init, planInit } from "./init.ts";
 import { launcherPreview } from "./preview.ts";
-import { buildLaunch, claudeObservationHooks, nativeLaunchEnv, UNATTENDED_WARNING } from "./launch.ts";
+import { cleanupStaleClaudeSettings, cleanupClaudeSettings, buildLaunch, claudeObservationHooks, nativeLaunchEnv, UNATTENDED_WARNING } from "./launch.ts";
 import { nextStep, parseList, pluginState, type InstalledPlugin, type Marketplace } from "./setup.ts";
 import { CLASSES } from "../hub/board.ts";
 import { VERSION } from "../version.ts";
@@ -33,13 +35,16 @@ import { setupOllamaModel } from "./models-setup.ts";
 import { unknownContext } from "../hub/context-window.ts";
 import { backendLine, contextLine, peerLine, type BackendRow, type PeerRow } from "./status-lines.ts";
 import { parseSince, readEvents } from "../hub/events.ts";
+import { armRuns, benchCompare, benchCsv, benchReport, formatCompare, formatReport as formatBenchReport, formatRuns, readRuns, runSummary, sameSuite } from "../hub/bench.ts";
+import { benchPreflight, defaultIo, runBench } from "./bench.ts";
+import { appendRecords, formatResearch, LABELS, labelTarget, RESEARCH_SCHEMA, projectKey, readStores, researchReport, taskRecords, toCsv, type Label, type TaskRecord } from "../hub/research.ts";
 import { formatReport, summarize, formatTaskReport, summarizeByTask } from "../hub/report.ts";
 import { hasTree, planUndo, repoOf, restore, Turns } from "../hub/snapshots.ts";
 import { pathWarnings } from "../hub/conflicts.ts";
 import { classifyPeerCommand, cliCommandLabel, detectCliIdentity, peerCommandRefusal } from "./identity.ts";
 import { recordCliAudit } from "./identity-audit.ts";
 import { runConsole } from "./console.ts";
-import { resolveColor } from "./console-state.ts";
+import { permissionBoundary, resolveColor } from "./console-state.ts";
 import { renderHelp } from "./help.ts";
 import { renderTailEvent } from "./tail-render.ts";
 import { archiveProblem, archiveState, damagedState, failureText, MANIFEST, planReset, resetLines, resetRuntime, startState, type ResetPlan } from "./reset.ts";
@@ -97,6 +102,7 @@ function audit(outcome: "run" | "refused" | "invalid"): void {
 if (identity.role === "invalid") { audit("invalid"); fail(`${identity.reason}; use ahub console or a terminal with no agent markers`); }
 if (identity.role === "tools" && commandAccess === "console") { audit("refused"); fail(peerCommandRefusal(identity.peer, commandLabel)); }
 if (identity.role === "tools") audit("run");
+const invokedFrom = process.cwd(); // relative paths a person types (a bench suite) are theirs, not the project's
 try { process.chdir(cwd); } catch { fail(`project directory is unavailable: ${cwd}`); }
 const unattendedEnv = process.env.AGENTHUB_UNATTENDED === "1";
 const lifecycle = { inspectProject, startProject, stopProject };
@@ -108,6 +114,13 @@ function registeredProject(): Project {
   finally { registry.close(); }
 }
 
+/** #247: this project's registration for its research records; writing needs `research.enabled` in its config. */
+function researchProject(writes = true): Project {
+  const project = matchingProject() ?? fail("this project has no hub registration; run ahub up here once first");
+  if (writes && !loadConfig(cwd).research.enabled) fail('research records are off for this project; set "research": { "enabled": true } in .agenthub/config.json first');
+  return project;
+}
+
 /** The registration of exactly this root and state directory, the only one kill and reset act on; never registers. */
 function matchingProject(): Project | undefined {
   const registry = new Registry();
@@ -124,10 +137,13 @@ function resetLockFree(): void {
 /** A manifest whose daemon is alive or uncertain, by inspectProject's rule; a crashed daemon's leftovers do not count. */
 function liveManifest(): boolean {
   const control = readControl(stateDir);
-  if (control && processAlive(control.pid) !== false) return true;
+  if (control && processLiveness(control.pid, control.pidSignature) !== "gone") return true;
+  // A signed manifest is this release's daemon, which writes no hub.pid: one beside it is an older run's leftover.
+  if (control?.pidSignature) return false;
   let text: string;
+  // Only daemons up to 0.12.20 wrote hub.pid (#226): an unsigned legacy record.
   try { text = readFileSync(join(stateDir, "hub.pid"), "utf8").trim(); } catch { return false; }
-  if (/^\d+$/.test(text)) return processAlive(Number(text)) !== false;
+  if (/^\d+$/.test(text)) return processLiveness(Number(text)) !== "gone";
   // Empty or garbled: beside a dead daemon's status it is that daemon's leftover too; alone it proves nothing.
   return !control;
 }
@@ -217,17 +233,16 @@ function hubDaemonCommand(pid: number, root: string): string | undefined {
 
 /** Live PID candidates for a registration whose project root is gone: the claim, the manifest, the legacy pid file. */
 function orphanPids(project: Project): number[] {
+  // #226: a recorded pid counts only while its signature (when one was recorded) still names its process.
   const candidates = new Set<number>();
-  if (typeof project.pid === "number") candidates.add(project.pid);
+  if (typeof project.pid === "number" && processLiveness(project.pid, project.pidSignature) === "live") candidates.add(project.pid);
   const control = readControl(project.stateDir);
-  if (control && Number.isSafeInteger(control.pid)) candidates.add(control.pid!);
+  if (control && Number.isSafeInteger(control.pid) && processLiveness(control.pid, control.pidSignature) === "live") candidates.add(control.pid!);
   try {
     const pid = Number(readFileSync(join(project.stateDir, "hub.pid"), "utf8").trim());
     if (Number.isSafeInteger(pid) && pid > 0) candidates.add(pid);
   } catch { /* no legacy pid file */ }
-  return [...candidates].filter((pid) => {
-    try { process.kill(pid, 0); return true; } catch { return false; }
-  });
+  return [...candidates].filter((pid) => processLiveness(pid) === "live");
 }
 
 const processGone = (pid: number): boolean => !processCommandLine(pid);
@@ -525,10 +540,6 @@ const commands: Record<string, () => Promise<void> | void> = {
       process.env.AGENTHUB_INSTANCE_ID = control.instanceId;
       const terminal = await recordTerminalLaunch("claude", cwd, stateDir, control.instanceId);
       if (!terminal) process.env.AGENTHUB_LAUNCH_ID = randomUUID();
-      // Native hook identity exists in an ordinary terminal too; this is not an Orca recovery record.
-      const file = join(stateDir, "claude-launch.json");
-      writeFileSync(`${file}.tmp`, JSON.stringify({ instanceId: control.instanceId, launchId: process.env.AGENTHUB_LAUNCH_ID }), { mode: 0o600 });
-      chmodSync(`${file}.tmp`, 0o600); renameSync(`${file}.tmp`, file);
     }
     // `--settings` outranks project and user settings, so the tee has to wrap whichever status line would have won:
     // project local, then project, then user.
@@ -542,9 +553,26 @@ const commands: Record<string, () => Promise<void> | void> = {
     }
     // Turn-free facts and opted-in task sweeps share native PreToolUse/PostToolUse/Stop observations.
     const facts = claudeObservationHooks(projectConfig(), { script: join(import.meta.dir, "facts-hook.ts"), stateDir });
+    let previousLaunch: unknown;
+    try { previousLaunch = JSON.parse(readFileSync(join(stateDir, "claude-launch.json"), "utf8")); } catch { /* no previous managed launch */ }
     const launch = buildLaunch("claude", args, { unattended: unattendedEnv, statusLine: { script: join(import.meta.dir, "statusline-tee.ts"), stateDir, ...(original ? { original } : {}) }, ...(facts ? { facts } : {}) });
-    if (launch.warning) console.error(launch.warning);
-    exec(launch.cmd, launch.args, "claude");
+    let result: ReturnType<typeof spawnSync>;
+    try {
+      if (control?.instanceId) {
+        // Publish only the final launch's installed hook and effective permission flags.
+        const file = join(stateDir, "claude-launch.json");
+        writeFileSync(`${file}.tmp`, JSON.stringify({ instanceId: control.instanceId, launchId: process.env.AGENTHUB_LAUNCH_ID, permissionHook: launch.permissionHook === true, hookPurpose: launch.hookPurpose, settingsFile: launch.settingsFile, launcherPid: process.pid, launcherSignature: processSignature(process.pid), unattended: launch.unattended === true }), { mode: 0o600 });
+        chmodSync(`${file}.tmp`, 0o600); renameSync(`${file}.tmp`, file);
+        cleanupStaleClaudeSettings(stateDir, previousLaunch);
+      }
+      if (launch.warning) console.error(launch.warning);
+      const env = nativeLaunchEnv("claude", childEnv());
+      result = spawnSync(launch.cmd, launch.args, { cwd, stdio: "inherit", env: { ...env, AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } });
+    } finally {
+      cleanupClaudeSettings(stateDir, launch.settingsFile);
+    }
+    if (result.error) fail(`cannot run ${launch.cmd}: ${result.error.message}`);
+    process.exit(result.status ?? 1);
   },
 
   codex: async () => {
@@ -561,7 +589,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     const before = readControl(stateDir);
     if (recovering && before?.instanceId) await recordTerminalLaunch("codex", cwd, stateDir, before.instanceId);
     const hub = await connect();
-    const res = await hub.request({ t: "start", peer: "codex", operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+    const res = await hub.request({ t: "start", peer: "codex", args: { unattended: launch0.unattended === true }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
     hub.close();
     if (!res.ok) fail(res.error);
     const control = readControl(stateDir);
@@ -766,6 +794,17 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (sub === "show") return console.log(await taskOp("task_show", { id: rest[0] }));
     if (sub === "escalate") return console.log(await taskOp("task_escalate", { id: rest[0] }));
     if (sub === "assign") return console.log(await taskOp("task_assign", { id: rest[0], peer: rest[1] }));
+    if (sub === "label") {
+      // #247: a person's later verdict on an approved task (the identity gate keeps it human-only), for research records.
+      const { one, rest: positional } = takeFlags(rest, ["--created"], []);
+      const id = Number(positional[0]), label = positional[1] as Label;
+      if (positional.length !== 2 || !/^[1-9]\d*$/.test(positional[0]!) || !Number.isSafeInteger(id) || !(LABELS as readonly string[]).includes(label)) fail(`usage: ahub task label <id> ${LABELS.join("|")} [--created <time from ahub research export>]`);
+      const project = researchProject();
+      let record: TaskRecord;
+      try { record = labelTarget(readStores(project.id), readEvents(join(stateDir, "events.jsonl")), id, one["--created"]); } catch (error) { fail((error as Error).message); }
+      appendRecords(project.id, [{ schema: RESEARCH_SCHEMA, kind: "label", project: projectKey(project.id), task: id, createdAt: record!.createdAt!, label, at: new Date().toISOString() }]);
+      return console.log(`task #${id} (approved ${record!.approvedAt}) labelled ${label} in the research records`);
+    }
     if (sub !== "propose" || rest.length < 1) fail("usage: ahub task propose [<class>] <title...> | show <id> | assign <id> <peer> | escalate <id>");
     // `--class` is the explicit form. A first word that is a class name is still taken as the class (the documented
     // short form), but said out loud: "review the auth module" would otherwise be filed as class review, silently.
@@ -814,6 +853,24 @@ const commands: Record<string, () => Promise<void> | void> = {
   pause: () => hold("pause"),
   resume: () => hold("resume"),
 
+  permission: async () => {
+    const positional = args.filter(arg => arg !== "--yes");
+    const [peer, mode] = positional;
+    if (positional.length > 2 || positional.some(arg => arg.startsWith("--")) || (mode !== undefined && !isPermissionMode(mode))) fail("usage: ahub permission [<peer> [ask|ask-when-needed|never-ask]] [--yes]");
+    if (mode === "never-ask" && !args.includes("--yes")) fail("never-ask requires --yes; nothing was changed");
+    if (mode === "never-ask" && peer) console.error(`never-ask: ${permissionBoundary(peer)}; approval prompts are disabled`);
+    const hub = await connect();
+    try {
+      const reply = await hub.request({ t: "permission", ...(peer ? { peer } : {}), ...(mode ? { mode, confirmed: args.includes("--yes") } : {}) }, 35_000);
+      if (reply.ok === false) {
+        const error = String(reply.error ?? "permission request refused");
+        fail(/unknown (?:control )?(?:message|request|command)(?:\b|:)|this hub does not know "permission"/i.test(error) ? `${error}; upgrade the running hub to use ahub permission` : error);
+      }
+      if (reply.peers) for (const [id, value] of Object.entries(reply.peers)) console.log(`${id}: ${value}`);
+      else console.log(`${peer}: ${reply.permissionMode}`);
+    } finally { hub.close(); }
+  },
+
   permit: async () => {
     const [id, option] = args;
     if (!id || !option) fail("usage: ahub permit <id> <option|deny>");
@@ -831,6 +888,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (args.includes("--json")) return console.log(JSON.stringify(status, null, 2));
     console.log(`hub pid ${status.pid}, control 127.0.0.1:${status.controlPort}, ${status.cwd}`);
     if (status.deliveryError) console.log(`  delivery storage: ${status.deliveryError}; dispatch is stopped`);
+    for (const pending of status.permissionDefaults ?? []) console.log(`  permission default ${pending.peer}: never-ask from ${pending.source}, stays ask until a person confirms in ahub console`);
     for (const line of (status as { crash?: string[] }).crash ?? []) console.log(`  crash recovery: ${line}`);
     const peers = Object.entries(status.peers as Record<string, PeerRow>);
     for (const [id, p] of peers) console.log(peerLine(id, { ...p, context: p.context ?? unknownContext() }));
@@ -846,6 +904,89 @@ const commands: Record<string, () => Promise<void> | void> = {
   export: () => {
     for (const e of readEvents(join(stateDir, "events.jsonl"), since())) console.log(JSON.stringify(e));
   },
+  bench: async () => {
+    // #251: benchmark suites run against the peers attached here, and their comparison across arms.
+    const json = args.includes("--json");
+    const [sub, ...rest] = args.filter((a) => a !== "--json");
+    if (sub === "run") {
+      const { one, rest: positional } = takeFlags(rest, ["--arm", "--repeat", "--tasks"], []);
+      const suite = positional[0];
+      const repeat = one["--repeat"] === undefined ? 1 : Number(one["--repeat"]);
+      if (!suite || positional.length !== 1 || !one["--arm"]?.trim() || !Number.isSafeInteger(repeat) || repeat < 1 || repeat > 100) {
+        fail("usage: ahub bench run <suite.json> --arm <label> [--repeat 1..100] [--tasks a,b]");
+      }
+      await benchPreflight(cwd, loadConfig(cwd).bench.enabled); // the suite's refs are checked once it is read
+      let interrupted = false;
+      const stop = () => { interrupted = true; console.log("stopping at the next check: the attempt in progress is recorded as interrupted (a task still open is named)"); };
+      process.on("SIGINT", stop);
+      try {
+        const run = await runBench({ cwd, stateDir, suitePath: resolve(invokedFrom, suite!), arm: one["--arm"]!.trim(), repeat, only: one["--tasks"]?.split(",").map((t) => t.trim()).filter(Boolean), stopped: () => interrupted }, defaultIo(stateDir, cwd));
+        return console.log(formatBenchReport(benchReport(readRuns().filter((r) => r.header.run === run))).join("\n"));
+      } finally { process.off("SIGINT", stop); }
+    }
+    const runs = readRuns();
+    if (sub === undefined || sub === "list") return console.log(json ? JSON.stringify(runs.map(runSummary), null, 2) : formatRuns(runs).join("\n"));
+    if (sub === "status") {
+      const live = runs.filter((r) => r.state === "running" || r.state === "unknown");
+      return console.log(json ? JSON.stringify(live.map(runSummary), null, 2) : live.length ? formatRuns(live).join("\n") : "no benchmark run is running");
+    }
+    if (sub === "report") {
+      const run = runs.find((r) => r.header.run === rest[0]) ?? fail(`usage: ahub bench report <run> (ahub bench list shows the runs)`);
+      const r = benchReport([run]);
+      return console.log(json ? JSON.stringify(r, null, 2) : formatBenchReport(r).join("\n"));
+    }
+    if (sub === "compare") {
+      const mixed = rest.includes("--mixed");
+      const { one, rest: picks } = takeFlags(rest.filter((a) => a !== "--mixed"), ["--suite"], []);
+      const scoped = one["--suite"] ? runs.filter((r) => r.header.suite === one["--suite"]) : runs;
+      const groups = picks.map((pick) => {
+        const byRun = scoped.filter((r) => r.header.run === pick);
+        const chosen = byRun.length ? byRun : armRuns(scoped, pick);
+        if (!chosen.length) fail(`no run, or arm with a run that is over, named ${pick}${one["--suite"] ? ` in suite ${one["--suite"]}` : ""}`);
+        return { arm: byRun.length ? `${pick} [${byRun[0]!.header.arm}]` : pick, runs: chosen };
+      });
+      if (groups.length < 2) fail("usage: ahub bench compare <run|arm> <run|arm>... [--suite <name>] [--mixed] [--json]");
+      const differs = sameSuite(groups);
+      if (differs && !mixed) fail(`${differs}; compare runs of one suite file (name runs by id, or --suite when the names differ), or pass --mixed to compare them anyway`);
+      const c = benchCompare(groups);
+      return console.log(json ? JSON.stringify(c, null, 2) : formatCompare(c).join("\n"));
+    }
+    if (sub === "export") {
+      const format = rest.includes("--format") ? rest[rest.indexOf("--format") + 1] : "jsonl";
+      if (format !== "jsonl" && format !== "csv") fail("--format takes jsonl or csv");
+      if (format === "csv") return void process.stdout.write(benchCsv(runs));
+      for (const r of runs) for (const record of [r.header, ...r.attempts, ...(r.end ? [r.end] : [])]) console.log(JSON.stringify(record));
+      return;
+    }
+    fail("usage: ahub bench run|list|status|report|compare|export (ahub help bench)");
+  },
+  research: () => {
+    // #247: measures from the opt-in research records; `export` writes them out, `backfill` builds them from events.jsonl.
+    const [sub] = args;
+    // Another project is `ahub --project <dir> research`; anything unknown is refused rather than ignored.
+    const flags = new Set(["--all", "--json", "--since", "--format"]), valued = new Set(["--since", "--format"]);
+    for (let i = sub === "export" || sub === "backfill" ? 1 : 0; i < args.length; i++) {
+      if (!flags.has(args[i]!)) fail(`ahub research: unknown argument ${args[i]} (another project: ahub --project <dir> research)`);
+      if (valued.has(args[i]!)) i++;
+    }
+    if (sub === "backfill") {
+      const project = researchProject();
+      const written = appendRecords(project.id, taskRecords(readEvents(join(stateDir, "events.jsonl")), project.id, { version: VERSION, source: "backfill" }));
+      return console.log(`${written} research record${written === 1 ? "" : "s"} written from this project's events`);
+    }
+    const all = args.includes("--all");
+    const records = readStores(all ? undefined : researchProject(false).id);
+    const from = since();
+    if (sub === "export") {
+      const format = args[args.indexOf("--format") + 1] ?? "jsonl";
+      if (args.includes("--format") && !["jsonl", "csv"].includes(format)) fail("--format takes jsonl or csv");
+      const kept = records.filter((r) => r.kind === "label" || Date.parse(r.approvedAt) >= from);
+      return void process.stdout.write(args.includes("--format") && format === "csv" ? toCsv(kept) : kept.map((r) => JSON.stringify(r)).join("\n") + (kept.length ? "\n" : ""));
+    }
+    if (sub !== undefined && !sub.startsWith("--")) fail("usage: ahub research [--since 30d] [--all] [--json] | export [--format jsonl|csv] [--since] [--all] | backfill");
+    const r = researchReport(records, from);
+    console.log(args.includes("--json") ? JSON.stringify(r, null, 2) : formatResearch(r).join("\n"));
+  },
   report: () => {
     const by = args.indexOf("--by");
     if (by >= 0 && args[by + 1] !== "task") return fail("--by takes task");
@@ -1020,7 +1161,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     // The prefix tells a concurrent reset's claim from a daemon's.
     const claim = `reset-${randomUUID()}`;
     try {
-      if (!registry.claim(project.id, claim, process.pid)) {
+      if (!registry.claim(project.id, claim, process.pid, processSignature(process.pid))) {
         const holder = registry.get(project.id);
         throw new Error(holder?.instanceId?.startsWith("reset-") ? `another ahub reset of this project is running (pid ${holder.pid}); nothing was reset` : "a hub started after the stop; nothing was reset, run ahub reset again");
       }

package/src/cli/preview.ts

@@ -38,9 +38,19 @@ export function launcherPreview(tool: "claude" | "codex" | "kimi" | "pi", raw: s
     }
     // Build with original inputs so channel selection and owned-flag validation match normal launch.
     const facts = claudeObservationHooks(config, { script: join(import.meta.dir, "facts-hook.ts"), stateDir });
-    launch = buildLaunch(tool, args, { unattended, statusLine: { script: join(import.meta.dir, "statusline-tee.ts"), stateDir, ...(original ? { original: { command: original.command ? REDACTED : "", ...(typeof original.refreshInterval === "number" && Number.isFinite(original.refreshInterval) ? { refreshInterval: original.refreshInterval } : {}), ...(typeof original.padding === "number" && Number.isFinite(original.padding) ? { padding: original.padding } : {}) } } : {}) }, ...(facts ? { facts } : {}) });
-    const passthrough = args.filter(arg => !["--unattended", "--safe", "--new"].includes(arg));
-    launch.args = launch.args.slice(0, launch.args.length - passthrough.length).concat(passthrough.map(publicArg));
+    launch = buildLaunch(tool, args, { preview: true, unattended, statusLine: { script: join(import.meta.dir, "statusline-tee.ts"), stateDir, ...(original ? { original: { command: original.command ? REDACTED : "", ...(typeof original.refreshInterval === "number" && Number.isFinite(original.refreshInterval) ? { refreshInterval: original.refreshInterval } : {}), ...(typeof original.padding === "number" && Number.isFinite(original.padding) ? { padding: original.padding } : {}) } } : {}) }, ...(facts ? { facts } : {}) });
+    // Merged caller settings change the native argument count. Rebuild a redacted preview,
+    // retaining the managed hooks but never serializing caller settings or their file path.
+    const safeArgs = args.map((arg, i) => {
+      if (args[i - 1] === "--settings") return "{}";
+      if (arg.startsWith("--settings=")) return "--settings={}";
+      if (["--unattended", "--safe", "--new"].includes(arg)) return arg;
+      return publicArg(arg);
+    });
+    const publicLaunch = buildLaunch(tool, safeArgs, { preview: true, unattended, statusLine: { script: join(import.meta.dir, "statusline-tee.ts"), stateDir,
+      ...(original ? { original: { command: original.command ? REDACTED : "", ...(typeof original.refreshInterval === "number" && Number.isFinite(original.refreshInterval) ? { refreshInterval: original.refreshInterval } : {}), ...(typeof original.padding === "number" && Number.isFinite(original.padding) ? { padding: original.padding } : {}) } } : {}) }, facts });
+    publicLaunch.args.splice(0, 2, ...launch.args.slice(0, 2)); // channel selection was verified against the original MCP config
+    launch = publicLaunch;
   } else if (tool === "codex") {
     // A fresh native proxy is assigned by start, never guessed from an old status file.
     launch = buildLaunch(tool, args, { unattended, proxyUrl: UNRESOLVED, codexBin: config.codex_bin === "codex" ? "codex" : REDACTED });

package/src/cli/status-lines.ts

@@ -1,7 +1,7 @@
 import type { ContextView } from "../hub/context-window.ts";
 // What `ahub status` prints for a peer and for a model backend, kept pure so it can be checked.
 
-export interface PeerRow { context?: ContextView; state?: string; queued?: number; queuedImportant?: number; needsReview?: number; heldBy?: string; holdNote?: string; liveAccepted?: string[]; oldestQueuedAt?: number; attached?: boolean; toolsOnly?: string; paused?: string; servedBy?: string; requestedModel?: string }
+export interface PeerRow { permissionMode?: string; context?: ContextView; state?: string; queued?: number; queuedImportant?: number; needsReview?: number; heldBy?: string; holdNote?: string; liveAccepted?: string[]; oldestQueuedAt?: number; attached?: boolean; toolsOnly?: string; paused?: string; servedBy?: string; requestedModel?: string }
 export interface BackendRow { kind?: string; alias?: string; state?: string; active?: number; requestedModel?: string; actualModel?: string; provider?: string; coolingUntil?: string; failures?: number; failingUntil?: string }
 
 /** Aliases are already namespaced ("dgx/coding"); only an alias that is not gets its kind in front of it. */
@@ -26,6 +26,7 @@ export function peerLine(id: string, p: PeerRow): string {
     (p.oldestQueuedAt !== undefined ? `  oldest ${Math.max(0, Math.floor((Date.now() - p.oldestQueuedAt) / 1000))}s` : "") +
     (p.attached === false ? "  disconnected" : "") +
     (p.toolsOnly ? `  ${p.toolsOnly}` : "") +
+    (p.permissionMode && p.permissionMode !== "ask" ? `  permission: ${p.permissionMode}` : "") +
     (p.paused ? `  (${p.paused})` : "") +
     (p.servedBy ? `  last call: ${p.servedBy}` : "") +
     // Which backend the peer asked for on its last turn: without it, telling a Pi DGX turn from an MLX one