@staix/agent-hub 0.15.0 → 0.17.0

package/src/adapters/reviewer-mcp.ts

@@ -10,6 +10,8 @@ export interface ReviewerMcpOptions {
   tools: readonly HubTool[];
   /** Fixed host port; the host still applies Tasks' role, privacy, head and running-child fences. */
   call(name: ReviewerToolName, args: Record<string, unknown>): Promise<string>;
+  /** Diagnostic metadata only; never tool arguments or successful result text. */
+  onTool?(name: ReviewerToolName, refusal?: string): void;
 }
 const NAMES: readonly ReviewerToolName[] = ["hub_review", "hub_task_show"];
 const BODY_CAP = 256 * 1024, RESULT_CAP = 4 * 1024 * 1024;
@@ -60,20 +62,24 @@ export function createReviewerMcpSession(options: ReviewerMcpOptions): ReviewerM
       if (!record(body.params)) return error("tool parameters required");
       const name = body.params.name;
       if (name !== "hub_review" && name !== "hub_task_show") return error("tool unavailable");
+      const observe = (refusal?: string) => { try { options.onTool?.(name, refusal); } catch { /* Diagnostics never change tool authority or results. */ } };
+      const refuse = (message: string, code?: number) => { observe(message); return error(message, code); };
+      observe();
       let args = body.params.arguments;
-      if (typeof args === "string") { try { args = JSON.parse(args); } catch { return error("invalid tool arguments"); } }
-      if (!record(args) || args.id !== options.task || !Number.isSafeInteger(args.id)) return error("tool is bound to its review task");
-      if (++calls > 64) return error("review tool call limit", -32002);
-      if (!current()) return error("review authority ended", -32001);
+      if (typeof args === "string") { try { args = JSON.parse(args); } catch { return refuse("invalid tool arguments"); } }
+      if (!record(args) || args.id !== options.task || !Number.isSafeInteger(args.id)) return refuse("tool is bound to its review task");
+      if (++calls > 64) return refuse("review tool call limit", -32002);
+      if (!current()) return refuse("review authority ended", -32001);
       try {
         const result = await options.call(name, args);
         // Tasks.review rechecks its captured authority through its final write. A successful verdict
         // ends that in_review binding itself; acknowledge its committed result, never fresh reads.
-        if (name !== "hub_review" && !current()) return error("review authority ended", -32001);
-        if (Buffer.byteLength(result) > RESULT_CAP) return error("tool result exceeds review limit");
+        if (name !== "hub_review" && !current()) return refuse("review authority ended", -32001);
+        if (Buffer.byteLength(result) > RESULT_CAP) return refuse("tool result exceeds review limit");
         return reply({ content: [{ type: "text", text: result }] });
       } catch (failure) {
         // The same host tool boundary supplies refusals to the released MCP transport.
+        observe(failure instanceof Error ? failure.message : "review tool refused");
         const message = failure instanceof Error ? sanitize(failure.message).slice(0, 4000) : "review tool refused";
         return reply({ isError: true, content: [{ type: "text", text: message }] });
       }

package/src/adapters/reviewer-print.ts

@@ -1,10 +1,10 @@
 import type { ChildProcess } from "node:child_process";
 import { OwnedPrintChild, PrintChildCleanupError } from "./claude-print-child.ts";
 import { randomUUID } from "node:crypto";
-import { HUB, frame } from "../hub/envelope.ts";
+import { HUB, frame, sanitize } from "../hub/envelope.ts";
 import { BasePeer } from "../hub/peers.ts";
 import type { Envelope } from "../hub/envelope.ts";
-import type { ReviewerMcpSession } from "./reviewer-mcp.ts";
+import type { ReviewerMcpSession, ReviewerToolName } from "./reviewer-mcp.ts";
 
 /** #722: the closed list of legs a reviewer's per-review start can fail on. A class names a leg, never a path, content or token. */
 export const REVIEWER_CAUSE_CLASSES = ["version", "binary", "mcp_inventory", "plugins_hooks_apps", "sandbox_proof", "credential_root", "timeout", "unknown"] as const;
@@ -27,6 +27,10 @@ export function reviewerUnavailableReason(cause: ReviewerCauseClass, detail?: st
 export class ReviewerUnavailableError extends Error {
   constructor(message: string, readonly causeClass: ReviewerCauseClass, readonly detail?: string) { super(message); }
 }
+/** A refused request says nothing about the reviewer's native isolation or ability to start. */
+class ReviewerAdmissionError extends Error {
+  constructor(readonly reason: "stale_binding" | "policy_changed") { super("review admission changed"); }
+}
 
 export interface ReviewerPrintUsage { input_tokens?: number; output_tokens?: number; cache_creation_input_tokens?: number; cache_read_input_tokens?: number }
 export interface ReviewerIsolationReceipt {
@@ -76,6 +80,31 @@ export interface ReviewerBackend {
   prepare(context: ReviewerPrepareContext): Promise<ReviewerLaunch | { unavailable: string; causeClass?: ReviewerCauseClass; detail?: string }>;
   usage?(event: unknown): ReviewerPrintUsage | undefined;
   failure?(event: unknown): "quota" | undefined;
+  /** Structured native MCP events only, never model messages or tool arguments. */
+  toolTrace?(event: unknown): ReviewerToolTrace | undefined;
+}
+export interface ReviewerToolTrace { tool: ReviewerToolName; refusal?: string }
+export interface ReviewerNoVerdict extends ReviewerReviewBinding {
+  task: number;
+  exitCode: number | null;
+  reviewCalled: boolean;
+  lastTool?: ReviewerToolName;
+  refusal?: string;
+  /** Preserve the first full host error across later truncated native echoes; differing host errors stay uncertain. */
+  hostRefusal?: string;
+  refusalUncertain?: true;
+}
+type ReviewerTraceState = Pick<ReviewerNoVerdict, "reviewCalled" | "lastTool" | "refusal" | "hostRefusal" | "refusalUncertain">;
+/** Host-produced receipt reason: an unconfirmed normal review fallback still needs a person's settlement. */
+export const REVIEWER_FALLBACK_UNCONFIRMED = "reviewer fallback unconfirmed: ";
+/** `safeRefusal` must have passed the host's complete privacy/secret screen before truncation. */
+export function reviewerNoVerdictLine(peer: string, diagnostic: ReviewerNoVerdict, safeRefusal?: string, withheld = false): string {
+  const prefix = `[${peer}] review of task #${diagnostic.task}: no verdict exit=${diagnostic.exitCode ?? "unknown"}; `;
+  if (withheld) return prefix + "diagnostic withheld";
+  const detail = diagnostic.lastTool ? `last hub tool ${diagnostic.lastTool}; ${diagnostic.reviewCalled ? "hub_review called" : "no hub_review call"}` : "no hub_review call";
+  const line = safeRefusal === undefined ? undefined : Array.from(sanitize(safeRefusal).replace(/\s+/g, " "))
+    .filter(char => !/\p{C}/u.test(char)).slice(0, 240).join("");
+  return prefix + detail + (diagnostic.refusal === undefined && diagnostic.hostRefusal === undefined ? "" : `; refusal: ${line ?? "withheld"}`);
 }
 export interface ReviewerFailure {
   task: number;
@@ -99,7 +128,9 @@ export interface ReviewerPrintOptions {
   facts?(env: Envelope): string | undefined;
   verdictSince(task: number, since: number): boolean;
   onUsage?(usage: ReviewerPrintUsage, task: number): void;
-  onUnavailable?(failure: ReviewerFailure, current: () => boolean): void | Promise<void>;
+  /** True confirms that the host re-offered the current review; void/false retains uncertainty. */
+  onUnavailable?(failure: ReviewerFailure, current: () => boolean): boolean | void | Promise<boolean | void>;
+  onNoVerdict?(diagnostic: ReviewerNoVerdict, current: () => boolean): void;
   log?(line: string): void;
   taskMcp?(task: number, current: () => boolean): ReviewerMcpSession;
   /** Synchronous host task/privacy/policy fence, checked again after awaited preparation. */
@@ -139,6 +170,24 @@ export class ReviewerPrintPeer extends BasePeer {
   reviewing: number | undefined;
   private reviewSeq = 0;
   private runningBinding: { task: number; binding: ReviewerReviewBinding } | undefined;
+  private activeTrace: { task: number; generation: number; value: ReviewerTraceState } | undefined;
+  /** Host observations are diagnostic data and never grant tool or verdict authority. */
+  recordToolTrace(task: number, trace: ReviewerToolTrace): void {
+    if (trace.tool !== "hub_review" && trace.tool !== "hub_task_show") return;
+    const active = this.activeTrace, binding = this.runningBinding;
+    if (!active || active.task !== task || active.generation !== this.generation || this.reviewing !== task || binding?.task !== task || this.opts.bindingCurrent?.(task, binding.binding) === false) return;
+    if (typeof trace.refusal === "string") {
+      if (active.value.hostRefusal === undefined) active.value.hostRefusal = trace.refusal;
+      else if (active.value.hostRefusal !== trace.refusal) active.value.refusalUncertain = true;
+    }
+    this.observeTool(active.value, trace);
+  }
+  private observeTool(value: ReviewerTraceState, trace: ReviewerToolTrace): void {
+    if (trace.tool !== "hub_review" && trace.tool !== "hub_task_show") return;
+    value.lastTool = trace.tool;
+    value.refusal = typeof trace.refusal === "string" ? trace.refusal : undefined;
+    if (trace.tool === "hub_review") value.reviewCalled = true;
+  }
   /** Immutable envelope identity of this running child, never the board's later head. */
   reviewBinding(task: number): ReviewerReviewBinding | undefined {
     return this.reviewing === task && this.runningBinding?.task === task ? this.runningBinding.binding : undefined;
@@ -234,10 +283,20 @@ export class ReviewerPrintPeer extends BasePeer {
       if (task === undefined) continue; // a withdrawal or other notice: nothing to review
       if (env.private) { failure = { state: "needs_review", reason: "a private review is the person's, never a cloud reviewer's" }; break; }
       const since = Date.now();
-      let result: { code: number | null; quota: boolean };
+      let result: { code: number | null; quota: boolean; trace: ReviewerTraceState };
       try { result = await this.review(env, task, generation); }
       catch (error) {
         if (generation !== this.generation) return;
+        if (error instanceof ReviewerAdmissionError) {
+          this.opts.log?.(`[${this.id}] review of task #${task} skipped: ${error.reason === "stale_binding" ? "stale binding" : "review policy changed"}`);
+          if (error.reason === "policy_changed") {
+            missing.push(task);
+            const target = batch.targets[index];
+            if (target) reroute.push({ ...target, cause: "no_verdict" });
+          }
+          batch.next = index + 1;
+          continue;
+        }
         if (error instanceof PrintChildCleanupError) {
           // Unavailable until a stop confirms the group gone: no new review runs beside the survivors.
           this.opts.log?.(`[${this.id}] review of task #${task}: ${error.message}`);
@@ -259,6 +318,11 @@ export class ReviewerPrintPeer extends BasePeer {
       if (!recorded) {
         missing.push(task);
         const target = batch.targets[index];
+        const diagnostic = { ...target, task, exitCode: result.code, ...result.trace };
+        try {
+          if (this.opts.onNoVerdict) this.opts.onNoVerdict(diagnostic, () => generation === this.generation);
+          else this.opts.log?.(reviewerNoVerdictLine(this.id, diagnostic));
+        } catch { this.opts.log?.(reviewerNoVerdictLine(this.id, { task, exitCode: result.code, reviewCalled: false }, undefined, true)); }
         if (target) reroute.push({ ...target, cause: result.quota ? "quota" : "no_verdict" });
         if (result.quota) {
           reroute.push(...remainingFailures(batch, index + 1, "quota"));
@@ -267,25 +331,30 @@ export class ReviewerPrintPeer extends BasePeer {
         }
       }
       batch.next = index + 1;
-      if (result.code !== 0) this.opts.log?.(`[${this.id}] review of task #${task} exited ${result.code}`);
+      if (recorded && result.code !== 0) this.opts.log?.(`[${this.id}] review of task #${task} exited ${result.code}`);
     }
     if (generation !== this.generation) return;
     this.clearWatchdog(); // the child is gone; keep busy while the host settles the remaining walk
-    this.settle(failure?.state ?? (missing.length ? "needs_review" : "completed"), failure?.reason ?? (missing.length ? `no verdict recorded for task ${missing.map(id => `#${id}`).join(", ")}` : undefined));
-    await this.reportFailures(reroute, generation);
+    const reoffered = await this.reportFailures(reroute, generation);
+    if (generation !== this.generation) return;
+    const unresolved = missing.length > 0 && !reoffered;
+    const normalNoVerdict = !failure && reroute.length > 0 && reroute.every(value => value.cause === "no_verdict");
+    this.settle(failure?.state ?? (unresolved ? "needs_review" : "completed"), failure?.reason ?? (unresolved ? `${normalNoVerdict ? REVIEWER_FALLBACK_UNCONFIRMED : ""}no verdict recorded for task ${missing.map(id => `#${id}`).join(", ")}` : undefined));
     if (generation === this.generation) { this.batch = undefined; this.setState("idle"); }
   }
 
-  private async reportFailures(failures: readonly ReviewerFailure[], generation: number): Promise<void> {
+  private async reportFailures(failures: readonly ReviewerFailure[], generation: number): Promise<boolean> {
     const seen = new Set<string>();
+    let reoffered = true;
     for (const failed of failures) {
-      if (generation !== this.generation) return;
+      if (generation !== this.generation) return false;
       const identity = JSON.stringify([failed.task, failed.head, failed.flowRevision]);
       if (seen.has(identity)) continue;
       seen.add(identity);
-      try { await this.opts.onUnavailable?.(failed, () => generation === this.generation); }
-      catch { this.opts.log?.(`[${this.id}] reviewer fallback could not be recorded; inspect the task`); }
+      try { if (await this.opts.onUnavailable?.(failed, () => generation === this.generation) !== true) reoffered = false; }
+      catch { reoffered = false; this.opts.log?.(`[${this.id}] reviewer fallback could not be recorded; inspect the task`); }
     }
+    return reoffered;
   }
 
   private prepare(sessionId: string, input?: string, task?: number, mcpConfig?: string): Promise<ReviewerLaunch> {
@@ -313,14 +382,21 @@ export class ReviewerPrintPeer extends BasePeer {
     return done;
   }
 
-  private async review(env: Envelope, task: number, generation: number): Promise<{ code: number | null; quota: boolean }> {
-    if (this.opts.admit?.(env) === false) throw new Error("review admission changed");
+  private assertAdmission(env: Envelope, task: number, binding: ReviewerReviewBinding): void {
+    if (this.opts.bindingCurrent?.(task, binding) === false) throw new ReviewerAdmissionError("stale_binding");
+    if (this.opts.admit?.(env) === false) throw new ReviewerAdmissionError(this.opts.bindingCurrent?.(task, binding) === false ? "stale_binding" : "policy_changed");
+  }
+
+  private async review(env: Envelope, task: number, generation: number): Promise<{ code: number | null; quota: boolean; trace: ReviewerTraceState }> {
+    const revision=Number(env.refs?.reviewRevision);
+    const binding: ReviewerReviewBinding=Object.freeze({head:env.refs?.commit,flowRevision:Number.isSafeInteger(revision)&&revision>0?revision:undefined});
+    this.assertAdmission(env, task, binding);
     let facts: string | undefined;
     try { facts = this.opts.facts?.(env); } catch (error) { this.opts.log?.(`[${this.id}] review facts for task #${task} failed: ${(error as Error).message}`); }
     const input = `${frame(env)}${facts ? `\n\n${facts}` : ""}`;
     let launch: ReviewerLaunch | undefined;
-    const revision=Number(env.refs?.reviewRevision);
-    const binding: ReviewerReviewBinding=Object.freeze({head:env.refs?.commit,flowRevision:Number.isSafeInteger(revision)&&revision>0?revision:undefined});
+    const trace: ReviewerTraceState = { reviewCalled: false };
+    this.activeTrace = { task, generation, value: trace };
     const mcp = this.opts.backend.taskMcp ? this.opts.taskMcp?.(task, () => generation === this.generation && this.reviewToken(task) !== undefined && this.opts.bindingCurrent?.(task,binding) !== false) : undefined;
     let mcpClosed=false;
     const closeMcp=()=>{ if(mcpClosed)return; mcpClosed=true; mcp?.close(); if(this.reviewMcpClose===closeMcp)this.reviewMcpClose=undefined; };
@@ -330,7 +406,9 @@ export class ReviewerPrintPeer extends BasePeer {
     const release = () => releasing ??= Promise.resolve().then(() => launch?.cleanup?.()).then(() => {});
     try {
     launch = await this.prepare(randomUUID(), input, task, mcp?.config);
-    if (generation !== this.generation || this.opts.admit?.(env) === false || launch.current?.() === false) throw new ReviewerUnavailableError("reviewer isolation or admission changed before child spawn", launch.current?.() === false ? "binary" : "unknown");
+    if (generation !== this.generation) throw new ReviewerAdmissionError("stale_binding");
+    this.assertAdmission(env, task, binding);
+    if (launch.current?.() === false) throw new ReviewerUnavailableError("reviewer isolation changed before child spawn", "binary");
     this.receipt = launch.isolation;
     let quota = false;
     const child = new OwnedPrintChild({ peer: this.id, command: launch.command, args: launch.args,
@@ -343,6 +421,10 @@ export class ReviewerPrintPeer extends BasePeer {
         if (this.childCurrent) policyTimer = setInterval(() => { this.reviewToken(task); }, 100);
       },
       onFrame: event => {
+        try {
+          const observed = this.opts.backend.toolTrace?.(event);
+          if (observed && generation === this.generation) this.observeTool(trace, observed);
+        } catch { /* Optional trace metadata never changes review execution. */ }
         const usage = this.opts.backend.usage?.(event);
         if (usage) this.opts.onUsage?.(usage, task);
         if (this.opts.backend.failure?.(event) === "quota") quota = true;
@@ -359,8 +441,9 @@ export class ReviewerPrintPeer extends BasePeer {
     this.childCurrent = launch.watchCurrent ? launch.current : undefined;
     const code = await child.done;
     if (this.child === child) this.child = undefined;
-    return { code, quota };
+    return { code, quota, trace };
     } finally {
+      if (this.activeTrace?.value === trace) this.activeTrace = undefined;
       closeMcp();
       if (policyTimer) clearInterval(policyTimer);
       try { if (!ownedChild || this.child !== ownedChild) { await release(); if (this.childCleanup === release) this.childCleanup = undefined; } }

package/src/cli/console-state.ts

@@ -10,6 +10,7 @@ import type { SettingRow, SettingValue } from "../hub/settings.ts";
 import { symbolFields, overlapFields } from "./console-symbols.ts";
 import { choicePrompt, reviewChoiceFor, reviewHint, reviewRefusal, verdictGuide, verdictInput, type ReviewChoice, type Verdict } from "./console-review.ts";
 import { configFormPrompt, reduceConfigForm, type ConfigEditBody, type ConfigForm } from "./console-config.ts";
+import { windowKind } from "../hub/window-kind.ts";
 import { USAGE_DROP, USAGE_HEAD, usageCells, usageDetail, usagePeers, usageTaskLines, type UsageState } from "./console-usage.ts";
 
 export interface Approval {
@@ -334,8 +335,25 @@ function taskFields(detail: Record<string, unknown>): [string, unknown][] {
   const at = fields.findIndex(([key]) => key === "plan");
   return at < 0 ? [...fields, ...block] : [...fields.slice(0, at + 1), ...block, ...fields.slice(at + 1)];
 }
-const detailLines = (detail: Detail, columns: number, now: number, task = false): Span[][] =>
-  typeof detail === "string" ? wrap(detail, columns).map(text => [span(text)]) : fieldLines(task ? taskFields(detail) : Object.entries(detail), columns, now).flat();
+/**
+ * The Peers panel's detail row carries the whole peer, `budget` included. Its windows read as one line each: `5h 23% resets in 10m, native, claude status line, measured 6s ago`,
+ * so a person sees what each number is and where it came from (#285 AC7). A window without a kind (an older hub) is classified like the CLI does.
+ */
+export function budgetFields(budget: any, now: number): [string, unknown][] {
+  if (!budget || typeof budget !== "object") return [];
+  const windows = Array.isArray(budget.windows) ? budget.windows : [];
+  const lines = windows.map((w: any) => {
+    const stale = w.stale ? " (stale)" : w.superseded ? " (information only: a measurement outranks it)" : "";
+    return `${w.id} ${Math.round(Number(w.used) * 100)}%${typeof w.resetsAt === "number" ? ` resets ${relative(w.resetsAt, now)}` : ""}, ${windowKind({ id: String(w.id), source: typeof w.source === "string" ? w.source : "", kind: w.kind })}, ${typeof w.source === "string" ? w.source : "unknown source"}${typeof w.at === "number" ? `, measured ${relative(w.at, now)}` : ""}${stale}`;
+  });
+  return [["quota", lines.length ? lines : typeof budget.note === "string" ? budget.note : "no reading"], ...(lines.length && typeof budget.note === "string" ? [["quota note", budget.note] as [string, unknown]] : [])];
+}
+const detailLines = (detail: Detail, columns: number, now: number, task = false): Span[][] => {
+  if (typeof detail === "string") return wrap(detail, columns).map(text => [span(text)]);
+  const { budget, ...rest } = detail as Record<string, unknown>;
+  const entries: [string, unknown][] = task ? taskFields(detail) : "budget" in detail && !task ? [...Object.entries(rest), ...budgetFields(budget, now)] : Object.entries(detail);
+  return fieldLines(entries, columns, now).flat();
+};
 const allowOptions = (a: Approval) => a.options.filter(o => o.kind.startsWith("allow"));
 /** A pushed request as the console keeps it: every agent-supplied field a string, so no draw can throw on one. */
 export function approvalFrom(msg: any): Approval {

package/src/cli/console-symbols.ts

@@ -40,8 +40,9 @@ export function classifySymbols(task: any): SymbolBlock {
 export function symbolFields(task: any): [string, unknown][] {
   // Only a task as `task_show` shapes it (a numeric id and a state): any other detail an agent or a test hands the Tasks panel keeps its own layout.
   if (!task || typeof task.id !== "number" || typeof task.state !== "string" || isPrivate(task)) return [];
+  const related: [string, unknown][] = task.relatedMemory ? [["related notes", task.relatedMemory.state === "known" && Number.isSafeInteger(task.relatedMemory.count) && task.relatedMemory.count >= 0 ? task.relatedMemory.count : "unknown"]] : [];
   const block = classifySymbols(task);
-  if (block.state === "unknown") return [["symbols", "changed symbols: unknown (no code facts)"]];
+  if (block.state === "unknown") return [...related, ["symbols", "changed symbols: unknown (no code facts)"]];
   const items: Record<string, string>[] = [
     ...block.matching.map(s => ({ matching: s.name, in: s.path })), ...block.unplanned.map(s => ({ unplanned: s.name, in: s.path })), ...block.untouched.map(name => ({ untouched: name })),
   ];
@@ -49,7 +50,7 @@ export function symbolFields(task: any): [string, unknown][] {
   const note = [`changed symbols: ${block.matching.length} matching, ${block.unplanned.length} unplanned, ${block.untouched.length} untouched${block.head ? ` at ${block.head}` : ""}`,
     block.complete ? "" : "incomplete: some changed symbols were not listed, so an untouched one may have changed",
     "advisory: deleted symbols are not reported"].filter(Boolean).join("; ");
-  return [["symbols", shown.length ? shown : "none observed"], ["symbols note", items.length > shown.length ? `${note}; ${items.length - shown.length} more not shown` : note]];
+  return [...related, ["symbols", shown.length ? shown : "none observed"], ["symbols note", items.length > shown.length ? `${note}; ${items.length - shown.length} more not shown` : note]];
 }
 
 

package/src/cli/console-usage.ts

@@ -1,3 +1,4 @@
+import { windowKind, type WindowKind } from "../hub/window-kind.ts";
 import type { Counter, LimitsResult, UsageResult, UsageRow } from "../hub/usage-rollup.ts";
 
 // #683 U3: what the console's Usage panel shows, as plain strings. No terminal code and no state import here: console-state.ts renders it.
@@ -32,7 +33,7 @@ export function usagePeers(usage: UsageState | undefined, budget: Record<string,
   return [...ids].sort().map(id => ({ id }));
 }
 
-interface Budget { windows?: { id: string; used: number; resetsAt?: number }[]; paused?: { resetsAt: number } }
+interface Budget { windows?: { id: string; used: number; resetsAt?: number; kind?: string; source?: string }[]; paused?: { resetsAt: number }; note?: string }
 const windowText = (w: { id: string; used: number; resetsAt?: number }, rel: (at: number) => string) =>
   `${w.id} ${Math.round(w.used * 100)}%${typeof w.resetsAt === "number" ? ` ${rel(w.resetsAt)}` : ""}`;
 const lastResets = (limits: LimitsResult | undefined, peer: string, count: number) =>
@@ -66,7 +67,9 @@ export function usageDetail(usage: UsageState | undefined, peer: string, budget:
   const resets = lastResets(usage?.limits, peer, 3).map(h => `${h.window} ${rel(Date.parse(h.at))}`);
   const out: Record<string, string> = {
     peer,
-    quota: budget?.windows?.length ? budget.windows.map(w => windowText(w, rel)).join(", ") : "no reading",
+    quota: budget?.windows?.length ? budget.windows.map(w => windowText(w, rel)).join(", ") : budget?.note ?? "no reading",
+    // What each number is and where it came from (#285 AC7), in its own field so the quota line keeps its shape.
+    ...(budget?.windows?.length ? { "quota sources": budget.windows.map(w => `${w.id} ${windowKind({ id: w.id, source: w.source, kind: w.kind as WindowKind | undefined })}${w.source ? `, ${w.source}` : ""}`).join("; ") } : {}),
     pause: budget?.paused ? `budget pause, resumes ${rel(budget.paused.resetsAt)}` : "none",
     "last resets": resets.length ? resets.join(", ") : "none recorded",
     today: splitText(rowOf(usage?.today, peer)),

package/src/cli/console.ts

@@ -226,7 +226,11 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
         state.recoveryNeed = status.status.recovery ? { id: status.status.recovery.operationId, running: true } : undefined;
       }
       if (syncPermissionDefaults(state, status.status?.permissionDefaults) && state.confirm?.type === "permission_default") stream({ text: permissionDefaultText(state.confirm), kind: "permission_default", peer: state.confirm.peer, tone: "attention" });
-      if (budget.budget) state.budget = budget.budget;
+      if (budget.budget) {
+        // #285: the hub's note per peer (no quota, nothing read yet) rides next to the windows, so the peer detail says why a number is missing.
+        const notes = new Map<string, any>((Array.isArray(budget.peers) ? budget.peers : []).map((n: any) => [String(n?.peer), n] as const));
+        state.budget = Object.fromEntries([...new Set([...Object.keys(budget.budget), ...notes.keys()])].map(peer => [peer, { windows: [], ...budget.budget[peer], ...(notes.get(peer)?.note ? { note: String(notes.get(peer).note) } : {}) }]));
+      }
       if (usageReplies) {
         const [today, week, life, limits, task] = usageReplies, failed = usageReplies.find(reply => reply?.ok === false);
         if (failed || !today?.usage || !week?.usage || !life?.usage || !limits?.limits) state.usage = { ...state.usage, problem: String(failed?.error ?? "usage is unavailable") };

package/src/cli/help.ts

@@ -40,7 +40,8 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub status [--json] [--full] [--color=auto|always|never]", "the hub, its peers, model backends and task counts"],
     ["ahub status --all [--json] [--color=auto|always|never]", "show every registered project"],
     ["ahub logs [-f]", "the last 100 lines of hub.log; -f shows the last 10 and follows it"],
-    ["ahub doctor [--json] [--full] [--color=auto|always|never]", "check the tools, daemon, plugin, gateway, models and memory worker this project uses"],
+    ["ahub doctor [--json] [--full] [--color=auto|always|never]", "check the tools, daemon, plugin, gateway, models and memory library this project uses"],
+    ["ahub doctor --stale-anchors [--json]", "read-only bounded report of public memory symbol anchors at current HEAD; private or unavailable evidence stays unknown"],
     ["ahub doctor --orphans [--kill] [--json] [--color=auto|always|never]", "list registrations whose project root is gone; --kill stops their daemons (SIGTERM, then SIGKILL) only after the process identity checks out"],
     ["ahub agents [--json]", "show each gated agent CLI's installed version and verdict (verified, in-line, trusted, refused or unknown)"],
     ["ahub agents trust <id> <version> [--revoke]", "accept an untested agent CLI version on this machine (person only; runtime proofs still run)"],
@@ -84,14 +85,15 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub board import github --label <label> [--milestone <milestone>] [--repo <owner/repo>]", "person only: read bounded open issues into deduplicated Backlog; never writes GitHub"],
     ["ahub board [state | --ready] [--columns] [--release <name> | --release-id <id>] [--json] [--full] [--color=auto|always|never]", "the task board, one line per task at a terminal width; --full: whole titles and SDLC advice; --ready: proposed tasks with nothing left to wait for"],
     ["ahub task propose [--class <c> | <class>] <title...> [--owner <peer>] [--path <p>]... [--after <id>]... [--urgent] [--backlog] [--detail <text>]", "put a task on the board; a first word that names a class is taken as the class; while a task named by --after is not approved yet, --owner reserves the task for that peer, offered to it first once it is ready; otherwise --owner assigns it now"],
-    ["ahub backlog list [--json] [--full] [--color=auto|always|never] | add <class> <title...> | plan <id> <revision> <fields-json> <reason...> | pin <id> <revision> true|false <reason...> | undo <id> <revision>", "person only: stage and plan work, preserve pins/frozen scope and refuse stale edits; list is a table by rank (--json: the raw listing)"],
+    ["ahub backlog list [--json] [--full] [--color=auto|always|never] | add <class> <title...> | plan <id> <revision> <fields-json> <reason...> | pin <id> <revision> true|false <reason...> | undo <id> <revision>", "person only: plan work with a reason; {} records a note-only revision, fields.sdlc sets backlog repo/issue identity and clears old spec acceptance; preserve pins/frozen scope and refuse stale edits; list is by rank (--json: raw listing)"],
     ["ahub release new <name> <goal> <order> | list | show <name> | plan <name> <revision> <dates-json> | activate|freeze|ship|drop <name> <revision>", "person only: planned UTC millisecond dates and phased scope; ship records a time after approval, never tags or publishes"],
     ["ahub backlog split <id> <revision> <parts-json> <reason...>", "person only: stage2..8 child prerequisites; original task retains integration, undo refuses used or changed children"],
     ["ahub backlog pull-ready <id> <revision> <reason...>", "person only: reserve an eligible WIP slot before routing; pending unowned work can be undone"],
     ["ahub backlog pull|return <id>", "person only: pull backlog into To Do or return ownerless proposed work; --backlog on task propose stages unoffered work"],
+    ["ahub deliverables [--task <id>] [--approved] [--check] [--json] [--color=auto|always|never]", "person only: what each task delivered and a reviewer approved, by id, hash and size (a path only where the PII screen allows); --check measures the files now and marks one changed since review"],
     ["ahub task show|escalate <id>", "full task with history (PII text included) / hand it to the next peer in escalate_to"],
     ["ahub task role <id> <role|none>", "person only: change bounded catalog guidance on an open task; routing and authority are unchanged"],
-    ["ahub task assign <id> <peer> [--role owner|reviewer] [--revision N]", "name the owner (default) or reviewer; a task that still waits reserves its owner; a peer that cannot take it is refused with the reason; --revision refuses stale console actions"],
+    ["ahub task assign <id> <peer> [--role owner|reviewer|planner] [--revision N]", "name the owner (default), reviewer or person-only planner; a task that still waits reserves its owner; a peer that cannot take it is refused with the reason; --revision refuses stale console actions"],
     ["ahub task unassign <id> [--role owner|reviewer] [--revision N]", "person only: remove the owner/reservation or reviewer without routing a replacement or stopping native work"],
     ["ahub task cancel <id> --reason <text> [--superseded-by <ref>] [--revision N]", "person only: close obsolete work with a reason; retain its history without stopping native work or releasing dependents"],
     ["ahub task label <id> ok|regressed|reverted|incomplete|wrong|abandoned [--created <time>]", "your later verdict on an approved task, kept in the research records (research must be on)"],
@@ -103,7 +105,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub remember <text...>", "save a note to the memory all agents share"],
   ]],
   ["Budget", [
-    ["ahub budget [--json] [--full] [--color=auto|always|never]", "quota windows per peer, and who is paused until when"],
+    ["ahub budget [--json] [--full] [--color=auto|always|never]", "quota windows per peer with each number's kind (native, count, manual) and source, why a peer shows no number, and who is paused until when"],
     ["ahub budget set <peer> <0..1> [--resets-in 30m] [--window 5h|week]", "feed a reading by hand (also: test the relay)"],
     ["ahub budget resume <peer>", "override a budget pause; readings are ignored for that peer until the window resets"],
     ["ahub budget execution status [id] [--json] [--color=auto|always|never]", "read execution counters and limits"],
@@ -129,7 +131,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub bench export [--format jsonl|csv]", "benchmark records for outside analysis: ids, outcomes and counts, never suite text"],
     ["ahub check-path <file> [--peer <id>]", "other owners' open tasks that claim or changed a file"],
     ["ahub memory [list] [--tier short|long] [--kind <kind>] [--peer <p>] [--machine <id>] [--since <iso>] [--limit N] [--json]", "the hub's own memory for this project: decisions, contracts, fails and findings, short- and long-term (docs/memory.md)"],
-    ["ahub memory search <words> | show <id> | graph <id|node> [--hops 1|2] [--json]", "find entries, read one with its provenance, or list its graph neighbourhood"],
+    ["ahub memory search <words> | show <id> | graph <id|node> [--hops 1|2] [--history | --as-of <iso>] [--json]", "find entries, read one with its provenance, or list its graph neighbourhood; superseded and expired entries are hidden unless a person asks for --history or --as-of"],
     ["ahub memory promote|demote|forget <id> | supersede <old> <new> | rebuild", "a person's changes to memory: move an entry between tiers, forget it, mark it superseded, or rebuild the index from the logs"],
     ["ahub memory sync [--remote <private git url>] | machine [--label <name>]", "sync hub memory with your other machines through a private git remote (a person's), or show or name this machine"],
     ["ahub memory import claude-mem [--db <path>] [--limit N] [--restart] | dedupe [--apply] | suggestions | confirm|reject <id>", "copy the hub's notes from claude-mem into hub memory (a person's); review the model's suggested edges"],

package/src/cli/identity.ts

@@ -17,7 +17,7 @@ export function liveTestRefusal(command: string, args: readonly string[], contex
   if (command === "sdlc" && (args[0] === "authorize-release" || args[0] === "plan-review" || args[0] === "release-assign" || args[0] === "train" && args[1] !== "report")) return true;
   if (args.some(arg => arg === "--as-user" || arg.startsWith("--as-user="))) return true;
   const sub = command === "recovery" ? recoveryAction(args) : args.find(arg => arg !== "--json");
-  return ["task", "role", "goal"].includes(command)
+  return ["task", "role", "goal", "deliverables"].includes(command)
     || (command === "backlog" && sub !== "list") || (command === "release" && !["list", "show"].includes(sub ?? ""))
     || (command === "memory" && sub !== "graph")
     || (command === "recovery" && (sub === "reattach" || sub === "dispose" && context.repairedFresh === true))
@@ -68,6 +68,8 @@ export function classifyPeerCommand(command: string, args: readonly string[], ca
     if (["assign", "escalate"].includes(args[0] ?? "")) return "conductor";
     return "console";
   }
+  // #317: the deliverable list is the person's view of the board (it can name files); an agent reads its own tasks through hub_task_show.
+  if (command === "deliverables") return "console";
   if (command === "route") return args[0] === "explain" ? "allowed" : "console";
   // #691: reading agent CLI versions is harmless; trusting an untested version on this machine is a person's.
   if (command === "agents") return args.every(arg => arg === "--json") ? "allowed" : "console";

package/src/cli/main.ts

@@ -1,4 +1,6 @@
 #!/usr/bin/env bun
+import type { DeliverableRow } from "../hub/tasks.ts";
+import { kimiSourceRow } from "../hub/budget-notes.ts";
 import { hubGitSync, hubGitEnv } from "../hub/git.ts";
 import { parseReleaseGuardArgv, parseReleasePushUpdates } from "./sdlc-release-guard.ts";
 import { validReleaseVersion } from "../hub/sdlc-release-authorization.ts";
@@ -46,7 +48,6 @@ import { inspectProject, startProject, stopProject, runProjectDaemon } from "../
 import { processLiveness, processSignature } from "../pi/process-signature.ts";
 import { openManager, startManager, stopManager } from "../hub/manager.ts";
 import { OmniRoute } from "../omniroute/client.ts";
-import { MemoryClient } from "../memory/client.ts";
 import { init, planInit } from "./init.ts";
 import { launcherPreview } from "./preview.ts";
 import { instanceLaunchArguments, requirePeerInstances, requireActiveInstance, cleanupStaleClaudeSettings, cleanupClaudeSettings, buildLaunch, buildKimiTuiLaunch, claudeObservationHooks, nativeLaunchEnv, recordClaudeLaunch, runClaudeLaunch, type ClaudeLaunchRecord, UNATTENDED_WARNING } from "./launch.ts";
@@ -75,8 +76,9 @@ import { parseSince, readEvents } from "../hub/events.ts";
 import { armRuns, benchCompare, benchCsv, benchReport, formatCompare, formatReport as formatBenchReport, formatRuns, MEMORY_MODES, readRuns, runSummary, sameSuite, type MemoryMode } from "../hub/bench.ts";
 import { benchPreflight, defaultIo, runBench } from "./bench.ts";
 import { ADDONS, isAddon, type AddonName } from "../hub/tooling.ts";
-import { goalCommand, memoryCommand } from "./memory.ts";
-import { selectedMemoryProfile } from "../hub/memory-profile.ts";
+import { goalCommand, memoryCommand, memoryStaleAnchorsCommand } from "./memory.ts";
+import { formatMemoryStaleAnchors } from "../hub/memory-stale-anchors.ts";
+import { AGENT_MEM_VERSION, assertAgentMemVersion, selectedMemoryProfile } from "../hub/memory-profile.ts";
 import { checkMemoryProfiles, formatMemoryProfileCheck } from "../hub/memory-profile-check.ts";
 import { addonReport, appendRecords, formatAddons, formatResearch, LABELS, labelTarget, RESEARCH_SCHEMA, projectKey, readStores, researchReport, taskRecords, toCsv, type Label, type TaskRecord } from "../hub/research.ts";
 import { summarize, summarizeByTask } from "../hub/report.ts";
@@ -1140,7 +1142,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     const res = await hub.request({ t: "budget", ...(set ? { set } : {}) });
     hub.close();
     if (!res.ok) fail(res.error);
-    const data = { budget: res.budget, gate: res.gate };
+    const data = { budget: res.budget, ...(res.peers ? { peers: res.peers } : {}), gate: res.gate };
     if (options.json) return console.log(JSON.stringify(data, null, 2));
     printOutput(renderBudget(data, options.columns, Date.now(), options.full), options.color);
   },
@@ -1195,6 +1197,27 @@ const commands: Record<string, () => Promise<void> | void> = {
     console.log(await taskOp("release_change", { name, revision: Number(revision), fields }));
   },
 
+  deliverables: async () => {
+    // #317: what each task delivered and what a reviewer approved, by id, hash and size (a path only where the PII screen allows it). Person only: the daemon refuses an agent.
+    const options = outputOptions();
+    const { one, rest } = takeFlags(args, ["--task"], []);
+    const approved = rest.includes("--approved"), check = rest.includes("--check");
+    const extra = rest.filter(arg => !["--json", "--full", "--approved", "--check"].includes(arg) && !arg.startsWith("--color="));
+    const task = one["--task"] === undefined ? undefined : Number(one["--task"]);
+    // takeFlags keeps the last of a repeated flag: for a command that selects a task that would silently drop one of two named tasks.
+    if (args.filter(arg => arg === "--task").length > 1) fail("usage: ahub deliverables [--task <id>] [--approved] [--check] [--json] [--color=auto|always|never] (--task takes one id)");
+    if (extra.length || (one["--task"] !== undefined && !/^[1-9]\d*$/.test(one["--task"])) || (task !== undefined && !Number.isSafeInteger(task))) fail("usage: ahub deliverables [--task <id>] [--approved] [--check] [--json] [--color=auto|always|never]");
+    const rows = JSON.parse(await taskOp("deliverables", { ...(task === undefined ? {} : { task }), ...(approved ? { approved: true } : {}), ...(check ? { check: true } : {}) })) as DeliverableRow[];
+    if (options.json) return console.log(JSON.stringify(rows, null, 2));
+    if (!rows.length) return console.log(task === undefined ? `no ${approved ? "approved " : ""}deliverables on the board` : `task #${task} has no ${approved ? "approved " : ""}deliverables`);
+    for (const row of rows) {
+      const flag = row.checked ? ({ changed: " (changed since review)", missing: " (a file is missing)", unknown: " (could not be measured)", unchanged: " (unchanged)" } as const)[row.result ?? "unknown"] : "";
+      console.log(`${row.title} [${row.state}${flag}]`);                                   // `title` is the hub's publicTitle: it already starts with `#<id>`
+      for (const file of row.files) console.log(`  ${file.id}  ${file.path ?? "(private)"}  ${file.format}${file.version ? ` ${file.version}` : ""}  ${file.bytes} B  sha256 ${file.sha256}${file.state ? `  ${file.state}` : ""}`);
+    }
+    if (!check) console.log("(hashes are the board's records; add --check to measure the files now)");
+  },
+
   board: async () => {
     if (args[0] === "import") {
       if (args[1] !== "github" || (args.length - 2) % 2 !== 0) fail("usage: ahub board import github --label <label> [--milestone <milestone>] [--repo <owner/repo>]");
@@ -1380,8 +1403,8 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (sub === "assign") {
       const { one, rest: positional } = takeFlags(rest, ["--role", "--revision"], []);
       const role = one["--role"] ?? "owner", rawRevision = one["--revision"], revision = rawRevision === undefined ? undefined : Number(rawRevision);
-      if (positional.length !== 2 || !["owner", "reviewer"].includes(role) || (rawRevision !== undefined && (!/^\d+$/.test(rawRevision) || !Number.isSafeInteger(revision)))) fail("usage: ahub task assign <id> <peer> [--role owner|reviewer] [--revision N]");
-      return console.log(await taskOp(revision === undefined ? "task_assign" : "task_assign_checked", { id: positional[0], peer: positional[1], ...(role === "reviewer" ? { role } : {}), ...(revision === undefined ? {} : { revision }) }));
+      if (positional.length !== 2 || !["owner", "reviewer", "planner"].includes(role) || (rawRevision !== undefined && (!/^\d+$/.test(rawRevision) || !Number.isSafeInteger(revision)))) fail("usage: ahub task assign <id> <peer> [--role owner|reviewer|planner] [--revision N]");
+      return console.log(await taskOp(revision === undefined ? "task_assign" : "task_assign_checked", { id: positional[0], peer: positional[1], ...(role !== "owner" ? { role } : {}), ...(revision === undefined ? {} : { revision }) }));
     }
     if (sub === "unassign") {
       const { one, rest: positional } = takeFlags(rest, ["--role", "--revision"], []);
@@ -2101,6 +2124,12 @@ const commands: Record<string, () => Promise<void> | void> = {
 
   doctor: async () => {
     const options = outputOptions();
+    if (args.includes("--stale-anchors")) {
+      if (args.some(arg => arg !== "--stale-anchors" && arg !== "--json")) fail("usage: ahub doctor --stale-anchors [--json]");
+      const report = await memoryStaleAnchorsCommand(cwd, { stateDir });
+      console.log(options.json ? JSON.stringify(report, null, 2) : formatMemoryStaleAnchors(report));
+      return;
+    }
     if (args.includes("--orphans")) return orphanDoctor(args.includes("--kill"), options);
     const version = (bin: string) => {
       const res = spawnSync(bin, ["--version"], { encoding: "utf8" });
@@ -2128,6 +2157,10 @@ const commands: Record<string, () => Promise<void> | void> = {
           const { status } = await hub.request({ t: "status" });
           const pending = Object.values(status.peers as Record<string, PeerRow>).reduce((n, peer) => n + (peer.needsReview ?? 0), 0);
           row(!status.deliveryError && pending === 0, "delivery recovery", status.deliveryError ?? (pending ? `${pending} deliveries need review; run ahub queue list` : "journal healthy; no deliveries need review"));
+          // #285 AC10: where Kimi's number comes from, and whether the hub can trust it right now. An older hub answers without `kimiSource`: no row, not a failure.
+          const quota = await hub.request({ t: "budget" });
+          const kimiRow = quota.ok ? kimiSourceRow(quota.kimiSource) : undefined;
+          if (kimiRow) row(kimiRow.ok, "kimi usage source", kimiRow.detail);
           const observed = await hub.request({ t: "recovery", op: "inspect", expectedInstanceId: status.instanceId });
           for (const peer of Object.values(observed.recovery?.peers ?? {}) as { id: string; state: string; sessionId?: string; threadId?: string }[]) {
             const check = nativeDoctorRecoveryIdentity(peer);
@@ -2182,9 +2215,9 @@ const commands: Record<string, () => Promise<void> | void> = {
         row(mlx.state === "ready" || mlx.state === "stopped", "pi mlx", `${mlx.state}${mlx.model ? ` (${mlx.model})` : ""}${mlx.lastError ? `: ${mlx.lastError}` : ""}`);
       }
 
-      const memory = new MemoryClient();
-      const mem = await memory.health();
-      row(mem.ok, "memory worker", mem.ok ? `claude-mem ${mem.version ?? ""} at ${memory.url}` : `unavailable at ${memory.url} (the hub works without it)`);
+      let memoryLibraryReady = false;
+      try { assertAgentMemVersion({ name: "@staix/agent-mem", version: AGENT_MEM_VERSION }); memoryLibraryReady = true; } catch { /* report the failed exact pin without opening a store */ }
+      row(memoryLibraryReady, "memory library", memoryLibraryReady ? `amem ${AGENT_MEM_VERSION}; in-process, no claude-mem worker` : "installed amem does not match the exact dependency pin");
       const bridge = spawnSync("dot", ["ai", "memory", "status"], { encoding: "utf8" });
       const out = bridge.error ? "" : bridge.stdout.replace(/\x1b\[[0-9;]*m/g, "");
       for (const tool of DOCTOR_MEMORY_CAPTURE_PEERS) {
@@ -2260,7 +2293,8 @@ async function runConductorCommand(): Promise<void> {
     op = args[0] === "assign" ? "hub_task_assign" : "hub_task_escalate";
     const { one, rest: positional } = takeFlags(args.slice(1), args[0] === "assign" ? ["--role"] : [], []);
     const role = one["--role"] ?? "owner";
-    if (!positional[0] || positional.length !== (args[0] === "assign" ? 2 : 1) || !["owner", "reviewer"].includes(role)) fail("usage: ahub task assign <id> <peer> [--role owner|reviewer] | escalate <id>");
+    if (!positional[0] || positional.length !== (args[0] === "assign" ? 2 : 1) || !["owner", "reviewer", "planner"].includes(role)) fail("usage: ahub task assign <id> <peer> [--role owner|reviewer|planner] | escalate <id>");
+    if (role === "planner") fail("only the person may name a task planner");
     input = { id: Number(positional[0]), ...(args[0] === "assign" ? { peer: positional[1], ...(role === "reviewer" ? { role } : {}) } : {}) };
   } else if (cmd === "pause" || cmd === "resume") {
     if (args.length !== 1) fail(`usage: ahub ${cmd} <peer>`);