@staix/agent-hub 0.7.11 → 0.8.0

package/src/cli/main.ts

@@ -28,6 +28,18 @@ 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 { parseSince, readEvents } from "../hub/events.ts";
+import { formatReport, summarize } from "../hub/report.ts";
+import { hasTree, planUndo, repoOf, restore, Turns } from "../hub/snapshots.ts";
+
+/** `--since 7d|24h|<iso>` for export and report; everything when absent. */
+const since = (): number => {
+  const at = args.indexOf("--since");
+  if (at < 0) return 0;
+  const t = parseSince(args[at + 1] ?? "");
+  if (t === undefined) fail("--since takes 7d, 24h, 90m or an ISO date");
+  return t;
+};
 
 const USAGE = `agent-hub ${VERSION}: Claude Code, Codex and Kimi as peers in one project directory
 
@@ -72,6 +84,11 @@ const USAGE = `agent-hub ${VERSION}: Claude Code, Codex and Kimi as peers in one
   ahub queue show <delivery-id>               inspect one delivery and revision
   ahub queue resolve <delivery-id> --action completed|retry|discard --reason <text>
   ahub status | logs [-f] | doctor | kill
+  ahub export [--since 7d|<iso>]  structured events (events.jsonl) as JSON lines; never message bodies
+  ahub report [--since 7d|<iso>] [--json]  turns, tokens, messages, overlaps and task events per period
+  ahub turns [peer] [--limit N]  recent turns and the files each changed (a git work tree only)
+  ahub undo <turn> [--yes] [--context]  put back the files a turn changed; refuses files changed since.
+                               Without --yes it only lists them; --context also drops a Codex turn from its conversation
   ahub doctor --orphans [--kill]  list registrations whose project root is gone; --kill stops their
                                daemons (SIGTERM, then SIGKILL) only after the process identity checks out`;
 
@@ -279,6 +296,22 @@ async function taskOp(op: string, a: Record<string, unknown>): Promise<string> {
   return res.text;
 }
 
+/** Reads hub.db's turn records; `none` when the hub never kept one (snapshots off, no git work tree, an older hub). */
+function turnRecords<T>(read: (turns: Turns) => T, none: T): T {
+  const db = join(stateDir, "hub.db");
+  if (!existsSync(db)) return none;
+  let turns: Turns | undefined;
+  try {
+    turns = new Turns(db, true);
+    return read(turns);
+  } catch (error) {
+    if (/no such table/.test((error as Error).message)) return none;
+    throw error;
+  } finally {
+    turns?.close();
+  }
+}
+
 /** `--flag value` pairs pulled out of an argument list; the rest keeps its order. */
 function takeFlags(argv: string[], single: string[], repeated: string[]) {
   const one: Record<string, string> = {};
@@ -716,6 +749,64 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   logs: () => exec("tail", [args.includes("-f") ? "-f" : "-n100", join(stateDir, "hub.log")]),
+  export: () => {
+    for (const e of readEvents(join(stateDir, "events.jsonl"), since())) console.log(JSON.stringify(e));
+  },
+  report: () => {
+    const r = summarize(readEvents(join(stateDir, "events.jsonl"), since()));
+    console.log(args.includes("--json") ? JSON.stringify(r, null, 2) : formatReport(r).join("\n"));
+  },
+  turns: () => {
+    const { one, rest } = takeFlags(args, ["--limit"], []);
+    const rows = turnRecords((t) => t.list(rest[0], Number(one["--limit"]) || 20), []);
+    if (!rows.length) return console.log("no turns recorded (they need a git work tree and snapshots.enabled)");
+    for (const r of rows) {
+      const shown = r.changed.slice(0, 5).join(", ") + (r.changed.length > 5 ? ", ..." : "");
+      const files = r.changed.length ? `: ${shown}` : "";
+      let status = "";
+      if (!r.ended) status = " (running)";
+      else if (!r.end_tree) status = " (no end snapshot)";
+      console.log(`${r.id}  ${new Date(r.started).toLocaleString()}${status}  ${r.changed.length} files${files}`);
+    }
+  },
+  undo: async () => {
+    const id = args.find((a) => !a.startsWith("--")) ?? fail("usage: ahub undo <turn> [--yes] [--context]");
+    const turn = turnRecords((t) => t.get(id), undefined) ?? fail(`no turn ${id} recorded (ahub turns lists them)`);
+    if (!turn.ended) fail(`turn ${id} is still running`);
+    const { start_tree: startTree, end_tree: endTree } = turn;
+    if (!startTree || !endTree) fail(`turn ${id} has no ${startTree ? "end" : "start"} snapshot: the hub stopped during it, or a snapshot failed (see hub.log)`);
+    const repo = repoOf(cwd) ?? fail(`${cwd} is not in a git work tree`);
+    if (!hasTree(repo.top, startTree) || !hasTree(repo.top, endTree)) fail(`turn ${id}'s snapshots are gone from the git object store (git gc prunes them after two weeks)`);
+    // Another peer's turn that overlapped this one in time has its changes in this turn's diff as well.
+    const keep = Math.max(1, Number(projectConfig().snapshots.keep) || 20);
+    const overlapping = turnRecords((t) => t.overlapping(turn, keep), { paths: [] as string[], unknown: [] as string[] });
+    if (overlapping.unknown.length) fail(`refusing to undo ${id}: these turns of other peers ran at the same time and their changes are not known (still running, cut short, or not snapshotted): ${overlapping.unknown.join(", ")}`);
+    let reverted = false;
+    const plan = () => {
+      const p = planUndo(repo, { start_tree: startTree, end_tree: endTree, changed: turn.changed }, overlapping.paths);
+      if (p.undone) return p;
+      const why = [
+        p.changedSince.length ? `these files changed again after it ended, and restoring them would lose that work:\n  ${p.changedSince.join("\n  ")}` : "",
+        p.concurrent.length ? `these files were also changed by another peer's turn running at the same time, so the change may be theirs:\n  ${p.concurrent.join("\n  ")}` : "",
+      ].filter(Boolean);
+      if (why.length) fail(`refusing to undo ${id}: ${why.join("\n")}${reverted ? "\nCodex's conversation was already reverted; restore the files later with ahub undo without --context" : ""}`);
+      return p;
+    };
+    const first = plan();
+    if (first.undone) return console.log(`turn ${id} is already undone: its files are as they were before it started`);
+    console.log(first.restore.length ? `turn ${id} changed:\n  ${first.restore.join("\n  ")}` : `turn ${id} changed no files`);
+    console.log("(every change made in the project during the turn counts as its own, including any by Claude or by you)");
+    if (!args.includes("--yes")) return console.log("nothing was changed; add --yes to restore these files");
+    if (args.includes("--context")) {
+      console.log(await taskOp("turn_revert", { turn: id }));
+      reverted = true;
+    }
+    // A peer may have written meanwhile (the revert alone can take seconds): plan again right before restoring.
+    const second = plan();
+    if (second.restore.join("\0") !== first.restore.join("\0")) fail(`the project changed while undoing; nothing was restored, run ahub undo again${reverted ? " without --context (Codex's conversation was already reverted)" : ""}`);
+    restore(repo, startTree, second.restore);
+    if (second.restore.length) console.log(`restored to their state before ${id}`);
+  },
 
   kill: async () => {
     const registry = new Registry();

package/src/hub/board.ts

@@ -11,6 +11,10 @@ export interface TaskRefs {
   commit?: string;
   paths?: string[];
 }
+/** What an owner says it will change, before it starts (issue #31). Each list holds short free-text items. */
+export const PLAN_KEYS = ["paths", "symbols", "signatures", "insertion_points"] as const;
+export type TaskPlan = Partial<Record<(typeof PLAN_KEYS)[number], string[]>>;
+
 export interface HistoryEntry {
   at: number;
   by: PeerId;
@@ -26,6 +30,8 @@ export interface Task {
   reviewer: PeerId | null;
   state: TaskState;
   refs: TaskRefs;
+  /** Absent only on tasks built outside the board (tests); the board always returns one, `{}` when none was given. */
+  plan?: TaskPlan;
   signals: string[];
   /** consecutive changes_requested verdicts */
   rejections: number;
@@ -43,11 +49,16 @@ const MOVES: Record<TaskState, TaskState[]> = {
   approved: [],
 };
 
-const JSON_COLS = ["refs", "signals", "history"] as const;
+const JSON_COLS = ["refs", "plan", "signals", "history"] as const;
 
 /** Task board in `.agenthub/state/hub.db`. It outlives the hub process: `ahub kill` leaves the file. */
 export class Board {
   private readonly db: Database;
+  /** Every recorded change, as it lands (telemetry, issue #40). */
+  onChange?: (task: Task, entry: HistoryEntry) => void;
+  private changed(task: Task, entry: HistoryEntry): void {
+    try { this.onChange?.(task, entry); } catch { /* never throw after a board write */ }
+  }
 
   constructor(path: string) {
     this.db = new Database(path, { create: true });
@@ -56,15 +67,21 @@ export class Board {
       id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT NOT NULL, detail TEXT NOT NULL DEFAULT '', class TEXT NOT NULL,
       owner TEXT, reviewer TEXT, state TEXT NOT NULL, refs TEXT NOT NULL DEFAULT '{}', signals TEXT NOT NULL DEFAULT '[]',
       rejections INTEGER NOT NULL DEFAULT 0, history TEXT NOT NULL DEFAULT '[]', created INTEGER NOT NULL, updated INTEGER NOT NULL)`);
+    // Boards from before issue #31 have no plan column.
+    if (!(this.db.query("PRAGMA table_info(tasks)").all() as { name: string }[]).some((c) => c.name === "plan")) {
+      this.db.run("ALTER TABLE tasks ADD COLUMN plan TEXT NOT NULL DEFAULT '{}'");
+    }
   }
 
-  propose(by: PeerId, t: { title: string; detail?: string; class: TaskClass; refs?: TaskRefs; signals?: string[] }): Task {
+  propose(by: PeerId, t: { title: string; detail?: string; class: TaskClass; refs?: TaskRefs; plan?: TaskPlan; signals?: string[] }): Task {
     const now = Date.now();
     const history: HistoryEntry[] = [{ at: now, by, event: "proposed" }];
     const { lastInsertRowid } = this.db
-      .query("INSERT INTO tasks (title, detail, class, state, refs, signals, history, created, updated) VALUES (?, ?, ?, 'proposed', ?, ?, ?, ?, ?)")
-      .run(t.title, t.detail ?? "", t.class, JSON.stringify(t.refs ?? {}), JSON.stringify(t.signals ?? []), JSON.stringify(history), now, now);
-    return this.get(Number(lastInsertRowid))!;
+      .query("INSERT INTO tasks (title, detail, class, state, refs, plan, signals, history, created, updated) VALUES (?, ?, ?, 'proposed', ?, ?, ?, ?, ?, ?)")
+      .run(t.title, t.detail ?? "", t.class, JSON.stringify(t.refs ?? {}), JSON.stringify(t.plan ?? {}), JSON.stringify(t.signals ?? []), JSON.stringify(history), now, now);
+    const task = this.get(Number(lastInsertRowid))!;
+    this.changed(task, history[0]!);
+    return task;
   }
 
   get(id: number): Task | undefined {
@@ -84,7 +101,8 @@ export class Board {
   }
 
   /** The only way a task changes. Validates the move, records who did what, returns the new row. */
-  update(id: number, by: PeerId, event: string, patch: Partial<Pick<Task, "state" | "owner" | "reviewer" | "refs" | "rejections">>, note?: string): Task {
+  /** A `plan` in the patch replaces the old one whole: a new plan is the owner's current intent, not an addition. */
+  update(id: number, by: PeerId, event: string, patch: Partial<Pick<Task, "state" | "owner" | "reviewer" | "refs" | "plan" | "rejections">>, note?: string): Task {
     const task = this.get(id);
     if (!task) throw new Error(`no task #${id}`);
     if (patch.state && patch.state !== task.state && !MOVES[task.state].includes(patch.state)) {
@@ -93,9 +111,11 @@ export class Board {
     const next = { ...task, ...patch, refs: { ...task.refs, ...patch.refs } };
     const history = [...task.history, { at: Date.now(), by, event, ...(note ? { note } : {}) }];
     this.db
-      .query("UPDATE tasks SET state = ?, owner = ?, reviewer = ?, refs = ?, rejections = ?, history = ?, updated = ? WHERE id = ?")
-      .run(next.state, next.owner, next.reviewer, JSON.stringify(next.refs), next.rejections, JSON.stringify(history), Date.now(), id);
-    return this.get(id)!;
+      .query("UPDATE tasks SET state = ?, owner = ?, reviewer = ?, refs = ?, plan = ?, rejections = ?, history = ?, updated = ? WHERE id = ?")
+      .run(next.state, next.owner, next.reviewer, JSON.stringify(next.refs), JSON.stringify(next.plan ?? {}), next.rejections, JSON.stringify(history), Date.now(), id);
+    const updated = this.get(id)!;
+    this.changed(updated, history.at(-1)!);
+    return updated;
   }
 
   close(): void {

package/src/hub/budget.ts

@@ -55,6 +55,8 @@ export interface BudgetHooks {
   /** Move the peer's open work. */
   handoff(peer: PeerId, context: string | undefined): Promise<Moved[]>;
   resumed(record: PauseRecord): void;
+  /** Every reading as it arrives, with the time it was measured (telemetry, issue #40). */
+  reading?(peer: PeerId, windows: UsageWindow[], hard: boolean, at: number): void;
   notify(line: string): void;
 }
 
@@ -144,6 +146,7 @@ export class Budget {
   /** `at`: when the numbers were measured, for sources that arrive through a file (a leftover file is not a fresh reading). */
   report(peer: PeerId, windows: UsageWindow[], hard = false, at = this.now()): void {
     if (EXEMPT.has(peer) || this.closed) return;
+    try { this.hooks.reading?.(peer, windows, hard, at); } catch { /* telemetry never costs a reading */ }
     const mine = this.readings.get(peer) ?? new Map<string, Reading>();
     this.readings.set(peer, mine);
     for (const w of windows) mine.set(w.id, { ...w, used: Math.max(0, Math.min(1, w.used)), at });

package/src/hub/daemon.ts

@@ -6,6 +6,7 @@ import { spawn } from "node:child_process";
 import { childEnv } from "./child-process.ts";
 import { runCheck } from "./checks.ts";
 import { stripUntrusted } from "./config-trust.ts";
+import { eventLog, tokenDeltas } from "./events.ts";
 import type { ServerWebSocket } from "bun";
 import { AcpPeer, type PermissionRequest } from "../adapters/acp.ts";
 import { CodexPeer } from "../adapters/codex-appserver.ts";
@@ -40,6 +41,7 @@ import { BasePeer, DEFAULT_WATCHDOG_MS, type PeerAdapter } from "./peers.ts";
 import { MemoryClient, workerUrl } from "../memory/client.ts";
 import { VERSION } from "../version.ts";
 import { projectChain, recallFor } from "../memory/recall.ts";
+import { changedPaths, repoOf, snapshot, Turns } from "./snapshots.ts";
 import { archiveRestartSnapshot, readRestartSnapshot, removeRestartSnapshot, restartPath, writeRestartSnapshot, type RecoveryPhase, type RestartPeerSnapshot, type RestartSnapshot } from "./restart.ts";
 
 export interface HubConfig {
@@ -63,6 +65,8 @@ export interface HubConfig {
   tasks: { release_after_min: number };
   /** A command per task class run when the owner marks the task done, and its timeout (issue #7). */
   checks: { timeout_s: number; [cls: string]: string | number };
+  /** A git tree at each turn boundary for `ahub turns` and `ahub undo`, the last `keep` per peer (issue #33). */
+  snapshots: { enabled: boolean; keep: number };
   /** Machine-local fields a config file set but git could not vouch for, and why (issue #17). */
   ignored?: string[];
 }
@@ -85,6 +89,8 @@ export const DEFAULT_CONFIG: HubConfig = {
   approvals: { timeout_s: 120, notify: false },
   tasks: { release_after_min: 30 },
   checks: { timeout_s: 600 },
+  // Off here like approvals.notify, so tests (whose cwd is this repository) write no objects; a project's config turns it on.
+  snapshots: { enabled: false, keep: 20 },
 };
 
 export { stateDirFor };
@@ -95,7 +101,7 @@ const PEER_ID = /^[a-z][a-z0-9-]{0,31}$/;
 
 /** The shared project config, then the machine's own file, which overrides it block by block (issue #17). */
 const CONFIG_FILES = ["config.json", "config.local.json"] as const;
-const CONFIG_BLOCKS = ["memory", "roles", "budget", "inference", "omniroute", "local", "pi", "approvals", "tasks", "checks", "mlx"];
+const CONFIG_BLOCKS = ["memory", "roles", "budget", "inference", "omniroute", "local", "pi", "approvals", "tasks", "checks", "snapshots", "mlx"];
 
 export function loadConfig(cwd: string): HubConfig {
   const ignored: string[] = [];
@@ -138,6 +144,7 @@ export function loadConfig(cwd: string): HubConfig {
     },
     tasks: { ...DEFAULT_CONFIG.tasks, ...file.tasks },
     checks: { ...DEFAULT_CONFIG.checks, ...file.checks },
+    snapshots: { ...DEFAULT_CONFIG.snapshots, enabled: true, ...file.snapshots },
     mlx,
     ...(ignored.length ? { ignored } : {}),
   };
@@ -224,6 +231,7 @@ export async function startDaemon(opts: DaemonOptions) {
   const logFile = join(opts.stateDir, "hub.log");
   // The state dir can vanish under a running hub (issue #56): a log line must never take a handler down with it.
   const log = (line: string) => { try { appendFileSync(logFile, `${new Date().toISOString()} ${line}\n`); } catch { /* the state dir is gone; the watchdog is stopping the hub */ } };
+  const event = eventLog(join(opts.stateDir, "events.jsonl"));
 
   // Any local web page can open a WebSocket to a loopback port, so the control link needs a secret.
   // The file is written only after the port is bound: a second daemon that loses the bind must not clobber it.
@@ -359,6 +367,7 @@ export async function startDaemon(opts: DaemonOptions) {
     project: chain.at(-1)!,
     ...(config.memory.enabled ? { memory, briefs: new Briefs(memory, chain.at(-1)!, config.memory.brief_items) } : {}),
     notify,
+    recordOverlap: (task, owner, others) => event({ type: "overlap", task, owner, others }),
     ...(checksAllowed ? { check: (cls: string) => checkCommands[cls], runCheck: async (command: string) => (checksClosed ? interrupted : runCheck(command, opts.cwd, checkTimeoutS * 1000, runningChecks)) } : {}),
     // What a peer learned reaches the peers working now, on their next delivery, instead of at their next session (#68).
     // Fail-open: the note is already saved, so a bus that cannot persist costs the sharing, not the tool call.
@@ -378,6 +387,7 @@ export async function startDaemon(opts: DaemonOptions) {
     },
     triage: { classify: (title, detail) => inference?.triage(title, detail) ?? Promise.resolve(undefined), onCampus: () => onCampus() },
   });
+  board.onChange = (t, h) => event({ type: "task", id: t.id, event: h.event, by: h.by, state: t.state, owner: t.owner, reviewer: t.reviewer, class: t.class, pii: tasks.isPii(t) });
   // ---- budget relay -------------------------------------------------------------------------------------------
   const checkpointWaits = new Map<PeerId, (summary: string | undefined) => void>();
   const PLATFORM: Record<PeerId, string> = { claude: "claude", codex: "codex", kimi: "kimi" };
@@ -414,6 +424,8 @@ export async function startDaemon(opts: DaemonOptions) {
     // Somebody other than the paused peer has to be there, or the handoff would only leave its tasks without an owner.
     canHandOff: (peer) => [...bus.peers.keys()].some((id) => id !== peer && ["idle", "busy"].includes(bus.stateOf(id))),
     handoff: (peer, context) => tasks.reassignForPause(peer, context),
+    // A reading that arrived through a file carries the file's time; a stale one must not look fresh in the export.
+    reading: (peer, windows, hard, at) => event({ type: "quota", peer, windows: windows.map((w) => ({ id: w.id, used: w.used, ...(w.resetsAt ? { resetsAt: w.resetsAt } : {}) })), hard, ...(Math.abs(Date.now() - at) > 1000 ? { measuredAt: new Date(at).toISOString() } : {}) }),
     resumed: (record) => {
       if (record.peer === "kimi") kimiTokens.length = 0; // a new window: the old counts would pause it again at once
       const moved = record.moved.length ? `While you were paused these moved: ${record.moved.map((m) => `${m.title} (${m.role} -> ${m.to ?? "nobody"})`).join("; ")}. They stay where they are; ask the user if you should take one back.` : "Nothing was moved while you were paused.";
@@ -424,14 +436,47 @@ export async function startDaemon(opts: DaemonOptions) {
   budget.setRecoveryHold(recoveryActive());
   const kimiTokens: { at: number; n: number }[] = [];
   startupCleanup.push(() => budget.close());
-  let kimiSessionTotal = 0;
-  /** `total` is the session's running count: only what was added since the last update goes into the rolling window. */
-  const onKimiTokens = (total: number) => {
-    if (!config.budget.kimi_tokens_5h) return;
+  // Turns and their tokens for telemetry (issue #40). Turn ids carry the hub run, so they stay unique across restarts.
+  const runId = Date.now().toString(36);
+  let turnSeq = 0;
+  const turns = new Map<PeerId, { id: string; start: number; tokens: number; tree?: string; snapshotMs?: number; private?: boolean }>();
+  // Per-turn snapshots (issue #33): a git tree at both turn boundaries, recorded in hub.db for `ahub turns` and `ahub undo`.
+  const repo = config.snapshots.enabled ? repoOf(opts.cwd) : undefined;
+  if (config.snapshots.enabled && !repo) log("snapshots: the project is not in a git work tree, so turns are not recorded");
+  const turnLog = repo ? new Turns(join(opts.stateDir, "hub.db")) : undefined;
+  if (turnLog) startupCleanup.push(() => turnLog.close());
+  /** Whether a peer has a PII task open in any state: assigned and not yet accepted counts. */
+  const holdsPii = (peer: PeerId) => board.list().some((t) => t.owner === peer && t.state !== "approved" && t.state !== "in_review" && tasks.isPii(t));
+  /**
+   * A snapshot that fails costs the undo record of that turn and nothing else. The peer's prompt waits for it (it
+   * runs inside the state change): three git calls at a turn's start and four at its end, each with the 10 s timeout
+   * in snapshots.ts.
+   */
+  const snap = (what: string): { tree?: string; ms: number } => {
+    const t0 = performance.now();
+    let tree: string | undefined;
+    try {
+      tree = repo && snapshot(repo);
+      if (repo && !tree) log(`snapshot failed at ${what}`);
+    } catch (error) {
+      log(`snapshot failed at ${what}: ${(error as Error).message}`);
+    }
+    return { tree, ms: Math.round(performance.now() - t0) };
+  };
+  const delta = tokenDeltas();
+  /** Tokens a peer used, as increments: Kimi reports a session total (turned into increments below), Codex increments. */
+  const addTokens = (peer: PeerId, n: number): number => {
+    if (n > 0) {
+      event({ type: "tokens", peer, n });
+      const turn = turns.get(peer);
+      if (turn) turn.tokens += n;
+    }
+    return n;
+  };
+  const onKimiTokens = (total: number, session: string) => {
+    const n = addTokens("kimi", delta("kimi", total, session));
+    if (!config.budget.kimi_tokens_5h || !n) return;
     const now = Date.now();
-    const n = total >= kimiSessionTotal ? total - kimiSessionTotal : total; // a smaller total means a new session
-    kimiSessionTotal = total;
-    if (!n) return;
     kimiTokens.push({ at: now, n });
     while (kimiTokens.length && now - kimiTokens[0]!.at > 5 * 3_600_000) kimiTokens.shift();
     const used = kimiTokens.reduce((s, t) => s + t.n, 0) / config.budget.kimi_tokens_5h;
@@ -478,6 +523,12 @@ export async function startDaemon(opts: DaemonOptions) {
     // Inside a PII turn the worker's words may carry the PII whatever they are attached to: a note would go to
     // claude-mem (a cloud observer) and a new task could be routed to a cloud peer without matching any pattern.
     if (piiTurn && (op === "hub_remember" || op === "hub_task_propose")) throw new Error(`${op} is not available while working on a PII task: its text must not leave this machine`);
+    // The same words attached to an ordinary task would reach its reviewer, its owner, overlapping owners (a plan, the
+    // completed-change notice) and claude-mem. A turn that holds a PII task acts on ordinary tasks in a turn of its own.
+    if (piiTurn && (op === "hub_task_done" || op === "hub_review" || (op === "hub_task_accept" && a.plan != null))) {
+      const target = board.get(Number(a.id));
+      if (target && !tasks.isPii(target)) throw new Error(`${op} on task #${target.id} is not available while working on a PII task: its text would reach other peers; do it in a turn without the PII task`);
+    }
     // Lists are redacted for everyone but the on-prem worker, and only when it calls from inside this process: over the
     // control WS anyone holding the token can claim to be "local". A board on a shared screen is a leak too, so the
     // console reads a PII task's text deliberately, with `ahub task show <id>`.
@@ -489,8 +540,11 @@ export async function startDaemon(opts: DaemonOptions) {
         const overlap = tasks.overlaps(t, t.owner === by);
         return overlap ? `${line(t)}\n${overlap}` : line(t);
       }
-      case "hub_task_accept":
-        return line(tasks.accept(by, a.id));
+      case "hub_task_accept": {
+        const t = tasks.accept(by, a.id, a.plan);
+        const overlap = a.plan == null ? "" : tasks.overlaps(t);
+        return overlap ? `${line(t)}\n${overlap}` : line(t);
+      }
       case "hub_task_decline":
         return line(await tasks.decline(by, a.id, a.reason));
       case "hub_task_done": {
@@ -521,6 +575,25 @@ export async function startDaemon(opts: DaemonOptions) {
         return line(await tasks.escalate(USER, a.id));
       case "route_explain":
         return tasks.explain(a.id !== undefined ? Number(a.id) : { title: String(a.title ?? ""), class: a.class as TaskClass }).join("\n");
+      case "turn_revert": {
+        // `ahub undo --context` (issue #33): the conversation half of an undo; the CLI restores the files itself.
+        const turn = turnLog?.get(String(a.turn));
+        if (!turn) throw new Error(`no turn ${a.turn} recorded`);
+        if (turn.peer !== "codex" || !turn.native) throw new Error(`turn ${turn.id} has no Codex conversation turn to revert`);
+        if (turnLog!.latest("codex")?.id !== turn.id) throw new Error(`turn ${turn.id} is not Codex's latest turn; reverting it would drop the later ones too`);
+        const codex = bus.peers.get("codex");
+        if (!(codex instanceof CodexPeer)) throw new Error("codex is not attached");
+        // Nothing may reach Codex while its history is rewritten: a turn started meanwhile would go with the reverted ones.
+        const held = bus.stateOf("codex") !== "paused";
+        if (held) bus.pause("codex");
+        try {
+          await codex.revert(turn.native);
+        } finally {
+          if (held && !manualPaused.has("codex") && !budget.record("codex")) bus.resume("codex");
+        }
+        log(`turn_revert ${turn.id}: Codex conversation reverted to before ${turn.native}`);
+        return `Codex's conversation no longer holds turn ${turn.id}`;
+      }
     }
     throw new Error(`unknown task operation ${op}`);
   }
@@ -672,12 +745,45 @@ export async function startDaemon(opts: DaemonOptions) {
     if (uiEvents.length > 200) uiEvents.shift();
     if (e.t === "state") {
       log(`state ${e.peer} -> ${e.state}`);
+      event({ type: "state", peer: e.peer, state: e.state });
+      const open = turns.get(e.peer);
+      // The adapter's own state: a pause shows a busy peer as paused, and its turn goes on all the same.
+      const busy = (bus.peers.get(e.peer)?.state ?? e.state) === "busy";
+      if (busy && !open) {
+        const id = `${e.peer}#${runId}.${++turnSeq}`;
+        // A turn of a peer with a PII task open is not snapshotted: what it writes would stay in git's object store until
+        // gc. It is still recorded, without trees, so an overlapping turn's undo knows its changes are unknown.
+        const pii = holdsPii(e.peer);
+        const start = turnLog && !pii ? snap(`the start of ${id}`) : undefined; // before the peer is handed anything: the tap runs inside setState
+        try { turnLog?.begin(id, e.peer, start?.tree); } catch (error) { log(`turn record ${id}: ${(error as Error).message}`); }
+        turns.set(e.peer, { id, start: Date.now(), tokens: 0, ...(start ? { tree: start.tree, snapshotMs: start.ms } : {}), ...(pii ? { private: true } : {}) });
+        event({ type: "turn_start", peer: e.peer, turn: id });
+      } else if (!busy && open) {
+        turns.delete(e.peer);
+        let files: number | undefined;
+        let snapshotMs = open.snapshotMs;
+        if (turnLog && (open.private || holdsPii(e.peer))) {
+          try { turnLog.end(open.id, undefined, [], Math.max(1, Number(config.snapshots.keep) || 20)); } catch (error) { log(`turn record ${open.id}: ${(error as Error).message}`); }
+        } else if (turnLog) {
+          const end = snap(`the end of ${open.id}`);
+          const changed = open.tree && end.tree ? changedPaths(repo!, open.tree, end.tree) : [];
+          if (open.tree && end.tree) files = changed.length; // unknown, not zero, when a snapshot failed
+          snapshotMs = (snapshotMs ?? 0) + end.ms;
+          try { turnLog.end(open.id, end.tree, changed, Math.max(1, Number(config.snapshots.keep) || 20)); } catch (error) { log(`turn record ${open.id}: ${(error as Error).message}`); }
+        }
+        event({ type: "turn_end", peer: e.peer, turn: open.id, ms: Date.now() - open.start, ...(open.tokens ? { tokens: open.tokens } : {}), ...(files !== undefined ? { files, snapshotMs } : {}) });
+      }
       if (e.state === "offline") offlineSince.set(e.peer, offlineSince.get(e.peer) ?? Date.now());
       else offlineSince.delete(e.peer);
     }
-    else if (e.t === "undeliverable") log(`UNDELIVERABLE to ${e.peer} after retries: ${e.env.id} from ${e.env.from}`);
-    else if (e.t === "overflow") log(`OVERFLOW ${e.peer}: dropped ${e.env.id} from ${e.env.from}`);
-    else log(`msg ${e.env.from} -> ${e.env.to?.join(",") ?? "*"} ${e.env.priority} hop=${e.env.hop}${e.dropped ? ` NOT DELIVERED(${e.dropped})` : ""}: ${e.env.body.slice(0, 200)}`);
+    else if (e.t === "undeliverable" || e.t === "overflow") {
+      log(e.t === "undeliverable" ? `UNDELIVERABLE to ${e.peer} after retries: ${e.env.id} from ${e.env.from}` : `OVERFLOW ${e.peer}: dropped ${e.env.id} from ${e.env.from}`);
+      event({ type: e.t, id: e.env.id, from: e.env.from, peer: e.peer });
+    } else {
+      log(`msg ${e.env.from} -> ${e.env.to?.join(",") ?? "*"} ${e.env.priority} hop=${e.env.hop}${e.dropped ? ` NOT DELIVERED(${e.dropped})` : ""}: ${e.env.body.slice(0, 200)}`);
+      const env = e.env;
+      event({ type: "envelope", id: env.id, from: env.from, ...(env.to ? { to: env.to } : {}), priority: env.priority, hop: env.hop, ...(env.kind ? { kind: env.kind } : {}), ...(env.refs?.task ? { task: env.refs.task } : {}), ...(env.private ? {} : { bytes: Buffer.byteLength(env.body) }), ...(env.private ? { private: true } : {}), ...(e.dropped ? { dropped: e.dropped } : {}) });
+    }
     if (!stopping) writeStatus();
   });
 
@@ -839,6 +945,11 @@ export async function startDaemon(opts: DaemonOptions) {
     }
     if (peer === "codex") {
       const codex = new CodexPeer("codex", {
+        onTokens: (added) => void addTokens("codex", added),
+        onTurn: (native) => {
+          const open = turns.get("codex");
+          if (open) turnLog?.native(open.id, native);
+        },
         appPort: opts.codexAppPort,
         proxyPort: opts.codexProxyPort,
         bin: config.codex_bin,
@@ -1425,6 +1536,7 @@ export async function startDaemon(opts: DaemonOptions) {
       await piReceipts?.close();
       budget.close();
       board.close();
+      turnLog?.close();
       server.stop(true);
       try { bus.closeJournal(); } catch { /* the state dir is gone; the journal went with it */ }
     } finally {

package/src/hub/events.ts

@@ -0,0 +1,91 @@
+import { appendFileSync, closeSync, existsSync, fstatSync, openSync, readFileSync, readSync } from "node:fs";
+
+/** Bumped whenever a field changes meaning or goes away; new fields and new types do not bump it. */
+export const EVENTS_SCHEMA = 1;
+
+/**
+ * One line of `events.jsonl`, the machine-readable twin of hub.log (issue #40). Never a message body: envelopes carry
+ * ids, routing and sizes, tasks carry ids and states, so the file can be exported without leaking what agents wrote.
+ */
+export type HubEvent =
+  | { type: "envelope"; id: string; from: string; to?: string[]; priority: string; hop: number; kind?: string; task?: string; bytes?: number; private?: boolean; dropped?: string }
+  | { type: "overflow" | "undeliverable"; id: string; from: string; peer: string }
+  | { type: "state"; peer: string; state: string }
+  | { type: "turn_start"; peer: string; turn: string }
+  | { type: "turn_end"; peer: string; turn: string; ms: number; tokens?: number; files?: number; snapshotMs?: number }
+  | { type: "tokens"; peer: string; n: number }
+  | { type: "task"; id: number; event: string; by: string; state: string; owner: string | null; reviewer: string | null; class: string; pii: boolean }
+  | { type: "overlap"; task: number; owner: string; others: { task: number; owner: string; paths: string[]; symbols?: string[] }[] }
+  | { type: "quota"; peer: string; windows: { id: string; used: number; resetsAt?: number }[]; hard: boolean; measuredAt?: string };
+
+export type StampedEvent = HubEvent & { v: number; at: string };
+
+/** Whether the file's last byte is something other than a newline: a crash cut its last line short. */
+function cutShort(file: string): boolean {
+  if (!existsSync(file)) return false;
+  const fd = openSync(file, "r");
+  try {
+    const { size } = fstatSync(fd);
+    if (!size) return false;
+    const last = Buffer.alloc(1);
+    readSync(fd, last, 0, 1, size - 1);
+    return last[0] !== 0x0a;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** An appender that never throws: the state dir can vanish under a running hub, and telemetry must not take it down. */
+export function eventLog(file: string): (e: HubEvent) => void {
+  let first = true;
+  return (e) => {
+    try {
+      // After a crash the first line goes on a line of its own, so only the cut event is lost.
+      const lead = first && cutShort(file) ? "\n" : "";
+      first = false;
+      appendFileSync(file, `${lead}${JSON.stringify({ v: EVENTS_SCHEMA, at: new Date().toISOString(), ...e })}\n`);
+    } catch {
+      // the state dir is gone; the watchdog is stopping the hub
+    }
+  };
+}
+
+/**
+ * Kimi's running session totals to increments: only what was added since the last update counts; a new session
+ * starts from zero whatever its first total, and a smaller total in the same session means it was reset. (Codex
+ * differences its thread totals in the adapter, which knows whether a thread was started or resumed.)
+ */
+export function tokenDeltas(): (peer: string, total: number, session: string) => number {
+  const last = new Map<string, { session: string; total: number }>();
+  return (peer, total, session) => {
+    const prev = last.get(peer);
+    last.set(peer, { session, total });
+    return prev?.session === session && total >= prev.total ? total - prev.total : total;
+  };
+}
+
+/**
+ * Events at or after `since` (ms), skipping lines a crash cut short.
+ * ponytail: reads the whole file, which is never rotated; rotate by month or index by time when it gets large.
+ */
+export function readEvents(file: string, since = 0): StampedEvent[] {
+  if (!existsSync(file)) return [];
+  return readFileSync(file, "utf8").split("\n").flatMap((line) => {
+    if (!line.trim()) return [];
+    try {
+      const e = JSON.parse(line) as StampedEvent;
+      return Date.parse(e.at) >= since ? [e] : [];
+    } catch {
+      return [];
+    }
+  });
+}
+
+/** `7d`, `24h`, `90m` or an ISO date, as epoch ms; undefined when it is neither. */
+export function parseSince(text: string, now = Date.now()): number | undefined {
+  const m = /^(\d+)([dhm])$/.exec(text);
+  if (m) return now - Number(m[1]) * { d: 86_400_000, h: 3_600_000, m: 60_000 }[m[2] as "d" | "h" | "m"];
+  // ISO dates only: Date.parse also takes "7" (a year in 2001), which would silently mean everything.
+  const t = /^\d{4}-\d\d-\d\d/.test(text) ? Date.parse(text) : NaN;
+  return Number.isNaN(t) ? undefined : t;
+}

package/src/hub/hub-tools.ts

@@ -9,6 +9,18 @@ const refs = {
   properties: { branch: str, commit: str, paths: { type: "array", items: str } },
   additionalProperties: false,
 } as const;
+const list = (description: string) => ({ type: "array", items: str, description }) as const;
+const plan = {
+  type: "object",
+  description: "what you will change, before you start. Owners of open tasks on the same files or symbols see it, and get a notice when your task is done.",
+  properties: {
+    paths: list("files you will edit or create"),
+    symbols: list("functions, types or other names you will change, as they appear in code (e.g. Bus.publish)"),
+    signatures: list("new or changed signatures, as you will write them"),
+    insertion_points: list("where new code goes (file and the function or line it follows)"),
+  },
+  additionalProperties: false,
+} as const;
 
 export interface HubTool {
   name: string;
@@ -23,8 +35,8 @@ const tool = (name: string, description: string, properties: Record<string, unkn
 });
 
 export const TASK_TOOLS: HubTool[] = [
-  tool("hub_task_propose", "Put a piece of work on the shared task board. The hub assigns an owner by class (routing.toml) unless you name one. Classes: plan, implement, bulk_edit, test, review, summarize, triage. Name the class when you know it; without one the hub tries to pick it. Name yourself as owner to claim work nobody assigned you: it starts in progress. Put the paths the work touches in refs; the hub says when they overlap another open task.", { title: str, class: { type: "string", enum: ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"] }, detail: str, refs, owner: { type: "string", description: "peer id; yours to claim the work, omit to let the hub route it" } }, ["title"]),
-  tool("hub_task_accept", "Take a task that was assigned to you.", { id }, ["id"]),
+  tool("hub_task_propose", "Put a piece of work on the shared task board. The hub assigns an owner by class (routing.toml) unless you name one. Classes: plan, implement, bulk_edit, test, review, summarize, triage. Name the class when you know it; without one the hub tries to pick it. Name yourself as owner to claim work nobody assigned you: it starts in progress. Put the paths the work touches in refs, and when you claim work, a plan; the hub says when they overlap another open task.", { title: str, class: { type: "string", enum: ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"] }, detail: str, refs, plan, owner: { type: "string", description: "peer id; yours to claim the work, omit to let the hub route it" } }, ["title"]),
+  tool("hub_task_accept", "Take a task that was assigned to you, with your plan for it.", { id, plan }, ["id"]),
   tool("hub_task_decline", "Pass on a task assigned to you; the hub offers it to the next peer.", { id, reason: str }, ["id"]),
   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"] } }),
@@ -38,7 +50,7 @@ export const TASK_TOOL_NAMES = new Set(TASK_TOOLS.map((t) => t.name));
 /** Role contracts, by role name. Shown to each peer for the roles `.agenthub/config.json` gives it. */
 export const ROLE_TEXT: Record<string, string> = {
   planner: "planner: break work into tasks with hub_task_propose (one outcome each, the right class, paths in refs) instead of doing everything yourself.",
-  implementer: "implementer: accept tasks assigned to you, do them, and finish with hub_task_done (summary: what changed, why, and the check you ran with its result; refs). Decline what you cannot do. Before starting work nobody assigned you, claim it with hub_task_propose naming yourself as owner, with the paths in refs.",
+  implementer: "implementer: accept tasks assigned to you, do them, and finish with hub_task_done (summary: what changed, why, and the check you ran with its result; refs). Decline what you cannot do. Before starting work nobody assigned you, claim it with hub_task_propose naming yourself as owner, with the paths in refs. With a claim or an accept, give a plan: the files, symbols and signatures you will change and where new code goes.",
   verifier: "verifier: run the checks a task names and report what passed and what did not in hub_task_done.",
   reviewer: "reviewer: when asked to review, read the change itself, then hub_review with approved or changes_requested and a note that says what to fix.",
 };