@staix/agent-hub 0.12.16 → 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 }

package/src/hub/hub-tools.ts

@@ -47,8 +47,21 @@ export const TASK_TOOLS: HubTool[] = [
 
 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/tasks.ts

@@ -1,7 +1,7 @@
 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";
@@ -195,7 +195,7 @@ export class Tasks {
           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", note: `idle sweep: ${finding.kind}; from ${responsible}` });
+            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}` });
           }
         }
       }
@@ -236,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. */
@@ -641,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`));
@@ -669,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). */
@@ -686,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) });
 
@@ -704,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).
@@ -893,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. */
@@ -1182,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);
@@ -1194,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" });
@@ -1204,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}`);
@@ -1213,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" });
   }
 
   /**
@@ -1232,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.

package/src/hub/usage.ts

@@ -4,6 +4,8 @@ import { normalizeUsage, safeModelLabel, type NormalizedUsage } from "../omnirou
 
 export interface UsageRecord {
   id: string;
+  /** True only for a native assistant end_turn row, never a tool-use/compaction message. */
+  completedTurn?: boolean;
   at?: string;
   usage?: NormalizedUsage;
   requestedModel?: string;
@@ -11,6 +13,39 @@ export interface UsageRecord {
   provider?: string;
 }
 
+/** Claude-native counters have separate input/output/cache categories, often no explicit total. */
+export function claudeReportedTokens(usage: NormalizedUsage | undefined): number | undefined {
+  if (!usage) return undefined;
+  if (usage.totalTokens !== undefined) return usage.totalTokens;
+  if (usage.inputTokens === undefined || usage.outputTokens === undefined) return undefined;
+  const total = usage.inputTokens + usage.outputTokens + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0);
+  return Number.isSafeInteger(total) && total >= 0 ? total : undefined;
+}
+
+export type ClaudeCompletionWait = { record?: UsageRecord; reason: "verified" | "unavailable" | "baseline" | "before-start" | "superseded" };
+/** After acknowledging Stop, observe its delayed transcript append within a bounded 1200 ms window. */
+export async function waitForClaudeCompletion(read: () => UsageRecord | undefined, current: () => boolean, start: { at: number; baseline?: string }, timeoutMs = 1200): Promise<ClaudeCompletionWait> {
+  const budget = Number.isFinite(timeoutMs) ? Math.min(1200, Math.max(0, timeoutMs)) : 1200;
+  if (budget === 0) return { reason: "unavailable" };
+  const deadline = performance.now() + budget;
+  let reason: ClaudeCompletionWait["reason"] = "unavailable";
+  while (true) {
+    if (!current()) return { reason: "superseded" };
+    const record = read();
+    if (!current()) return { reason: "superseded" };
+    if (performance.now() > deadline) return { reason };
+    const at = typeof record?.at === "string" ? Date.parse(record.at) : NaN;
+    if (record?.completedTurn && Number.isFinite(at)) {
+      if (record.id === start.baseline) reason = "baseline";
+      else if (at < start.at) reason = "before-start";
+      else return { record, reason: "verified" };
+    } else reason = "unavailable";
+    const left = deadline - performance.now();
+    if (left <= 0) return { reason };
+    await Bun.sleep(Math.min(40, left));
+  }
+}
+
 function opaqueId(sessionId: string, messageId: string): string {
   return createHash("sha256").update(sessionId).update("\0").update(messageId).digest("hex");
 }
@@ -30,7 +65,7 @@ export function readClaudeTranscriptUsage(sessionId: string, transcriptPath: str
       // Signal unavailable coverage with a stable opaque id; a repeated poll dedupes in the report.
       return [{ id: opaqueId(sessionId, "transcript-too-large") }];
     }
-    const latest = new Map<string, { usage?: NormalizedUsage; at?: string; servedModel?: string }>();
+    const latest = new Map<string, { usage?: NormalizedUsage; at?: string; servedModel?: string; completedTurn?: boolean }>();
     for (const line of readFileSync(transcriptPath, "utf8").split("\n")) {
       if (!line.trim()) continue;
       try {
@@ -43,7 +78,7 @@ export function readClaudeTranscriptUsage(sessionId: string, transcriptPath: str
         const usage = supportedStopReason ? normalizeUsage(message.usage) : undefined;
         const at = typeof row.timestamp === "string" && Number.isFinite(Date.parse(row.timestamp)) ? new Date(row.timestamp).toISOString() : undefined;
         const servedModel = safeModelLabel(message.model);
-        latest.set(message.id, { ...(usage ? { usage } : {}), ...(at ? { at } : {}), ...(servedModel ? { servedModel } : {}) });
+        latest.set(message.id, { ...(usage ? { usage } : {}), ...(at ? { at } : {}), ...(servedModel ? { servedModel } : {}), ...(message.stop_reason === "end_turn" ? { completedTurn: true } : {}) });
       } catch {
         // A streaming or crash-truncated line is not a record.
       }

package/src/pi/launch.ts

@@ -1,4 +1,5 @@
 import { join } from "node:path";
+import { peerChildEnv } from "../hub/child-process.ts";
 import type { PiOptions, PiModelDescriptor, PiTuiLaunch } from "../adapters/pi.ts";
 
 const modelFor = (backend: PiOptions["backend"], models: PiModelDescriptor[]): string => {
@@ -12,7 +13,7 @@ const modelFor = (backend: PiOptions["backend"], models: PiModelDescriptor[]): s
 
 /** Pure native launch; bridge/relay setup and session validation remain with the adapter. */
 export function buildPiLaunch(opts: Pick<PiOptions, "stateDir" | "cmd" | "mode" | "backend" | "model" | "relay" | "tools" | "preamble" | "maxSteps" | "sessionFile" | "sessionId">, inherited: NodeJS.ProcessEnv, extension: string, bridgePort: number | string, bridgeToken: string): PiTuiLaunch {
-  const env: NodeJS.ProcessEnv = { ...inherited, PI_CODING_AGENT_DIR: join(opts.stateDir, "pi"), AGENTHUB_PI_BRIDGE_URL: `http://127.0.0.1:${bridgePort}`, AGENTHUB_PI_BRIDGE_TOKEN: bridgeToken, AGENTHUB_PI_OWNER_TOKEN: bridgeToken, AGENTHUB_PI_RELAY_URL: opts.relay.url, AGENTHUB_PI_RELAY_TOKEN: opts.relay.token, AGENTHUB_PI_MODELS: JSON.stringify(opts.relay.models), AGENTHUB_PI_TOOLS: JSON.stringify(opts.tools), AGENTHUB_PI_MAX_STEPS: String(opts.maxSteps ?? 30) };
+  const env: NodeJS.ProcessEnv = { ...peerChildEnv("pi", inherited), PI_CODING_AGENT_DIR: join(opts.stateDir, "pi"), AGENTHUB_PI_BRIDGE_URL: `http://127.0.0.1:${bridgePort}`, AGENTHUB_PI_BRIDGE_TOKEN: bridgeToken, AGENTHUB_PI_OWNER_TOKEN: bridgeToken, AGENTHUB_PI_RELAY_URL: opts.relay.url, AGENTHUB_PI_RELAY_TOKEN: opts.relay.token, AGENTHUB_PI_MODELS: JSON.stringify(opts.relay.models), AGENTHUB_PI_TOOLS: JSON.stringify(opts.tools), AGENTHUB_PI_MAX_STEPS: String(opts.maxSteps ?? 30) };
   const args = [ ...(opts.mode === "headless" ? ["--mode", "rpc"] : []), "--provider", "agent-hub-local", "--model", opts.model ?? modelFor(opts.backend, opts.relay.models), "--models", opts.relay.models.map((model) => `agent-hub-local/${model.id}`).join(","), "--no-builtin-tools", "--no-skills", "--no-prompt-templates", "--no-extensions", "--extension", extension, ...(opts.preamble ? ["--append-system-prompt", opts.preamble] : []), "--session-dir", join(opts.stateDir, "pi-sessions")];
   if (opts.sessionFile) args.push("--session", opts.sessionFile); else if (opts.sessionId) args.push("--session-id", opts.sessionId);
   const command = opts.cmd ?? ["pi"];