@staix/agent-hub 0.12.16 → 0.12.18

package/src/cli/facts-hook.ts

@@ -5,15 +5,22 @@
 // call; the hub confirms it from the transcript row Claude Code writes for it, by tool use id, before it counts as seen.
 import { ControlClient } from "../hub/control-client.ts";
 
+/** A library call may target another hub; only the managed command hook inherits that target's native identity. */
+export function nativeHookIdentity(stateDir: string, peer: string, env: NodeJS.ProcessEnv = process.env): { nativeInstanceId?: string; nativeLaunchId?: string } {
+  if (env.AGENTHUB_STATE_DIR !== stateDir || env.AGENTHUB_PEER_ID !== peer) return {};
+  return { ...(env.AGENTHUB_INSTANCE_ID ? { nativeInstanceId: env.AGENTHUB_INSTANCE_ID } : {}), ...(env.AGENTHUB_LAUNCH_ID ? { nativeLaunchId: env.AGENTHUB_LAUNCH_ID } : {}) };
+}
+
 /** The hook's stdout for one Claude Code hook input, or undefined for none. */
 export async function factsHook(stdin: string, stateDir: string, peer: string, timeoutMs = 2000): Promise<string | undefined> {
   const input = JSON.parse(stdin) as { hook_event_name?: unknown; tool_name?: unknown; tool_input?: unknown; tool_use_id?: unknown; session_id?: unknown; transcript_path?: unknown };
-  const phase = ({ PostToolUse: "post", Stop: "stop" } as Record<string, string>)[String(input.hook_event_name)] ?? "pre";
+  const phase = ({ SessionStart: "session", UserPromptSubmit: "start", PostToolUse: "post", Stop: "stop" } as Record<string, string>)[String(input.hook_event_name)] ?? "pre";
   const hub = await ControlClient.connect(stateDir, { role: "tools", peer }, timeoutMs);
   try {
     const res = await hub.request({
       t: "facts",
       phase,
+      ...nativeHookIdentity(stateDir, peer),
       tool: typeof input.tool_name === "string" ? input.tool_name : "",
       input: input.tool_input ?? {},
       ...(typeof input.tool_use_id === "string" ? { toolUseId: input.tool_use_id } : {}),

package/src/cli/identity-audit.ts

@@ -0,0 +1,66 @@
+import { mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { cliCommandLabel } from "./identity.ts";
+
+export interface CliAudit {
+  v: 1; id: string; at: number; peer: string; command: string; outcome: "run" | "refused" | "invalid";
+}
+const MAX_FILES = 256;
+const MAX_BYTES = 64 * 1024;
+const MAX_ROW_BYTES = 512;
+const READY = /^[a-f0-9-]{36}\.json$/;
+const PENDING = /^[a-f0-9-]{36}\.tmp$/;
+const valid = (row: any): row is CliAudit => row?.v === 1 && typeof row.id === "string" && /^[a-f0-9-]{36}$/.test(row.id)
+  && typeof row.at === "number" && Number.isFinite(row.at) && row.at > 0
+  && typeof row.peer === "string" && /^[a-z][a-z0-9-]{0,31}$/.test(row.peer) && !/\s/.test(row.peer)
+  && typeof row.command === "string" && row.command.length <= 64 && row.command === cliCommandLabel(...splitLabel(row.command))
+  && ["run", "refused", "invalid"].includes(row.outcome);
+const splitLabel = (label: string): [string, string[]] => { const [command = "unknown", ...args] = label.split(" "); return [command, args]; };
+
+/**
+ * An ids-only outbox, published atomically without a writer lock. Concurrent writers can overshoot
+ * the checked 256-file / 64 KiB ceiling by at most one bounded row per concurrent writer.
+ * Unpublished temp files count against the ceiling, so a crashed writer cannot grow the spool forever.
+ */
+export function recordCliAudit(stateDir: string, peer: string, command: string, outcome: CliAudit["outcome"]): void {
+  const row: CliAudit = { v: 1, id: crypto.randomUUID(), at: Date.now(), peer, command, outcome };
+  if (!valid(row)) throw new Error("invalid CLI audit identifiers");
+  const dir = join(stateDir, "cli-audit");
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const files = readdirSync(dir).filter(name => READY.test(name) || PENDING.test(name));
+  let bytes = 0;
+  for (const name of files) {
+    try { bytes += statSync(join(dir, name)).size; }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+  }
+  const text = JSON.stringify(row) + "\n";
+  if (Buffer.byteLength(text) > MAX_ROW_BYTES || files.length >= MAX_FILES || bytes + Buffer.byteLength(text) > MAX_BYTES) throw new Error("CLI audit outbox is full");
+  const pending = join(dir, `${row.id}.tmp`);
+  try {
+    writeFileSync(pending, text, { mode: 0o600, flag: "wx" });
+    renameSync(pending, join(dir, `${row.id}.json`));
+  } catch (error) {
+    try { unlinkSync(pending); } catch { /* only this writer's unpublished file */ }
+    throw error;
+  }
+}
+
+/** Consume ready files only; rebuild fixed fields so titles or other injected text cannot be rendered. */
+export function drainCliAudits(stateDir: string): CliAudit[] {
+  const dir = join(stateDir, "cli-audit");
+  let files: string[];
+  try { files = readdirSync(dir).filter(name => READY.test(name)).sort(); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return []; throw error; }
+  const rows: CliAudit[] = [];
+  for (const name of files) {
+    const path = join(dir, name);
+    try {
+      if (statSync(path).size <= MAX_ROW_BYTES) {
+        const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+        if (valid(parsed) && `${parsed.id}.json` === name) rows.push({ v: 1, id: parsed.id, at: parsed.at, peer: parsed.peer, command: parsed.command, outcome: parsed.outcome });
+      }
+    } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT" && !(error instanceof SyntaxError)) throw error; }
+    try { unlinkSync(path); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+  }
+  return rows;
+}

package/src/cli/identity.ts

@@ -0,0 +1,54 @@
+export type CliIdentity =
+  | { role: "console" }
+  | { role: "tools"; peer: string }
+  | { role: "invalid"; reason: string };
+
+/** Honest defaults for native shells, not authentication against an agent that can edit its environment. */
+export function detectCliIdentity(env: Readonly<Record<string, string | undefined>>): CliIdentity {
+  const hub = env.AGENTHUB_PEER_ID;
+  const claude = env.CLAUDECODE;
+  const session = env.CLAUDE_CODE_SESSION_ID;
+  const codex = env.CODEX_THREAD_ID;
+  const invalid = (reason: string): CliIdentity => ({ role: "invalid", reason });
+  if (hub !== undefined && (!/^[a-z][a-z0-9-]{0,31}$/.test(hub) || /\s/.test(hub) || ["user", "hub", "digest"].includes(hub))) return invalid("invalid AGENTHUB_PEER_ID marker");
+  if (claude !== undefined && claude !== "1") return invalid("invalid CLAUDECODE marker");
+  if (session !== undefined && (!session || /\s/.test(session))) return invalid("invalid CLAUDE_CODE_SESSION_ID marker");
+  if (codex !== undefined && (!codex || /\s/.test(codex))) return invalid("invalid CODEX_THREAD_ID marker");
+  if (session !== undefined && claude === undefined) return invalid("CLAUDE_CODE_SESSION_ID without CLAUDECODE marker");
+  if (claude !== undefined && codex !== undefined) return invalid("conflicting native agent markers");
+  const native = claude !== undefined ? "claude" : codex !== undefined ? "codex" : undefined;
+  if (hub !== undefined && native !== undefined && hub !== native) return invalid("AGENTHUB_PEER_ID conflicts with native agent marker");
+  const peer = hub ?? native;
+  return peer === undefined ? { role: "console" } : { role: "tools", peer };
+}
+
+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 (args.some((arg) => arg === "--as-user" || arg.startsWith("--as-user="))) return "console";
+  if (command === "task") {
+    if (["propose", "show"].includes(args[0] ?? "")) return "allowed";
+    if (["assign", "escalate"].includes(args[0] ?? "")) return "conductor";
+    return "console";
+  }
+  if (command === "route") return args[0] === "explain" ? "allowed" : "console";
+  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", "--help", "version", "--version", "say", "status", "board", "report", "turns", "review", "remember", "facts", "check-path"].includes(command)) return "allowed";
+  return "console";
+}
+
+/** 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", "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", "setup", "start", "stop", "remove"].includes(sub)) return `${command} ${sub}`;
+  }
+  return (/^[a-z][a-z0-9-]*$/.test(command) && !/\s/.test(command)) || ["--help", "--version"].includes(command) ? command : "unknown";
+}
+
+export function peerCommandRefusal(peer: string, command: string): string {
+  return `${peer} cannot run ahub ${command}; the person runs it in ahub console or a terminal`;
+}

package/src/cli/launch.ts

@@ -1,8 +1,16 @@
 // Launchers inject only the flags the hub owns and refuse user-supplied duplicates.
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { peerChildEnv } from "../hub/child-process.ts";
 export const CLAUDE_CHANNEL = "plugin:agent-hub@agent-hub";
 
+/** Launch identity belongs to the native child, never to the agent that invoked the wrapper. */
+export function nativeLaunchEnv(tool: "claude" | "codex" | "pi", source: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const env = peerChildEnv(tool, source);
+  delete env.AGENTHUB_UNATTENDED;
+  return env;
+}
+
 /** A scoped candidate MCP server can be selected without promoting the installed plugin. */
 function claudeChannel(userArgs: string[]): string {
   const bundle = resolve(import.meta.dir, "../../plugins/agent-hub/server.js");
@@ -57,13 +65,16 @@ export interface FactsHook {
   stateDir: string;
   /** The same hook transport can observe native turns without injecting facts. */
   purpose?: "facts" | "idle" | "facts-and-idle";
+  /** 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 } }, paths: Pick<FactsHook, "script" | "stateDir">): FactsHook | undefined {
+export function claudeObservationHooks(config: { coordination?: string; task_sweep?: { enabled: boolean }; roles?: Record<string, string[]> }, paths: Pick<FactsHook, "script" | "stateDir">): FactsHook | undefined {
   const facts = config.coordination === "turn-free";
   const idle = config.task_sweep?.enabled === true;
-  return facts || idle ? { ...paths, purpose: facts ? (idle ? "facts-and-idle" : "facts") : "idle" } : undefined;
+  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;
 }
 
 /**
@@ -76,6 +87,7 @@ export function sessionSettings(tee: StatusLineTee, facts?: FactsHook): string {
   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 }] };
+    if (facts.observeNative) Object.assign(settings.hooks as object, { SessionStart: [{ matcher: "*", hooks }], UserPromptSubmit: [{ hooks }] });
   }
   return JSON.stringify(settings);
 }
@@ -101,6 +113,7 @@ export function buildLaunch(
       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",

package/src/cli/main.ts

@@ -1,7 +1,8 @@
 #!/usr/bin/env bun
 import { currentRouting } from "../hub/routing.ts";
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { chmodSync, existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { ControlClient, readControl } from "../hub/control-client.ts";
@@ -11,12 +12,11 @@ import { projectContext, realPath } from "../hub/project.ts";
 import { Registry, type Project } from "../hub/registry.ts";
 import { inspectProject, startProject, stopProject, runProjectDaemon } from "../hub/lifecycle.ts";
 import { openManager, startManager, stopManager } from "../hub/manager.ts";
-import type { BusEvent } from "../hub/bus.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, UNATTENDED_WARNING } from "./launch.ts";
+import { 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,9 +33,14 @@ 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 { formatReport, summarize } from "../hub/report.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 { renderTailEvent } from "./tail-render.ts";
 
 /** `--since 7d|24h|<iso>` for export and report; everything when absent. */
 const since = (): number => {
@@ -56,7 +61,8 @@ const USAGE = `agent-hub ${VERSION}: Claude Code, Codex and Kimi as peers in one
   ahub ui --all --stop           stop only the dashboard manager
   ahub setup [--yes]            install or update the Claude Code channel plugin from this package, then run doctor
   ahub init [--dry-run --json]   preview or write .agenthub/config.json and the AGENTS.md marker block (drops a legacy CLAUDE.md block)
-  ahub up [--unattended]        start the daemon for this directory
+  ahub up [--unattended] [--no-console]  start the daemon; interactive terminals enter console
+  ahub console [--panels] [--color=auto|always|never]  enter the human console, leaving the daemon running on exit
   ahub upgrade --to <version> [--dry-run] [--yes]   review and upgrade running projects
   ahub restart [--dry-run] [--yes]                 recover this project's runtime
   ahub recovery status|resume|abort <operation-id> inspect, resume or cancel a preflight
@@ -91,7 +97,7 @@ const USAGE = `agent-hub ${VERSION}: Claude Code, Codex and Kimi as peers in one
   ahub queue resolve <delivery-id> --action completed|retry|discard --reason <text>
   ahub status | logs [-f] | doctor | kill
   ahub export [--since 7d|<iso>]  structured events (events.jsonl) as JSON lines; never message bodies
-  ahub report [--since 7d|<iso>] [--json]  turns, tokens, messages, overlaps and task events per period
+  ahub report [--since 7d|<iso>] [--by task] [--json]  turns, tokens, messages, overlaps and task events per period
   ahub check-path <file> [--peer <id>]  other owners' open tasks that claim or changed a file
   ahub check-path --hook        the same as a Claude Code PreToolUse hook (templates/claude-hooks.json); never blocks
   ahub facts --hook             turn-free facts as a Claude Code PreToolUse, PostToolUse and Stop hook (issue #108); never blocks
@@ -129,10 +135,21 @@ const projectConfig = () => {
   return config;
 };
 const stateDir = selected.stateDir;
+const identity = detectCliIdentity(process.env);
+const commandLabel = cliCommandLabel(cmd, args);
+const commandAccess = classifyPeerCommand(cmd, args);
+function audit(outcome: "run" | "refused" | "invalid"): void {
+  if (identity.role === "console") return;
+  try { recordCliAudit(stateDir, identity.role === "tools" ? identity.peer : "unknown", commandLabel, outcome); }
+  catch { console.error("ahub: CLI audit could not be recorded (outbox unavailable or full)"); }
+}
+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");
 try { process.chdir(cwd); } catch { fail(`project directory is unavailable: ${cwd}`); }
 const unattendedEnv = process.env.AGENTHUB_UNATTENDED === "1";
 const lifecycle = { inspectProject, startProject, stopProject };
-const connect = () => ControlClient.connect(stateDir, { role: "console", projectRoot: cwd });
+const connect = () => ControlClient.connect(stateDir, identity.role === "tools" ? { role: "tools", peer: identity.peer, projectRoot: cwd } : { role: "console", projectRoot: cwd });
 
 function registeredProject(): Project {
   const registry = new Registry();
@@ -147,14 +164,15 @@ async function healthy(): Promise<boolean> {
   finally { hub?.close(); }
 }
 
-function exec(bin: string, argv: string[]): never {
-  const res = spawnSync(bin, argv, { cwd, stdio: "inherit", env: { ...childEnv(), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } });
+function exec(bin: string, argv: string[], tool?: "claude" | "codex"): never {
+  const env = tool ? nativeLaunchEnv(tool, childEnv()) : childEnv();
+  const res = spawnSync(bin, argv, { cwd, stdio: "inherit", env: { ...env, AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } });
   if (res.error) fail(`cannot run ${bin}: ${res.error.message}`);
   process.exit(res.status ?? 1);
 }
 
 function execWithEnv(bin: string, argv: string[], extra: NodeJS.ProcessEnv): never {
-  const env: NodeJS.ProcessEnv = { ...extra, AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd };
+  const env: NodeJS.ProcessEnv = { ...nativeLaunchEnv("pi", extra), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd };
   delete env.AGENTHUB_RECOVERY_OPERATION;
   delete env.AGENTHUB_UNATTENDED;
   const res = spawnSync(bin, argv, { cwd, stdio: "inherit", env });
@@ -284,26 +302,11 @@ function fail(message: string): never {
   process.exit(1);
 }
 
-function render(e: BusEvent): string {
-  if (e.t === "state") return `  . ${e.peer} is ${e.state}`;
-  if (e.t === "undeliverable") return `  ! gave up delivering ${e.env.id} (from ${e.env.from}) to ${e.peer}`;
-  if (e.t === "envelope" && e.env.from === "hub" && e.env.kind !== "chat") {
-    return `${new Date(e.env.ts).toLocaleTimeString()} hub -> ${e.env.to?.join(",")} [${e.env.kind}${e.env.refs?.task ? ` #${e.env.refs.task}` : ""}]\n${e.env.body.split("\n")[0]!.replace(/^/, "    ")}`;
-  }
-  if (e.t === "overflow") return `  ! ${e.peer}'s queue is full: dropped ${e.env.id} (from ${e.env.from})`;
-  if (e.t === "stale") return `  . dropped ${e.env.id} (from ${e.env.from}) for ${e.peer}: ${e.reason}`;
-  if (e.t === "quiet") return `  . ${e.env.id} (from ${e.env.from}) not delivered to ${e.peers.join(", ")}: turn-free cohort`;
-  const { env } = e;
-  const note = e.dropped === "hop" ? " [not delivered: hop limit]" : e.dropped === "fyi" ? " [fyi: record only]" : "";
-  const head = `${env.from} -> ${env.to?.join(",") ?? "*"}${env.priority === "important" ? " !" : ""}${note}`;
-  return `${new Date(env.ts).toLocaleTimeString()} ${head}\n${env.body.replace(/^/gm, "    ")}`;
-}
-
 async function taskOp(op: string, a: Record<string, unknown>): Promise<string> {
   const hub = await connect();
   const res = await hub.request({ t: "task", op, args: a });
   hub.close();
-  if (!res.ok) fail(res.error);
+  if (!res.ok) { audit("refused"); fail(res.error); }
   return res.text;
 }
 
@@ -488,11 +491,19 @@ const commands: Record<string, () => Promise<void> | void> = {
     await runProjectDaemon(registeredProject(), unattendedEnv || args.includes("--unattended"));
   },
 
+  console: async () => {
+    if (args.some(arg => arg !== "--panels" && !arg.startsWith("--color=")) || args.filter(arg => arg.startsWith("--color=")).length > 1) fail("usage: ahub console [--panels] [--color=auto|always|never]");
+    const color = resolveColor(args.find(arg => arg.startsWith("--color="))?.slice("--color=".length), { isTTY: !!process.stdin.isTTY && !!process.stdout.isTTY, TERM: process.env.TERM, NO_COLOR: process.env.NO_COLOR });
+    if (color instanceof Error) return fail(color.message);
+    await runConsole({ client: await connect(), cwd, stateDir, panels: args.includes("--panels"), color });
+  },
+
   up: async () => {
     const unattended = unattendedEnv || args.includes("--unattended");
     if (unattended) console.error(UNATTENDED_WARNING);
     const status = await startProject(registeredProject(), { unattended });
     console.log(`ahub up (ws://127.0.0.1:${status.controlPort}), state in ${stateDir}`);
+    if (process.stdin.isTTY && process.stdout.isTTY && !args.includes("--no-console")) await runConsole({ client: await connect(), cwd, stateDir });
   },
 
   claude: async () => {
@@ -504,7 +515,12 @@ const commands: Record<string, () => Promise<void> | void> = {
     const control = readControl(stateDir);
     if (control?.instanceId) {
       process.env.AGENTHUB_INSTANCE_ID = control.instanceId;
-      await recordTerminalLaunch("claude", cwd, stateDir, 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.
@@ -520,7 +536,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     const facts = claudeObservationHooks(projectConfig(), { script: join(import.meta.dir, "facts-hook.ts"), stateDir });
     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);
+    exec(launch.cmd, launch.args, "claude");
   },
 
   codex: async () => {
@@ -538,7 +554,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (control?.instanceId) await recordTerminalLaunch("codex", cwd, stateDir, control.instanceId);
     const launch = buildLaunch("codex", args, { unattended: unattendedEnv, proxyUrl: res.proxyUrl, codexBin: projectConfig().codex_bin });
     if (launch0.warning) console.error(launch0.warning);
-    exec(launch.cmd, launch.args);
+    exec(launch.cmd, launch.args, "codex");
   },
 
   kimi: async () => {
@@ -663,7 +679,7 @@ const commands: Record<string, () => Promise<void> | void> = {
   tail: async () => {
     const hub = await connect();
     hub.onPush = (msg) => {
-      if (msg.t === "event") console.log(render(msg.e));
+      if (msg.t === "event") console.log(renderTailEvent(msg.e));
       else if (msg.t === "context") console.log(`  ${msg.peer}: ${contextLine(msg.reading)}`);
       else if (msg.t === "notice") console.log(`  * ${msg.line}`);
       else if (msg.t === "permission") {
@@ -812,7 +828,14 @@ const commands: Record<string, () => Promise<void> | void> = {
     for (const e of readEvents(join(stateDir, "events.jsonl"), since())) console.log(JSON.stringify(e));
   },
   report: () => {
-    const r = summarize(readEvents(join(stateDir, "events.jsonl"), since()));
+    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());
+    if (by >= 0) {
+      const r = summarizeByTask(events);
+      return console.log(args.includes("--json") ? JSON.stringify(r, null, 2) : formatTaskReport(r).join("\n"));
+    }
+    const r = summarize(events);
     console.log(args.includes("--json") ? JSON.stringify(r, null, 2) : formatReport(r).join("\n"));
   },
   facts: async () => {
@@ -998,9 +1021,29 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 };
 
-const run = commands[cmd] ?? (() => fail(`unknown command "${cmd}"\n\n${USAGE}`));
+async function runConductorCommand(): Promise<void> {
+  let op: string;
+  let input: Record<string, unknown>;
+  if (cmd === "task") {
+    op = args[0] === "assign" ? "hub_task_assign" : "hub_task_escalate";
+    if (!args[1] || (args[0] === "assign" && !args[2]) || args.length !== (args[0] === "assign" ? 3 : 2)) fail("usage: ahub task assign <id> <peer> | escalate <id>");
+    input = { id: Number(args[1]), ...(args[0] === "assign" ? { peer: args[2] } : {}) };
+  } else if (cmd === "pause" || cmd === "resume") {
+    if (args.length !== 1) fail(`usage: ahub ${cmd} <peer>`);
+    op = cmd === "pause" ? "hub_peer_hold" : "hub_peer_release";
+    input = { peer: args[0] };
+  } else {
+    // Native TUIs return a human launch command through the daemon; an agent shell never executes it.
+    if (args.length && !(cmd === "pi" && args.length === 2 && args[0] === "--mode" && ["headless", "tui"].includes(args[1] ?? ""))) fail(`conductor starts accept no launch overrides; use ahub ${cmd}${cmd === "pi" ? " [--mode headless|tui]" : ""}`);
+    op = "hub_peer_start";
+    input = { peer: cmd, ...(cmd === "pi" ? { mode: args[1] ?? "headless" } : {}) };
+  }
+  console.log(await taskOp(op, input));
+}
+const run = identity.role === "tools" && commandAccess === "conductor" ? runConductorCommand : commands[cmd] ?? (() => fail(`unknown command "${cmd}"\n\n${USAGE}`));
 try {
   await run();
 } catch (e) {
+  audit("refused");
   fail((e as Error).message);
 }

package/src/cli/tail-render.ts

@@ -0,0 +1,17 @@
+import type { BusEvent } from "../hub/bus.ts";
+
+export function renderTailEvent(e: BusEvent): string {
+  if (e.t === "state") return `  . ${e.peer} is ${e.state}`;
+  if (e.t === "undeliverable") return `  ! gave up delivering ${e.env.id} (from ${e.env.from}) to ${e.peer}`;
+  if (e.t === "envelope" && e.env.from === "hub" && e.env.kind !== "chat") {
+    return `${new Date(e.env.ts).toLocaleTimeString()} hub -> ${e.env.to?.join(",")} [${e.env.kind}${e.env.refs?.task ? ` #${e.env.refs.task}` : ""}]\n${e.env.body.split("\n")[0]!.replace(/^/, "    ")}`;
+  }
+  if (e.t === "overflow") return `  ! ${e.peer}'s queue is full: dropped ${e.env.id} (from ${e.env.from})`;
+  if (e.t === "stale") return `  . dropped ${e.env.id} (from ${e.env.from}) for ${e.peer}: ${e.reason}`;
+  if (e.t === "quiet") return `  . ${e.env.id} (from ${e.env.from}) not delivered to ${e.peers.join(", ")}: turn-free cohort`;
+  const { env } = e;
+  const note = e.dropped === "hop" ? " [not delivered: hop limit]" : e.dropped === "fyi" ? " [fyi: record only]" : "";
+  const head = `${env.from} -> ${env.to?.join(",") ?? "*"}${env.priority === "important" ? " !" : ""}${note}`;
+  return `${new Date(env.ts).toLocaleTimeString()} ${head}\n${env.body.replace(/^/gm, "    ")}`;
+}
+

package/src/cli/upgrade-runtime.ts

@@ -114,7 +114,7 @@ export async function makeUpgradePlan(kind: "restart" | "upgrade", version: stri
     catch { source = { state: "unavailable", peers: [], blockers: ["source recovery metadata could not be authenticated"] }; }
     if (source.state === "stopped" || source.state === "missing") continue;
     const blockers = [...source.blockers];
-    if (!RECOVERY_SOURCE_PROTOCOLS.includes(source.protocol as (typeof RECOVERY_SOURCE_PROTOCOLS)[number]) || source.state !== "running") blockers.push("manual-bootstrap-required: an authenticated protocol-9, protocol-10, protocol-11, protocol-12, protocol-13 or protocol-14 source is required");
+    if (!RECOVERY_SOURCE_PROTOCOLS.includes(source.protocol as (typeof RECOVERY_SOURCE_PROTOCOLS)[number]) || source.state !== "running") blockers.push("manual-bootstrap-required: an authenticated protocol-9, protocol-10, protocol-11, protocol-12, protocol-13, protocol-14 or protocol-15 source is required");
     if (source.recovery?.operationId && source.recovery.phase !== "released") blockers.push(`existing recovery operation ${source.recovery.operationId} must be resolved first`);
     const sessions: { codex?: string; claude?: string; pi?: SessionRef } = {};
     for (const peer of source.peers) {

package/src/hub/attribution.ts

@@ -0,0 +1,20 @@
+import type { Envelope } from "./envelope.ts";
+
+export type Attribution = "delivery" | "single_open" | "unattributed";
+export interface TaskAttribution { task?: number; attribution: Attribution; pii?: true }
+
+/** Only one distinct positive task id in the original delivery can identify its turn. */
+export function deliveryTask(originals: Envelope[]): number | undefined {
+  const ids = new Set(originals.flatMap(env => {
+    const id = Number(env.refs?.task);
+    return Number.isSafeInteger(id) && id > 0 ? [id] : [];
+  }));
+  return ids.size === 1 ? ids.values().next().value : undefined;
+}
+
+/** Rule order is deliberate: a delivered review belongs to its task, regardless of ownership. */
+export function attribute(delivery: number | undefined, inProgress: number[]): TaskAttribution {
+  if (delivery !== undefined && Number.isSafeInteger(delivery) && delivery > 0) return { task: delivery, attribution: "delivery" };
+  if (inProgress.length === 1) return { task: inProgress[0]!, attribution: "single_open" };
+  return { attribution: "unattributed" };
+}

package/src/hub/board.ts

@@ -18,6 +18,8 @@ export type TaskPlan = Partial<Record<(typeof PLAN_KEYS)[number], string[]>>;
 /** Task outcomes older than this are pruned: demotion (issue #36) reads one week, seven half-lives. */
 export const OUTCOMES_KEPT_MS = 7 * 24 * 3_600_000;
 
+export const TASK_MOVE_REASONS = ["manual", "budget", "offline", "idle", "rejections", "declined", "inference_failed", "delivery_failed"] as const;
+export type TaskMoveReason = (typeof TASK_MOVE_REASONS)[number];
 export interface HistoryEntry {
   at: number;
   by: PeerId;
@@ -27,6 +29,8 @@ export interface HistoryEntry {
   owner?: PeerId | null;
   /** On a hand-over: the new owner's split profile then (#109); absent when it was unknown. */
   profile?: string;
+  /** Structured cause recorded at the operation source, never inferred from note text. */
+  reason?: TaskMoveReason;
   /** Persisted task-idle ladder; never counted as fresh task activity (#186). */
   sweep?: SweepRecord;
 }
@@ -122,14 +126,14 @@ export class Board {
 
   /** The only way a task changes. Validates the move, records who did what, returns the new row. */
   /** A `plan` in the patch replaces the old one whole: a new plan is the owner's current intent, not an addition. */
-  update(id: number, by: PeerId, event: string, patch: Partial<Pick<Task, "state" | "owner" | "reviewer" | "refs" | "plan" | "rejections">>, note?: string, extra: Pick<HistoryEntry, "profile" | "sweep"> = {}): Task {
+  update(id: number, by: PeerId, event: string, patch: Partial<Pick<Task, "state" | "owner" | "reviewer" | "refs" | "plan" | "rejections">>, note?: string, extra: Pick<HistoryEntry, "profile" | "sweep" | "reason"> = {}): Task {
     const task = this.get(id);
     if (!task) throw new Error(`no task #${id}`);
     if (patch.state && patch.state !== task.state && !MOVES[task.state].includes(patch.state)) {
       throw new Error(`task #${id} is ${task.state}: cannot move to ${patch.state}`);
     }
     const next = { ...task, ...patch, refs: { ...task.refs, ...patch.refs } };
-    const history = [...task.history, { at: Date.now(), by, event, ...(note ? { note } : {}), ...("owner" in patch ? { owner: next.owner } : {}), ...(extra.profile ? { profile: extra.profile } : {}), ...(extra.sweep ? { sweep: extra.sweep } : {}) }];
+    const history = [...task.history, { at: Date.now(), by, event, ...(note ? { note } : {}), ...("owner" in patch ? { owner: next.owner } : {}), ...(extra.profile ? { profile: extra.profile } : {}), ...(extra.sweep ? { sweep: extra.sweep } : {}), ...(extra.reason && TASK_MOVE_REASONS.includes(extra.reason) ? { reason: extra.reason } : {}) }];
     this.db
       .query("UPDATE tasks SET state = ?, owner = ?, reviewer = ?, refs = ?, plan = ?, rejections = ?, history = ?, updated = ? WHERE id = ?")
       .run(next.state, next.owner, next.reviewer, JSON.stringify(next.refs), JSON.stringify(next.plan ?? {}), next.rejections, JSON.stringify(history), Date.now(), id);