@staix/agent-hub 0.34.1 → 0.35.0

package/src/hub/research.ts

@@ -5,13 +5,21 @@ import type { RoleIdentity, StampedEvent } from "./events.ts";
 import { hubHome } from "./project.ts";
 import { ADDONS, addonState, type Addon, type AddonName } from "./tooling.ts";
 import { MIN_ATTEMPTS, mulberry32 } from "./bench.ts";
+import { UNKNOWN_MEMORY_FIGURES } from "./research-memory.ts";
+import { addPersonEvent, emptyPersonCounts, isPersonEvent, personCoverage, personFigures, personTask, startsAttribution, type PersonCounts } from "./person-figures.ts";
+import { closedId, journalFigures, mergeBlock, NO_EVIDENCE, reviewBlock, specsBlock, type CancelCause, type CohortKind, type DeliveryBlock, type HandoffsBlock, type MemoryBlock, type MergeBlock, type PersonBlock, type ResearchEvidence, type ReviewBlock, type SpecsBlock, cancelCauseOf } from "./research-record.ts";
+export type { CancelCause, CohortKind, DeliveryBlock, HandoffsBlock, MemoryBlock, MergeBlock, PersonBlock, ResearchEvidence, ReviewBlock, SpecsBlock } from "./research-record.ts";
 
 /**
  * #247: opt-in research records of how tasks went, built only from `events.jsonl` (ids, states, counts, tokens), so the
  * live writer and `ahub research backfill` produce the same records. Never a title, detail, plan, note, path, message
  * body or check output: the events carry none of those.
  */
-export const RESEARCH_SCHEMA = "agent-hub.research/v1";
+/** v1 rows (approved tasks only, no review, delivery, merge, specs, memory or person block) stay readable; every row written now is v2 (#1277). */
+export const RESEARCH_SCHEMA_V1 = "agent-hub.research/v1";
+export const RESEARCH_SCHEMA = "agent-hub.research/v2";
+export type ResearchSchema = typeof RESEARCH_SCHEMA | typeof RESEARCH_SCHEMA_V1;
+const SCHEMAS: readonly string[] = [RESEARCH_SCHEMA_V1, RESEARCH_SCHEMA];
 export const LABELS = ["ok", "regressed", "reverted", "incomplete", "wrong", "abandoned"] as const;
 export type Label = (typeof LABELS)[number];
 /** A person's later verdict that turns an approved task into a failure. */
@@ -19,16 +27,22 @@ const FAILED: ReadonlySet<string> = new Set(["regressed", "reverted", "incomplet
 
 export interface PeerUsage { input: number | null; output: number | null; cacheRead: number | null; total: number | null }
 export interface TaskRecord {
-  schema: typeof RESEARCH_SCHEMA; kind: "task"; project: string; task: number;
+  schema: ResearchSchema; kind: "task"; project: string; task: number;
   profile?: string; profileClass?: string;
   release?: number | null; priority?: number | null; plannedStart?: number | null; due?: number | null;
   role?: string; roleIdentity?: { id: string; layer: "shipped" | "project"; hash: string };
   /** Native preamble preparations frozen at each attributed turn's start, never proof of model consumption. */
   sessionRoles?: { peer: string; turn: string; roles: RoleIdentity[] | null }[];
-  class: string | null; pii: boolean; outcome: "approved";
+  class: string | null; pii: boolean;
+  /** #1277 AC6: every task in a terminal board state has a record. A v1 row is always `approved`. Statistics about approved tasks filter on this. */
+  outcome: "approved" | "cancelled";
   /** The proposal time also tells a task from an earlier one with the same id after `ahub reset --all`. */
-  createdAt: string | null; startedAt: string | null; approvedAt: string;
-  /** From the first `in_progress` to the approval; null when the start is not in the events. */
+  createdAt: string | null; startedAt: string | null;
+  /** Null on a cancelled record. */
+  approvedAt: string | null;
+  /** When the task reached its terminal state (v2); a v1 row reads as its `approvedAt`. */
+  closedAt?: string;
+  /** From the first `in_progress` to the terminal state; null when the start is not in the events. */
   wallMs: number | null;
   /** Sum of the attributed turns' durations, the turns still open at the approval included. */
   activeMs: number;
@@ -57,9 +71,30 @@ export interface TaskRecord {
   peers?: string[];
   /** #258 AC11: task briefs handed over for it, and how many of them carried a hub-memory fail note; absent without briefs. */
   briefs?: { delivered: number; withFail: number };
+  /** #1277 (v2). Every block is a count, a duration or a closed value; a value that cannot be derived is null and counted as unknown by the quality report, never 0. */
+  /** Only on a cancelled record: an explicit closed cause the board retains, else `unknown`. Never inferred from a decline, an escalation or the cancellation note. */
+  cancelCause?: CancelCause;
+  /** Intermediate declines and escalations (history events, not terminal), counted on every record next to `reassignments`. */
+  declines?: number; escalations?: number;
+  review?: ReviewBlock; delivery?: DeliveryBlock; merge?: MergeBlock; specs?: SpecsBlock; memory?: MemoryBlock; person?: PersonBlock;
+  /** Persisted idle-ladder entries on the task's board history (the stall table itself is cleared when a task closes); null without the board. */
+  stalls?: number | null;
+  handoffs?: HandoffsBlock; cohort?: CohortKind;
 }
+/** A record carries merge figures when any of them is known. */
+const mergeKnown = (r: TaskRecord): boolean => !!r.merge && (r.merge.ciRuns !== null || r.merge.ciReruns !== null || r.merge.githubReviews !== null || r.merge.approvedToMergedMs !== null);
+/** True when `next` has merge figures the held record of the same task lacks. */
+export const fillsMerge = (held: TaskRecord, next: TaskRecord): boolean => next.schema === RESEARCH_SCHEMA && !mergeKnown(held) && mergeKnown(next);
+
+/** The latest record of each task (a later row of the same task replaces an earlier one), in order of first appearance. */
+export function latestTaskRecords(records: readonly ResearchRecord[]): TaskRecord[] {
+  const latest = new Map<string, TaskRecord>();
+  for (const r of records) if (r.kind === "task") latest.set(recordKey(r), r);
+  return [...latest.values()];
+}
+
 /** A person's later verdict on one task record: `createdAt` binds it to that task, not a later one with the same id. `by`: the agent that labelled its own task (#933); absent for the person. */
-export interface LabelRecord { schema: typeof RESEARCH_SCHEMA; kind: "label"; project: string; task: number; createdAt: string; label: Label; at: string; by?: string }
+export interface LabelRecord { schema: ResearchSchema; kind: "label"; project: string; task: number; createdAt: string; label: Label; at: string; by?: string }
 export type ResearchRecord = TaskRecord | LabelRecord;
 
 /** The store name for a project: a hash of its id, never its path. */
@@ -67,29 +102,43 @@ export const projectKey = (projectId: string): string => createHash("sha256").up
 export const researchDir = (home = hubHome()): string => join(home, "research");
 export const researchFile = (projectId: string, home = hubHome()): string => join(researchDir(home), `${projectKey(projectId)}.jsonl`);
 /** One task across every record about it: a task id is reused after `ahub reset --all`, its proposal time is not. */
-export const recordKey = (r: { project: string; task: number; createdAt: string | null; approvedAt?: string }): string => `${r.project}#${r.task}@${r.createdAt ?? r.approvedAt ?? ""}`;
+export const recordKey = (r: { project: string; task: number; createdAt: string | null; approvedAt?: string | null; closedAt?: string }): string => `${r.project}#${r.task}@${r.createdAt ?? r.approvedAt ?? r.closedAt ?? ""}`;
+/** When a record's task closed: v2 says so, a v1 row is approved-only and closed at its approval. */
+export const closedAtOf = (r: TaskRecord): string | null => r.closedAt ?? r.approvedAt;
 
-type Acc = Omit<TaskRecord, "schema" | "kind" | "project" | "approvedAt" | "wallMs" | "firstPass" | "outcome" | "writer" | "models" | "tooling" | "peers" | "briefs"> & {
+type V2Fields = "closedAt" | "cancelCause" | "declines" | "escalations" | "review" | "delivery" | "merge" | "specs" | "memory" | "person" | "stalls" | "handoffs" | "cohort";
+type Acc = Omit<TaskRecord, "schema" | "kind" | "project" | "approvedAt" | "wallMs" | "firstPass" | "outcome" | "writer" | "models" | "tooling" | "peers" | "briefs" | "person" | V2Fields> & {
   models: Set<string>; approvedAt: string | null; lastState: string | null; tooling: Record<string, Addon[]>; peers: Map<string, number>; briefs: { delivered: number; withFail: number };
+  /** #1278: the counts of the four attributed person events; joined with whether the log covers the task at the end. */
+  person: PersonCounts;
+  /** #1277: what the events alone say; the board and journal evidence is joined at the end. */
+  cancelledAt: string | null; declines: number; escalations: number; lastDoneMs: number | null; envelopes: number; dropped: { fyi: number; hop: number };
+  briefNotes: number; briefFails: number; cohort: "silent" | "advisory" | null;
 };
 /** Keyed by peer ids, model names and reasons, any of which may be `constructor` or `__proto__`: no prototype to inherit from. */
 const keyed = <T>(): Record<string, T> => Object.create(null) as Record<string, T>;
 const blank = (task: number): Acc => ({ task, class: null, pii: false, createdAt: null, startedAt: null, activeMs: 0, owners: [], reviewer: null,
   reviewRounds: 0, changesRequested: 0, checkPassed: 0, checkFailed: 0, dones: 0, reassignments: 0, reassignedBy: keyed(), stuck: 0, overlaps: 0, conflicts: 0,
   tests: { pass: 0, fail: 0 }, tokens: { total: 0, byPeer: keyed(), byAttribution: keyed() }, usage: keyed(), usageByModel: keyed(), turns: 0, filesChanged: 0, models: new Set(),
-  approvedAt: null, lastState: null, tooling: keyed(), peers: new Map(), briefs: { delivered: 0, withFail: 0 } });
+  approvedAt: null, lastState: null, tooling: keyed(), peers: new Map(), briefs: { delivered: 0, withFail: 0 }, person: emptyPersonCounts(),
+  cancelledAt: null, declines: 0, escalations: 0, lastDoneMs: null, envelopes: 0, dropped: { fyi: 0, hop: 0 }, briefNotes: 0, briefFails: 0, cohort: null });
 const add = (current: number | null, value: unknown): number | null => typeof value === "number" && Number.isFinite(value) ? (current ?? 0) + value : current;
 const bump = (counts: Record<string, number>, key: string, n = 1) => { counts[key] = (counts[key] ?? 0) + n; };
 
 /**
- * One record per approved task in `events`. Approval is final on the board, so everything attributed to the task
+ * One record per task that reached a terminal board state in `events`: approved, or cancelled (#1277 AC6). Approval is final on the board, so everything attributed to the task
  * counts, also after the approval: the turn that approved it ends later, and its usage arrives after that. The live
- * writer therefore waits for those turns (daemon `recordResearch`); backfill reads to the end of the file.
+ * writer therefore waits for those turns (daemon `recordResearch`); backfill reads to the end of the file. `evidence` (the board's history and the delivery journal,
+ * read-only and closed fields only, `readEvidence`) fills the review, merge, spec and delivery-state blocks; without it those fields are null, not 0. A task that was approved
+ * and later reopened keeps its approved record, as before.
  */
-export function taskRecords(events: StampedEvent[], projectId: string, writer: TaskRecord["writer"]): TaskRecord[] {
+export function taskRecords(events: StampedEvent[], projectId: string, writer: TaskRecord["writer"], evidence: ResearchEvidence = NO_EVIDENCE): TaskRecord[] {
   const tasks = new Map<number, Acc>(), earlier: Acc[] = [];
   const acc = (id: number) => { let a = tasks.get(id); if (!a) tasks.set(id, a = blank(id)); return a; };
   const seenUsage = new Set<string>();
+  let briefReporting = false;
+  // #1278: the time of the first hub run that attributes person events. A task that began before it has an unknown person block (see `startsAttribution`).
+  let personReportingSince: number | null = null;
   // A fingerprint belongs to one attachment of its peer: from a state event that brings it online to the next offline.
   // Detection settles in the background, so it can arrive after the peer's first work in that attachment.
   const attach = new Map<string, number>(), online = new Set<string>();
@@ -109,7 +158,7 @@ export function taskRecords(events: StampedEvent[], projectId: string, writer: T
   };
   for (const e of events) {
     // A crash writes no offline: a new run is a new attachment, and no fingerprint from before it describes later work.
-    if (e.type === "hub_start") { online.clear(); tooling.clear(); continue; }
+    if (e.type === "hub_start") { online.clear(); tooling.clear(); if (startsAttribution(e)) personReportingSince ??= Date.parse(e.at); continue; }
     if (e.type === "state") {
       if (e.state === "offline") online.delete(e.peer);
       else if (!online.has(e.peer)) { online.add(e.peer); attach.set(e.peer, (attach.get(e.peer) ?? 0) + 1); }
@@ -121,6 +170,15 @@ export function taskRecords(events: StampedEvent[], projectId: string, writer: T
       for (const a of tasks.values()) if (a.peers.get(e.peer) === now) a.tooling[e.peer] = e.addons;
       continue;
     }
+    if (e.type === "envelope") {
+      // An envelope names its task as a string; a count of them, and of the ones the bus dropped, is all the record keeps.
+      if (typeof e.task === "string" && /^[1-9]\d{0,9}$/.test(e.task)) { const a = acc(Number(e.task)); a.envelopes++; if (e.dropped === "fyi" || e.dropped === "hop") a.dropped[e.dropped]++; }
+      continue;
+    }
+    if (e.type === "cohort") {
+      for (const id of e.tasks) if (Number.isSafeInteger(id) && id > 0) { const a = acc(id); if (e.silent) a.cohort = "silent"; else a.cohort ??= "advisory"; }
+      continue;
+    }
     if (e.type === "task") {
       const proposed = e.event === "proposed" || e.event === "backlog pulled";
       // Ids restart after `ahub reset --all` archives the events, but a file that kept both starts the task anew.
@@ -136,16 +194,25 @@ export function taskRecords(events: StampedEvent[], projectId: string, writer: T
       if (e.reviewer) a.reviewer = e.reviewer;
       if (proposed) a.createdAt ??= e.at;
       if (e.state === "in_progress") a.startedAt ??= e.at;
-      if (e.event === "done") a.dones++;
+      if (e.event === "done") { a.dones++; if (a.approvedAt === null) a.lastDoneMs = Date.parse(e.at); }
+      if (e.event === "declined") a.declines++;
+      if (e.event === "escalated") a.escalations++;
       if (e.event === "check passed") a.checkPassed++;
       if (e.event === "check failed") a.checkFailed++;
       if (e.state === "in_review" && a.lastState !== "in_review") a.reviewRounds++;
       if (e.state === "changes_requested" && a.lastState !== "changes_requested") a.changesRequested++;
       if (e.state === "approved") a.approvedAt ??= e.at;
+      if (e.state === "cancelled" && a.lastState !== "cancelled") a.cancelledAt = e.at;
       a.lastState = e.state;
       involve(a, e.by); involve(a, e.owner, false); involve(a, e.reviewer, false);
       continue;
     }
+    if (isPersonEvent(e)) {
+      // Before the generic path on purpose: a permission or a question does not make its peer a worker on the task (`peers`, `tooling`).
+      const owner = personTask(e);
+      if (owner !== undefined) { const a = acc(owner); if (e.pii) a.pii = true; addPersonEvent(a.person, e); }
+      continue;
+    }
     const task = "task" in e && typeof e.task === "number" ? e.task : undefined;
     if (task === undefined) continue;
     const a = acc(task);
@@ -168,22 +235,45 @@ export function taskRecords(events: StampedEvent[], projectId: string, writer: T
     }
     else if (e.type === "route") a.models.add(e.route);
     else if (e.type === "route_outcome") { if (e.next?.tests === "pass") a.tests.pass++; if (e.next?.tests === "fail") a.tests.fail++; }
-    else if (e.type === "memory_brief") { a.briefs.delivered++; if (e.fails > 0) a.briefs.withFail++; }
+    else if (e.type === "memory_brief") { briefReporting = true; a.briefs.delivered++; if (e.fails > 0) a.briefs.withFail++; a.briefNotes += (Number.isSafeInteger(e.native) ? e.native : 0) + (Number.isSafeInteger(e.claudeMem) ? e.claudeMem : 0); a.briefFails += Number.isSafeInteger(e.fails) ? e.fails : 0; }
     else if (e.type === "stuck") a.stuck++;
     else if (e.type === "overlap") a.overlaps++;
     else if (e.type === "conflict") a.conflicts++;
   }
   const out: TaskRecord[] = [];
   for (const a of [...earlier, ...tasks.values()]) {
-    if (!a.approvedAt) continue;
-    const { approvedAt, lastState: _state, models, tooling: fingerprints, peers, briefs, ...rest } = a;
-    const start = a.startedAt ? Date.parse(a.startedAt) : NaN, end = Date.parse(approvedAt);
-    out.push({ schema: RESEARCH_SCHEMA, kind: "task", project: projectKey(projectId), ...rest, outcome: "approved", approvedAt,
+    // Approved wins over a later reopening (the record the live writer stored at the approval); otherwise the task must end cancelled.
+    const outcome: "approved" | "cancelled" | undefined = a.approvedAt ? "approved" : a.lastState === "cancelled" && a.cancelledAt ? "cancelled" : undefined;
+    if (!outcome) continue;
+    const { person, approvedAt, lastState: _state, models, tooling: fingerprints, peers, briefs, cancelledAt, declines, escalations, lastDoneMs, envelopes, dropped, briefNotes, briefFails, cohort, ...rest } = a;
+    const closedAt = (outcome === "approved" ? approvedAt : cancelledAt)!;
+    const start = a.startedAt ? Date.parse(a.startedAt) : NaN, end = Date.parse(closedAt);
+    const task = evidence.tasks.get(a.task), board = evidence.board;
+    const began = a.createdAt ? Date.parse(a.createdAt) : a.startedAt ? Date.parse(a.startedAt) : NaN;
+    const covered = personCoverage(personReportingSince, began);
+    const ownerFamily = closedId(a.owners.at(-1) ? evidence.familyOf?.(a.owners.at(-1)!) : undefined);
+    const approvedMs = outcome === "approved" ? Date.parse(approvedAt!) : null;
+    const created = a.createdAt ? Date.parse(a.createdAt) : NaN;
+    const journal = journalFigures(evidence, a.task, Number.isFinite(created) ? created : null, Number.isFinite(end) ? end : 0);
+    const review = reviewBlock(task, board, ownerFamily, a.pii);
+    // The events say whether the task went to review at all; a board that cannot say leaves the round count unknown.
+    out.push({ schema: RESEARCH_SCHEMA, kind: "task", project: projectKey(projectId), ...rest, outcome, approvedAt: approvedAt ?? null, closedAt,
       wallMs: Number.isFinite(start) && Number.isFinite(end) && end >= start ? end - start : null,
-      firstPass: a.changesRequested === 0 && a.checkFailed === 0 && a.reviewRounds <= 1, models: [...models].sort(), writer,
-      ...(Object.keys(fingerprints).length ? { tooling: fingerprints, peers: [...peers.keys()].sort() } : {}), ...(briefs.delivered ? { briefs } : {}) });
+      firstPass: outcome === "approved" && a.changesRequested === 0 && a.checkFailed === 0 && a.reviewRounds <= 1, models: [...models].sort(), writer,
+      ...(Object.keys(fingerprints).length ? { tooling: fingerprints, peers: [...peers.keys()].sort() } : {}), ...(briefs.delivered ? { briefs } : {}),
+      ...(outcome === "cancelled" ? { cancelCause: task?.history.findLast(entry => entry.event === "cancelled")?.cause ?? "unknown" } : {}),
+      declines, escalations, review,
+      delivery: { count: envelopes, ...journal, dropped: { fyi: dropped.fyi, hop: dropped.hop } },
+      merge: mergeBlock(task, lastDoneMs, approvedMs),
+      specs: specsBlock(task, a.pii),
+      // A task with no brief is a known 0 only when the log shows briefs were being reported at all (memory on); otherwise nothing says whether one was built.
+      memory: { briefs: briefs.delivered || (briefReporting ? 0 : null), briefNotes: briefs.delivered ? briefNotes : briefReporting ? 0 : null, fails: briefs.delivered ? briefFails : briefReporting ? 0 : null, ...(evidence.memory?.(a.task) ?? UNKNOWN_MEMORY_FIGURES) },
+      person: personFigures(person, covered),
+      stalls: task && board ? task.history.filter(entry => entry.sweep).length : null,
+      handoffs: task?.handoffs ? { in: task.handoffs.in, out: task.handoffs.out } : { in: null, out: null },
+      cohort: cohort ?? "none" });
   }
-  return out.sort((x, y) => x.approvedAt.localeCompare(y.approvedAt) || x.task - y.task);
+  return out.sort((x, y) => closedAtOf(x)!.localeCompare(closedAtOf(y)!) || x.task - y.task);
 }
 
 /** Every record in one store file; a line that does not parse is skipped. */
@@ -191,9 +281,13 @@ export function readStore(file: string): ResearchRecord[] {
   if (!existsSync(file)) return [];
   return readFileSync(file, "utf8").split("\n").flatMap((line) => {
     if (!line.trim()) return [];
-    try { const r = JSON.parse(line); return r?.schema === RESEARCH_SCHEMA ? [r as ResearchRecord] : []; } catch { return []; }
+    try { const r = JSON.parse(line); return SCHEMAS.includes(r?.schema) ? [normalize(r)] : []; } catch { return []; }
   });
 }
+/** A v1 task row predates `outcome` and was written only at an approval, so it reads as approved; the file itself is never rewritten. */
+function normalize(r: ResearchRecord): ResearchRecord {
+  return r.kind === "task" && r.schema === RESEARCH_SCHEMA_V1 && r.outcome === undefined ? { ...r, outcome: "approved" } : r;
+}
 /** This project's store, or every project's with `all`. */
 export function readStores(projectId: string | undefined, home = hubHome()): ResearchRecord[] {
   if (projectId) return readStore(researchFile(projectId, home));
@@ -208,8 +302,10 @@ export function appendRecords(projectId: string, records: ResearchRecord[], home
   const file = researchFile(projectId, home);
   mkdirSync(researchDir(home), { recursive: true, mode: 0o700 });
   chmodSync(researchDir(home), 0o700); // mkdir's mode applies only when it creates the directory
-  const held = new Set(readStore(file).flatMap((r) => r.kind === "task" ? [recordKey(r)] : []));
-  const added = records.filter((r) => r.kind === "label" || !held.has(recordKey(r)));
+  // A v2 row replaces a held v1 row of the same task (readers keep the latest per task). A held v2 row is final, as a held row always was, with one exception: the live writer
+  // records a task at its approval and the guarded merge writes its receipt later, so a later pass may append the same task with the merge figures it could not know then.
+  const held = new Map(readStore(file).flatMap((r) => r.kind === "task" && r.schema === RESEARCH_SCHEMA ? [[recordKey(r), r] as const] : []));
+  const added = records.filter((r) => r.kind === "label" || r.schema !== RESEARCH_SCHEMA || !held.has(recordKey(r)) || fillsMerge(held.get(recordKey(r))!, r));
   if (!added.length) return 0;
   appendFileSync(file, added.map((r) => JSON.stringify(r)).join("\n") + "\n", { mode: 0o600 });
   chmodSync(file, 0o600);
@@ -224,7 +320,9 @@ export function appendRecords(projectId: string, records: ResearchRecord[], home
  */
 export function labelTarget(records: ResearchRecord[], events: StampedEvent[], task: number, created?: string): TaskRecord {
   // A record without a proposal time (its proposal was not in the events) cannot be told apart, so it takes no label.
-  const mine = records.filter((r): r is TaskRecord => r.kind === "task" && r.task === task && r.createdAt !== null);
+  // A label is a verdict on an approved task: a cancelled record takes none.
+  // One candidate per task: a later revision of a record (the merge figures filled in, or a v2 row over a v1 one) is the same task, and listing it twice would refuse an unambiguous historical label.
+  const mine = latestTaskRecords(records).filter((r) => r.outcome === "approved" && r.task === task && r.createdAt !== null);
   if (created !== undefined) {
     return mine.find((r) => r.createdAt === created) ?? fail(`no research record for task #${task} proposed at ${created}${mine.length ? ` (it has: ${mine.map((r) => r.createdAt).join(", ")})` : ""}`);
   }
@@ -311,7 +409,8 @@ const labelValues = (labels: Map<string, LabelRecord>): Map<string, Label> => ne
 /** Each approved task once, its last record, and every task's effective label: what both reports count. */
 function latestRecords(records: ResearchRecord[], since: number): { all: TaskRecord[]; labels: Map<string, Label> } {
   const latest = new Map<string, TaskRecord>();
-  for (const r of records) if (r.kind === "task" && Date.parse(r.approvedAt) >= since) latest.set(recordKey(r), r);
+  // Statistics about approved tasks: a cancelled record (#1277) is another outcome and never counts here.
+  for (const r of records) if (r.kind === "task" && r.outcome === "approved" && Date.parse(r.approvedAt!) >= since) latest.set(recordKey(r), r);
   return { all: [...latest.values()], labels: labelValues(effectiveLabels(records)) };
 }
 

package/src/hub/restart.ts

@@ -46,6 +46,7 @@ export interface RestartSnapshot {
     manualPaused: PeerId[];
     boardDigest: string;
     budgetDigest: string;
+    modelOverrides?: { count: number; digest: string };
     /** Whole captured binding set; portable identities are covered alongside queue/board integrity. */
     externalBindingsDigest?: string;
     /** Research state remains part of controlled-recovery integrity when present. */
@@ -56,6 +57,8 @@ export interface RestartSnapshot {
     researchRunners?: { count: number; digest: string };
     researchEvidence?: { links: number; revisions: number; digest: string };
     reviewComments?: { comments: number; packages: number; digest: string };
+    /** Stored visual payloads and image metadata, never external image bytes. */
+    visuals?: { count: number; digest: string };
   };
 }
 
@@ -106,6 +109,11 @@ export function readRestartSnapshot(stateDir: string, expected: RestartReadExpec
   if (s.peers.some(peer => Object.hasOwn(peer, "controlProtocol") && (typeof peer.controlProtocol !== "number" || !Number.isSafeInteger(peer.controlProtocol) || peer.controlProtocol < 1))) return undefined;
   if (s.integrity !== undefined && (!s.integrity || typeof s.integrity !== "object" || typeof s.integrity.boardDigest !== "string" || typeof s.integrity.budgetDigest !== "string" || !Array.isArray(s.integrity.manualPaused) || !s.integrity.manualPaused.every((id) => typeof id === "string") || !s.integrity.queues || typeof s.integrity.queues !== "object" || !Object.values(s.integrity.queues).every((ids) => Array.isArray(ids) && ids.every((id) => typeof id === "string")))) return undefined;
   if (s.integrity && Object.hasOwn(s.integrity, "externalBindingsDigest") && (typeof s.integrity.externalBindingsDigest !== "string" || !/^[a-f0-9]{64}$/.test(s.integrity.externalBindingsDigest))) return undefined;
+  if (s.integrity && Object.hasOwn(s.integrity, "modelOverrides")) {
+    const value = s.integrity.modelOverrides;
+    if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).sort().join(",") !== "count,digest"
+      || !Number.isSafeInteger(value.count) || value.count < 0 || typeof value.digest !== "string" || !/^[a-f0-9]{64}$/.test(value.digest)) return undefined;
+  }
   if (s.integrity && Object.hasOwn(s.integrity, "research")) {
     const research = s.integrity.research;
     if (!research || typeof research !== "object" || Array.isArray(research)
@@ -144,6 +152,12 @@ export function readRestartSnapshot(stateDir: string, expected: RestartReadExpec
       || ![value.comments, value.packages].every(count => Number.isSafeInteger(count) && count >= 0)
       || typeof value.digest !== "string" || !/^[a-f0-9]{64}$/.test(value.digest)) return undefined;
   }
+  if (s.integrity && Object.hasOwn(s.integrity, "visuals")) {
+    const value = s.integrity.visuals;
+    if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some(key => !["count", "digest"].includes(key))
+      || !Number.isSafeInteger(value.count) || value.count < 0
+      || typeof value.digest !== "string" || !/^[a-f0-9]{64}$/.test(value.digest)) return undefined;
+  }
   if (bus.journal !== undefined) { try { validateJournalSnapshot(bus.journal); } catch { return undefined; } }
   return s as RestartSnapshot;
 }

package/src/hub/settings.ts

@@ -80,7 +80,10 @@ export const SETTINGS: readonly SettingDef[] = [
   ...ADAPTERS.flatMap(adapter => adapter.configuration?.settings ?? []),
   { key: "routing.stay_switch", group: "Routing", label: "Stay or switch (hub/auto and stage routes)", type: "enum", values: ["off", "shadow", "enforce"], store: "routing", applies: "live", risk: "raises", path: ["stay_switch"] },
   ...CLASSES.flatMap(perClass),
+  { key: "visuals.retention_days", group: "Switches", label: "Unbound visual retention (days)", type: "integer", min: 1, max: 3650, store: "config", applies: "live", risk: "raises", floor: 1, path: ["visuals", "retention_days"] },
   { key: "research.enabled", group: "Switches", label: "Research records", type: "boolean", store: "config", applies: "live", risk: "safe", path: ["research", "enabled"] },
+  // #1292: the quota share at which a peer checkpoints and pauses (resume is below gate - 0.1); default 0.99 in DEFAULT_BUDGET. Raising it is guarded.
+  { key: "budget.gate", group: "Routing", label: "Budget gate: pause a peer when a fresh quota window reaches this share (0..1)", type: "number", min: 0, max: 1, store: "config", applies: "next use", risk: "raises", path: ["budget", "gate"] },
   { key: "specs.enabled", group: "Switches", label: "Design specs and freshness", type: "boolean", store: "config", applies: "live", risk: "safe", path: ["specs", "enabled"] },
   { key: "specs.review", group: "Switches", label: "Covering spec review", type: "enum", values: ["off", "report", "require"], store: "config", applies: "live", risk: "safe", path: ["specs", "review"] },
   { key: "approvals.notify", group: "Switches", label: "Desktop notice for a waiting approval", type: "boolean", store: "config", applies: "live", risk: "safe", path: ["approvals", "notify"] },

package/src/hub/startup-event-seeds.ts

@@ -0,0 +1,51 @@
+import { closeSync, existsSync, openSync, readSync } from "node:fs";
+import { StringDecoder } from "node:string_decoder";
+import { parseEventLine, type StampedEvent } from "./events.ts";
+
+const STARTUP_EVENT_BUFFER_BYTES = 64 * 1024;
+export interface StartupEventSeeds {
+  events: StampedEvent[];
+  nativeStopsSeen: Set<string>;
+  claudeNativeUsageSeen: Set<string>;
+  readPasses: number;
+  readBytes: number;
+}
+
+/** One streaming pass, retaining every accepted row and every historical dedupe key. */
+export function readStartupEventSeeds(file: string, options: { bufferBytes?: number } = {}): StartupEventSeeds {
+  const seeds: StartupEventSeeds = { events: [], nativeStopsSeen: new Set(), claudeNativeUsageSeen: new Set(), readPasses: 0, readBytes: 0 };
+  if (!existsSync(file)) return seeds;
+  // Host-only chunk-boundary test seam, never a line, history or total-byte ceiling.
+  const bufferBytes = options.bufferBytes ?? STARTUP_EVENT_BUFFER_BYTES;
+  if (!Number.isSafeInteger(bufferBytes) || bufferBytes < 1) throw new Error("startup event buffer must be a positive integer; use the default reader buffer");
+  const decoder = new StringDecoder("utf8"), buffer = Buffer.alloc(bufferBytes), fd = openSync(file, "r");
+  let parts: string[] = [];
+  const accept = (line: string) => {
+    const event = parseEventLine(line);
+    if (event === undefined) return;
+    seeds.events.push(event);
+    // Keep the same predicates as the former three readEvents consumers, including legacy malformed IDs.
+    if (event.type === "native_turn_end" && event.id) seeds.nativeStopsSeen.add(event.id);
+    if (event.type === "usage" && event.source === "claude_transcript") seeds.claudeNativeUsageSeen.add((event as { id: string }).id);
+  };
+  const consume = (text: string) => {
+    let start = 0;
+    for (let end = text.indexOf("\n", start); end >= 0; end = text.indexOf("\n", start)) {
+      parts.push(text.slice(start, end)); accept(parts.join("")); parts = []; start = end + 1;
+    }
+    if (start < text.length) parts.push(text.slice(start));
+  };
+  try {
+    seeds.readPasses++;
+    for (;;) {
+      const bytes = readSync(fd, buffer, 0, buffer.length, null);
+      if (!bytes) break;
+      seeds.readBytes += bytes;
+      consume(decoder.write(buffer.subarray(0, bytes)));
+    }
+    consume(decoder.end());
+    // readEvents also accepts a complete final JSON record without a newline.
+    if (parts.length) accept(parts.join(""));
+    return seeds;
+  } finally { closeSync(fd); }
+}

package/src/hub/startup-readiness.ts

@@ -0,0 +1,65 @@
+const STARTUP_NOTICE_MS = 12_000;
+const STARTUP_OUTER_MS = 120_000;
+const STARTUP_POLL_MS = 100;
+const STARTUP_INSPECTION_MS = 3000;
+
+export type StartupOwner = { state: "live"; pid: number } | { state: "gone" } | { state: "unknown" } | undefined;
+export interface StartupReadinessPorts<T> {
+  now(): number;
+  sleep(ms: number): Promise<void>;
+  inspect(timeoutMs: number): Promise<{ state: string; status?: T; error?: string }>;
+  current(): void;
+  /** A live result requires the bound spawned child and its full process identity, never PID-only evidence. */
+  owner(): StartupOwner;
+  confirm(status: T): void;
+  starting?(pid: number): void;
+}
+
+/** Keep the existing status promise pending; only readiness confirms the retained runtime selection. */
+export async function waitForStartupReadiness<T>(ports: StartupReadinessPorts<T>): Promise<T> {
+  const started = ports.now(), deadline = started + STARTUP_OUTER_MS;
+  let reported = false, owner: StartupOwner;
+  const expired = (): never => {
+    throw new Error(owner?.state === "live"
+      ? `hub readiness remains unconfirmed after ${STARTUP_OUTER_MS / 1000} s; its daemon was last observed running as pid ${owner.pid}; run ahub status and inspect hub.log before retrying`
+      : `hub readiness remains unconfirmed after ${STARTUP_OUTER_MS / 1000} s; run ahub status and inspect hub.log before retrying`);
+  };
+  for (;;) {
+    ports.current();
+    const remaining = deadline - ports.now();
+    if (remaining <= 0) return expired();
+    // inspectProject has a connect and a status timeout. A zero timeout would disable the request timer.
+    const timeout = Math.min(STARTUP_INSPECTION_MS, Math.floor(remaining / 2));
+    if (timeout < 1) {
+      await ports.sleep(remaining);
+      ports.current();
+      if (ports.now() >= deadline) return expired();
+      continue;
+    }
+    const observed = await ports.inspect(timeout);
+    ports.current();
+    if (ports.now() >= deadline) return expired();
+    if (observed.state === "running") {
+      if (observed.status === undefined) throw new Error("hub readiness reply has no status; run ahub status before retrying");
+      ports.current();
+      if (ports.now() >= deadline) return expired();
+      ports.confirm(observed.status);
+      return observed.status;
+    }
+    if (observed.state === "incompatible" || observed.state === "missing") throw new Error(observed.error ?? observed.state);
+    if (observed.state === "stopping") throw new Error(observed.error ?? "hub shutdown is pending; wait until it stops before retrying");
+    owner = ports.owner();
+    ports.current();
+    if (ports.now() >= deadline) return expired();
+    if (owner?.state === "gone") throw new Error("hub daemon exited before readiness was confirmed; inspect hub.log and run ahub status before retrying");
+    if (!reported && ports.now() - started >= STARTUP_NOTICE_MS && owner?.state === "live") {
+      reported = true;
+      try { ports.starting?.(owner.pid); } catch { /* Advisory progress never changes startup or confirmation. */ }
+    }
+    const sleep = Math.min(STARTUP_POLL_MS, deadline - ports.now());
+    if (sleep <= 0) return expired();
+    await ports.sleep(sleep);
+    ports.current();
+    if (ports.now() >= deadline) return expired();
+  }
+}

package/src/hub/startup-timing.ts

@@ -0,0 +1,38 @@
+/** Closed labels only: startup diagnostics must never carry paths, task text or errors. */
+export const STARTUP_PHASES = [
+  "schema", "source", "configuration", "control", "recovery", "journal", "bus", "memory", "model_runtime", "board",
+  "task_runtime", "native_stop_seed", "budget", "usage_seed", "usage_rollup", "token_runtime", "token_seed",
+  "services", "transcript_usage_seed", "ready", "post_ready",
+] as const;
+export type StartupPhase = typeof STARTUP_PHASES[number];
+
+/** Exclusive boundary durations; no timers, I/O, wall clock or startup policy changes. */
+export class StartupTimings {
+  private readonly started: number;
+  private last = 0;
+  private readonly durations = new Map<StartupPhase, number>();
+  private line: string | undefined;
+
+  constructor(private readonly clock: () => number = () => performance.now()) {
+    this.started = this.sample();
+  }
+
+  private sample(): number {
+    try {
+      const value = this.clock();
+      if (Number.isFinite(value)) this.last = Math.max(this.last, Math.floor(value));
+    } catch { /* An unavailable diagnostic clock must never fail startup. */ }
+    return this.last;
+  }
+
+  mark(phase: StartupPhase): void {
+    if (this.line !== undefined || !STARTUP_PHASES.includes(phase)) return;
+    const before = this.last, now = this.sample();
+    this.durations.set(phase, (this.durations.get(phase) ?? 0) + now - before);
+  }
+
+  finish(): string {
+    // The final caller mark includes all synchronous work through daemon return.
+    return this.line ??= `startup timings ms: ${STARTUP_PHASES.map(phase => `${phase}=${this.durations.get(phase) ?? 0}`).join(" ")} total=${this.last - this.started}`;
+  }
+}

package/src/hub/tasks.ts

@@ -11,6 +11,7 @@ import { approvalBinding, approvalText } from "./task-approval.ts";
 import type { InvocationRow } from "./invocations.ts";
 import type { ContextAdmission } from "./context-window.ts";
 import { queueBackpressure, queueBackpressurePolicy, type QueueBackpressureCode, type QueueBackpressurePolicy, type QueueBackpressureStatus, type QueuePressure } from "./queue-backpressure.ts";
+import { generatedRecordAnchors, type GeneratedNoteProof } from "../memory/record-provenance.ts";
 import { canonicalMemorySymbolNode, normalizeMemorySymbolInput, MEMORY_SYMBOL_LIMIT, type MemorySymbolNodes } from "./memory-symbols.ts";
 import { createHash, randomBytes } from "node:crypto";
 import { types } from "node:util";
@@ -104,6 +105,9 @@ function requireLocalTaskPeer(peer: unknown): void {
 
 export type TaskAssignmentRole = "owner" | "reviewer" | "planner";
 
+/** What `hub_remember` carries (#802: one shape for `remember` and `rememberOutcome`). */
+export interface RememberInput { text?: string; title?: string; kind?: string; task?: unknown; horizon?: unknown; scope?: unknown; approach?: unknown; symptom?: unknown; cause?: unknown; evidence?: unknown; retry_when?: unknown }
+
 interface PreparedSpecInspection {
   report?: SpecTaskReport;
   policyKey: string;
@@ -204,7 +208,7 @@ export interface TasksDeps {
   /** Captured native profile fence at our memory operation boundaries; no board mutation. */
   memoryCheck?: () => void;
   /** #258: the hub's own store, the project name it files entries under (the git chain) and the repo `#N` issues belong to. */
-  store?: { store: MemoryStore; project: string; repo: string; deny?: string[]; onNote?: (id: string) => void };
+  store?: { store: MemoryStore; project: string; repo: string; deny?: string[]; onNote?: (id: string) => void; onGeneratedNote?: (entry: GeneratedNoteProof) => void };
   /** a line for the human: console tail and hub.log */
   notify: (line: string) => void;
   /** The completion check configured for a class, if any (local config only; issue #7). */
@@ -8019,7 +8023,13 @@ export class Tasks {
     return `candidate:${id}; a person reviews it with amem review; memory was not edited`;
   }
 
-  async remember(by: PeerId, input: { text?: string; title?: string; kind?: string; task?: unknown; horizon?: unknown; scope?: unknown; approach?: unknown; symptom?: unknown; cause?: unknown; evidence?: unknown; retry_when?: unknown }): Promise<string> {
+  async remember(by: PeerId, input: RememberInput): Promise<string> { return (await this.rememberOutcome(by, input)).message; }
+
+  /**
+   * #802: what `remember` answered and whether it stored anything, so a caller never decides that from the wording. `saved` is a note in shared memory, `candidate` one held for a person's
+   * review (stored, not yet evidence), `not_saved` a note nothing took. A refusal still throws and never reaches here.
+   */
+  async rememberOutcome(by: PeerId, input: RememberInput): Promise<{ message: string; outcome: "saved" | "candidate" | "not_saved" }> {
     const requestCheck = this.requestCheck(by);
     const text = composeRememberText(input);
     const task = input.task !== undefined ? this.d.board.get(Number(input.task)) : undefined;
@@ -8034,7 +8044,7 @@ export class Tasks {
     if (this.isPii({ signals: detectSignals({ title, detail: text, refs: {} }, this.d.routing(), this.d.cwd) })) throw new Error("this note matches a PII pattern and is not saved: shared memory excludes private data");
     if (input.horizon !== undefined && input.horizon !== "short" && input.horizon !== "long") throw new Error('horizon is "short" or "long"');
     if (input.scope !== undefined && input.scope !== "project" && input.scope !== "shared") throw new Error('scope is "project" or "shared"');
-    if (!this.d.memory && !this.d.store) return "memory is disabled; nothing saved";
+    if (!this.d.memory && !this.d.store) return { message: "memory is disabled; nothing saved", outcome: "not_saved" };
     // Long-term notes can leave the machine (#258); local storage does not relax secret exclusion.
     if (looksSecret(`${title}\n${text}`)) throw new Error("this note looks like it holds a secret (a key, token or password) and is not saved");
     if (this.aboutPrivatePath(title, text, task)) throw new Error("this note is about a path the project keeps private (pii.paths) and is not saved");
@@ -8045,15 +8055,15 @@ export class Tasks {
     if (native && "refused" in native) throw new PreEffectToolRefusal(`${native.refused}; save it with horizon "short" or correct the machine/repository privacy policy, then retry`);
     if (task && this.d.memory) this.markMemoryReference(task, by);
     const res = !native && this.d.memory ? await this.d.memory.save({ text, ...(title ? { title } : {}), project: this.d.project, metadata: { peer: by, kind, ...(task ? { task: task.id } : {}) } }) : undefined;
-    if (!res && !native) return "memory store unavailable; nothing saved";
+    if (!res && !native) return { message: "memory store unavailable; nothing saved", outcome: "not_saved" };
     if (!native && res && typeof res === "object" && "status" in res && res.status === "candidate") {
-      return "saved as a pending memory candidate; a person must review it before it becomes shared evidence";
+      return { message: "saved as a pending memory candidate; a person must review it before it becomes shared evidence", outcome: "candidate" };
     }
     const line = noteLine(by, kind, title ? `${title}: ${text}` : text);
     this.d.notify(line);
     // Display identity only: a queued recall may already contain this saved entry. Stored/captured text stays unchanged.
     this.d.share?.(by, native ? noteLine(by, kind, `mem:${native.id} ${title ? `${title}: ` : ""}${text}`) : line);
-    return `saved to shared memory${native ? ` (hub memory ${native.id.slice(0, 8)}, ${native.tier}-term)` : ""}; the other agents get it with their next message`;
+    return { message: `saved to shared memory${native ? ` (hub memory ${native.id.slice(0, 8)}, ${native.tier}-term)` : ""}; the other agents get it with their next message`, outcome: "saved" };
   }
 
   /** The task's key in the hub's store: unique across `ahub reset --all`, which restarts the ids. */
@@ -8097,7 +8107,7 @@ export class Tasks {
    * long, decisions, contracts and fails are long-term. Fail-open: a store that cannot be written costs one notice.
    * The caller has screened the text for PII; never a PII task's.
    */
-  private saveNative(by: PeerId, kind: Kind, text: string, title: string, task: Task | undefined, horizon?: Tier, scope: Scope = "project", symbols?: MemorySymbolNodes): { id: string; tier: Tier } | { refused: string } | undefined {
+  private saveNative(by: PeerId, kind: Kind, text: string, title: string, task: Task | undefined, horizon?: Tier, scope: Scope = "project", symbols?: MemorySymbolNodes): { id: string; tier: Tier; about: string[] } | { refused: string } | undefined {
     const st = this.d.store;
     if (!st || (task && this.isPii(task))) return undefined;
     let longTerm = horizon === "long" || (horizon !== "short" && !!task && task.state === "approved" && PROMOTED_KINDS.includes(kind));
@@ -8125,8 +8135,8 @@ export class Tasks {
       }
       if (task) this.markMemoryReference(task, by);
       const id = st.store.note(row, horizon === "short");
-      st.onNote?.(id);
-      return { id, tier };
+      try { st.onNote?.(id); } catch { /* The native note is committed; an observer cannot make it fail. */ }
+      return { id, tier, about: [...about] };
     } catch (e) {
       if (longTerm) return { refused: "machine privacy policy unavailable" };
       this.releaseNotice(`a ${kind} note was not saved to hub memory (${(e as Error).message})`);
@@ -8202,6 +8212,16 @@ export class Tasks {
     if (this.aboutPrivatePath(title, text, task)) return this.releaseNotice(`task #${task.id}: a ${kind} note was not saved to shared memory (it is about a private path)`);
     const native = this.saveNative(by, kind, text, title, task, undefined, "project", symbols);
     if (native && "refused" in native) return this.releaseNotice(`task #${task.id}: a ${kind} note was not saved to shared memory (${native.refused})`);
+    if (native && "id" in native && this.d.store?.onGeneratedNote) {
+      try {
+        // Existing repository metadata is warmed by normal task admission/completion, never a new provenance probe.
+        // At the extraction ceiling completeness is unknown. Keep the old bytes rather than a partial proof.
+        if (this.d.privateTurn?.(by) === false && this.memoryCodeEligible(task) && native.about.length < 64 && !symbols?.truncated && !symbols?.unknown) {
+          const anchors = generatedRecordAnchors(native.about);
+          if (anchors && anchors.every(anchor => this.nameable(anchor))) this.d.store.onGeneratedNote({ id: native.id, anchors });
+        }
+      } catch { /* Callback/privacy uncertainty cannot affect a saved note or the preceding board write. */ }
+    }
     if (!native && this.d.memory) {
       try { this.markMemoryReference(task, by); } catch { return this.releaseNotice(`task #${task.id}: memory reference could not be recorded; note was not saved`); }
       void this.d.memory.save({ text, title, project: this.d.project, metadata: { peer: by, task: task.id, kind } });