@staix/agent-hub 0.7.11 → 0.8.1

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

package/src/hub/lifecycle.ts

@@ -179,6 +179,15 @@ export async function startProject(project: Project, options: { unattended?: boo
   } finally { registry.close(); }
 }
 
+/** Whether `instanceId` still holds the project's registry claim, counted as held while its process may be alive. */
+function claimHeld(id: string, instanceId: string): boolean {
+  const registry = new Registry();
+  try {
+    const row = registry.get(id);
+    return row?.instanceId === instanceId && (row.pid === null || processAlive(row.pid) !== false);
+  } finally { registry.close(); }
+}
+
 export async function stopProject(project: Project, expectedInstance?: string): Promise<void> {
   assertLifecycleAvailable();
   const inspection = await inspectProject(project);
@@ -194,8 +203,10 @@ export async function stopProject(project: Project, expectedInstance?: string):
   const deadline = Date.now() + 10_000;
   while (Date.now() < deadline) {
     const current = readControl(project.stateDir);
-    if (!current) return; // daemon removes its manifest only after owned children stop
-    if (current.instanceId !== instanceId) throw new Error("a new hub instance started; it was not stopped");
+    // The daemon removes its manifest only after owned children stop; its process releases the registry claim just
+    // after that. Until then `projects remove` refuses and `up` reads the project as starting, so wait for both.
+    if (!current && !claimHeld(project.id, instanceId)) return;
+    if (current && current.instanceId !== instanceId) throw new Error("a new hub instance started; it was not stopped");
     await Bun.sleep(100);
   }
   throw new Error("shutdown is still pending; state and ownership were retained");

package/src/hub/report.ts

@@ -0,0 +1,68 @@
+import type { StampedEvent } from "./events.ts";
+
+export interface Report {
+  from?: string;
+  to?: string;
+  peers: Record<string, { turns: number; busyMinutes: number; tokens: number }>;
+  messages: { total: number; dropped: Record<string, number>; overflow: number; undeliverable: number; perTask: number };
+  overlaps: { warnings: number; pairs: number };
+  tasks: Record<string, number>;
+  quota: { readings: number; hard: number };
+}
+
+/** The numbers `ahub report` prints, from `events.jsonl` alone (issue #40). */
+export function summarize(events: StampedEvent[]): Report {
+  const r: Report = { peers: {}, messages: { total: 0, dropped: {}, overflow: 0, undeliverable: 0, perTask: 0 }, overlaps: { warnings: 0, pairs: 0 }, tasks: {}, quota: { readings: 0, hard: 0 } };
+  const peer = (id: string) => (r.peers[id] ??= { turns: 0, busyMinutes: 0, tokens: 0 });
+  const pairs = new Set<string>();
+  const taskMessages = new Map<string, number>();
+  for (const e of events) {
+    r.from ??= e.at;
+    r.to = e.at;
+    switch (e.type) {
+      case "envelope":
+        r.messages.total++;
+        if (e.dropped) r.messages.dropped[e.dropped] = (r.messages.dropped[e.dropped] ?? 0) + 1;
+        if (e.task) taskMessages.set(e.task, (taskMessages.get(e.task) ?? 0) + 1);
+        break;
+      case "overflow":
+      case "undeliverable":
+        r.messages[e.type]++;
+        break;
+      case "turn_end":
+        peer(e.peer).turns++;
+        peer(e.peer).busyMinutes += e.ms / 60_000;
+        break;
+      case "tokens":
+        peer(e.peer).tokens += e.n;
+        break;
+      case "task":
+        r.tasks[e.event] = (r.tasks[e.event] ?? 0) + 1;
+        break;
+      case "overlap":
+        r.overlaps.warnings++;
+        for (const o of e.others) pairs.add([e.task, o.task].sort((a, b) => a - b).join("-"));
+        break;
+      case "quota":
+        r.quota.readings++;
+        if (e.hard) r.quota.hard++;
+        break;
+    }
+  }
+  r.overlaps.pairs = pairs.size;
+  r.messages.perTask = taskMessages.size ? Number(([...taskMessages.values()].reduce((a, b) => a + b, 0) / taskMessages.size).toFixed(1)) : 0;
+  for (const p of Object.values(r.peers)) p.busyMinutes = Number(p.busyMinutes.toFixed(1));
+  return r;
+}
+
+export function formatReport(r: Report): string[] {
+  const lines = [`period: ${r.from ?? "-"} .. ${r.to ?? "-"}`];
+  for (const [id, p] of Object.entries(r.peers).sort(([a], [b]) => a.localeCompare(b))) lines.push(`peer ${id}: ${p.turns} turn${p.turns === 1 ? "" : "s"}, ${p.busyMinutes} busy minutes, ${p.tokens || "-"} tokens`);
+  const dropped = Object.entries(r.messages.dropped).map(([k, n]) => `${n} ${k}`).join(", ");
+  lines.push(`messages: ${r.messages.total} (dropped: ${dropped || "none"}; overflow ${r.messages.overflow}; undeliverable ${r.messages.undeliverable}); ${r.messages.perTask} per task that had any`);
+  lines.push(`overlap warnings: ${r.overlaps.warnings}, task pairs: ${r.overlaps.pairs}`);
+  const tasks = Object.entries(r.tasks).sort().map(([k, n]) => `${k} ${n}`).join(", ");
+  lines.push(`task events: ${tasks || "none"}`);
+  lines.push(`quota readings: ${r.quota.readings} (${r.quota.hard} hard limits)`);
+  return lines;
+}

package/src/hub/snapshots.ts

@@ -0,0 +1,191 @@
+import { Database } from "bun:sqlite";
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { childEnv } from "./child-process.ts";
+
+/**
+ * Per-turn workspace snapshots (issue #33): git tree objects written through a copy of the index, so the user's index
+ * and HEAD never change. They hold tracked and unignored files as `git add -A` sees them, shell-made changes included.
+ * ponytail: snapshots run synchronously on the turn boundary (before the agent sees its prompt); a very large tree
+ * costs that much latency per turn, `snapshots.enabled` is the switch and `turn_end.snapshotMs` the measurement.
+ * ponytail: the trees are unreferenced, so `git gc` may prune them after gc.pruneExpire (two weeks by default); undo
+ * of an older turn says so. Refs under refs/agenthub/ would keep them, at the cost of showing up in the user's repo.
+ */
+const git = (top: string, args: string[], env: Record<string, string> = {}) =>
+  spawnSync("git", ["-C", top, ...args], {
+    encoding: "utf8",
+    env: { ...childEnv(process.env), ...env },
+    // These run inside the bus's state change: a hung git (a huge new directory, a stuck filter) must not freeze the hub.
+    timeout: SNAPSHOT_TIMEOUT_MS,
+  });
+const SNAPSHOT_TIMEOUT_MS = 10_000;
+
+/** A repository and where the project sits in it: `prefix` is "" at the top level, else "sub/dir/". */
+export interface Repo {
+  top: string;
+  dir: string;
+  prefix: string;
+}
+
+/** The repository holding `root`, or undefined when it is not inside a work tree. */
+export function repoOf(root: string): Repo | undefined {
+  const r = git(root, ["rev-parse", "--show-toplevel", "--absolute-git-dir", "--show-prefix"]);
+  if (r.status !== 0) return undefined;
+  const [top, dir, prefix = ""] = r.stdout.replace(/\n$/, "").split("\n");
+  return top && dir ? { top, dir, prefix } : undefined;
+}
+
+/**
+ * A path as a pathspec that means only itself: `app/[slug]/page.tsx` must not match `app/s/page.tsx`. Per-path
+ * `:(literal)` rather than --literal-pathspecs, which would also switch off the state exclude's glob.
+ */
+const literal = (path: string) => `:(literal)${path}`;
+/** Only the project's own files: a hub in a subdirectory of a larger repository snapshots that subdirectory. */
+const scope = (repo: Repo) => (repo.prefix ? literal(repo.prefix) : ".");
+
+/** A tree id for the project's files as they are now, leaving out the hub's own state. */
+export function snapshot(repo: Repo): string | undefined {
+  const tmp = mkdtempSync(join(tmpdir(), "ahub-snap-"));
+  try {
+    const env = { GIT_INDEX_FILE: join(tmp, "index") };
+    if (existsSync(join(repo.dir, "index"))) copyFileSync(join(repo.dir, "index"), env.GIT_INDEX_FILE);
+    if (git(repo.top, ["add", "-A", "--", scope(repo), ":(exclude,glob)**/.agenthub/state/**"], env).status !== 0) return undefined;
+    // The copy starts from the user's index: hub state somebody tracked or staged is still in it, and the exclude above
+    // only keeps `add` from touching it. Take it out explicitly; -f because staged state the hub has rewritten since
+    // matches neither HEAD nor the file, which `rm --cached` otherwise refuses. Only the copy changes.
+    if (git(repo.top, ["rm", "-r", "-f", "--cached", "--quiet", "--ignore-unmatch", "--", ":(glob)**/.agenthub/state/**"], env).status !== 0) return undefined;
+    const r = git(repo.top, ["write-tree"], env);
+    return r.status === 0 ? r.stdout.trim() : undefined;
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+/** Project paths (relative to the top level) that differ between two trees. */
+export function changedPaths(repo: Repo, from: string, to: string): string[] {
+  const r = git(repo.top, ["diff-tree", "-r", "--no-renames", "--name-only", "-z", from, to, "--", scope(repo)]);
+  return r.status === 0 ? r.stdout.split("\0").filter(Boolean) : [];
+}
+
+const inTree = (top: string, tree: string, path: string) => git(top, ["rev-parse", "--verify", "--quiet", `${tree}:${path}`]).status === 0;
+
+/** Whether a snapshot's tree is still in the object store (`git gc` prunes unreferenced ones eventually). */
+export const hasTree = (top: string, tree: string): boolean => git(top, ["cat-file", "-e", `${tree}^{tree}`]).status === 0;
+
+export interface UndoPlan {
+  restore: string[];
+  /** Changed again after the turn ended (by anyone): restoring them would destroy that work. */
+  changedSince: string[];
+  /** Also changed by another peer's turn that overlapped this one: the change may be theirs. */
+  concurrent: string[];
+  /** Every path the turn changed is already as it was when the turn started. */
+  undone: boolean;
+}
+
+/**
+ * What undoing a turn would do. The current state is read the way the snapshots are (one more snapshot), so modes,
+ * symlinks, directories and filters compare like for like. A path is refused when anything at or under it differs
+ * from what the turn left, or when an overlapping turn of another peer changed it too.
+ */
+export function planUndo(repo: Repo, turn: { start_tree: string; end_tree: string; changed: string[] }, overlapping: string[] = []): UndoPlan {
+  const now = snapshot(repo);
+  if (!now) throw new Error("could not read the work tree (see git's output above, or try again)");
+  const hit = (paths: string[], p: string) => paths.some((d) => d === p || d.startsWith(`${p}/`));
+  const sinceEnd = changedPaths(repo, turn.end_tree, now);
+  const sinceStart = changedPaths(repo, turn.start_tree, now);
+  const plan: UndoPlan = { restore: [], changedSince: [], concurrent: [], undone: turn.changed.length > 0 && turn.changed.every((p) => !hit(sinceStart, p)) };
+  for (const p of turn.changed) {
+    if (hit(sinceEnd, p)) plan.changedSince.push(p);
+    else if (hit(overlapping, p)) plan.concurrent.push(p);
+    else plan.restore.push(p);
+  }
+  return plan;
+}
+
+/**
+ * Puts each path back as it was when the turn started; a file the turn created is removed (never a directory: the
+ * plan refuses a path with anything under it). The index is untouched.
+ */
+export function restore(repo: Repo, startTree: string, paths: string[]): void {
+  // Removals first: after a case-only rename on a case-insensitive disk, `Foo.ts` and `foo.ts` are one file, and
+  // removing the created spelling after restoring the old one would delete it.
+  const back = paths.filter((p) => inTree(repo.top, startTree, p));
+  for (const path of paths.filter((p) => !back.includes(p))) rmSync(join(repo.top, path), { force: true });
+  for (const path of back) {
+    if (git(repo.top, ["restore", `--source=${startTree}`, "--worktree", "--", literal(path)]).status !== 0) throw new Error(`could not restore ${path}`);
+  }
+}
+
+export interface TurnRecord {
+  id: string;
+  peer: string;
+  started: number;
+  ended: number | null;
+  start_tree: string | null;
+  end_tree: string | null;
+  changed: string[];
+  native: string | null;
+}
+
+/** Turn records in hub.db: the daemon writes them, `ahub turns` and `ahub undo` read them. */
+export class Turns {
+  private readonly db: Database;
+  constructor(path: string, readonly?: boolean) {
+    this.db = new Database(path, readonly ? { readonly: true } : { create: true });
+    if (readonly) return;
+    this.db.run("PRAGMA journal_mode = WAL");
+    this.db.run(`CREATE TABLE IF NOT EXISTS turns (id TEXT PRIMARY KEY, peer TEXT NOT NULL, started INTEGER NOT NULL, ended INTEGER,
+      start_tree TEXT, end_tree TEXT, changed TEXT NOT NULL DEFAULT '[]', native TEXT)`);
+    // Opened by a starting hub: a turn still open was cut short when the last run stopped. It has no end snapshot, and
+    // it may have run until now, so its window ends now (other turns that overlapped it stay unknowable).
+    this.db.query("UPDATE turns SET ended = ? WHERE ended IS NULL").run(Date.now());
+  }
+  begin(id: string, peer: string, startTree: string | undefined): void {
+    this.db.query("INSERT OR REPLACE INTO turns (id, peer, started, start_tree) VALUES (?, ?, ?, ?)").run(id, peer, Date.now(), startTree ?? null);
+  }
+  /** The first native turn of a hub turn: reverting the conversation drops it and every later one. */
+  native(id: string, native: string): void {
+    this.db.query("UPDATE turns SET native = ? WHERE id = ? AND native IS NULL").run(native, id);
+  }
+  end(id: string, endTree: string | undefined, changed: string[], keep: number): void {
+    this.db.query("UPDATE turns SET ended = ?, end_tree = ?, changed = ? WHERE id = ?").run(Date.now(), endTree ?? null, JSON.stringify(changed), id);
+    const peer = (this.db.query("SELECT peer FROM turns WHERE id = ?").get(id) as { peer: string } | null)?.peer;
+    if (peer) this.db.query("DELETE FROM turns WHERE peer = ? AND id NOT IN (SELECT id FROM turns WHERE peer = ? ORDER BY started DESC, rowid DESC LIMIT ?)").run(peer, peer, keep);
+  }
+  list(peer?: string, limit = 20): TurnRecord[] {
+    const rows = (peer
+      ? this.db.query("SELECT * FROM turns WHERE peer = ? ORDER BY started DESC, rowid DESC LIMIT ?").all(peer, limit)
+      : this.db.query("SELECT * FROM turns ORDER BY started DESC, rowid DESC LIMIT ?").all(limit)) as (Omit<TurnRecord, "changed"> & { changed: string })[];
+    return rows.map((r) => ({ ...r, changed: JSON.parse(r.changed) as string[] }));
+  }
+  get(id: string): TurnRecord | undefined {
+    const r = this.db.query("SELECT * FROM turns WHERE id = ?").get(id) as (Omit<TurnRecord, "changed"> & { changed: string }) | null;
+    return r ? { ...r, changed: JSON.parse(r.changed) as string[] } : undefined;
+  }
+  /**
+   * Other peers' turns that overlapped this one in time: their changes are in this turn's diff too. `unknown` lists
+   * those whose changes cannot be known (still running, cut short by a stop, a failed snapshot, a PII turn), and a
+   * peer whose `keep` records all start after this turn: its turns from then may have been pruned.
+   */
+  // ponytail: pruning is inferred from `keep` as the CLI reads it now; a `keep` raised while the hub runs (which prunes
+  // with the value it started with) can hide a pruned overlap until the hub restarts. Record a per-peer "pruned
+  // before" time in Turns.end if that ever matters.
+  overlapping(turn: TurnRecord, keep: number): { paths: string[]; unknown: string[] } {
+    const rows = this.db.query("SELECT id, changed, ended, start_tree, end_tree FROM turns WHERE id != ? AND peer != ? AND started < ? AND (ended IS NULL OR ended > ?)").all(turn.id, turn.peer, turn.ended ?? Date.now(), turn.started) as { id: string; changed: string; ended: number | null; start_tree: string | null; end_tree: string | null }[];
+    const known = rows.filter((r) => r.ended !== null && r.start_tree !== null && r.end_tree !== null);
+    const pruned = (this.db.query("SELECT peer, MIN(started) AS oldest FROM turns WHERE peer != ? GROUP BY peer HAVING COUNT(*) >= ?").all(turn.peer, keep) as { peer: string; oldest: number }[])
+      .filter((p) => p.oldest > turn.started)
+      .map((p) => `${p.peer} (its turns from then were pruned)`);
+    return { paths: [...new Set(known.flatMap((r) => JSON.parse(r.changed) as string[]))], unknown: [...rows.filter((r) => !known.includes(r)).map((r) => r.id), ...pruned] };
+  }
+
+  /** The latest turn of a peer: a conversation can only be reverted from its latest turn. */
+  latest(peer: string): TurnRecord | undefined {
+    return this.list(peer, 1)[0];
+  }
+  close(): void {
+    this.db.close();
+  }
+}

package/src/hub/tasks.ts

@@ -1,6 +1,6 @@
 import type { Briefs } from "../memory/brief.ts";
 import type { MemoryClient } from "../memory/client.ts";
-import { CLASSES, type Board, type Task, type TaskClass, type TaskRefs } from "./board.ts";
+import { CLASSES, PLAN_KEYS, type Board, type Task, type TaskClass, type TaskPlan, type TaskRefs } from "./board.ts";
 import type { Bus } from "./bus.ts";
 import { HUB, newEnvelope, NOTE_KINDS, noteLine, USER, type Envelope, type PeerId, type PeerState } from "./envelope.ts";
 import { assign, detectSignals, LOCAL, PI, type Assignment, type Routing } from "./routing.ts";
@@ -23,6 +23,8 @@ export interface TasksDeps {
   share?: (by: PeerId, line: string) => void;
   /** Hands one peer a line that rides on its next delivery, without a turn of its own (issue #6). */
   tell?: (peer: PeerId, line: string) => void;
+  /** Structured overlap records for telemetry (issue #40); the notice line stays for the human. */
+  recordOverlap?: (task: number, owner: PeerId, others: { task: number; owner: PeerId; paths: string[]; symbols?: string[] }[]) => void;
   /** Optional: name a class for a task proposed without one. `onCampus` says whether the model call stays on campus. */
   triage?: { classify: (title: string, detail: string) => Promise<TaskClass | undefined>; onCampus: () => Promise<boolean> };
 }
@@ -39,17 +41,31 @@ const samePlace = (a: string, b: string) => {
   return x === "." || y === "." || x === y || x.startsWith(`${y}/`) || y.startsWith(`${x}/`);
 };
 
+/** One line of model-written text: whitespace (newlines included) collapses, so it can never start a forged log line. */
+const text = (v: unknown) => (typeof v === "string" && v.trim() ? v.replace(/\s+/g, " ").trim().slice(0, 300) : undefined);
+/** A list of short strings; a lone string counts as a list of one. */
+const textList = (v: unknown) => (Array.isArray(v) ? v : typeof v === "string" ? [v] : []).map(text).filter((p): p is string => !!p).slice(0, 50);
+const fields = (input: unknown) => (input && typeof input === "object" && !Array.isArray(input) ? input : {}) as Record<string, unknown>;
+
 /** Tool callers are models: inputSchema is not enforced on the way in, so refs are normalized before they reach the board. */
 function cleanRefs(input: unknown): TaskRefs {
-  const r = (input && typeof input === "object" ? input : {}) as Record<string, unknown>;
-  const text = (v: unknown) => (typeof v === "string" && v.trim() ? v.trim().slice(0, 300) : undefined);
-  const paths = (Array.isArray(r.paths) ? r.paths : typeof r.paths === "string" ? [r.paths] : []).map(text).filter((p): p is string => !!p).slice(0, 50);
+  const r = fields(input);
+  const paths = textList(r.paths);
   const out: TaskRefs = {};
   for (const k of ["repo", "branch", "commit"] as const) if (text(r[k])) out[k] = text(r[k])!;
   if (paths.length) out.paths = paths;
   return out;
 }
 
+/** The same for a plan (issue #31): only its four lists, each of short strings. */
+function cleanPlan(input: unknown): TaskPlan {
+  const r = fields(input);
+  return Object.fromEntries(PLAN_KEYS.map((k) => [k, textList(r[k])] as const).filter(([, v]) => v.length));
+}
+
+/** A plan as one line for other owners; the whole plan is on the board. */
+const planText = (plan: TaskPlan = {}) => PLAN_KEYS.filter((k) => plan[k]?.length).map((k) => `${k.replace("_", " ")}: ${plan[k]!.join("; ")}`).join(" | ");
+
 /**
  * The task flow. Adapters and tools never touch the board: every change comes through here, where assignment,
  * PII handling, envelopes, briefs and memory notes are decided in one place.
@@ -76,20 +92,23 @@ export class Tasks {
   /** A task as a cloud peer may see it. */
   publicView(task: Task): Record<string, unknown> {
     const { title, detail, history, ...rest } = task;
-    return this.isPii(task) ? { ...rest, refs: {}, title: "[pii]", detail: "[pii]" } : { ...rest, title, detail, history: history.slice(-5) };
+    return this.isPii(task) ? { ...rest, refs: {}, plan: {}, title: "[pii]", detail: "[pii]" } : { ...rest, title, detail, history: history.slice(-5) };
   }
 
   private states(): Record<PeerId, PeerState> {
     return Object.fromEntries([...this.d.bus.peers.keys()].map((id) => [id, this.d.bus.stateOf(id)]));
   }
 
-  async propose(by: PeerId, input: { title?: string; detail?: string; class?: string; refs?: TaskRefs; owner?: PeerId }): Promise<Task> {
-    const title = String(input.title ?? "").trim().slice(0, 300); // callers are models: a title is a line, not a document
+  async propose(by: PeerId, input: { title?: string; detail?: string; class?: string; refs?: TaskRefs; plan?: TaskPlan; owner?: PeerId }): Promise<Task> {
+    // Callers are models: a title is one line (it is part of console and hub.log lines), not a document.
+    const title = String(input.title ?? "").replace(/\s+/g, " ").trim().slice(0, 300);
     if (!title) throw new Error("title is required");
     const given = input.class === undefined || input.class === "" ? undefined : input.class;
     if (given !== undefined && !CLASSES.includes(given as TaskClass)) throw new Error(`class must be one of ${CLASSES.join(", ")}`);
     const text = { title, detail: String(input.detail ?? "").slice(0, 8000), refs: cleanRefs(input.refs) };
-    const signals = detectSignals(text, this.d.routing(), this.d.cwd);
+    const plan = cleanPlan(input.plan);
+    // The plan reaches other owners, so a PII pattern in it makes the task a PII task like one in the detail would.
+    const signals = detectSignals({ ...text, detail: [text.detail, planText(plan)].join("\n") }, this.d.routing(), this.d.cwd);
     let cls = given as TaskClass | undefined;
     let triaged = false;
     if (!cls && this.d.triage) {
@@ -103,7 +122,7 @@ export class Tasks {
     if (defaulted) cls = "implement";
     if (!cls) throw new Error(`class is required (one of ${CLASSES.join(", ")}); the hub could not name one for you`);
     const draft = { ...text, class: cls };
-    let task = this.d.board.propose(by, { ...draft, signals });
+    let task = this.d.board.propose(by, { ...draft, plan, signals });
     if (triaged) task = this.d.board.update(task.id, "hub", "triaged", {}, `class ${cls} named by the hub's model`);
     if (defaulted) task = this.d.board.update(task.id, "hub", "class defaulted", {}, "class implement for a claim without one");
     this.d.notify(`task ${this.publicTitle(task)} proposed by ${by} [${task.class}]${task.signals.length ? ` signals: ${task.signals.join(", ")}` : ""}`);
@@ -116,8 +135,8 @@ export class Tasks {
    * only the new owner reads "settle it"; anyone else learns that the owner was told. PII tasks are left out on both
    * sides: their refs are hidden from cloud peers.
    */
-  overlaps(task: Task, forOwner = true): string {
-    const hits = this.overlapHits(task).map((h) => `#${h.task.id} (owner ${h.task.owner}) on ${h.paths.join(", ")}`);
+  overlaps(task: Task, forOwner = true, found = this.overlapHits(task)): string {
+    const hits = found.map((h) => `#${h.task.id} (owner ${h.task.owner}) on ${this.where(h)}`);
     if (!hits.length) return "";
     const who = forOwner ? "Settle it with that owner via hub_send before editing those paths." : `${task.owner ?? "Whoever takes it"} is told to settle it.`;
     return `Overlaps ${hits.join("; ")}. ${who}`;
@@ -126,22 +145,48 @@ export class Tasks {
   /** While a gone owner's tasks move, its other tasks are about to move too: they are no one to settle with. */
   private releasing: PeerId | undefined;
 
-  private overlapHits(task: Task): { task: Task; paths: string[] }[] {
-    const mine = task.refs.paths ?? [];
-    if (!mine.length || this.isPii(task)) return [];
+  /** Whether a model-written name may be shown to other peers and in the log: one matching a PII pattern may be PII. */
+  private nameable = (t: string): boolean => !this.isPii({ signals: detectSignals({ title: "", detail: t, refs: {} }, this.d.routing(), this.d.cwd) });
+
+  /** Where two tasks meet: shared paths, then shared symbols, leaving out any name that matches a PII pattern. */
+  private where(hit: { paths: string[]; symbols: string[] }): string {
+    const shown = [...hit.paths.filter(this.nameable), ...hit.symbols.filter(this.nameable).map((s) => `symbol ${s}`)];
+    return shown.length ? shown.join(", ") : "a path whose name is withheld (it matches a PII pattern)";
+  }
+
+  /** Paths from refs and plan, symbols from the plan: the places a task says it touches (issue #31). */
+  private places(task: Task): { paths: string[]; symbols: string[] } {
+    return { paths: [...new Set([...(task.refs.paths ?? []), ...(task.plan?.paths ?? [])])], symbols: task.plan?.symbols ?? [] };
+  }
+
+  private overlapHits(task: Task): { task: Task; paths: string[]; symbols: string[] }[] {
+    const mine = this.places(task);
+    if ((!mine.paths.length && !mine.symbols.length) || this.isPii(task)) return [];
     return this.d.board.list().flatMap((t) => {
       if (t.id === task.id || !t.owner || t.owner === task.owner || t.owner === this.releasing || !OPEN.includes(t.state) || this.isPii(t)) return [];
-      const paths = mine.filter((p) => (t.refs.paths ?? []).some((q) => samePlace(p, q)));
-      return paths.length ? [{ task: t, paths }] : [];
+      const theirs = this.places(t);
+      const paths = mine.paths.filter((p) => theirs.paths.some((q) => samePlace(p, q)));
+      const symbols = mine.symbols.filter((x) => theirs.symbols.includes(x));
+      return paths.length || symbols.length ? [{ task: t, paths, symbols }] : [];
     });
   }
 
-  /** The earlier owner hears of an overlap on its next delivery, costing it no turn; the newcomer settles it (#6). */
-  private tellEarlierOwners(task: Task): void {
+  /** The console notice and the telemetry record of an overlap; the two are counted against each other (issue #40). */
+  private announceOverlap(task: Task, hits: ReturnType<Tasks["overlapHits"]>): void {
+    this.d.notify(`task ${this.publicTitle(task)} (${task.owner}): ${this.overlaps(task, false, hits)}`);
+    this.d.recordOverlap?.(task.id, task.owner!, hits.map((h) => ({ task: h.task.id, owner: h.task.owner!, paths: h.paths.filter(this.nameable), ...(h.symbols.length ? { symbols: h.symbols.filter(this.nameable) } : {}) })));
+  }
+
+  /**
+   * The earlier owners hear of an overlap on their next delivery, costing them no turn; the newcomer settles it (#6).
+   * Its plan rides along, so they know what it will touch (issue #31).
+   */
+  private tellEarlierOwners(task: Task, hits = this.overlapHits(task)): void {
     if (!task.owner || !this.d.tell) return;
-    for (const hit of this.overlapHits(task)) {
+    const plan = planText(task.plan);
+    for (const hit of hits) {
       if (hit.task.owner === USER || hit.task.owner === HUB) continue;
-      this.d.tell(hit.task.owner!, noteLine(HUB, "finding", `task #${task.id} (owner ${task.owner}) now overlaps your #${hit.task.id} on ${hit.paths.join(", ")}; ${task.owner} is told to settle it`));
+      this.d.tell(hit.task.owner!, noteLine(HUB, "finding", `task #${task.id} (owner ${task.owner}) now overlaps your #${hit.task.id} on ${this.where(hit)}; ${task.owner} is told to settle it${plan ? `. Its plan (full: hub_task_list): ${plan}` : ""}`));
     }
   }
 
@@ -198,17 +243,17 @@ export class Tasks {
       return opts.clearOnFail && task.owner ? this.d.board.update(task.id, by, "unassigned", { owner: null }) : task;
     }
     const next = this.d.board.update(task.id, by, opts.event ?? "assigned", { owner: a.owner, reviewer: a.reviewer ?? null, ...(opts.event === "escalated" ? { rejections: 0 } : {}) }, opts.note ?? `to ${a.owner}`);
-    const overlap = this.overlaps(next, false);
-    if (overlap) {
-      this.d.notify(`task ${this.publicTitle(next)} (${next.owner}): ${overlap}`);
-      this.tellEarlierOwners(next);
+    const hits = this.overlapHits(next);
+    if (hits.length) {
+      this.announceOverlap(next, hits);
+      this.tellEarlierOwners(next, hits);
     }
     if (opts.claim && a.owner === by) {
       const claimed = this.d.board.update(next.id, by, "accepted", { state: "in_progress" });
       this.d.notify(`task ${this.publicTitle(claimed)} claimed by ${by}`);
       return claimed;
     }
-    await this.sendTask(next, a, opts.context, this.overlaps(next));
+    await this.sendTask(next, a, opts.context, this.overlaps(next, true, hits));
     return next;
   }
 
@@ -217,16 +262,18 @@ export class Tasks {
     const brief = pii ? undefined : await this.d.briefs?.forTask(task.owner!, task).catch(() => undefined);
     const rejected = task.history.filter((h) => h.event === "changes_requested").map((h) => `- ${h.by}: ${h.note ?? ""}`);
     const facts = [`class ${task.class}`, a.owner === PI ? `backend pi/${a.piBackend ?? "dgx"}` : "", task.refs.paths?.length ? `paths ${task.refs.paths.join(", ")}` : "", task.refs.branch ? `branch ${task.refs.branch}` : "", a.reviewer ? `reviewer ${a.reviewer}` : "no reviewer"].filter(Boolean).join("; ");
+    const plan = planText(task.plan);
     const body = [
       `Task #${task.id} [${task.class}] ${task.title}`,
       task.detail,
       `Facts: ${facts}`,
+      plan ? `Plan so far: ${plan}` : "",
       overlap,
       rejected.length ? `Earlier review notes:\n${rejected.join("\n")}` : "",
       brief ?? "",
       // What the previous owner left behind. Peer-written free text: never attached to a PII task.
       context && !pii ? `Handoff from the previous owner:\n${context.slice(0, 3000)}` : "",
-      `Take it with hub_task_accept {id: ${task.id}} or pass with hub_task_decline. When finished: hub_task_done {id: ${task.id}, summary: what changed, why, and the check you ran with its result, refs}.`,
+      `Take it with hub_task_accept {id: ${task.id}, plan: {paths, symbols, signatures, insertion_points}} (what you will change, before you start${pii ? "" : "; owners of overlapping tasks see it"}) or pass with hub_task_decline. When finished: hub_task_done {id: ${task.id}, summary: what changed, why, and the check you ran with its result, refs}.`,
     ].filter(Boolean).join("\n\n");
     this.d.bus.publish(newEnvelope(HUB, body, { to: [task.owner!], kind: "task", priority: "important", refs: { ...task.refs, task: String(task.id) }, ...(pii ? { private: true } : {}) }));
   }
@@ -243,11 +290,29 @@ export class Tasks {
     return task;
   }
 
-  accept(by: PeerId, id: unknown): Task {
+  /**
+   * With a plan, the owners of overlapping tasks get it as a ride-along line, and an overlap only the plan reveals is
+   * announced like one found at assignment (issue #31).
+   */
+  accept(by: PeerId, id: unknown, plan?: unknown): Task {
     const task = this.need(id);
     this.mine(task, by, "owner");
-    const next = this.d.board.update(task.id, by, "accepted", { state: "in_progress" });
+    // Models send null or {} for an optional field they leave empty: neither replaces a plan.
+    const given = plan == null ? undefined : cleanPlan(plan);
+    const cleaned = given && Object.keys(given).length ? given : undefined;
+    // A task's signals are fixed when it is proposed: text that matches a PII pattern cannot be let in afterwards.
+    if (cleaned && !this.isPii(task) && this.isPii({ signals: detectSignals({ title: "", detail: planText(cleaned), refs: {} }, this.d.routing(), this.d.cwd) })) {
+      throw new Error("this plan matches a PII pattern and is not kept: other owners would see it");
+    }
+    const before = new Set(this.overlapHits(task).map((h) => h.task.id));
+    const next = this.d.board.update(task.id, by, "accepted", { state: "in_progress", ...(cleaned ? { plan: cleaned } : {}) });
     this.d.notify(`task ${this.publicTitle(next)} accepted by ${by}`);
+    if (cleaned) {
+      const hits = this.overlapHits(next);
+      const fresh = hits.filter((h) => !before.has(h.task.id));
+      if (fresh.length) this.announceOverlap(next, fresh);
+      this.tellEarlierOwners(next, hits);
+    }
     return next;
   }
 
@@ -318,12 +383,38 @@ export class Tasks {
     const reviewer = task.reviewer;
     const next = this.d.board.update(task.id, by, "done", { state: reviewer ? "in_review" : "approved", refs: cleanRefs(refs) }, checkOutput ? `${summary ?? ""}\n${checkOutput}`.trim() : summary);
     this.note(next, by, "finding", `Task #${next.id} done by ${by}: ${next.title}\n${summary ?? ""}`);
+    this.tellCompleted(next, summary);
     if (!reviewer) this.d.notify(`task ${this.publicTitle(next)} done by ${by}, no reviewer: approved`);
     else if (reviewer === USER) this.d.notify(`task ${this.publicTitle(next)} done by ${by}: review it with ahub task show ${next.id}, then ahub review ${next.id} approved|changes_requested [note]`);
     else this.sendReview(next, reviewer);
     return next;
   }
 
+  /**
+   * "Passes alone, fails together": the owners of open tasks on the same places hear what changed under them, once the
+   * work is done (after its check, when one runs), and nobody else does (issue #31). A message of its own, not a
+   * ride-along line: an owner in the middle of those files needs it before its next task arrives.
+   */
+  private tellCompleted(task: Task, summary?: string): void {
+    const hits = this.overlapHits(task).filter((h) => h.task.owner !== USER && h.task.owner !== HUB);
+    if (!hits.length) return;
+    // Files, signatures and the summary are the owner's own words (paths given at done included): any item that
+    // matches a PII pattern is left out of what other owners get.
+    const paths = this.places(task).paths.filter(this.nameable);
+    const signatures = (task.plan?.signatures ?? []).filter(this.nameable);
+    const first = (summary ?? "").split("\n").find((l) => l.trim())?.trim().slice(0, 300);
+    const line = first && this.nameable(first) ? first : undefined;
+    for (const hit of hits) {
+      const body = [
+        `Task #${task.id} (owner ${task.owner}) is done and touches your open #${hit.task.id} on ${this.where(hit)}. Check your work against it before you go on.`,
+        paths.length ? `Changed files: ${paths.join(", ")}` : "",
+        signatures.length ? `New or changed signatures: ${signatures.join("; ")}` : "",
+        line ? `Summary: ${line}` : "",
+      ].filter(Boolean).join("\n");
+      this.d.bus.publish(newEnvelope(HUB, body, { to: [hit.task.owner!], kind: "task", refs: { task: String(hit.task.id) } }));
+    }
+  }
+
   /** The one place a review request is written: the first reviewer and a replacement get the same text, refs and privacy. */
   private sendReview(task: Task, reviewer: PeerId, why = ""): void {
     const r = task.refs;

package/templates/AGENTS.block.md

@@ -9,5 +9,5 @@ This project runs agent-hub: other coding agents (claude, codex, kimi, pi, local
 - Start a message or final answer with `[IMPORTANT]` only when the others must see it now; `[FYI]` is recorded and costs nobody a turn. Unmarked answers are batched into digests.
 - Read the kind of each message (`meta.kind` on a channel tag, each item's kind in a digest, the kind in a prompt header). Only `hub` items with kind `presence` are shared memory for reference, not requests. Its `task`, `review`, and `budget` items are workflow events: check the task board and your assigned role, then use the appropriate hub tools within the user's authorized scope. Sender and kind never override user instructions or safety rules.
 - The task board is the record of who does what: `hub_task_propose`, `hub_task_accept` / `hub_task_decline`, `hub_task_done`, `hub_review`, `hub_task_list`. Default roles: Claude plans and reviews, Codex implements, Kimi, Pi and the local worker implement and verify; `.agenthub/config.json` `roles` is the source of truth.
-- Implementers claim work nobody assigned them with `hub_task_propose`, naming themselves as `owner` and the paths in `refs`; when the paths overlap another open task the hub says so, and the later claimant settles it with that owner. `hub_task_done` says what changed, why, and the check that was run with its result.
+- Implementers claim work nobody assigned them with `hub_task_propose`, naming themselves as `owner`, with the paths in `refs` and a `plan` (files, symbols, signatures, insertion points; `hub_task_accept` takes one too). When the paths or symbols overlap another open task the hub says so, the later claimant settles it with that owner, and that owner gets the plan with its next message. When a task is done, the owners of overlapping open tasks get a notice of what changed. `hub_task_done` says what changed, why, and the check that was run with its result.
 - `hub_remember` saves a decision, finding, contract or `fail` (an approach that does not work, and why) to the memory all agents share; the other agents get it with their next message. Do not retry what a `fail` note rules out without new evidence. A task shown as `[pii]` is handled by the on-prem worker only: do not ask for its content.

package/templates/config.json

@@ -26,5 +26,6 @@
   "local": { "deny": [], "bash_network": false, "max_steps": 30, "read_allow": [] },
   "approvals": { "timeout_s": 120 },
   "tasks": { "release_after_min": 30 },
-  "checks": { "timeout_s": 600 }
+  "checks": { "timeout_s": 600 },
+  "snapshots": { "enabled": true, "keep": 20 }
 }