@staix/agent-hub 0.12.14 → 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.14",
+  "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.14",
+  "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.14",
+  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";
@@ -7,6 +8,8 @@ import { BasePeer } from "../hub/peers.ts";
 import { stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 import { processSignature } from "../pi/process-signature.ts";
 import { realPath } from "../hub/project.ts";
+import { toolResultFailed } from "../local/tools.ts";
+import { piToolStepCeiling, type PiToolStepCeiling } from "../pi/ceiling.ts";
 import type { ExecutionBudgetDecision, ExecutionUnit } from "../hub/execution-budget.ts";
 
 export interface PiModelDescriptor { id: string; name?: string; contextWindow?: number; maxTokens?: number; reasoning?: boolean; }
@@ -22,7 +25,8 @@ export interface PiOptions {
   admitBudget?: (envs: Envelope[], unit: ExecutionUnit) => Promise<ExecutionBudgetDecision[]>;
   /** Reported message usage as increments, before agent_settled releases the turn. */
   onTokens?: (added: number) => void;
-  onTurnFailure?: (envs: Envelope[], reason: string) => Promise<void>;
+  /** `ceiling` is the validated, session/turn-bound tool-step ceiling signal (#179), present only when the trusted extension emitted one for this turn. */
+  onTurnFailure?: (envs: Envelope[], reason: string, ceiling?: PiToolStepCeiling) => Promise<void>;
   watchdogMs?: number; log?: (line: string) => void;
   /** How long stop() waits for a graceful TUI owner exit before verified teardown. Tests shrink this. */
   stopGraceMs?: number;
@@ -32,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;
@@ -58,6 +54,7 @@ export class PiPeer extends BasePeer {
   private executionBudgetTimer?: ReturnType<typeof setTimeout>;
   private executionAbort?: AbortController;
   private readonly budgetStops = new Map<number, string>();
+  private readonly ceilingStops = new Map<number, PiToolStepCeiling>();
   private readonly idleBashReservations = new Map<string, { generation: number; expiresAt: number; deadlineAt?: number }>();
   private budgetGeneration = 0;
   private modelStep = 0;
@@ -185,8 +182,11 @@ export class PiPeer extends BasePeer {
     this.activeTools++;
     if (this.state === "idle") this.setState("busy");
     if (this.state === "busy") this.touch();
-    try { return Response.json({ text: await this.opts.executeTool(String(body.name), body.args, String(body.toolCallId ?? ""), this.sessionId, executionSignal) }); }
-    catch (error) { return Response.json({ text: `error: ${(error as Error).message}` }, { status: 200 }); }
+    // `failed` is the managed-tool failure verdict (toolResultFailed, the one contract): Pi 1.0.1
+    // classifies a native tool result by isError === true alone, so the extension needs the flag,
+    // not just the text (#181). An older extension simply ignores the extra field.
+    try { const text = await this.opts.executeTool(String(body.name), body.args, String(body.toolCallId ?? ""), this.sessionId, executionSignal); return Response.json({ text, failed: toolResultFailed(String(body.name), text) }); }
+    catch (error) { return Response.json({ text: `error: ${(error as Error).message}`, failed: true }, { status: 200 }); }
     finally {
       clearTimeout(idleBashTimer);
       this.activeTools--;
@@ -267,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()}`));
@@ -426,7 +423,17 @@ export class PiPeer extends BasePeer {
       const generation = Number.isSafeInteger(event.generation) ? event.generation : this.budgetGeneration + 1;
       if (generation <= this.budgetGeneration) return;
       this.modelStep = 0;
-      this.usageSeen.clear(); this.idleBashReservations.clear(); this.executionAbort = new AbortController(); this.budgetGeneration = generation; this.noteActivity(); this.agentRunning = true; this.setState("busy");
+      this.usageSeen.clear(); this.idleBashReservations.clear(); this.ceilingStops.clear(); this.executionAbort = new AbortController(); this.budgetGeneration = generation; this.noteActivity(); this.agentRunning = true; this.setState("busy");
+    }
+    // #179: the extension's tool-step ceiling signal. Only a schema-valid event bound to THIS session,
+    // THIS turn generation and a running turn is stored; the first signal of a turn stands. Anything
+    // else (stale, cross-session, free text) is dropped and the failure stays unclassified.
+    if (event.type === "ceiling") {
+      const ceiling = piToolStepCeiling(event);
+      if (ceiling && ceiling.sessionId === this.sessionId && ceiling.generation === this.budgetGeneration && this.agentRunning && this.state === "busy" && !this.ceilingStops.has(ceiling.generation)) {
+        this.ceilingStops.set(ceiling.generation, ceiling);
+        for (const old of this.ceilingStops.keys()) if (old < ceiling.generation - 8) this.ceilingStops.delete(old);
+      }
     }
     if (event.type === "activity" && this.state === "busy") this.touch();
     if (event.type === "tokens" && this.state === "busy" && typeof event.id === "string" && event.id.length <= 100 && Number.isSafeInteger(event.tokens) && event.tokens >= 0 && !this.usageSeen.has(event.id)) {
@@ -451,14 +458,16 @@ export class PiPeer extends BasePeer {
       if (typeof event.text === "string" && event.text.trim()) this.settledText = event.text;
       const generation = Number.isSafeInteger(event.generation) ? event.generation : this.budgetGeneration;
       const text = this.settledText.trim(); const error = this.budgetStops.get(generation) ?? this.settledError; const cancelled = !error && this.settledCancelled;
+      const ceiling = this.ceilingStops.get(generation);
       this.budgetStops.delete(generation);
+      this.ceilingStops.delete(generation);
       this.settledText = ""; this.settledError = ""; this.settledCancelled = false;
       // Answer the peers this turn was for, not every peer on the bus (issue #29). activeEnvs still holds the
       // whole delivery here, steered additions included.
       const reply = { inReplyTo: this.currentReply, to: replyAudience(this.activeEnvs) };
       if (cancelled) this.onMessage?.("Pi turn cancelled; inspect any partial effects before continuing.", reply);
       else if (error?.startsWith("execution budget")) this.onMessage?.(`Pi stopped at the execution budget: ${error}. Inspect partial work before continuing.`, reply);
-      else if (error) void this.opts.onTurnFailure?.(this.activeEnvs, error);
+      else if (error) void this.opts.onTurnFailure?.(this.activeEnvs, error, ceiling);
       else if (text) this.onMessage?.(text, reply);
       for (const id of this.activeDeliveryIds) this.delivery({ id, state: error || cancelled ? "needs_review" : "completed", ...(error || cancelled ? { reason: error || "Pi turn cancelled; partial effects are possible" } : {}) });
       this.activeDeliveryIds.clear();

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}`);