@staix/agent-hub 0.12.15 → 0.12.17

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,11 +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 } from "./init.ts";
-import { buildLaunch, UNATTENDED_WARNING } from "./launch.ts";
+import { init, planInit } from "./init.ts";
+import { launcherPreview } from "./preview.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";
@@ -29,11 +30,16 @@ import { recordTerminalLaunch } from "./terminal-recovery.ts";
 import { ensureMlx, inspectMlx, stopMlx } from "../models/mlx.ts";
 import { setupOllamaModel } from "./models-setup.ts";
 
-import { backendLine, peerLine, type BackendRow, type PeerRow } from "./status-lines.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 { 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 { renderTailEvent } from "./tail-render.ts";
 
 /** `--since 7d|24h|<iso>` for export and report; everything when absent. */
 const since = (): number => {
@@ -53,15 +59,16 @@ const USAGE = `agent-hub ${VERSION}: Claude Code, Codex and Kimi as peers in one
   ahub ui --all [--no-open]      open the unified project dashboard
   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                     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 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] [--no-console]  start the daemon; interactive terminals enter console
+  ahub console [--panels]      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
-  ahub claude [args...]         launch Claude Code with the hub channel   [--unattended]
-  ahub codex [args...]          start the Codex adapter and attach the TUI [--unattended]
-  ahub kimi [--model <alias>]   start Kimi headless under ACP
-  ahub pi [--mode headless|tui] [--backend auto|dgx|mlx] [--session-id <id>] [--session-file <path>]  start Pi
+  ahub claude [--print-command] [args...]         launch Claude Code with the hub channel   [--unattended]
+  ahub codex [--print-command] [args...]          start the Codex adapter and attach the TUI [--unattended]
+  ahub kimi [--print-command] [--model <alias>]   start Kimi headless under ACP
+  ahub pi [--print-command] [--mode headless|tui] [--backend auto|dgx|mlx] [--session-id <id>] [--session-file <path>]  start Pi
   ahub models setup|status|start|stop  prepare or inspect local Ollama MLX (legacy stop is explicit)
   ahub local [--route <id> | --model <id>]
                                start the hub-native worker on the self-hosted models (routing.toml)
@@ -127,10 +134,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();
@@ -145,14 +163,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 });
@@ -282,26 +301,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;
 }
 
@@ -469,6 +473,10 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   init: () => {
+    if (args.includes("--dry-run")) {
+      const plan = planInit(cwd);
+      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);
     registeredProject();
@@ -482,19 +490,34 @@ const commands: Record<string, () => Promise<void> | void> = {
     await runProjectDaemon(registeredProject(), unattendedEnv || args.includes("--unattended"));
   },
 
+  console: async () => {
+    if (args.some(arg => arg !== "--panels")) fail("usage: ahub console [--panels]");
+    await runConsole({ client: await connect(), cwd, stateDir, panels: args.includes("--panels") });
+  },
+
   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 () => {
+    if (args.includes("--print-command") || args.includes("--dry-run")) {
+      try { return console.log(JSON.stringify(launcherPreview("claude", args, cwd, stateDir, unattendedEnv), null, 2)); }
+      catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }
+    }
     assertLifecycleAvailable();
     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.
@@ -506,14 +529,18 @@ const commands: Record<string, () => Promise<void> | void> = {
         // no such file, or no status line in it
       }
     }
-    // A turn-free project (issue #108) gets the facts hook before and after every tool call, and at Stop.
-    const facts = projectConfig().coordination === "turn-free" ? { script: join(import.meta.dir, "facts-hook.ts"), stateDir } : undefined;
+    // 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 });
     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 () => {
+    if (args.includes("--print-command") || args.includes("--dry-run")) {
+      try { return console.log(JSON.stringify(launcherPreview("codex", args, cwd, stateDir, unattendedEnv), null, 2)); }
+      catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }
+    }
     assertLifecycleAvailable();
     const launch0 = buildLaunch("codex", args, { unattended: unattendedEnv, proxyUrl: "pending" }); // refuse bad flags before starting anything
     const hub = await connect();
@@ -524,10 +551,14 @@ 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 () => {
+    if (args.includes("--print-command") || args.includes("--dry-run")) {
+      try { return console.log(JSON.stringify(launcherPreview("kimi", args, cwd, stateDir, unattendedEnv), null, 2)); }
+      catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }
+    }
     const i = args.indexOf("--model");
     const model = i === -1 ? undefined : args[i + 1] ?? fail("--model needs an alias");
     const hub = await connect();
@@ -538,6 +569,10 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   pi: async () => {
+    if (args.includes("--print-command") || args.includes("--dry-run")) {
+      try { return console.log(JSON.stringify(launcherPreview("pi", args, cwd, stateDir, unattendedEnv), null, 2)); }
+      catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }
+    }
     const options = piFlags();
     const hub = await connect();
     const res = await hub.request({ t: "start", peer: "pi", args: options, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
@@ -641,7 +676,8 @@ 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") {
         const options = msg.options.map((o: any) => `${o.optionId} (${o.name})`).join(", ");
@@ -775,7 +811,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (status.deliveryError) console.log(`  delivery storage: ${status.deliveryError}; dispatch is stopped`);
     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));
+    for (const [id, p] of peers) console.log(peerLine(id, { ...p, context: p.context ?? unknownContext() }));
     const models = (status as any).models?.backends as BackendRow[] | undefined;
     if (models?.length) for (const backend of models) console.log(backendLine(backend));
     if (status.switchyard) console.log(`  switchyard: ${status.switchyard}`);
@@ -975,9 +1011,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/preview.ts

@@ -0,0 +1,80 @@
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { loadConfig } from "../hub/daemon.ts";
+import { childEnv } from "../hub/child-process.ts";
+import { relayModelIds } from "../models/relay.ts";
+import { buildPiLaunch } from "../pi/launch.ts";
+import { buildLaunch, buildKimiLaunch, claudeObservationHooks, type Launch } from "./launch.ts";
+
+const REDACTED = "[redacted]";
+const UNRESOLVED = "[unresolved]";
+/** Arbitrary native arguments can contain secrets even without a credential-looking key. */
+function publicArg(arg: string): string {
+  const flags = new Set(["--settings", "--model", "--mcp-config", "--session-id", "--session-file", "--resume", "--continue", "--print", "--safe", "--new"]);
+  const key = arg.split("=", 1)[0]!;
+  return flags.has(key) ? (arg.includes("=") ? key + "=" + REDACTED : key) : REDACTED;
+}
+function nativeCommand(command: string[], trusted: string[]): string[] {
+  return command.map((value, i) => value === trusted[i] ? value : REDACTED);
+}
+/** Read-only preview. Inputs passed to shared native builders are redacted before serialization. */
+export function launcherPreview(tool: "claude" | "codex" | "kimi" | "pi", raw: string[], cwd: string, stateDir: string, unattended: boolean) {
+  const args = raw.filter(arg => !["--print-command", "--dry-run", "--json"].includes(arg));
+  const config = loadConfig(cwd);
+  const unresolved: { field: string; reason: string }[] = [];
+  let launch: Launch;
+  let envNames = Object.keys(childEnv()).concat(["AGENTHUB_STATE_DIR", "AGENTHUB_PROJECT_DIR"]);
+  const value = (flag: string) => {
+    const at = args.indexOf(flag);
+    if (at < 0) return undefined;
+    const next = args[at + 1];
+    if (!next || next.startsWith("--")) throw new Error("missing option value");
+    return next;
+  };
+  if (tool === "claude") {
+    let original: { command?: string; refreshInterval?: number; padding?: number } | undefined;
+    for (const file of [join(cwd, ".claude/settings.local.json"), join(cwd, ".claude/settings.json"), join(process.env.HOME ?? "", ".claude/settings.json")]) {
+      try { original ??= JSON.parse(readFileSync(file, "utf8")).statusLine; } catch { /* optional */ }
+    }
+    // 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));
+  } 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 });
+    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));
+    unresolved.push({ field: "proxyUrl", reason: "assigned when the native adapter starts; preview does not start it" });
+  } else if (tool === "kimi") {
+    const model = value("--model");
+    launch = buildKimiLaunch(nativeCommand(config.kimi_cmd, ["kimi", "acp"]), model ? REDACTED : undefined);
+    unresolved.push({ field: "sessionId", reason: "ACP session identity is available only after native initialization" });
+  } else {
+    const mode = value("--mode") ?? "headless";
+    const backend = value("--backend") ?? config.pi.backend;
+    if (!["headless", "tui"].includes(mode) || !["auto", "dgx", "mlx"].includes(backend) || (value("--session-id") && value("--session-file"))) throw new Error("invalid Pi options");
+    for (let i = 0; i < args.length; i += 2) if (!["--mode", "--backend", "--model", "--session-id", "--session-file"].includes(args[i]!)) throw new Error("unknown Pi option");
+    const models = relayModelIds({ enableHubAuto: true, mlx: config.mlx.enabled === false ? undefined : config.mlx, mlxAlias: "mlx/fast", allowedDGXmodels: { "dgx/coding": config.pi.dgx_coding, "dgx/fast": config.pi.dgx_fast } });
+    const pi = buildPiLaunch({
+      stateDir, cmd: nativeCommand(config.pi.cmd, ["pi"]), mode: mode as "headless" | "tui", backend: backend as "auto" | "dgx" | "mlx",
+      ...(value("--model") ? { model: REDACTED } : {}),
+      ...(value("--session-id") ? { sessionId: REDACTED } : {}),
+      ...(value("--session-file") ? { sessionFile: REDACTED } : {}),
+      relay: { url: UNRESOLVED, token: UNRESOLVED, models: models.map(id => ({ id })) },
+      tools: [], preamble: REDACTED, maxSteps: config.pi.max_steps,
+    }, {}, resolve(join(import.meta.dir, "../pi/extension.ts")), UNRESOLVED, UNRESOLVED);
+    launch = pi;
+    envNames = Object.keys(pi.env).concat(["PATH", "HOME", "USER", "SHELL", "TMPDIR", "TERM", "TERM_PROGRAM", "LANG", "LC_ALL", "LC_CTYPE", "NO_COLOR", "CODEX_HOME"].filter(key => process.env[key] !== undefined));
+    if (mode === "tui") envNames.push("AGENTHUB_STATE_DIR", "AGENTHUB_PROJECT_DIR");
+    unresolved.push({ field: "bridge/relay endpoints and owner credentials", reason: "assigned at runtime; preview does not bind a server or start a model" });
+    if (!value("--session-id") && !value("--session-file")) unresolved.push({ field: "sessionId", reason: "new native session identity is not allocated by preview" });
+  }
+  if (tool === "claude" || tool === "codex") {
+    envNames.push("AGENTHUB_INSTANCE_ID", "AGENTHUB_LAUNCH_ID");
+    unresolved.push({ field: "env.AGENTHUB_INSTANCE_ID", reason: tool === "claude" ? "injected when an existing daemon instance is read at launch; preview does not read runtime state" : "injected when a verified Orca terminal launch is recorded against the daemon; preview does not record it" });
+    unresolved.push({ field: "env.AGENTHUB_LAUNCH_ID", reason: "allocated only for a verified Orca terminal launch; preview does not query Orca, allocate identity or write launch records" });
+  }
+  return { tool, cmd: launch.cmd, args: launch.args, settings: tool === "claude" && launch.args.includes("--settings") ? launch.args[launch.args.indexOf("--settings") + 1] : undefined, envNames: [...new Set(envNames)].sort(), ...(launch.warning ? { warning: launch.warning } : {}), unresolved, redaction: "Arbitrary user arguments, settings, commands and configured executable overrides are redacted. Environment values are never displayed.", needs: ["Native executable, accounts and runtime readiness are not checked."] };
+}

package/src/cli/status-lines.ts

@@ -1,6 +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 { state?: string; queued?: number; queuedImportant?: number; needsReview?: number; heldBy?: string; holdNote?: string; liveAccepted?: string[]; oldestQueuedAt?: number; attached?: boolean; paused?: string; servedBy?: string; requestedModel?: string }
+export interface PeerRow { context?: ContextView; state?: string; queued?: number; queuedImportant?: number; needsReview?: number; heldBy?: string; holdNote?: string; liveAccepted?: string[]; oldestQueuedAt?: number; attached?: boolean; paused?: string; servedBy?: string; requestedModel?: string }
 export interface BackendRow { kind?: string; alias?: string; state?: string; active?: number; requestedModel?: string; actualModel?: string; provider?: string }
 
 /** Aliases are already namespaced ("dgx/coding"); only an alias that is not gets its kind in front of it. */
@@ -10,6 +11,10 @@ export function backendLabel(backend: BackendRow): string {
   return alias.startsWith(`${kind}/`) ? alias : `${kind}/${alias}`;
 }
 
+export function contextLine(reading: ContextView): string {
+  return `context ${reading.used === null ? "unknown" : `${Math.round(reading.used * 100)}%`} (${reading.freshness}${reading.source ? `, ${reading.source}` : ""}${reading.measuredAt !== null ? `, measured ${new Date(reading.measuredAt).toISOString()}` : ""})`;
+}
+
 export function peerLine(id: string, p: PeerRow): string {
   return `  ${id.padEnd(8)} ${(p.state ?? "unknown").padEnd(8)} queued ${p.queued ?? 0}` +
     // Which queued messages the peer will not wait out the batch window for (issue #41).
@@ -23,7 +28,8 @@ export function peerLine(id: string, p: PeerRow): string {
     (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
     // meant reading status.json by hand.
-    (p.requestedModel ? `  model: ${p.requestedModel}` : "");
+    (p.requestedModel ? `  model: ${p.requestedModel}` : "") +
+    (p.context ? `  ${contextLine(p.context)}` : "");
 }
 
 export function backendLine(backend: BackendRow): string {

package/src/cli/statusline-tee.ts

@@ -22,6 +22,20 @@ try {
     renameSync(`${file}.tmp`, file);
   }
   const sessionId = typeof parsed.session_id === "string" ? parsed.session_id : typeof parsed.sessionId === "string" ? parsed.sessionId : "";
+  if (sessionId && dir) {
+    // Bind context to the launcher, daemon and native session. Persist no prompts or transcript text.
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, "claude-context.json");
+    const c = parsed.context_window;
+    const current = c?.current_usage;
+    const numeric = (v: unknown) => typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : null;
+    const record = current !== null && typeof current === "object" && !Array.isArray(current);
+    const context = { context_window_size: numeric(c?.context_window_size), used_percentage: numeric(c?.used_percentage),
+      current_usage: !record ? null : { input_tokens: numeric(current.input_tokens), cache_creation_input_tokens: numeric(current.cache_creation_input_tokens), cache_read_input_tokens: numeric(current.cache_read_input_tokens) } };
+    writeFileSync(`${file}.tmp`, JSON.stringify({ at: Date.now(), sessionId, instanceId: process.env.AGENTHUB_INSTANCE_ID, launchId: process.env.AGENTHUB_LAUNCH_ID, context }), { mode: 0o600 });
+    chmodSync(`${file}.tmp`, 0o600);
+    renameSync(`${file}.tmp`, file);
+  }
   if (sessionId && dir) {
     mkdirSync(dir, { recursive: true });
     const file = join(dir, "claude-session.json");

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 or protocol-13 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/board.ts

@@ -1,5 +1,6 @@
 import { Database } from "bun:sqlite";
 import type { PeerId } from "./envelope.ts";
+import type { SweepRecord } from "./task-sweep.ts";
 
 export const CLASSES = ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"] as const;
 export type TaskClass = (typeof CLASSES)[number];
@@ -17,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;
@@ -26,6 +29,10 @@ 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;
 }
 export interface Task {
   id: number;
@@ -119,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"> = {}): 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 } : {}) }];
+    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);