@staix/agent-hub 0.12.15 → 0.12.16

package/docs/verified.json

@@ -0,0 +1,159 @@
+{
+  "schemaVersion": 1,
+  "documents": {
+    "README.md": {
+      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "paths": [
+        "package.json",
+        "src/",
+        "templates/",
+        "plugins/agent-hub/.claude-plugin/plugin.json"
+      ]
+    },
+    "docs/security.md": {
+      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "paths": [
+        "src/",
+        "templates/"
+      ]
+    },
+    "docs/operations.md": {
+      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "paths": [
+        "package.json",
+        "src/",
+        "templates/",
+        "scripts/overlaps.ts",
+        "scripts/check-docs.mjs",
+        "scripts/seeded-check.ts",
+        "scripts/seeds.json",
+        ".github/workflows/check.yml",
+        "scripts/ci-gates.mjs",
+        "scripts/ci-reuse.mjs",
+        ".github/workflows/release.yml"
+      ]
+    },
+    "docs/quickstart.md": {
+      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "paths": [
+        "package.json",
+        "src/",
+        "templates/"
+      ]
+    },
+    "docs/agent-notes/adapters.md": {
+      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "paths": [
+        "src/adapters/",
+        "src/pi/",
+        "src/hub/peers.ts",
+        "src/hub/child-process.ts",
+        "src/hub/lifecycle.ts",
+        "src/memory/capture.ts",
+        "scripts/benchmarks/teardown.ts",
+        "src/hub/daemon.ts"
+      ]
+    },
+    "docs/agent-notes/benchmarks.md": {
+      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "paths": [
+        "scripts/benchmarks/",
+        "test/benchmarks/",
+        "src/pi/",
+        "src/adapters/acp.ts",
+        "src/adapters/pi.ts",
+        "src/models/relay.ts",
+        "src/local/"
+      ]
+    },
+    "docs/agent-notes/budget.md": {
+      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "paths": [
+        "src/hub/budget.ts",
+        "src/cli/statusline-tee.ts",
+        "src/hub/bus.ts",
+        "src/hub/delivery-journal.ts",
+        "src/hub/restart.ts",
+        "src/hub/context-window.ts",
+        "src/hub/daemon.ts"
+      ]
+    },
+    "docs/agent-notes/bus.md": {
+      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "paths": [
+        "src/hub/bus.ts",
+        "src/hub/envelope.ts",
+        "src/hub/limits.ts",
+        "src/hub/delivery-journal.ts",
+        "src/hub/inference.ts",
+        "src/hub/daemon.ts"
+      ]
+    },
+    "docs/agent-notes/daemon.md": {
+      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "paths": [
+        "src/hub/daemon.ts",
+        "src/hub/control-client.ts",
+        "src/adapters/claude-channel.ts",
+        "src/hub/restart.ts",
+        "src/hub/recovery-store.ts",
+        "src/hub/snapshots.ts",
+        "src/hub/manager.ts",
+        "src/hub/lifecycle.ts",
+        "src/hub/crash.ts",
+        "src/cli/setup.ts",
+        "src/cli/upgrade*.ts",
+        "src/cli/terminal-recovery.ts",
+        "src/cli/recovery-package.ts",
+        "src/cli/facts-hook.ts",
+        "src/pi/process-signature.ts",
+        "src/hub/context-window.ts"
+      ]
+    },
+    "docs/agent-notes/local-worker.md": {
+      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "paths": [
+        "src/adapters/local-worker.ts",
+        "src/local/",
+        "src/memory/capture.ts",
+        "src/hub/facts.ts"
+      ]
+    },
+    "docs/agent-notes/models.md": {
+      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "paths": [
+        "src/models/",
+        "src/hub/inference.ts",
+        "src/omniroute/",
+        "src/switchyard/"
+      ]
+    },
+    "docs/agent-notes/tasks.md": {
+      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "paths": [
+        "src/hub/tasks.ts",
+        "src/hub/board.ts",
+        "src/hub/routing.ts",
+        "src/hub/hub-tools.ts",
+        "src/hub/task-sweep.ts",
+        "src/cli/launch.ts",
+        "src/cli/main.ts",
+        "src/cli/preview.ts"
+      ]
+    },
+    "docs/agent-notes/tests.md": {
+      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "paths": [
+        "test/",
+        "scripts/check.sh",
+        "scripts/hang-watch.sh",
+        "scripts/seeded-check.ts",
+        "scripts/seeds.json",
+        "scripts/ci-gates.mjs",
+        "scripts/ci-reuse.mjs",
+        ".github/workflows/check.yml",
+        ".github/workflows/release.yml"
+      ]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-hub",
-  "version": "0.12.15",
+  "version": "0.12.16",
   "description": "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   "license": "MIT",
   "type": "module",

package/plugins/agent-hub/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-hub",
-  "version": "0.12.15",
+  "version": "0.12.16",
   "description": "Channel between Claude Code and the agent-hub daemon: peer messages from Codex, Kimi and the local worker arrive as channel events; hub_send replies.",
   "author": {
     "name": "Young Joon Lee",

package/plugins/agent-hub/server.js

@@ -15291,8 +15291,8 @@ function projectContext(cwd, env = process.env) {
 function stateDirFor(cwd) {
   return projectContext(cwd).stateDir;
 }
-var PROTOCOL = 13;
-var RECOVERY_SOURCE_PROTOCOLS = [9, 10, 11, 12, PROTOCOL];
+var PROTOCOL = 14;
+var RECOVERY_SOURCE_PROTOCOLS = [9, 10, 11, 12, 13, PROTOCOL];
 function readControl(stateDir) {
   try {
     const status = JSON.parse(readFileSync2(join2(stateDir, "status.json"), "utf8"));
@@ -15403,7 +15403,7 @@ class ControlClient {
 // package.json
 var package_default = {
   name: "@staix/agent-hub",
-  version: "0.12.15",
+  version: "0.12.16",
   description: "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   license: "MIT",
   type: "module",
@@ -15499,7 +15499,7 @@ var TASK_TOOLS = [
   tool("hub_task_done", "Mark your task finished. It goes to its reviewer with your summary and refs. When the project configures a check for its class, the hub runs it first and the result comes as a task message: a failed check keeps the task with you.", { id, summary: { type: "string", description: "what changed, why, and the check you ran with its result" }, refs }, ["id", "summary"]),
   tool("hub_task_list", "The task board. PII tasks show as [pii].", { state: { type: "string", enum: ["proposed", "in_progress", "in_review", "approved", "changes_requested"] }, ready: { type: "boolean", description: "only proposed tasks with nothing left to wait for" } }),
   tool("hub_review", "Give your verdict on a task you were asked to review: map the changed signatures and call sites to the task's plan or detail, read the check result, and list what is unmet. Two changes_requested in a row move the task to another peer.", { id, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str, unmet: { type: "array", items: str, description: "each requirement of the plan or detail that the change does not meet" } }, ["id", "verdict"]),
-  tool("hub_checkpoint", "Answer a checkpoint request from the hub (your quota window is nearly used up): what you were doing, what is half done, what whoever continues must know. Write the same to .agenthub/checkpoint.md first if you can.", { summary: str }, ["summary"]),
+  tool("hub_checkpoint", "Answer a checkpoint request from the hub (quota or context window pressure): what you were doing, what is half done, what whoever continues must know. Write the same to .agenthub/checkpoint.md first if you can.", { summary: str, request_id: { type: "string", description: "The request id supplied by a context checkpoint request; required for context checkpoints" } }, ["summary"]),
   tool("hub_remember", "Save a decision, finding, contract or fail to the memory all agents share (claude-mem); the other agents also get it with their next message. A fail is an approach you tried that does not work, and why: the most useful note, it stops the others spending their quota on it. Do not retry what a fail note rules out without new evidence. Conclusions worth recalling, not chatter.", { text: str, title: str, kind: { type: "string", enum: [...NOTE_KINDS] }, task: id }, ["text"])
 ];
 var TASK_TOOL_NAMES = new Set(TASK_TOOLS.map((t) => t.name));

package/src/adapters/codex-appserver.ts

@@ -2,6 +2,7 @@ import { spawn, type ChildProcess } from "node:child_process";
 import type { Server, ServerWebSocket } from "bun";
 import { renderDigest, replyAudience, replyParent, type Envelope, type PeerId } from "../hub/envelope.ts";
 import { BasePeer } from "../hub/peers.ts";
+import { codexContext, type ContextReading } from "../hub/context-window.ts";
 import { childEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 
 export interface CodexOptions {
@@ -20,6 +21,7 @@ export interface CodexOptions {
   onUsage?: (rateLimits: unknown, hard: boolean) => void;
   /** Tokens the thread used since the previous update (see `tokenTotal` for how they are counted). */
   onTokens?: (added: number) => void;
+  onContext?: (reading: ContextReading) => void;
   /** The native id of each turn as it starts, after the peer turned busy (issue #33: `ahub undo --context`). */
   onTurn?: (turnId: string) => void;
   /**
@@ -62,6 +64,8 @@ export class CodexPeer extends BasePeer {
   /** Claimed as soon as a TUI WebSocket opens, before it can start a thread. */
   private claimedTui: Link | undefined;
   private threadId = "";
+  private contextEpoch = 0;
+  get sessionGeneration(): number { return this.contextEpoch; }
   /**
    * The thread's running token total at the last update, and whether the thread started here. Codex 0.156.1 also
    * sends `thread/tokenUsage/updated` for compaction (an estimate in `last`, `total` unchanged), a usage-limit refresh
@@ -344,6 +348,7 @@ export class CodexPeer extends BasePeer {
     clearInterval(this.usageTimer);
     this.link = undefined;
     this.threadId = "";
+    this.contextEpoch++;
     this.activeTurns.clear();
     for (const p of this.pending.values()) {
       if (p.deliveryId) this.delivery({ id: p.deliveryId, state: "needs_review", reason: "Codex TUI detached" });
@@ -396,6 +401,7 @@ export class CodexPeer extends BasePeer {
     this.freshThread = fresh;
     this.link = link;
     this.threadId = threadId;
+    this.contextEpoch++;
     this.activeTurns.clear();
     this.forgetTurn();
     this.opts.log?.(`[${this.id}] thread ${threadId}`);
@@ -440,6 +446,7 @@ export class CodexPeer extends BasePeer {
     }
     if (link !== this.link || params.threadId !== this.threadId) return;
     if (method === "thread/tokenUsage/updated") {
+      this.opts.onContext?.(codexContext(params.tokenUsage, this.threadId, Date.now()));
       const total = Number(params.tokenUsage?.total?.totalTokens);
       if (!Number.isFinite(total)) return;
       const added = this.tokenTotal === undefined ? (this.freshThread ? total : 0) : Math.max(0, total - this.tokenTotal);

package/src/adapters/pi.ts

@@ -1,3 +1,4 @@
+import { buildPiLaunch } from "../pi/launch.ts";
 import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join, resolve, relative } from "node:path";
@@ -35,14 +36,6 @@ type RpcMessage = { type?: string; id?: string | number; command?: string; succe
 type VerifiedEmptyResume = { sessionId: string };
 function ownerStillAlive(pid: number, signature: string | undefined): boolean { const current = processSignature(pid); if (current !== undefined) return current === signature; try { process.kill(pid, 0); return true; } catch { return false; } }
 
-const modelFor = (backend: PiOptions["backend"], models: PiModelDescriptor[]): string => {
-  const ids = models.map((m) => m.id);
-  const find = (needle: string) => ids.find((id) => id === needle) ?? needle;
-  if (backend === "mlx") return find("mlx/fast");
-  if (backend === "dgx") return find("dgx/coding");
-  if (ids.includes("hub/auto")) return "hub/auto";
-  return find(ids.find((id) => id === "dgx/coding") ? "dgx/coding" : ids.find((id) => id === "mlx/fast") ?? "dgx/coding");
-};
 
 export class PiPeer extends BasePeer {
   readonly hubNative = true;
@@ -274,14 +267,11 @@ export class PiPeer extends BasePeer {
     const extension = resolve(join(import.meta.dir, "../pi/extension.ts"));
     const inherited: NodeJS.ProcessEnv = {};
     for (const key of ["PATH", "HOME", "USER", "SHELL", "TMPDIR", "TERM", "TERM_PROGRAM", "LANG", "LC_ALL", "LC_CTYPE", "NO_COLOR", "CODEX_HOME"]) if (process.env[key]) inherited[key] = process.env[key];
-    const env: NodeJS.ProcessEnv = { ...inherited, PI_CODING_AGENT_DIR: join(this.opts.stateDir, "pi"), AGENTHUB_PI_BRIDGE_URL: `http://127.0.0.1:${bridge.port}`, AGENTHUB_PI_BRIDGE_TOKEN: token, AGENTHUB_PI_OWNER_TOKEN: token, AGENTHUB_PI_RELAY_URL: this.opts.relay.url, AGENTHUB_PI_RELAY_TOKEN: this.opts.relay.token, AGENTHUB_PI_MODELS: JSON.stringify(this.opts.relay.models), AGENTHUB_PI_TOOLS: JSON.stringify(this.opts.tools), AGENTHUB_PI_MAX_STEPS: String(this.opts.maxSteps ?? 30) };
-    const args = [ ...(this.opts.mode === "headless" ? ["--mode", "rpc"] : []), "--provider", "agent-hub-local", "--model", this.opts.model ?? modelFor(this.opts.backend, this.opts.relay.models), "--models", this.opts.relay.models.map((model) => `agent-hub-local/${model.id}`).join(","), "--no-builtin-tools", "--no-skills", "--no-prompt-templates", "--no-extensions", "--extension", extension, ...(this.opts.preamble ? ["--append-system-prompt", this.opts.preamble] : []), "--session-dir", join(this.opts.stateDir, "pi-sessions")];
-    if (this.opts.sessionFile) args.push("--session", this.opts.sessionFile); else if (this.opts.sessionId) args.push("--session-id", this.opts.sessionId);
-    const command = this.opts.cmd ?? ["pi"];
-    this._tuiLaunch = { cmd: command[0]!, args: [...command.slice(1), ...args], env };
+    this._tuiLaunch = buildPiLaunch(this.opts, inherited, extension, bridge.port!, token);
+    const { cmd: bin, args, env } = this._tuiLaunch;
     if (this.opts.mode === "tui") { return; }
     // Its own process group, stopped as a whole (#115, as Codex's in #113).
-    this.proc = spawn(command[0]!, [...command.slice(1), ...args], { cwd: this.opts.cwd, env, stdio: ["pipe", "pipe", "pipe"], detached: true });
+    this.proc = spawn(bin, args, { cwd: this.opts.cwd, env, stdio: ["pipe", "pipe", "pipe"], detached: true });
     trackGroup(this.proc);
     this.proc.stdout.on("data", (chunk) => this.onOutput(String(chunk)));
     this.proc.stderr.on("data", (chunk) => this.opts.log?.(`[${this.id}] ${String(chunk).trimEnd()}`));

package/src/cli/init.ts

@@ -23,47 +23,57 @@ export function removeBlock(existing: string): string {
   return rest && `${rest}\n`;
 }
 
-/** Returns the paths it changed. */
-export function init(cwd: string): string[] {
-  const changed: string[] = [];
-  const write = (path: string, next: string) => {
-    if (existsSync(path) && readFileSync(path, "utf8") === next) return;
-    writeFileSync(path, next);
-    changed.push(path);
+export interface InitChange {
+  action: "create" | "modify" | "delete";
+  path: string;
+  reason: string;
+  managedBlock?: "insert" | "replace" | "remove";
+}
+/** Content is internal to apply, never included in a public preview. */
+interface PlannedWrite extends InitChange { next?: string; }
+function changes(cwd: string): PlannedWrite[] {
+  const changed: PlannedWrite[] = [];
+  const write = (path: string, next: string, reason: string, managedBlock?: InitChange["managedBlock"]) => {
+    const exists = existsSync(path);
+    if (exists && readFileSync(path, "utf8") === next) return;
+    changed.push({ action: exists ? "modify" : "create", path, next, reason, ...(managedBlock ? { managedBlock } : {}) });
   };
-
-  mkdirSync(join(cwd, ".agenthub"), { recursive: true });
-  const config = join(cwd, ".agenthub", "config.json");
-  if (!existsSync(config)) write(config, readFileSync(join(TEMPLATES, "config.json"), "utf8"));
-
-  const routing = join(cwd, ".agenthub", "routing.toml");
-  if (!existsSync(routing)) write(routing, readFileSync(join(TEMPLATES, "routing.toml"), "utf8"));
-
+  for (const name of ["config.json", "routing.toml"]) {
+    const path = join(cwd, ".agenthub", name);
+    if (!existsSync(path)) write(path, readFileSync(join(TEMPLATES, name), "utf8"), "create missing project defaults");
+  }
   const agents = join(cwd, "AGENTS.md");
-  write(agents, upsertBlock(existsSync(agents) ? readFileSync(agents, "utf8") : "", readFileSync(join(TEMPLATES, "AGENTS.block.md"), "utf8")));
-
-  // Any CLAUDE.md, even an empty one, stops Claude Code from loading AGENTS.md: take back the block older versions wrote there.
-  // Only a regular file of its own: a symlink may lead out of the project, and a link to AGENTS.md
-  // (hard, or AGENTS.md -> CLAUDE.md) holds the block just written.
+  const existing = existsSync(agents) ? readFileSync(agents, "utf8") : "";
+  write(agents, upsertBlock(existing, readFileSync(join(TEMPLATES, "AGENTS.block.md"), "utf8")), "refresh hub instructions; preserve surrounding text", existing.includes("<!-- AGENT_HUB:BEGIN") ? "replace" : "insert");
   const claude = join(cwd, "CLAUDE.md");
   const own = lstatSync(claude, { throwIfNoEntry: false });
-  const target = statSync(agents);
-  const legacy = own?.isFile() && !(own.dev === target.dev && own.ino === target.ino) ? readFileSync(claude, "utf8") : "";
+  // The write preserves an existing inode, including AGENTS.md -> CLAUDE.md and hard links.
+  const target = existsSync(agents) ? statSync(agents) : undefined;
+  const legacy = own?.isFile() && !(target && own.dev === target.dev && own.ino === target.ino) ? readFileSync(claude, "utf8") : "";
   const rest = removeBlock(legacy);
   if (rest !== legacy) {
-    if (rest) write(claude, rest);
-    else {
-      unlinkSync(claude);
-      changed.push(claude);
-    }
+    if (rest) write(claude, rest, "remove legacy hub instructions; preserve surrounding text", "remove");
+    else changed.push({ action: "delete", path: claude, reason: "remove legacy-only instructions", managedBlock: "remove" });
   }
-
   const ignore = join(cwd, ".gitignore");
   let lines = existsSync(ignore) ? readFileSync(ignore, "utf8") : "";
-  // The machine's own config: only a file nobody committed may choose commands and credential files (issue #17).
   for (const entry of [".agenthub/state/", ".agenthub/config.local.json"]) {
     if (!lines.split("\n").includes(entry)) lines = `${lines}${lines && !lines.endsWith("\n") ? "\n" : ""}${entry}\n`;
   }
-  write(ignore, lines);
+  write(ignore, lines, "ignore runtime state and machine-local configuration");
   return changed;
 }
+/** Read-only metadata, deliberately omitting project/user file contents. */
+export function planInit(cwd: string): InitChange[] {
+  return changes(cwd).map(({ next, ...change }) => change);
+}
+/** Returns the paths it changed, applying the same plan as the preview. */
+export function init(cwd: string): string[] {
+  const plan = changes(cwd);
+  mkdirSync(join(cwd, ".agenthub"), { recursive: true });
+  for (const change of plan) {
+    if (change.action === "delete") unlinkSync(change.path);
+    else writeFileSync(change.path, change.next!);
+  }
+  return plan.map(change => change.path);
+}

package/src/cli/launch.ts

@@ -55,6 +55,15 @@ export function statusLineSettings(tee: StatusLineTee): string {
 export interface FactsHook {
   script: string;
   stateDir: string;
+  /** The same hook transport can observe native turns without injecting facts. */
+  purpose?: "facts" | "idle" | "facts-and-idle";
+}
+
+/** 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 {
+  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;
 }
 
 /**
@@ -90,7 +99,8 @@ export function buildLaunch(
     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 ? "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" ? "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." : "",
     ].filter(Boolean);
     return {
       cmd: "claude",
@@ -105,3 +115,10 @@ export function buildLaunch(
     ...warning,
   };
 }
+
+
+/** The daemon and preview use exactly the same ACP command insertion. */
+export function buildKimiLaunch(command: string[], model?: string): Launch {
+  const [cmd, ...args] = command;
+  return { cmd: cmd!, args: model ? ["--model", model, ...args] : args };
+}

package/src/cli/main.ts

@@ -14,8 +14,9 @@ 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, 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,7 +30,8 @@ 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";
@@ -53,15 +55,15 @@ 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 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 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)
@@ -469,6 +471,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();
@@ -490,6 +496,10 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   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) {
@@ -506,14 +516,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);
   },
 
   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();
@@ -528,6 +542,10 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   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 +556,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 });
@@ -642,6 +664,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     const hub = await connect();
     hub.onPush = (msg) => {
       if (msg.t === "event") console.log(render(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 +798,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}`);

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."] };
+}