@staix/agent-hub 0.12.15 → 0.12.17

package/src/hub/envelope.ts

@@ -14,7 +14,7 @@ export interface Envelope {
   kind: Kind;
   priority: Priority;
   body: string; // agent conclusions only, never tool noise
-  refs?: { repo?: string; branch?: string; commit?: string; paths?: string[]; task?: string };
+  refs?: { repo?: string; branch?: string; commit?: string; paths?: string[]; task?: string; supervision?: boolean; supervisionKey?: string };
   /** The body must not be shown outside its recipients: console tail and log print a stub instead (PII tasks). */
   private?: boolean;
   ts: number;

package/src/hub/events.ts

@@ -24,7 +24,12 @@ export type HubEvent =
   | { 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: "native_turn_end"; peer: string }
+  | { type: "native_turn_end"; peer: string; id?: string }
+  | { type: "conduct"; peer: string; action: string; task?: number; target?: string }
+  | { type: "agent_cli"; peer: string; command: string; refused: boolean }
+  | { type: "permission"; id: string; peer: string; event: "requested" | "answered" | "expired" | "cancelled"; latencyMs?: number; surface?: "console" | "dashboard" | "terminal"; option?: "allow_once" | "allow_always" | "reject_once" | "reject_always" }
+  /** Completed native turns that received supervision, not feed enqueues or inferred costs. */
+  | { type: "supervision_turn"; peer: string; turn: string; tokens?: number; ms?: number }
   | { type: "hook_stats"; peer: string; n: number; startupMs: number; hubMs: number; maxStartupMs: number }
   | { type: "cohort"; id: number; event: "formed" | "joined" | "lifted"; silent: boolean; tasks: number[]; owners: string[] }
   | { type: "tokens"; peer: string; n: number }
@@ -32,6 +37,7 @@ export type HubEvent =
   | { 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: "conflict"; peer: string; task?: number; other: number; owner: string; paths: string[]; concurrent: boolean; turns?: [string, string] }
+  | { type: "context_pressure"; peer: string; source: string; measuredAt: number; used: number; window: number | null }
   | { type: "quota"; peer: string; windows: { id: string; used: number; resetsAt?: number }[]; hard: boolean; measuredAt?: string };
 
 export type StampedEvent = HubEvent & { v: number; at: string };

package/src/hub/hub-tools.ts

@@ -41,14 +41,27 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_task_done", "Mark your task finished. It goes to its reviewer with your summary and refs. When the project configures a check for its class, the hub runs it first and the result comes as a task message: a failed check keeps the task with you.", { id, summary: { type: "string", description: "what changed, why, and the check you ran with its result" }, refs }, ["id", "summary"]),
   tool("hub_task_list", "The task board. PII tasks show as [pii].", { state: { type: "string", enum: ["proposed", "in_progress", "in_review", "approved", "changes_requested"] }, ready: { type: "boolean", description: "only proposed tasks with nothing left to wait for" } }),
   tool("hub_review", "Give your verdict on a task you were asked to review: map the changed signatures and call sites to the task's plan or detail, read the check result, and list what is unmet. Two changes_requested in a row move the task to another peer.", { id, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str, unmet: { type: "array", items: str, description: "each requirement of the plan or detail that the change does not meet" } }, ["id", "verdict"]),
-  tool("hub_checkpoint", "Answer a checkpoint request from the hub (your quota window is nearly used up): what you were doing, what is half done, what whoever continues must know. Write the same to .agenthub/checkpoint.md first if you can.", { summary: str }, ["summary"]),
+  tool("hub_checkpoint", "Answer a checkpoint request from the hub (quota or context window pressure): what you were doing, what is half done, what whoever continues must know. Write the same to .agenthub/checkpoint.md first if you can.", { summary: str, request_id: { type: "string", description: "The request id supplied by a context checkpoint request; required for context checkpoints" } }, ["summary"]),
   tool("hub_remember", "Save a decision, finding, contract or fail to the memory all agents share (claude-mem); the other agents also get it with their next message. A fail is an approach you tried that does not work, and why: the most useful note, it stops the others spending their quota on it. Do not retry what a fail note rules out without new evidence. Conclusions worth recalling, not chatter.", { text: str, title: str, kind: { type: "string", enum: [...NOTE_KINDS] }, task: id }, ["text"]),
 ];
 
 export const TASK_TOOL_NAMES = new Set(TASK_TOOLS.map((t) => t.name));
 
+/** Separately published: serving a schema grants no authority, only the daemon's explicit role does. */
+export const CONDUCTOR_TOOLS: HubTool[] = [
+  tool("hub_status", "Inspect public team state, holds, quota windows, task counts and pending approval peer/tool/age. Only the configured conductor may use this tool.", {}),
+  tool("hub_task_show", "Read a task's public view and history. PII tasks remain stubs. Only the conductor may use this tool.", { id }, ["id"]),
+  tool("hub_task_assign", "Move a task to another peer, as the conductor. Requires assign capability when the conductor has an explicit capabilities list.", { id, peer: str }, ["id", "peer"]),
+  tool("hub_task_escalate", "Escalate a task through the normal task flow, as the conductor. Requires assign capability when explicitly listed.", { id }, ["id"]),
+  tool("hub_peer_start", "Start local, kimi or headless pi. Claude, Codex and Pi TUI requests return a command for the person to run, without launching a terminal.", { peer: { type: "string", enum: ["local", "kimi", "pi", "claude", "codex"] }, mode: { type: "string", enum: ["headless", "tui"] } }, ["peer"]),
+  tool("hub_peer_hold", "Hold a peer's deliveries as the conductor. This hold is separate from the person's hold and budget pauses.", { peer: str }, ["peer"]),
+  tool("hub_peer_release", "Release only the conductor hold you placed. Never lifts a person's hold or a budget pause.", { peer: str }, ["peer"]),
+];
+export const CONDUCTOR_TOOL_NAMES = new Set(CONDUCTOR_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> = {
+  conductor: "conductor: plan and split work into tasks with owners, watch the team with hub_status, move stalled work, and ensure every task is reviewed (review it yourself only if you also hold reviewer). Report results and open decisions to the person. Do not implement tasks you handed out. Never ask a peer to answer an approval; ask the person for human-only actions. You may release only holds you placed, never human holds or budget pauses.",
   planner: "planner: break work into tasks with hub_task_propose (one outcome each, the right class, paths in refs, and after: [ids] for work that must wait for other tasks) 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. 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.",

package/src/hub/report.ts

@@ -3,7 +3,7 @@ import type { StampedEvent } from "./events.ts";
 export interface Report {
   from?: string;
   to?: string;
-  peers: Record<string, { turns: number; busyMinutes: number; tokens: number }>;
+  peers: Record<string, { turns: number | null; busyMinutes: number; tokens: number; turnSource?: "native-stop" | "logical-state" | "unknown" }>;
   usage: { peers: Record<string, UsageCoverage>; totals: UsageTotals; unknownPeers: string[]; completeCoverage: boolean; estimatedUsd?: number; measuredSpendUsd?: number };
   messages: { total: number; dropped: Record<string, number>; overflow: number; undeliverable: number; perTask: number };
   overlaps: { warnings: number; pairs: number };
@@ -11,6 +11,8 @@ export interface Report {
   conflicts: number;
   tasks: Record<string, number>;
   quota: { readings: number; hard: number };
+  conduct: Record<string, Record<string, number>>;
+  supervision: Record<string, { turns: number | null; tokens: number | null; measuredTokens: number | null; knownTokenTurns: number; unknownTokenTurns: number }>;
 }
 
 export interface UsageCoverage {
@@ -83,16 +85,39 @@ function formatUsage(usage: Report["usage"]): string[] {
 
 /** The numbers `ahub report` prints, from `events.jsonl` alone (issue #40). */
 export function summarize(events: StampedEvent[]): Report {
-  const r: Report = { peers: {}, usage: { peers: {}, totals: { inputTokens: 0, inputRecords: 0, outputTokens: 0, outputRecords: 0, cacheReadTokens: 0, cacheReadRecords: 0, cacheWriteTokens: 0, cacheWriteRecords: 0, totalTokens: 0, totalRecords: 0 }, unknownPeers: [], completeCoverage: true }, messages: { total: 0, dropped: {}, overflow: 0, undeliverable: 0, perTask: 0 }, overlaps: { warnings: 0, pairs: 0 }, conflicts: 0, tasks: {}, quota: { readings: 0, hard: 0 } };
+  const r: Report = { peers: {}, conduct: {}, supervision: {}, usage: { peers: {}, totals: { inputTokens: 0, inputRecords: 0, outputTokens: 0, outputRecords: 0, cacheReadTokens: 0, cacheReadRecords: 0, cacheWriteTokens: 0, cacheWriteRecords: 0, totalTokens: 0, totalRecords: 0 }, unknownPeers: [], completeCoverage: true }, messages: { total: 0, dropped: {}, overflow: 0, undeliverable: 0, perTask: 0 }, overlaps: { warnings: 0, pairs: 0 }, conflicts: 0, tasks: {}, quota: { readings: 0, hard: 0 } };
+  const supervisor = (id: string) => (r.supervision[id] ??= { turns: null, tokens: null, measuredTokens: null, knownTokenTurns: 0, unknownTokenTurns: 0 });
   const peer = (id: string) => (r.peers[id] ??= { turns: 0, busyMinutes: 0, tokens: 0 });
+  const claudeNativeStops = events.some(event => event.type === "native_turn_end" && event.peer === "claude" && !!event.id);
+  const seenNativeStops = new Set<string>();
   const usagePeer = (id: string) => (r.usage.peers[id] ??= emptyUsage());
   const pairs = new Set<string>();
   const taskMessages = new Map<string, number>();
   const seenUsage = new Set<string>();
+  const seenSupervision = new Set<string>();
   for (const e of events) {
     r.from ??= e.at;
     r.to = e.at;
     switch (e.type) {
+      case "conduct": {
+        const actions = r.conduct[e.peer] ??= {};
+        actions[e.action] = (actions[e.action] ?? 0) + 1;
+        supervisor(e.peer);
+        break;
+      }
+      case "supervision_turn": {
+        const key = `${e.peer}\0${e.turn}`;
+        if (seenSupervision.has(key)) break;
+        seenSupervision.add(key);
+        const s = supervisor(e.peer);
+        s.turns = (s.turns ?? 0) + 1;
+        if (typeof e.tokens === "number" && Number.isSafeInteger(e.tokens) && e.tokens >= 0) {
+          s.measuredTokens = (s.measuredTokens ?? 0) + e.tokens;
+          s.tokens = s.unknownTokenTurns ? null : s.measuredTokens;
+          s.knownTokenTurns++;
+        } else { s.unknownTokenTurns++; s.tokens = null; }
+        break;
+      }
       case "envelope":
         r.messages.total++;
         if (e.dropped) r.messages.dropped[e.dropped] = (r.messages.dropped[e.dropped] ?? 0) + 1;
@@ -106,9 +131,16 @@ export function summarize(events: StampedEvent[]): Report {
         r.messages.dropped.stale = (r.messages.dropped.stale ?? 0) + 1;
         break;
       case "turn_end":
-        peer(e.peer).turns++;
+        if (e.peer !== "claude" || !claudeNativeStops) peer(e.peer).turns = (peer(e.peer).turns ?? 0) + 1;
         peer(e.peer).busyMinutes += e.ms / 60_000;
         break;
+      case "native_turn_end":
+        if (e.peer === "claude" && e.id) {
+          if (seenNativeStops.has(e.id)) break;
+          seenNativeStops.add(e.id);
+          peer(e.peer).turns = (peer(e.peer).turns ?? 0) + 1;
+        }
+        break;
       case "state":
         peer(e.peer);
         break;
@@ -143,13 +175,30 @@ export function summarize(events: StampedEvent[]): Report {
   // Pricing is intentionally absent: a token count is neither an estimated price nor provider-reported spend.
   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));
+  if (r.peers.claude) {
+    const logical = events.some(event => event.type === "turn_end" && event.peer === "claude");
+    r.peers.claude.turnSource = claudeNativeStops ? "native-stop" : logical ? "logical-state" : "unknown";
+    if (!claudeNativeStops && !logical) r.peers.claude.turns = null;
+  }
   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 ? `${p.tokens} tokens` : id === "pi" ? "tokens not reported" : "- tokens"}`);
+  for (const [id, p] of Object.entries(r.peers).sort(([a], [b]) => a.localeCompare(b))) {
+    const turns = p.turns === null ? "turns unknown" : `${p.turns} turn${p.turns === 1 ? "" : "s"}${p.turnSource === "native-stop" ? " (native Stop)" : p.turnSource === "logical-state" ? " (logical state, native completion unobserved)" : ""}`;
+    lines.push(`peer ${id}: ${turns}, ${p.busyMinutes} busy minutes, ${p.tokens ? `${p.tokens} tokens` : id === "pi" ? "tokens not reported" : "- tokens"}`);
+  }
   if (Object.keys(r.usage.peers).length) lines.push(...formatUsage(r.usage));
+  for (const [id, s] of Object.entries(r.supervision).sort(([a], [b]) => a.localeCompare(b))) {
+    const turns = s.turns === null ? "turns unknown" : `${s.turns} completed native turns`;
+    const tokens = s.tokens === null ? "tokens unknown" : `${s.tokens} tokens`;
+    const measured = s.measuredTokens === null ? "measured subset unknown" : `${s.measuredTokens} measured tokens (${s.knownTokenTurns} known turns)`;
+    lines.push(`supervision ${id}: ${turns}; ${tokens}; ${measured}; ${s.unknownTokenTurns} completed turns with unknown tokens; whole native turns containing supervision, including other work; estimated price unknown; measured spend unknown`);
+  }
+  for (const [id, actions] of Object.entries(r.conduct).sort(([a], [b]) => a.localeCompare(b))) {
+    lines.push(`conductor ${id}: ${Object.entries(actions).sort(([a], [b]) => a.localeCompare(b)).map(([action, n]) => `${action} ${n}`).join(", ")}`);
+  }
   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}; edit conflicts: ${r.conflicts}`);

package/src/hub/supervision.ts

@@ -0,0 +1,152 @@
+import type { HistoryEntry, Task, TaskMoveReason } from "./board.ts";
+import { sanitize, type Kind, type Priority } from "./envelope.ts";
+
+export type SupervisionScope = "own" | "all" | "off";
+export type SupervisionMilestone = "assigned" | "accepted" | "declined" | "done" | "review" | "approved" | "moved" | "escalated" | "stuck" | "sweep";
+/** Codes, never free-form notes or check output. */
+export type SupervisionReason = TaskMoveReason | "repetition" | "false_progress" | "drift" | "desperation" | "capability_gap";
+export interface SupervisionFields {
+  by?: string;
+  owner?: string | null;
+  check?: "passed" | "failed" | "unknown";
+  verdict?: "approved" | "changes_requested";
+  reason?: SupervisionReason;
+  sweep?: "unaccepted-assignment" | "idle-owner" | "review-pending";
+}
+export interface SupervisionNotice {
+  peer: string;
+  /** Replace only queued entries with this key; accepted/in-flight deliveries stay authoritative. */
+  key: string;
+  body: string;
+  priority: Priority;
+  kind: Kind;
+  task?: number;
+}
+export interface SupervisionDeps {
+  /** Current role holder; undefined immediately revokes the feed. */
+  conductor: () => string | undefined;
+  scope: () => SupervisionScope;
+  tasks: () => Task[];
+  publicTitle: (task: Task) => string;
+  isPrivate: (task: Task) => boolean;
+  /** false means not admitted, so latches must remain retryable. No separate batching timer. */
+  emit: (notice: SupervisionNotice) => boolean | void;
+  approvalAgeMs?: number;
+  now?: () => number;
+  /** Durable round state belongs to the daemon's store, not the controller. */
+  readRound?: (peer: string) => string | undefined;
+  writeRound?: (peer: string, signature: string) => void;
+}
+
+/** Deterministic milestone producer. The Bus alone owns batching, retry and native turns. */
+export class SupervisionFeed {
+  private readonly approvals = new Set<string>();
+  private readonly holds = new Set<string>();
+  private readonly rounds = new Map<string, string>();
+  constructor(private readonly d: SupervisionDeps) {}
+
+  /** Pending notices may have been withdrawn on role/off change; live requests can notify again on regrant. */
+  resetPending(peer: string): void {
+    for (const key of this.approvals) if (key.startsWith(`${peer}:`)) this.approvals.delete(key);
+    for (const key of this.holds) if (key.startsWith(`${peer}:`)) this.holds.delete(key);
+  }
+
+  private recipient(): string | undefined {
+    return this.d.scope() === "off" ? undefined : this.d.conductor();
+  }
+
+  includes(task: Task): boolean {
+    const peer = this.recipient();
+    return !!peer && (this.d.scope() === "all" || task.history.some((h) => h.by === peer && ["proposed", "assigned", "reassigned", "escalated"].includes(h.event)));
+  }
+
+  private send(key: string, body: string, priority: Priority = "status", task?: number, kind: Kind = "task"): boolean {
+    const peer = this.recipient();
+    if (!peer) return false;
+    try {
+      return this.d.emit({ peer, key: `supervision:${peer}:${key}`, body: sanitize(body), priority, kind, ...(task === undefined ? {} : { task }) }) !== false;
+    } catch { return false; } // a feed failure must not invalidate a successful board write
+  }
+
+  milestone(id: number, milestone: SupervisionMilestone, fields: SupervisionFields = {}): boolean {
+    const task = this.d.tasks().find((t) => t.id === id);
+    if (!task || !this.includes(task)) return false;
+    if (this.d.isPrivate(task)) return this.send(`task:${id}:${milestone}`, `#${id} [pii]: ${milestone}; ahub task show ${id}`, "status", id);
+    const bits = [this.d.publicTitle(task), milestone];
+    if (fields.by) bits.push(`by ${fields.by}`);
+    if ("owner" in fields) bits.push(`owner ${fields.owner ?? "none"}`);
+    if (fields.check) bits.push(`check ${fields.check}`);
+    if (fields.verdict) bits.push(`verdict ${fields.verdict}`);
+    if (fields.reason) bits.push(`reason ${fields.reason}`);
+    if (fields.sweep) bits.push(`finding ${fields.sweep}`);
+    return this.send(`task:${id}:${milestone}`, bits.join("; "), "status", id);
+  }
+
+  /** Only structured history metadata is read; notes may contain private content. */
+  taskChanged(task: Task, entry: HistoryEntry, metadata: SupervisionFields = {}): void {
+    const fields: SupervisionFields = { by: entry.by, owner: task.owner, ...(entry.reason ? { reason: entry.reason } : {}), ...metadata };
+    const event = entry.event;
+    if (event === "done" || event === "check failed") {
+      const latestCheck = task.history.findLast((h) => ["check passed", "check failed", "check interrupted", "done (checking)", "accepted", "reopened"].includes(h.event));
+      fields.check = event === "check failed" ? "failed" : metadata.check ?? (latestCheck?.event === "check passed" ? "passed" : "unknown");
+      this.milestone(task.id, "done", fields);
+      if (event === "done" && task.state === "approved") this.milestone(task.id, "approved", fields);
+    } else if (event === "changes_requested") this.milestone(task.id, "review", { ...fields, verdict: "changes_requested" });
+    else if (event === "approved") {
+      this.milestone(task.id, "review", { ...fields, verdict: "approved" });
+      this.milestone(task.id, "approved", fields);
+    } else if (event === "idle sweep" && entry.sweep) this.milestone(task.id, "sweep", { ...fields, sweep: entry.sweep.kind });
+    else if (event === "reassigned") this.milestone(task.id, "moved", fields);
+    else if (["assigned", "accepted", "declined", "escalated"].includes(event)) this.milestone(task.id, event as SupervisionMilestone, fields);
+    this.checkRound();
+  }
+
+  peerOffline(peer: string): boolean {
+    if (this.d.scope() !== "all" && !this.d.tasks().some((t) => this.includes(t) && t.state !== "approved" && (t.owner === peer || t.reviewer === peer))) return false;
+    return this.send(`peer:${peer}:offline`, `${peer}: offline`);
+  }
+
+  budgetPaused(peer: string, resetsAt?: number): boolean {
+    if (this.d.scope() !== "all" && !this.d.tasks().some((t) => this.includes(t) && t.state !== "approved" && (t.owner === peer || t.reviewer === peer))) return false;
+    const resetDate = new Date(resetsAt ?? NaN);
+    const reset = Number.isFinite(resetDate.getTime()) ? resetDate.toISOString() : "unknown";
+    return this.send(`peer:${peer}:budget`, `${peer}: budget paused; reset ${reset}`, "status", undefined, "budget");
+  }
+
+  approvalWaiting(request: { id: string; peer: string; tool: string; createdAt: number }): boolean {
+    const peer = this.recipient();
+    const age = (this.d.now?.() ?? Date.now()) - request.createdAt;
+    const key = `${peer}:${request.id}`;
+    if (!peer || !Number.isFinite(age) || age < (this.d.approvalAgeMs ?? 60_000) || this.approvals.has(key)) return false;
+    const sent = this.send(`approval:${request.id}`, `${request.peer}: approval waiting; tool ${request.tool}; age ${Math.floor(age / 1000)}s; ask the person to answer it in ahub console`, "important");
+    if (sent) this.approvals.add(key);
+    return sent;
+  }
+
+  needsReview(peer: string, deliveryId: string): boolean {
+    const conductor = this.recipient();
+    const key = `${conductor}:${peer}:${deliveryId}`;
+    if (!conductor || this.holds.has(key)) return false;
+    const sent = this.send(`hold:${peer}:${deliveryId}`, `${peer}: needs_review hold; delivery ${deliveryId}; ask the person to resolve it with ahub queue resolve`, "important");
+    if (sent) this.holds.add(key);
+    return sent;
+  }
+
+  checkRound(): boolean {
+    const peer = this.recipient();
+    if (!peer) return false;
+    const tasks = this.d.tasks().filter((t) => this.includes(t));
+    if (!tasks.length || tasks.some((t) => t.state !== "approved")) return false;
+    const signature = tasks.map((t) => t.id).sort((a, b) => a - b).join(",");
+    const previous = this.d.readRound?.(peer) ?? this.rounds.get(peer);
+    const completed = new Set(previous?.split(",") ?? []);
+    const newlyJoined = tasks.filter((t) => !completed.has(String(t.id)));
+    if (!newlyJoined.length) return false;
+    const sent = this.send("round", `Supervision round complete: ${newlyJoined.length} task${newlyJoined.length === 1 ? "" : "s"} approved; report the results and open decisions to the person.`);
+    if (sent) {
+      this.rounds.set(peer, signature);
+      this.d.writeRound?.(peer, signature);
+    }
+    return sent;
+  }
+}

package/src/hub/task-sweep.ts

@@ -0,0 +1,59 @@
+import type { Task } from "./board.ts";
+
+export type SweepKind = "unaccepted-assignment" | "idle-owner" | "review-pending";
+export interface SweepRecord {
+  kind: SweepKind;
+  /** Index of the last real activity, distinguishing even events at the same time. */
+  activity: number;
+  step: 1 | 2 | 3;
+  at: number;
+}
+export interface TaskSweepConfig {
+  enabled: boolean;
+  interval_s: number;
+  unaccepted_min: number;
+  idle_min: number;
+  review_min: number;
+  ladder_min: number;
+  auto_reassign: boolean;
+}
+export const DEFAULT_TASK_SWEEP: TaskSweepConfig = {
+  enabled: false, interval_s: 300, unaccepted_min: 60, idle_min: 120, review_min: 120, ladder_min: 30, auto_reassign: false,
+};
+
+/** Config cannot silently enable a sweep or reassignment through a truthy string. */
+export function taskSweepConfig(input: unknown): TaskSweepConfig {
+  if (input === undefined) return { ...DEFAULT_TASK_SWEEP };
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("task_sweep must be an object");
+  const out = { ...DEFAULT_TASK_SWEEP };
+  const values = input as Record<string, unknown>;
+  for (const key of ["enabled", "auto_reassign"] as const) {
+    if (values[key] === undefined) continue;
+    if (typeof values[key] !== "boolean") throw new Error(`task_sweep.${key} must be a boolean`);
+    out[key] = values[key];
+  }
+  for (const key of ["interval_s", "unaccepted_min", "idle_min", "review_min", "ladder_min"] as const) {
+    if (values[key] === undefined) continue;
+    const value = values[key];
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 1 || value * (key === "interval_s" ? 1000 : 60_000) > 2_147_483_647) throw new Error(`task_sweep.${key} must be a bounded number of at least 1`);
+    out[key] = value;
+  }
+  return out;
+}
+
+/** Pure time/kind ladder; Tasks decides whether the responsible peer is available. */
+export function nextSweep(task: Task, config: TaskSweepConfig, now: number): SweepRecord | undefined {
+  if (!config.enabled || !Number.isFinite(now)) return undefined;
+  const kind = task.state === "proposed" && task.owner ? "unaccepted-assignment"
+    : task.state === "in_progress" && task.owner ? "idle-owner"
+      : task.state === "in_review" && task.reviewer ? "review-pending" : undefined;
+  if (!kind) return undefined;
+  let activity = task.history.length - 1;
+  while (activity >= 0 && task.history[activity]?.sweep) activity--;
+  const at = task.history[activity]?.at ?? task.created;
+  const threshold = kind === "unaccepted-assignment" ? config.unaccepted_min : kind === "idle-owner" ? config.idle_min : config.review_min;
+  if (now - at < threshold * 60_000) return undefined;
+  const previous = task.history.flatMap((h) => h.sweep?.kind === kind && h.sweep.activity === activity ? [h.sweep] : []).at(-1);
+  if (previous && (previous.step === 3 || now - previous.at < config.ladder_min * 60_000)) return undefined;
+  return { kind, activity, step: previous ? (previous.step + 1) as 2 | 3 : 1, at: now };
+}

package/src/hub/tasks.ts

@@ -1,13 +1,14 @@
 import { isAbsolute, relative } from "node:path";
 import type { Briefs } from "../memory/brief.ts";
 import type { MemoryClient } from "../memory/client.ts";
-import { CLASSES, OUTCOMES_KEPT_MS, PLAN_KEYS, type Board, type Task, type TaskClass, type TaskPlan, type TaskRefs } from "./board.ts";
+import { CLASSES, OUTCOMES_KEPT_MS, PLAN_KEYS, TASK_MOVE_REASONS, type Board, type Task, type TaskClass, type TaskMoveReason, 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, predictSplit, type Assignment, type Routing, type SplitObservation, type SplitPrediction } from "./routing.ts";
 import { ExecutionBudget, type ExecutionBudgetConfig, type ExecutionBudgetDecision, type ExecutionBudgetStatus, type ExecutionUnit } from "./execution-budget.ts";
 import { Cohorts, MAX_REQUESTS, type Cohort, type Completion } from "./cohorts.ts";
 import { realPath } from "./project.ts";
+import { nextSweep, taskSweepConfig, type TaskSweepConfig, type SweepRecord } from "./task-sweep.ts";
 
 export interface TasksDeps {
   board: Board;
@@ -68,6 +69,9 @@ export interface TasksDeps {
   recordSplit?: (task: number, prediction: SplitPrediction, where: "routing" | "cohort") => void;
   /** A cohort formed, changed or was lifted (issue #107), for the record: the benchmark's treatment check reads it. */
   recordCohort?: (cohort: { id: number; event: "formed" | "joined" | "lifted"; silent: boolean; tasks: number[]; owners: PeerId[] }) => void;
+  sweep?: TaskSweepConfig;
+  /** Shutdown or coordinator work holds task sweeps too. */
+  sweepHeld?: () => boolean;
 }
 
 const ESCALATE_AFTER = 2;
@@ -80,7 +84,7 @@ const DEMOTE_AT = 1.5;
 const CONTRADICTION_WINDOW_MS = 7 * 86_400_000;
 const OPEN: Task["state"][] = ["proposed", "in_progress", "changes_requested"];
 /** Board events that leave a task where its completion check found it; any other event means it moved on meanwhile. */
-const QUIET_EVENTS = new Set(["answer", "reviewer changed"]);
+const QUIET_EVENTS = new Set(["answer", "reviewer changed", "idle sweep"]);
 
 /** A project path as one spelling (#67): no leading `./`, no repeated or trailing `/`; the root is `.`. */
 export const normPath = (p: string) => p.replace(/^(\.\/)+/, "").replace(/\/{2,}/g, "/").replace(/\/+$/, "") || ".";
@@ -134,8 +138,11 @@ const planText = (plan: TaskPlan = {}) => PLAN_KEYS.filter((k) => plan[k]?.lengt
 export class Tasks {
   /** Turn-free cohorts (issue #107): who works without messages, and who integrates. */
   readonly cohorts: Cohorts;
+  private readonly sweepConfig: TaskSweepConfig;
+  private sweeping = false;
 
   constructor(private readonly d: TasksDeps) {
+    this.sweepConfig = taskSweepConfig(d.sweep);
     this.cohorts = new Cohorts({
       silence: (owners) => this.turnFree() && owners.every((p) => p !== USER && p !== HUB && (this.d.capable?.(p) ?? false)),
       idle: (peer) => this.d.idle?.(peer) ?? false,
@@ -157,6 +164,55 @@ export class Tasks {
 
   isPii = (task: Pick<Task, "signals">) => task.signals.includes("pii") && this.d.routing().constraints.pii === "local_only";
 
+  /** Task-owned, default-off between-turn ladder. Persist before sending so restart cannot repeat a step. */
+  async sweep(now = Date.now()): Promise<{ task: number; finding: SweepRecord }[]> {
+    const recorded: { task: number; finding: SweepRecord }[] = [];
+    if (!this.sweepConfig.enabled || this.sweeping || this.d.sweepHeld?.() || this.d.bus.isRecoveryHeld || this.d.bus.storageError) return recorded;
+    this.sweeping = true;
+    try {
+      for (const task of this.d.board.list()) {
+        if (this.d.sweepHeld?.() || this.d.bus.isRecoveryHeld || this.d.bus.storageError) break;
+        const finding = nextSweep(task, this.sweepConfig, now);
+        if (!finding || this.waitsFor(task).length || this.isChecking(task.id) || this.silentFor(task.id)) continue;
+        const responsible = finding.kind === "review-pending" ? task.reviewer! : task.owner!;
+        if (responsible !== USER && !this.sweepAvailable(responsible)) continue;
+        const title = this.publicTitle(task);
+        const message = `Task ${title}: ${finding.kind}, idle escalation ${finding.step}/3.`;
+        // Only identifiers, kind and step are kept in the ladder event. A crash after this write and before publish
+        // leaves the notice unpublished or uncertain; the durable-delivery journal owns any delivery retries.
+        this.d.board.update(task.id, HUB, "idle sweep", {}, undefined, { sweep: finding });
+        recorded.push({ task: task.id, finding });
+        if (finding.step === 1) {
+          this.sweepNotice(task, responsible, `${message} Check its current state with hub_task_list and accept, complete or review your assigned work.`);
+        } else if (finding.step === 2) {
+          this.d.notify(message);
+          for (const [peer, roles] of Object.entries(this.d.roles ?? {})) {
+            if (peer !== responsible && roles.includes("planner") && this.sweepAvailable(peer)) this.sweepNotice(task, peer, `${message} The assigned ${finding.kind === "review-pending" ? "reviewer" : "owner"} has not recorded fresh task activity; check the board before coordinating.`);
+          }
+        } else {
+          const reviewer = finding.kind === "review-pending";
+          const a = assign(task, this.states(), this.d.routing(), { exclude: [...this.declined(task), responsible], waitsFor: this.waitsFor(task), ...(reviewer ? { candidates: [], notReviewer: task.owner ?? undefined } : {}), ...this.weights(task.class) });
+          const candidate = reviewer ? a.reviewer : a.owner;
+          this.d.notify(`${message} ${reviewer ? "Reviewer" : "Owner"} reassignment suggestion: ${candidate ?? "no eligible peer"}.`);
+          if (!reviewer && candidate && this.sweepConfig.auto_reassign && this.sweepAvailable(candidate)) {
+            await this.assignOwner(this.d.board.get(task.id)!, HUB, { candidates: [candidate], exclude: [responsible], event: "reassigned", reason: "idle", note: `idle sweep: ${finding.kind}; from ${responsible}` });
+          }
+        }
+      }
+    } finally { this.sweeping = false; }
+    return recorded;
+  }
+
+  private sweepAvailable(peer: PeerId): boolean {
+    const bus = this.d.bus;
+    return bus.stateOf(peer) === "idle" && (this.d.idle?.(peer) ?? true) && !this.d.held?.()[peer] && !bus.queueSummary(peer).heldBy && !bus.queued(peer) && !bus.hasInFlight(peer);
+  }
+
+  private sweepNotice(task: Task, peer: PeerId, body: string): void {
+    if (peer === USER) this.d.notify(body);
+    else this.d.bus.publish(newEnvelope(HUB, body, { to: [peer], kind: "task", refs: { task: String(task.id) } }));
+  }
+
   configureExecutionBudget = (config: ExecutionBudgetConfig): ExecutionBudgetStatus | undefined => {
     if (!this.d.executionBudget) return undefined;
     if (config.kind === "task" && (!config.taskId || !this.d.board.get(config.taskId))) throw new Error(`task #${config.taskId ?? "?"} does not exist`);
@@ -180,9 +236,19 @@ export class Tasks {
   publicTitle = (task: Task) => (this.isPii(task) ? `#${task.id} [pii]` : `#${task.id} ${task.title}`);
 
   /** A task as a cloud peer may see it. */
-  publicView(task: Task): Record<string, unknown> {
+  publicView(task: Task, fullHistory = false): Record<string, unknown> {
     const { title, detail, history, ...rest } = task;
-    return this.isPii(task) ? { ...rest, refs: {}, plan: {}, title: "[pii]", detail: "[pii]" } : { ...rest, title, detail, history: history.slice(-5) };
+    if (this.isPii(task)) return { ...rest, refs: {}, plan: {}, title: "[pii]", detail: "[pii]" };
+    const screenHistoryText = (text: string, field: string): string => this.nameable(text) ? text : `[history ${field} withheld: it matches a PII pattern; ahub task show ${task.id}]`;
+    const publicHistory = (fullHistory ? history : history.slice(-5)).map(h => ({
+      at: h.at, by: h.by, event: h.event,
+      ...(h.note === undefined ? {} : { note: screenHistoryText(h.note, "note") }),
+      ...(h.profile === undefined ? {} : { profile: screenHistoryText(h.profile, "profile") }),
+      ...(h.owner === undefined ? {} : { owner: h.owner }),
+      ...(h.reason && TASK_MOVE_REASONS.includes(h.reason) ? { reason: h.reason } : {}),
+      ...(h.sweep ? { sweep: { kind: h.sweep.kind, activity: h.sweep.activity, step: h.sweep.step, at: h.sweep.at } } : {}),
+    }));
+    return { ...rest, title, detail, history: publicHistory };
   }
 
   /** Console results expose direct approval and delivery holds, not just the chosen peer ids. */
@@ -585,7 +651,7 @@ export class Tasks {
         if (!assign(task, this.states(), this.d.routing(), { exclude: [...this.declined(task), peer], ...this.health() }).owner) continue;
         try {
           const back = task.state === "in_progress" ? this.d.board.update(task.id, HUB, "released", { state: "proposed" }, why) : task;
-          const next = await this.assignOwner(back, HUB, { exclude: [peer], event: "reassigned", note: why });
+          const next = await this.assignOwner(back, HUB, { exclude: [peer], event: "reassigned", reason: "offline", note: why });
           moved.push({ id: task.id, title: this.publicTitle(task), to: next.owner });
           // The gone owner hears it on its next delivery, if it comes back mid-work.
           if (next.owner && next.owner !== peer) this.d.tell?.(peer, noteLine(HUB, "decision", `task #${task.id} moved to ${next.owner} while you were offline; stop working on it`));
@@ -613,6 +679,11 @@ export class Tasks {
     return assign({ class: target.class, signals: detectSignals(draft, routing, this.d.cwd) }, this.states(), routing, this.weights(target.class)).trace;
   }
 
+  /** Public read path: every generated line is screened, including profile/config-derived trace fields. */
+  publicExplain(target: number | { title: string; detail?: string; class: TaskClass; refs?: TaskRefs }): string[] {
+    return this.explain(target).map(line => this.nameable(line) ? line : "[routing explanation withheld: it matches a PII pattern]");
+  }
+
   private declined = (task: Task) => task.history.filter((h) => h.event === "declined").map((h) => h.by);
 
   /** Why the task will approve directly at done: no reviewer could be picked, and who was skipped (issue #92). */
@@ -630,7 +701,7 @@ export class Tasks {
     if (hold) this.d.notify(`task ${this.publicTitle(task)}: ${a.owner}'s queue is held (${hold}); the task arrives once the hold is resolved`);
   }
 
-  private async assignOwner(task: Task, by: PeerId, opts: { candidates?: PeerId[]; event?: string; note?: string; clearOnFail?: boolean; exclude?: PeerId[]; context?: string; claim?: boolean } = {}): Promise<Task> {
+  private async assignOwner(task: Task, by: PeerId, opts: { candidates?: PeerId[]; event?: string; note?: string; reason?: TaskMoveReason; clearOnFail?: boolean; exclude?: PeerId[]; context?: string; claim?: boolean } = {}): Promise<Task> {
     const waits = this.waitsFor(task);
     const a = assign(task, this.states(), this.d.routing(), { exclude: [...this.declined(task), ...(opts.exclude ?? []), ...(opts.event === "escalated" && task.owner ? [task.owner] : [])], ...(opts.candidates ? { candidates: opts.candidates } : {}), waitsFor: waits, ...this.weights(task.class) });
 
@@ -648,7 +719,7 @@ export class Tasks {
       return task;
     }
     const profile = this.d.splitProfile?.(a.owner);
-    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}`, profile ? { profile } : {});
+    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}`, { ...(profile ? { profile } : {}), ...(opts.reason ? { reason: opts.reason } : {}) });
     // What calibration reads (issue #109): routing chose the first owner (no single named candidate, no claim; not an
     // escalation, relay or reassignment of work already begun), and the work overlaps another owner's task not started
     // yet. For the record only. Work routed back to its proposer is left out, as its observations are (by === owner).
@@ -837,7 +908,7 @@ export class Tasks {
     this.mine(task, by, "owner");
     const back = this.d.board.update(task.id, by, "declined", task.state === "in_progress" ? { state: "proposed" } : {}, reason);
     this.d.notify(`task ${this.publicTitle(back)} declined by ${by}${reason && !this.isPii(back) ? `: ${reason}` : ""}`);
-    return this.assignOwner(back, HUB, { event: "reassigned", clearOnFail: true });
+    return this.assignOwner(back, HUB, { event: "reassigned", reason: "declined", clearOnFail: true });
   }
 
   /** Tasks whose check is queued or running, and the owner it was started for. */
@@ -1126,7 +1197,7 @@ export class Tasks {
     this.contradict(rejected);
     this.note(rejected, by, "decision", `Task #${rejected.id} changes requested by ${by}: ${rejected.title}\n${note ?? ""}`);
     if (rejected.rejections >= ESCALATE_AFTER) {
-      const moved = await this.escalate(HUB, rejected.id, `${rejected.rejections} consecutive changes_requested`);
+      const moved = await this.escalate(HUB, rejected.id, `${rejected.rejections} consecutive changes_requested`, "rejections");
       if (moved.owner !== rejected.owner) return moved;
       // Nobody to escalate to: the owner still has to hear the verdict and the note.
       this.tell(moved, `Task #${moved.id}: ${by} requests changes again.${note ? ` ${this.screen(moved, note, "review note", moved.owner)}` : ""} Nobody else can take it; fix it and call hub_task_done again.`, pii);
@@ -1138,7 +1209,7 @@ export class Tasks {
   }
 
   /** Task-level escalation: the next attached peer in the class's escalate_to takes over, with the history. */
-  async escalate(by: PeerId, id: unknown, why = "by hand"): Promise<Task> {
+  async escalate(by: PeerId, id: unknown, why = "by hand", reason: TaskMoveReason | undefined = by === HUB ? undefined : "manual"): Promise<Task> {
     let task = this.need(id, true);
     const list = this.d.routing().classes[task.class]?.escalate_to ?? [];
     if (task.state === "changes_requested") task = this.d.board.update(task.id, HUB, "reopened", { state: "in_progress" });
@@ -1148,7 +1219,7 @@ export class Tasks {
     if (from && by !== HUB) this.d.board.recordOutcome(from, task.class, false);
     // Only a reviewer that asked for changes on this work saw it fail: not an escalation of unreviewed work (a Pi failure).
     if (from && task.reviewer && task.reviewer !== USER && this.requestedChanges(task).has(task.reviewer)) this.d.board.recordReview({ implementer: from, reviewer: task.reviewer, class: task.class, kind: "escalated", task: task.id });
-    const next = await this.assignOwner(task, by, { candidates: list, event: "escalated", note: `${why}; from ${from ?? "none"}`, context: why });
+    const next = await this.assignOwner(task, by, { candidates: list, event: "escalated", reason, note: `${why}; from ${from ?? "none"}`, context: why });
     if (next.owner && next.owner !== from) {
       this.d.notify(`task ${this.publicTitle(next)} escalated from ${from} to ${next.owner} (${why})`);
       this.note(next, by, "decision", `Task #${next.id} escalated from ${from} to ${next.owner}: ${why}`);
@@ -1157,9 +1228,9 @@ export class Tasks {
     return this.d.board.get(next.id)!;
   }
 
-  /** Console only. */
-  async assignTo(id: unknown, peer: PeerId): Promise<Task> {
-    return this.assignOwner(this.need(id, true), USER, { candidates: [peer], event: "reassigned" });
+  /** Caller authority is checked by the daemon; keep the real actor in task history. */
+  async assignTo(id: unknown, peer: PeerId, by: PeerId = USER): Promise<Task> {
+    return this.assignOwner(this.need(id, true), by, { candidates: [peer], event: "reassigned", reason: "manual" });
   }
 
   /**
@@ -1176,7 +1247,7 @@ export class Tasks {
         const pii = this.isPii(task);
         const candidates = [pii ? LOCAL : PI, pii ? undefined : LOCAL, ...(routing.classes[task.class]?.peers ?? []).filter((p) => p !== LOCAL && p !== PI)].filter((p): p is PeerId => !!p);
         const back = task.state === "in_progress" ? this.d.board.update(task.id, HUB, "released", { state: "proposed" }, `budget pause of ${peer}`) : task;
-        const next = await this.assignOwner(back, HUB, { candidates, exclude: [peer], event: "reassigned", note: `budget pause of ${peer}`, clearOnFail: true, ...(context ? { context } : {}) });
+        const next = await this.assignOwner(back, HUB, { candidates, exclude: [peer], event: "reassigned", reason: "budget", note: `budget pause of ${peer}`, clearOnFail: true, ...(context ? { context } : {}) });
         moved.push({ id: task.id, title: this.publicTitle(task), to: next.owner, role: "owner" });
       } else if (task.reviewer === peer && task.state !== "approved") {
         // No owner candidates: only the reviewer is wanted, and it must be neither the paused peer nor the task's owner.