@staix/agent-hub 0.12.15 → 0.12.17

package/src/cli/console.ts

@@ -0,0 +1,201 @@
+import { fileURLToPath } from "node:url";
+import { StringDecoder } from "node:string_decoder";
+import type { ControlClient } from "../hub/control-client.ts";
+import { contextLine } from "./status-lines.ts";
+import { renderTailEvent } from "./tail-render.ts";
+import { initialConsoleState, pruneApprovals, reduceConsole, renderConsole, terminalText, wrap } from "./console-state.ts";
+import type { ConsoleEffect, ConsoleEvent } from "./console-state.ts";
+
+export interface ConsoleTerminal {
+  columns: number; rows: number; isTTY: boolean; isRaw?: boolean;
+  write(text: string): void;
+  raw(enabled: boolean): void;
+  onData(listener: (text: string) => void): () => void;
+  onResize(listener: () => void): () => void;
+  onSignal(listener: () => void): () => void;
+  onError?(listener: (error: Error) => void): () => void;
+}
+export interface ConsoleOptions {
+  client: Pick<ControlClient, "request" | "send" | "close" | "onPush" | "onClose">;
+  cwd: string; stateDir: string; panels?: boolean; columns?: number; rows?: number;
+  terminal?: ConsoleTerminal;
+  /** Injected command runner must use argv, closed stdin, and return a cancellation handle. */
+  runCommand?: (args: string[], output: (text: string) => void, done: () => void) => (() => void);
+  pollMs?: number;
+}
+export const RESTORE_CONSOLE = "\x1b[?1049l\x1b[r\x1b[0m\x1b[?25h";
+function nativeTerminal(): ConsoleTerminal {
+  return {
+    get columns() { return process.stdout.columns ?? 80; }, get rows() { return process.stdout.rows ?? 24; },
+    get isTTY() { return !!process.stdin.isTTY && !!process.stdout.isTTY; }, get isRaw() { return process.stdin.isRaw; },
+    write: text => { process.stdout.write(text); }, raw: enabled => { process.stdin.setRawMode(enabled); },
+    onData: listener => {
+      const decoder = new StringDecoder("utf8"); const onData = (data: Buffer) => listener(decoder.write(data));
+      process.stdin.on("data", onData); process.stdin.resume();
+      return () => { process.stdin.off("data", onData); process.stdin.pause(); };
+    },
+    onResize: listener => { process.stdout.on("resize", listener); return () => { process.stdout.off("resize", listener); }; },
+    onError: listener => {
+      const rejected = (reason: unknown) => listener(reason instanceof Error ? reason : new Error(String(reason)));
+      process.on("uncaughtException", listener); process.on("unhandledRejection", rejected);
+      return () => { process.off("uncaughtException", listener); process.off("unhandledRejection", rejected); };
+    },
+    onSignal: listener => { process.on("SIGINT", listener); process.on("SIGTERM", listener); return () => { process.off("SIGINT", listener); process.off("SIGTERM", listener); }; },
+  };
+}
+/** One terminal client, no daemon ownership. All text crosses terminalText before writing. */
+export async function runConsole(options: ConsoleOptions): Promise<void> {
+  const { client } = options; const terminal = options.terminal ?? nativeTerminal();
+  let state = initialConsoleState(!!options.panels);
+  let columns = options.columns ?? terminal.columns; let rows = options.rows ?? terminal.rows;
+  let active = true; let inAlternate = false; let plain = !terminal.isTTY || columns < 80 || rows < 24;
+  let polling = false; let childRunning = false; let cancelChild: (() => void) | undefined;
+  const priorPush = client.onPush; const priorClose = client.onClose; const priorRaw = !!terminal.isRaw;
+  const removers: (() => void)[] = []; const timers: ReturnType<typeof setInterval>[] = [];
+  let resolveDone: () => void = () => {}; const done = new Promise<void>(resolve => { resolveDone = resolve; });
+  let pendingStream: ConsoleEvent[] = []; let droppedStream = 0;
+  const safeWrite = (text: string) => terminal.write(terminalText(text));
+  const writeStream = (text: string) => {
+    terminal.write(`\x1b[${rows - 3};1H`);
+    for (const line of wrap(text, columns)) { safeWrite(line); terminal.write("\r\n"); }
+  };
+  const stream = (event: ConsoleEvent) => {
+    state.events = [...state.events, { ...event, text: terminalText(event.text) }].slice(-1000);
+    if (plain) safeWrite(event.text + "\n");
+    else if (state.mode === "stream") writeStream(event.text);
+    else { pendingStream.push(event); if (pendingStream.length > 1000) { pendingStream.shift(); droppedStream++; } }
+  };
+  const draw = () => {
+    if (!active || plain) return;
+    if (state.mode === "panels" && !inAlternate) { terminal.write("\x1b[r\x1b[?1049h\x1b[2J"); inAlternate = true; }
+    else if (state.mode === "stream" && inAlternate) {
+      terminal.write(`\x1b[?1049l\x1b[1;${rows - 3}r`); inAlternate = false;
+      if (droppedStream) writeStream(`${droppedStream} older panel-mode events omitted from console memory; inspect hub.log for the full stream.`);
+      for (const event of pendingStream) writeStream(event.text);
+      pendingStream = []; droppedStream = 0;
+    }
+    terminal.write(state.mode === "stream" ? `\x1b[1;${rows - 3}r` : "\x1b[r");
+    const lines = renderConsole(state, columns, rows);
+    const start = state.mode === "stream" ? rows - 2 : 1;
+    for (const [index, line] of lines.entries()) { terminal.write(`\x1b[${start + index};1H\x1b[2K`); safeWrite(line); }
+    terminal.write(`\x1b[${rows};${Math.min(columns, Bun.stringWidth(lines.at(-1) ?? "") + 1)}H\x1b[?25h`);
+  };
+  const stop = (reason?: string) => {
+    if (!active) return;
+    active = false;
+    for (const timer of timers) clearInterval(timer);
+    for (const remove of removers) remove();
+    cancelChild?.(); cancelChild = undefined;
+    client.onPush = priorPush; client.onClose = priorClose;
+    if (terminal.isTTY) {
+      try { terminal.raw(priorRaw); } finally { terminal.write(RESTORE_CONSOLE + "\r\n"); }
+    }
+    client.close();
+    safeWrite(`${reason ? reason + "\n" : ""}Left console; the hub keeps running (ahub kill stops it).\n`);
+    resolveDone();
+  };
+  const refresh = async () => {
+    if (polling || !active) return; polling = true;
+    try {
+      const panels = state.mode === "panels" && !plain;
+      const replies = await Promise.all([
+        client.request({ t: "status" }, 3000), client.request({ t: "budget" }, 3000),
+        ...(panels ? [client.request({ t: "task", op: "hub_task_list", args: {} }, 3000), client.request({ t: "queue", op: "list" }, 3000), client.request({ t: "task", op: "hub_task_list", args: { ready: true } }, 3000)] : []),
+      ]);
+      if (!active) return;
+      const [status, budget, tasks, queue, ready] = replies;
+      if (status.status?.peers) state.peers = status.status.peers;
+      if (budget.budget) state.budget = budget.budget;
+      if (tasks?.ok && state.mode === "panels") { const parsed = JSON.parse(tasks.text); if (Array.isArray(parsed)) {
+          const readyIds = new Set(ready?.ok ? JSON.parse(ready.text).map((task: any) => task.id) : []);
+          state.tasks = parsed.map(task => ({ ...task, ready: readyIds.has(task.id) }));
+        } }
+      if (queue?.ok && state.mode === "panels" && Array.isArray(queue.deliveries)) state.queue = queue.deliveries;
+      const error = replies.find(reply => reply.ok === false)?.error; if (error) state.notice = String(error);
+      draw();
+    } catch (error) { if (active) { state.notice = String((error as Error).message); draw(); } }
+    finally { polling = false; }
+  };
+  const run = options.runCommand ?? ((args, output, finished) => {
+    const child = Bun.spawn([process.execPath, fileURLToPath(new URL("./main.ts", import.meta.url)), "--project", options.cwd, ...args], {
+      cwd: options.cwd, stdin: "ignore", stdout: "pipe", stderr: "pipe",
+    });
+    const read = async (source: ReadableStream<Uint8Array>) => {
+      const decoder = new TextDecoder(); const reader = source.getReader();
+      try { while (true) { const { value, done } = await reader.read(); if (done) break; output(decoder.decode(value, { stream: true })); } const end = decoder.decode(); if (end) output(end); }
+      finally { reader.releaseLock(); }
+    };
+    void Promise.all([read(child.stdout), read(child.stderr), child.exited]).then(([, , code]) => { if (code) output(`command exited ${code}`); }).catch(error => output(String(error.message))).finally(finished);
+    return () => { child.kill(); };
+  });
+  const effect = async (action: ConsoleEffect) => {
+    if (action.type === "exit") return stop();
+    if (action.type === "permit") { client.send({ t: "permit", surface: "console", id: action.id, ...(action.option ? { option: action.option } : {}) }); return; }
+    if (action.type === "show") {
+      const result = await client.request(action.panel === 3 ? { t: "task", op: "task_show", args: { id: action.id } } : { t: "queue", op: "show", id: action.id }, 3000);
+      if (!active) return;
+      state.detailOffset = 0;
+      state.detail = result.ok === false ? String(result.error) : action.panel === 3 ? String(result.text) : JSON.stringify(result.delivery, null, 2);
+      draw(); return;
+    }
+    if (childRunning) { state.notice = "a command is already running"; draw(); return; }
+    childRunning = true;
+    stream({ text: `> ${action.args.join(" ")}`, kind: "command" });
+    try {
+      cancelChild = run(action.args, text => { if (active) { stream({ text, kind: "command" }); draw(); } }, () => { childRunning = false; cancelChild = undefined; if (active) void refresh(); });
+    } catch (error) { childRunning = false; state.notice = String((error as Error).message); draw(); }
+  };
+  const handle = (key: string) => {
+    if (!active) return;
+    const result = reduceConsole(state, key); state = result.state;
+    if (state.mode === "panels" && (plain || columns < 80 || rows < 24)) { state.mode = "stream"; state.notice = "panels need at least 80x24"; }
+    for (const action of result.effects) void effect(action).catch(error => stop(`Console error: ${String(error.message)}`));
+    draw();
+    if (key === "v" && state.detail && state.mode === "stream") { stream({ text: state.detail, kind: "permission" }); state.detail = undefined; draw(); }
+    if (key === "\t") void refresh();
+  };
+  client.onPush = msg => {
+    if (!active) return;
+    try {
+      if (msg.t === "event") stream({ text: renderTailEvent(msg.e), peer: msg.e.peer ?? msg.e.env?.from, kind: msg.e.env?.kind ?? msg.e.t });
+      else if (msg.t === "context") stream({ text: `  ${msg.peer}: ${contextLine(msg.reading)}`, peer: msg.peer, kind: "context" });
+      else if (msg.t === "notice") stream({ text: `  * ${msg.line}`, kind: "notice" });
+      else if (msg.t === "permission") {
+        stream({ text: `  ? ${msg.peer} asks permission: ${String(msg.title).replace(/\n/g, "\n      | ")}\n    answer with: ahub permit ${msg.id} <${msg.options.map((o: any) => `${o.optionId} (${o.name})`).join(", ")}> | deny`, peer: msg.peer, kind: "permission" });
+        if (typeof msg.expiresAt === "number" && msg.expiresAt > Date.now() && !state.approvals.some(a => a.id === msg.id)) state.approvals.push(msg);
+      } else if (msg.t === "permission_closed") {
+        state.approvals = state.approvals.filter(a => a.id !== msg.id); state = pruneApprovals(state, Date.now());
+      }
+      draw();
+    } catch (error) { stop(`Console error: ${String((error as Error).message)}`); }
+  };
+  client.onClose = (_code, reason) => stop(`Hub connection closed${reason ? `: ${reason}` : ""}`);
+  try {
+    if (plain) { state.mode = "stream"; safeWrite("Console panels need a terminal of at least 80x24; showing the plain stream.\n"); }
+    if (terminal.isTTY) {
+      terminal.raw(true);
+      removers.push(terminal.onData(text => {
+        // A pasted chunk can only edit text, never approve, confirm or run commands. Bracketed-paste delimiters are stripped.
+        if (Array.from(text).length > 1 && !["\x1b[A", "\x1b[B", "\x1b[C", "\x1b[D"].includes(text)) {
+          state.confirm = undefined; state.optionChoice = undefined; state.editing = true;
+          state.input += terminalText(text.replace(/\x1b\[20[01]~/g, "")).replace(/\n/g, " "); draw();
+        } else handle(text);
+      }));
+      removers.push(terminal.onResize(() => {
+        columns = terminal.columns; rows = terminal.rows; plain = columns < 80 || rows < 24;
+        if (plain) {
+          if (inAlternate) { terminal.write("\x1b[?1049l"); inAlternate = false; }
+          terminal.write("\x1b[r"); state.mode = "stream"; state.notice = "panels need at least 80x24";
+          safeWrite("\nTerminal below 80x24; showing the plain stream.\n");
+        }
+        draw();
+      }));
+    }
+    removers.push(terminal.onSignal(() => stop()));
+    if (terminal.onError) removers.push(terminal.onError(error => { process.exitCode = 1; stop(`Console error: ${error.message}`); }));
+    timers.push(setInterval(() => { try { state = pruneApprovals(state, Date.now()); draw(); } catch (error) { stop(`Console error: ${String((error as Error).message)}`); } }, 1000));
+    timers.push(setInterval(() => void refresh(), Math.max(2000, options.pollMs ?? 4000)));
+    draw(); client.send({ t: "tail" }); void refresh(); await done;
+  } catch (error) { stop(`Console error: ${String((error as Error).message)}`); }
+  finally { stop(); }
+}

package/src/cli/facts-hook.ts

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

package/src/cli/identity-audit.ts

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

package/src/cli/identity.ts

@@ -0,0 +1,54 @@
+export type CliIdentity =
+  | { role: "console" }
+  | { role: "tools"; peer: string }
+  | { role: "invalid"; reason: string };
+
+/** Honest defaults for native shells, not authentication against an agent that can edit its environment. */
+export function detectCliIdentity(env: Readonly<Record<string, string | undefined>>): CliIdentity {
+  const hub = env.AGENTHUB_PEER_ID;
+  const claude = env.CLAUDECODE;
+  const session = env.CLAUDE_CODE_SESSION_ID;
+  const codex = env.CODEX_THREAD_ID;
+  const invalid = (reason: string): CliIdentity => ({ role: "invalid", reason });
+  if (hub !== undefined && (!/^[a-z][a-z0-9-]{0,31}$/.test(hub) || /\s/.test(hub) || ["user", "hub", "digest"].includes(hub))) return invalid("invalid AGENTHUB_PEER_ID marker");
+  if (claude !== undefined && claude !== "1") return invalid("invalid CLAUDECODE marker");
+  if (session !== undefined && (!session || /\s/.test(session))) return invalid("invalid CLAUDE_CODE_SESSION_ID marker");
+  if (codex !== undefined && (!codex || /\s/.test(codex))) return invalid("invalid CODEX_THREAD_ID marker");
+  if (session !== undefined && claude === undefined) return invalid("CLAUDE_CODE_SESSION_ID without CLAUDECODE marker");
+  if (claude !== undefined && codex !== undefined) return invalid("conflicting native agent markers");
+  const native = claude !== undefined ? "claude" : codex !== undefined ? "codex" : undefined;
+  if (hub !== undefined && native !== undefined && hub !== native) return invalid("AGENTHUB_PEER_ID conflicts with native agent marker");
+  const peer = hub ?? native;
+  return peer === undefined ? { role: "console" } : { role: "tools", peer };
+}
+
+export type PeerCommandAccess = "allowed" | "conductor" | "console";
+
+/** A closed list: unknown commands cannot acquire console authority through an agent shell. */
+export function classifyPeerCommand(command: string, args: readonly string[]): PeerCommandAccess {
+  if (args.some((arg) => arg === "--as-user" || arg.startsWith("--as-user="))) return "console";
+  if (command === "task") {
+    if (["propose", "show"].includes(args[0] ?? "")) return "allowed";
+    if (["assign", "escalate"].includes(args[0] ?? "")) return "conductor";
+    return "console";
+  }
+  if (command === "route") return args[0] === "explain" ? "allowed" : "console";
+  if (command === "budget") return !args.length || args.every((arg) => arg === "--json") ? "allowed" : "console";
+  if (["claude", "codex", "kimi", "pi", "local", "pause", "resume"].includes(command)) return "conductor";
+  if (["help", "--help", "version", "--version", "say", "status", "board", "report", "turns", "review", "remember", "facts", "check-path"].includes(command)) return "allowed";
+  return "console";
+}
+
+/** No argument text is included: notices and refusal logs must not copy task text or credentials. */
+export function cliCommandLabel(command: string, args: readonly string[]): string {
+  if (!["upgrade", "restart", "recovery", "recovery-run", "help", "--help", "--version", "version", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "claude", "codex", "kimi", "pi", "local", "models", "say", "queue", "tail", "budget", "board", "task", "review", "remember", "ask", "route", "pause", "resume", "permit", "status", "logs", "export", "report", "facts", "check-path", "turns", "undo", "kill", "doctor"].includes(command)) return "unknown";
+  if (["task", "queue", "budget", "route", "recovery", "models", "projects"].includes(command)) {
+    const sub = args[0];
+    if (sub && ["propose", "show", "assign", "escalate", "list", "resolve", "resume", "set", "execution", "explain", "status", "abort", "setup", "start", "stop", "remove"].includes(sub)) return `${command} ${sub}`;
+  }
+  return (/^[a-z][a-z0-9-]*$/.test(command) && !/\s/.test(command)) || ["--help", "--version"].includes(command) ? command : "unknown";
+}
+
+export function peerCommandRefusal(peer: string, command: string): string {
+  return `${peer} cannot run ahub ${command}; the person runs it in ahub console or a terminal`;
+}

package/src/cli/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

@@ -1,8 +1,16 @@
 // Launchers inject only the flags the hub owns and refuse user-supplied duplicates.
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { peerChildEnv } from "../hub/child-process.ts";
 export const CLAUDE_CHANNEL = "plugin:agent-hub@agent-hub";
 
+/** Launch identity belongs to the native child, never to the agent that invoked the wrapper. */
+export function nativeLaunchEnv(tool: "claude" | "codex" | "pi", source: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const env = peerChildEnv(tool, source);
+  delete env.AGENTHUB_UNATTENDED;
+  return env;
+}
+
 /** A scoped candidate MCP server can be selected without promoting the installed plugin. */
 function claudeChannel(userArgs: string[]): string {
   const bundle = resolve(import.meta.dir, "../../plugins/agent-hub/server.js");
@@ -55,6 +63,18 @@ 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";
+  /** Observe native sessions/turns for every enabled facts, idle or conductor hook configuration. */
+  observeNative?: boolean;
+}
+
+/** Shared by actual launch and read-only preview; advisory facts remain disabled. */
+export function claudeObservationHooks(config: { coordination?: string; task_sweep?: { enabled: boolean }; roles?: Record<string, string[]> }, paths: Pick<FactsHook, "script" | "stateDir">): FactsHook | undefined {
+  const facts = config.coordination === "turn-free";
+  const idle = config.task_sweep?.enabled === true;
+  const observeNative = facts || idle || config.roles?.claude?.includes("conductor") === true;
+  return facts || idle || observeNative ? { ...paths, purpose: facts ? (idle ? "facts-and-idle" : "facts") : "idle", ...(observeNative ? { observeNative: true } : {}) } : undefined;
 }
 
 /**
@@ -67,6 +87,7 @@ export function sessionSettings(tee: StatusLineTee, facts?: FactsHook): string {
   if (facts) {
     const hooks = [{ type: "command", command: `AGENTHUB_STATE_DIR=${sh(facts.stateDir)} bun ${sh(facts.script)}`, timeout: 5 }];
     settings.hooks = { PreToolUse: [{ matcher: "*", hooks }], PostToolUse: [{ matcher: "*", hooks }], Stop: [{ hooks }] };
+    if (facts.observeNative) Object.assign(settings.hooks as object, { SessionStart: [{ matcher: "*", hooks }], UserPromptSubmit: [{ hooks }] });
   }
   return JSON.stringify(settings);
 }
@@ -90,7 +111,9 @@ 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." : "",
+      ctx.facts?.observeNative && own ? "note: you passed --settings, so native session/turn observation hooks are off: completed turns and supervision tokens may be unavailable." : "",
     ].filter(Boolean);
     return {
       cmd: "claude",
@@ -105,3 +128,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 };
+}