@staix/agent-hub 0.12.16 → 0.12.17

package/src/cli/console-state.ts

@@ -0,0 +1,213 @@
+import { sanitize } from "../hub/envelope.ts";
+
+export interface Approval {
+  id: string; peer: string; title: string; expiresAt: number;
+  options: { optionId: string; name: string; kind: string }[];
+}
+export interface ConsoleEvent { text: string; peer?: string; kind?: string }
+export interface ConsoleState {
+  mode: "stream" | "panels"; panel: number; selection: number; approvalIndex: number;
+  input: string; editing: boolean; history: string[]; historyIndex: number;
+  approvals: Approval[]; events: ConsoleEvent[]; peers: Record<string, any>; budget: Record<string, any>;
+  tasks: any[]; queue: any[]; detail?: string; detailOffset: number; help: boolean; notice: string;
+  peerFilter?: string; kindFilter?: string;
+  confirm?: { type: "permission"; id: string; option: string; peer: string } | { type: "command"; args: string[] };
+  optionChoice?: string;
+}
+export type ConsoleEffect = { type: "exit" } | { type: "permit"; id: string; option?: string } |
+  { type: "command"; args: string[] } | { type: "show"; panel: number; id: string };
+export function initialConsoleState(panels = false): ConsoleState {
+  return { mode: panels ? "panels" : "stream", panel: 1, selection: 0, approvalIndex: 0,
+    input: "", editing: false, history: [], historyIndex: 0, approvals: [], events: [], peers: {}, budget: {}, tasks: [], queue: [], detailOffset: 0, help: false, notice: "" };
+}
+/** Strip terminal controls before any daemon or child output reaches a terminal. Preserve printable Unicode. */
+export function terminalText(value: unknown): string {
+  return sanitize(String(value ?? ""))
+    .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\|$)/g, "")
+    .replace(/\x1b[P_X^][\s\S]*?(?:\x1b\\|$)/g, "")
+    .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
+    .replace(/\x1b[^\n]?/g, "").replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, "");
+}
+export function fit(value: unknown, columns: number): string {
+  const text = terminalText(value).replace(/\n/g, " ");
+  if (columns <= 0) return "";
+  if (Bun.stringWidth(text) <= columns) return text;
+  let result = ""; const marker = ".".repeat(Math.min(3, columns));
+  for (const char of text) { if (Bun.stringWidth(result + char) > columns - marker.length) break; result += char; }
+  return result + marker;
+}
+export function wrap(value: unknown, columns: number): string[] {
+  const lines: string[] = [];
+  for (const part of terminalText(value).split("\n")) {
+    let line = "";
+    for (const char of part) {
+      if (Bun.stringWidth(line + char) > columns) { lines.push(line); line = ""; }
+      line += char;
+    }
+    lines.push(line);
+  }
+  return lines;
+}
+export function pruneApprovals(s: ConsoleState, now: number): ConsoleState {
+  const approvals = s.approvals.filter(a => a.expiresAt > now);
+  const live = (id: string) => approvals.some(a => a.id === id);
+  return { ...s, approvals, approvalIndex: Math.min(s.approvalIndex, Math.max(0, approvals.length - 1)),
+    ...(s.confirm?.type === "permission" && !live(s.confirm.id) ? { confirm: undefined } : {}),
+    ...(s.optionChoice && !live(s.optionChoice) ? { optionChoice: undefined } : {}) };
+}
+const COMMANDS = new Set(["status", "board", "task", "review", "say", "pause", "resume", "budget", "queue", "permit", "ask", "remember", "route", "turns", "undo", "check-path", "report"]);
+/** A tiny argv parser, never a shell. Quotes group arguments; backslash escapes one character. */
+export function parseConsoleCommand(input: string): string[] {
+  const words: string[] = []; let word = ""; let quote = ""; let escaped = false; let started = false;
+  for (const char of input.trim()) {
+    if (escaped) { word += char; escaped = false; started = true; }
+    else if (char === "\\") { escaped = true; started = true; }
+    else if (quote) { if (char === quote) quote = ""; else word += char; }
+    else if (char === '"' || char === "'") { quote = char; started = true; }
+    else if (/\s/.test(char)) { if (started) { words.push(word); word = ""; started = false; } }
+    else { word += char; started = true; }
+  }
+  if (quote || escaped) throw new Error("unfinished quote or escape");
+  if (started) words.push(word);
+  if (!COMMANDS.has(words[0] ?? "")) throw new Error("use another shell for this command");
+  if (words.some(w => w === "--project" || w.startsWith("--project="))) throw new Error("console commands stay in the selected project");
+  return words;
+}
+export function commandNeedsConfirmation(args: string[]): boolean {
+  return (args[0] === "task" && args[1] === "assign") || (args[0] === "queue" && args[1] === "resolve") || (args[0] === "permit" && args[2] !== "deny");
+}
+export function panelRows(s: ConsoleState): any[] {
+  if (s.panel === 1) return Object.entries(s.peers).map(([id, peer]) => ({ id, ...peer, budget: s.budget[id] }));
+  if (s.panel === 2) return s.approvals;
+  if (s.panel === 3) {
+    const states = ["proposed", "in_progress", "in_review", "changes_requested"];
+    return s.tasks.filter(t => states.includes(t.state)).sort((a, b) => states.indexOf(a.state) - states.indexOf(b.state));
+  }
+  if (s.panel === 4) return s.queue.filter(q => q.state === "needs_review" || q.state === "queued");
+  return s.events.filter(e => (!s.peerFilter || e.peer === s.peerFilter) && (!s.kindFilter || e.kind === s.kindFilter));
+}
+export function reduceConsole(state: ConsoleState, key: string, now = Date.now()): { state: ConsoleState; effects: ConsoleEffect[] } {
+  let s = pruneApprovals({ ...state }, now); const effects: ConsoleEffect[] = [];
+  const done = () => ({ state: s, effects });
+  if (key === "\x03") { effects.push({ type: "exit" }); return done(); }
+  if (s.confirm) {
+    const confirm = s.confirm; s.confirm = undefined;
+    if (key === "y") {
+      if (confirm.type === "command") effects.push({ type: "command", args: confirm.args });
+      else if (s.approvals.some(a => a.id === confirm.id && a.options.some(o => o.optionId === confirm.option && o.kind.startsWith("allow")))) {
+        effects.push({ type: "permit", id: confirm.id, option: confirm.option });
+        s.approvals = s.approvals.filter(a => a.id !== confirm.id);
+      }
+    }
+    return done();
+  }
+  if (s.editing || s.input) {
+    if (key === "\x1b") { s.input = ""; s.editing = false; }
+    else if (key === "\x7f" || key === "\b") s.input = Array.from(s.input).slice(0, -1).join("");
+    else if (key === "\x15") s.input = "";
+    else if (key === "\x1b[A" || key === "\x1b[B") {
+      s.historyIndex = Math.max(0, Math.min(s.history.length, s.historyIndex + (key === "\x1b[A" ? -1 : 1)));
+      s.input = s.history[s.historyIndex] ?? "";
+    } else if (key === "\r" || key === "\n") {
+      const input = s.input; s.input = ""; s.editing = false;
+      if (!input.trim()) return done();
+      try {
+        const args = parseConsoleCommand(input);
+        if (args[0] === "queue" && args[1] === "resolve") {
+          const reason = args.indexOf("--reason");
+          if (reason < 0 || !args[reason + 1]?.trim()) throw new Error("queue resolve requires --reason");
+        }
+        s.history = [...s.history, input].slice(-100); s.historyIndex = s.history.length;
+        if (commandNeedsConfirmation(args)) s.confirm = { type: "command", args };
+        else effects.push({ type: "command", args });
+      } catch (error) { s.notice = String((error as Error).message); }
+    } else if (!key.startsWith("\x1b")) s.input += terminalText(key).replace(/\n/g, "");
+    return done();
+  }
+  if (key === "q") { effects.push({ type: "exit" }); return done(); }
+  if (key === "\t") { s.mode = s.mode === "panels" ? "stream" : "panels"; s.detail = undefined; return done(); }
+  if (key === ":") { s.editing = true; return done(); }
+  if (s.mode === "panels" && /^[1-5]$/.test(key) && !s.optionChoice) { s.panel = Number(key); s.selection = 0; s.detail = undefined; return done(); }
+  if (key === "?") { s.help = !s.help; return done(); }
+  if (key === "\x1b") { s.detail = undefined; s.help = false; s.optionChoice = undefined; return done(); }
+  if (s.mode === "panels" && ["j", "k", "\x1b[A", "\x1b[B"].includes(key)) {
+    if (s.detail) { s.detailOffset = Math.max(0, s.detailOffset + (["j", "\x1b[B"].includes(key) ? 1 : -1)); return done(); }
+    s.selection = Math.max(0, Math.min(panelRows(s).length - 1, s.selection + (["j", "\x1b[B"].includes(key) ? 1 : -1)));
+    if (s.panel === 2) s.approvalIndex = s.selection;
+    return done();
+  }
+  if (key === "[" || key === "]") {
+    s.approvalIndex = (s.approvalIndex + (key === "[" ? -1 : 1) + s.approvals.length) % Math.max(1, s.approvals.length); return done();
+  }
+  const approval = s.approvals[s.approvalIndex];
+  if (s.optionChoice) {
+    const a = s.approvals.find(a => a.id === s.optionChoice); const options = a?.options.filter(o => o.kind.startsWith("allow")) ?? [];
+    const option = options[Number(key) - 1];
+    if (/^[1-9]$/.test(key) && a && option) { s.confirm = { type: "permission", id: a.id, peer: a.peer, option: option.optionId }; s.optionChoice = undefined; }
+    return done();
+  }
+  if (approval && (s.mode === "stream" || s.panel === 2)) {
+    if (key === "d") { effects.push({ type: "permit", id: approval.id }); s.approvals = s.approvals.filter(a => a.id !== approval.id); return done(); }
+    if (key === "a") {
+      const options = approval.options.filter(o => o.kind.startsWith("allow"));
+      if (options.length === 1) s.confirm = { type: "permission", id: approval.id, peer: approval.peer, option: options[0]!.optionId };
+      else if (options.length) s.optionChoice = approval.id;
+      return done();
+    }
+    if (key === "v") { s.detail = approval.title; s.detailOffset = 0; return done(); }
+  }
+  const row = panelRows(s)[s.selection];
+  if (s.mode === "panels" && row) {
+    if (key === "\r" || key === "\n") {
+      if (s.panel === 3 || s.panel === 4) effects.push({ type: "show", panel: s.panel, id: String(row.id) });
+      else { s.detail = s.panel === 2 ? row.title : s.panel === 5 ? row.text : JSON.stringify(row, null, 2); s.detailOffset = 0; }
+      return done();
+    }
+    const prefill = s.panel === 1 && key === "p" ? `pause ${row.id}` : s.panel === 1 && key === "r" ? `resume ${row.id}` :
+      s.panel === 3 && key === "a" ? `task assign ${row.id} ` : s.panel === 3 && key === "r" ? `review ${row.id} ` :
+      s.panel === 4 && key === "r" ? `queue resolve ${row.id} --action retry --reason ` : undefined;
+    if (prefill) { s.input = prefill; s.editing = true; return done(); }
+  }
+  if (s.mode === "panels" && s.panel === 5 && (key === "f" || key === "g")) {
+    const field = key === "f" ? "peer" : "kind"; const current = key === "f" ? s.peerFilter : s.kindFilter;
+    const values = [...new Set(s.events.map(e => e[field]).filter((x): x is string => !!x))];
+    const next = values[values.indexOf(current ?? "") + 1];
+    if (key === "f") s.peerFilter = next; else s.kindFilter = next;
+    s.selection = 0; return done();
+  }
+  if (s.mode === "stream" && !key.startsWith("\x1b")) { s.editing = true; s.input = terminalText(key).replace(/\n/g, ""); }
+  return done();
+}
+export function renderConsole(s: ConsoleState, columns: number, rows = 24, now = Date.now()): string[] {
+  const permission = s.approvals[s.approvalIndex];
+  let prompt = s.editing ? `: ${s.input}` : "q quit | Tab panels | : command | a allow d deny v view [ ] select";
+  if (s.confirm?.type === "permission") prompt = `allow ${s.confirm.option} for ${s.confirm.peer} (request ${s.confirm.id})? y/N`;
+  if (s.confirm?.type === "command") prompt = `${s.confirm.args.join(" ")}? y/N`;
+  if (s.optionChoice) prompt = s.approvals.find(a => a.id === s.optionChoice)?.options.filter(o => o.kind.startsWith("allow")).map((o, i) => `${i + 1}:${o.name}`).join(" | ") ?? "";
+  const quotas = Object.entries(s.budget).map(([id, b]) => `${id}:${b.windows?.map((w: any) => `${w.id} ${Math.round(w.used * 100)}%`).join("/") ?? "?"}`).join(" ");
+  const summary = Object.entries(s.peers).map(([id, p]) => `${id}:${p.state} q${p.queued ?? 0}${p.needsReview ? ` review${p.needsReview}` : ""}${p.paused ? " paused" : ""}`).join(" ");
+  const footer = [fit(summary + (quotas ? ` | ${quotas}` : ""), columns), fit(`${s.approvals.length} approvals${permission ? ` | ${permission.peer} ${permission.id} ${Math.max(0, Math.ceil((permission.expiresAt - now) / 1000))}s` : ""}${s.notice ? ` | ${s.notice}` : ""}`, columns), fit(prompt, columns)];
+  if (s.mode === "stream") return footer;
+  const title = ["Peers", "Approvals", "Tasks", "Queue", "Events"][s.panel - 1];
+  const lines = [fit(`agent-hub | 1 Peers 2 Approvals 3 Tasks 4 Queue 5 Events | ${title}`, columns), fit(`j/k move Enter detail Esc back ? keys${s.panel === 5 ? ` | f peer:${s.peerFilter ?? "all"} g kind:${s.kindFilter ?? "all"}` : ""}`, columns)];
+  if (s.help) lines.push(...wrap("Tab stream/panels; 1-5 panel; j/k or arrows move; Enter detail; Esc back; : command; q quit. Approvals: a allow (confirm y), d deny, v title, [ ] select. Peers: p pause, r resume. Tasks: a assign (confirm y), r review. Queue: r resolve (reason and confirm y). Events: f peer filter, g kind filter.", columns));
+  else if (s.detail) { const detail = wrap(s.detail, columns); lines.push(...detail.slice(Math.min(s.detailOffset, Math.max(0, detail.length - (rows - 5))))); }
+  else {
+    const data = panelRows(s); const capacity = Math.max(1, s.panel === 2 ? Math.floor((rows - 6) / 2) : rows - 6); const start = Math.max(0, s.selection - capacity + 1);
+    for (const [i, row] of data.slice(start, start + capacity).entries()) {
+      let text = "";
+      if (s.panel === 1) {
+        const b = s.budget[row.id];
+        text = `${row.id} ${row.state} ${row.attached === false ? "detached" : "attached"} q:${row.queued ?? 0} !:${row.queuedImportant ?? 0} review:${row.needsReview ?? 0} ${row.paused ? `paused:${JSON.stringify(row.paused)}` : ""} ${b?.paused ? `budget pause ${b.paused.reason} reset:${b.paused.resetsAt}` : ""} ${b?.windows?.map((w: any) => `${w.id}:${Math.round(w.used * 100)}% reset:${w.resetsAt ?? "?"}`).join(" ") ?? "quota:?"} model:${row.servedBy ?? row.requestedModel ?? "?"}`;
+      } else if (s.panel === 2) text = `${row.id} ${row.peer} ${Math.max(0, Math.ceil((row.expiresAt - now) / 1000))}s ${row.title}`;
+      else if (s.panel === 3) { const at = row.history?.at(-1)?.at ?? row.updated ?? row.created; text = `#${row.id} ${row.state}${row.ready ? " ready" : ""} ${row.owner ?? "-"} review:${row.reviewer ?? "-"} ${row.class} age:${at ? Math.max(0, Math.floor((now - at) / 1000)) + "s" : "?"} ${row.title}`; }
+      else if (s.panel === 4) text = `${row.id} ${row.peer} ${row.state} rev:${row.revision} age:${row.createdAt ? Math.max(0, Math.floor((now - row.createdAt) / 1000)) + "s" : "?"}`;
+      else text = row.text;
+      lines.push(fit(`${start + i === s.selection ? ">" : " "} ${text}`, columns));
+    }
+    if (!data.length) lines.push("(empty)");
+    if (s.panel === 2 && permission) lines.push(...wrap(permission.title, columns).slice(0, Math.max(0, rows - 3 - lines.length)));
+  }
+  const body = lines.slice(0, rows - 3); while (body.length < rows - 3) body.push("");
+  return [...body, ...footer];
+}

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/launch.ts

@@ -1,8 +1,16 @@
 // Launchers inject only the flags the hub owns and refuse user-supplied duplicates.
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { peerChildEnv } from "../hub/child-process.ts";
 export const CLAUDE_CHANNEL = "plugin:agent-hub@agent-hub";
 
+/** Launch identity belongs to the native child, never to the agent that invoked the wrapper. */
+export function nativeLaunchEnv(tool: "claude" | "codex" | "pi", source: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const env = peerChildEnv(tool, source);
+  delete env.AGENTHUB_UNATTENDED;
+  return env;
+}
+
 /** A scoped candidate MCP server can be selected without promoting the installed plugin. */
 function claudeChannel(userArgs: string[]): string {
   const bundle = resolve(import.meta.dir, "../../plugins/agent-hub/server.js");
@@ -57,13 +65,16 @@ export interface FactsHook {
   stateDir: string;
   /** The same hook transport can observe native turns without injecting facts. */
   purpose?: "facts" | "idle" | "facts-and-idle";
+  /** Observe native sessions/turns for every enabled facts, idle or conductor hook configuration. */
+  observeNative?: boolean;
 }
 
 /** Shared by actual launch and read-only preview; advisory facts remain disabled. */
-export function claudeObservationHooks(config: { coordination?: string; task_sweep?: { enabled: boolean } }, paths: Pick<FactsHook, "script" | "stateDir">): FactsHook | undefined {
+export function claudeObservationHooks(config: { coordination?: string; task_sweep?: { enabled: boolean }; roles?: Record<string, string[]> }, paths: Pick<FactsHook, "script" | "stateDir">): FactsHook | undefined {
   const facts = config.coordination === "turn-free";
   const idle = config.task_sweep?.enabled === true;
-  return facts || idle ? { ...paths, purpose: facts ? (idle ? "facts-and-idle" : "facts") : "idle" } : undefined;
+  const observeNative = facts || idle || config.roles?.claude?.includes("conductor") === true;
+  return facts || idle || observeNative ? { ...paths, purpose: facts ? (idle ? "facts-and-idle" : "facts") : "idle", ...(observeNative ? { observeNative: true } : {}) } : undefined;
 }
 
 /**
@@ -76,6 +87,7 @@ export function sessionSettings(tee: StatusLineTee, facts?: FactsHook): string {
   if (facts) {
     const hooks = [{ type: "command", command: `AGENTHUB_STATE_DIR=${sh(facts.stateDir)} bun ${sh(facts.script)}`, timeout: 5 }];
     settings.hooks = { PreToolUse: [{ matcher: "*", hooks }], PostToolUse: [{ matcher: "*", hooks }], Stop: [{ hooks }] };
+    if (facts.observeNative) Object.assign(settings.hooks as object, { SessionStart: [{ matcher: "*", hooks }], UserPromptSubmit: [{ hooks }] });
   }
   return JSON.stringify(settings);
 }
@@ -101,6 +113,7 @@ export function buildLaunch(
       ctx.statusLine && own ? "note: you passed --settings, so the hub's status line tee is off and the budget coordinator cannot see Claude's quota (ahub budget set claude <0..1> still works)." : "",
       ctx.facts && own && ctx.facts.purpose !== "idle" ? "note: you passed --settings, so the hub's turn-free facts hooks are off for this session: Claude will not see the other agents' changes at its tool calls." : "",
       ctx.facts && own && (ctx.facts.purpose === "idle" || ctx.facts.purpose === "facts-and-idle") ? "note: you passed --settings, so native idle observation hooks are off for this session: task idle sweeps cannot verify Claude between turns." : "",
+      ctx.facts?.observeNative && own ? "note: you passed --settings, so native session/turn observation hooks are off: completed turns and supervision tokens may be unavailable." : "",
     ].filter(Boolean);
     return {
       cmd: "claude",