@staix/agent-hub 0.12.19 → 0.12.21

package/src/hub/registry.ts

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { createHash } from "node:crypto";
 import { canonicalPath, hubHome, projectRoot } from "./project.ts";
+import { processLiveness } from "../pi/process-signature.ts";
 
 const BASE_PORT = 4600;
 const STRIDE = 10;
@@ -19,22 +20,27 @@ export interface Project {
   basePort: number;
   instanceId: string | null;
   pid: number | null;
+  /** #226: the claimant's processSignature; absent for a claim written by 0.12.20 or older (judged by its pid alone). */
+  pidSignature?: string | null;
+}
+
+/**
+ * #226: `pid_signature` holds "<instance id> <signature>". An older daemon's claim rewrites instance_id and pid but not
+ * this column, so a signature counts only for the instance that wrote it: under another instance the claim is unsigned.
+ */
+export const PROJECT_COLUMNS = "id, root, state_dir as stateDir, base_port as basePort, instance_id as instanceId, pid";
+export function projectFromRow(raw: Record<string, unknown>): Project {
+  const { pid_signature: signed, ...row } = raw;
+  const project = { ...row } as unknown as Project;
+  const prefix = `${project.instanceId} `;
+  if (project.instanceId && typeof signed === "string" && signed.startsWith(prefix) && signed.length > prefix.length) project.pidSignature = signed.slice(prefix.length);
+  return project;
 }
 
 const idFor = (root: string) => `p_${createHash("sha256").update(root).digest("hex").slice(0, 24)}`;
 // Preserve the original identifier of missing legacy checkouts as a reservation.
 const legacyRoot = (path: string) => { try { return realpathSync(path); } catch { return resolve(path); } };
 const canonicalState = canonicalPath;
-const alive = (pid: number): boolean | undefined => {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    const code = (error as NodeJS.ErrnoException).code;
-    if (code === "ESRCH") return false;
-    return undefined;
-  }
-};
 
 export class Registry {
   readonly path: string;
@@ -56,6 +62,11 @@ export class Registry {
       base_port INTEGER NOT NULL UNIQUE, instance_id TEXT, pid INTEGER, claimed_at INTEGER
     )`);
     this.db.run("CREATE TABLE IF NOT EXISTS registry_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)");
+    const columns = this.db.query("PRAGMA table_info(projects)").all() as { name: string }[];
+    if (!columns.some((c) => c.name === "pid_signature")) {
+      try { this.db.run("ALTER TABLE projects ADD COLUMN pid_signature TEXT"); }
+      catch (error) { if (!/duplicate column/i.test((error as Error).message)) throw error; } // a concurrent open added it
+    }
     this.importLegacy();
   }
 
@@ -70,7 +81,7 @@ export class Registry {
       if (existing) {
         if (existing.root !== canonicalRoot) throw new Error(`registry id collision for ${canonicalRoot}`);
         if (explicitState && existing.stateDir !== state) {
-          if (existing.instanceId && (existing.pid === null || alive(existing.pid) !== false)) throw new Error(`cannot relocate live or uncertain project ${id}`);
+          if (existing.instanceId && (existing.pid === null || processLiveness(existing.pid, existing.pidSignature) !== "gone")) throw new Error(`cannot relocate live or uncertain project ${id}`);
           this.db.query("UPDATE projects SET state_dir = ? WHERE id = ?").run(state, id);
         }
         return;
@@ -91,7 +102,7 @@ export class Registry {
   }
 
   list(): Project[] {
-    return this.db.query("SELECT id, root, state_dir as stateDir, base_port as basePort, instance_id as instanceId, pid FROM projects ORDER BY root").all() as Project[];
+    return (this.db.query(`SELECT ${PROJECT_COLUMNS}, pid_signature FROM projects ORDER BY root`).all() as Record<string, unknown>[]).map(projectFromRow);
   }
 
   allocate(root: string): number {
@@ -110,17 +121,18 @@ export class Registry {
     return base;
   }
 
-  claim(id: string, instanceId: string, pid: number): boolean {
+  /** `signature`: the claimant's processSignature (#226); without one the claim is judged by its pid alone. */
+  claim(id: string, instanceId: string, pid: number, signature?: string): boolean {
     let claimed = false;
     const tx = this.db.transaction(() => {
       const project = this.row(id);
       if (!project) return;
       if (project.instanceId && project.instanceId !== instanceId) {
         if (project.pid === null) return;
-        const state = alive(project.pid);
-        if (state !== false) return;
+        if (processLiveness(project.pid, project.pidSignature) !== "gone") return;
       }
-      this.db.query("UPDATE projects SET instance_id = ?, pid = ?, claimed_at = ? WHERE id = ?").run(instanceId, pid, Date.now(), id);
+      this.db.query("UPDATE projects SET instance_id = ?, pid = ?, pid_signature = ?, claimed_at = ? WHERE id = ?")
+        .run(instanceId, pid, signature ? `${instanceId} ${signature}` : null, Date.now(), id);
       claimed = true;
     });
     runTx(tx as Tx);
@@ -128,7 +140,7 @@ export class Registry {
   }
 
   release(id: string, instanceId: string): void {
-    this.db.query("UPDATE projects SET instance_id = NULL, pid = NULL, claimed_at = NULL WHERE id = ? AND instance_id = ?").run(id, instanceId);
+    this.db.query("UPDATE projects SET instance_id = NULL, pid = NULL, pid_signature = NULL, claimed_at = NULL WHERE id = ? AND instance_id = ?").run(id, instanceId);
   }
 
   remove(id: string): void {
@@ -136,16 +148,17 @@ export class Registry {
       const project = this.row(id);
       if (!project) return;
       if (project.instanceId) {
-        if (project.pid === null || alive(project.pid) !== false) throw new Error(`project ${id} has a live or uncertain claim`);
+        if (project.pid === null || processLiveness(project.pid, project.pidSignature) !== "gone") throw new Error(`project ${id} has a live or uncertain claim`);
       } else if (existsSync(join(project.stateDir, "status.json")) || existsSync(join(project.stateDir, "control-token"))) {
-        let pid: number | undefined;
+        let pid: number | undefined, signature: string | undefined;
         try {
-          const status = JSON.parse(readFileSync(join(project.stateDir, "status.json"), "utf8")) as { pid?: number };
+          const status = JSON.parse(readFileSync(join(project.stateDir, "status.json"), "utf8")) as { pid?: number; pidSignature?: unknown };
           pid = typeof status.pid === "number" ? status.pid : undefined;
+          signature = typeof status.pidSignature === "string" ? status.pidSignature : undefined;
         } catch {
           // A state directory without a readable owner marker is uncertain.
         }
-        if (pid === undefined || alive(pid) !== false) throw new Error(`project ${id} has a live or uncertain legacy state`);
+        if (pid === undefined || processLiveness(pid, signature) !== "gone") throw new Error(`project ${id} has a live or uncertain legacy state`);
       }
       this.db.query("DELETE FROM projects WHERE id = ?").run(id);
     });
@@ -157,7 +170,8 @@ export class Registry {
   }
 
   private row(id: string): Project | null {
-    return this.db.query("SELECT id, root, state_dir as stateDir, base_port as basePort, instance_id as instanceId, pid FROM projects WHERE id = ?").get(id) as Project | null;
+    const raw = this.db.query(`SELECT ${PROJECT_COLUMNS}, pid_signature FROM projects WHERE id = ?`).get(id) as Record<string, unknown> | null;
+    return raw ? projectFromRow(raw) : null;
   }
 
   private nextBase(after = BASE_PORT - STRIDE): number {

package/src/hub/report.ts

@@ -13,6 +13,21 @@ export interface Report {
   quota: { readings: number; hard: number };
   conduct: Record<string, Record<string, number>>;
   supervision: Record<string, { turns: number | null; tokens: number | null; measuredTokens: number | null; knownTokenTurns: number; unknownTokenTurns: number }>;
+  /** Per "peer route": model changes between consecutive decisions of a session, and the planner's verdicts (#197). */
+  routes: Record<string, RouteSwitches>;
+}
+
+export interface RouteSwitches {
+  decisions: number;
+  /** Pins the planner started; 0 while stay_switch is off, when session boundaries are not recorded. */
+  sessions: number;
+  /** Decisions made without a session key: each looks like a new session, so sessions are unknown. */
+  stateless: number;
+  switches: number;
+  toolLoopSwitches: number;
+  planned: number;
+  plannedInToolLoops: number;
+  modes: string[];
 }
 
 export interface UsageCoverage {
@@ -85,7 +100,7 @@ function formatUsage(usage: Report["usage"]): string[] {
 
 /** The numbers `ahub report` prints, from `events.jsonl` alone (issue #40). */
 export function summarize(events: StampedEvent[]): Report {
-  const r: Report = { peers: {}, conduct: {}, supervision: {}, usage: { peers: {}, totals: { inputTokens: 0, inputRecords: 0, outputTokens: 0, outputRecords: 0, cacheReadTokens: 0, cacheReadRecords: 0, cacheWriteTokens: 0, cacheWriteRecords: 0, totalTokens: 0, totalRecords: 0 }, unknownPeers: [], completeCoverage: true }, messages: { total: 0, dropped: {}, overflow: 0, undeliverable: 0, perTask: 0 }, overlaps: { warnings: 0, pairs: 0 }, conflicts: 0, tasks: {}, quota: { readings: 0, hard: 0 } };
+  const r: Report = { peers: {}, conduct: {}, supervision: {}, routes: {}, usage: { peers: {}, totals: { inputTokens: 0, inputRecords: 0, outputTokens: 0, outputRecords: 0, cacheReadTokens: 0, cacheReadRecords: 0, cacheWriteTokens: 0, cacheWriteRecords: 0, totalTokens: 0, totalRecords: 0 }, unknownPeers: [], completeCoverage: true }, messages: { total: 0, dropped: {}, overflow: 0, undeliverable: 0, perTask: 0 }, overlaps: { warnings: 0, pairs: 0 }, conflicts: 0, tasks: {}, quota: { readings: 0, hard: 0 } };
   const supervisor = (id: string) => (r.supervision[id] ??= { turns: null, tokens: null, measuredTokens: null, knownTokenTurns: 0, unknownTokenTurns: 0 });
   const peer = (id: string) => (r.peers[id] ??= { turns: 0, busyMinutes: 0, tokens: 0 });
   const claudeNativeStops = events.some(event => event.type === "native_turn_end" && event.peer === "claude" && !!event.id);
@@ -95,6 +110,7 @@ export function summarize(events: StampedEvent[]): Report {
   const taskMessages = new Map<string, number>();
   const seenUsage = new Set<string>();
   const seenSupervision = new Set<string>();
+  const lastTier = new Map<string, string>();
   for (const e of events) {
     r.from ??= e.at;
     r.to = e.at;
@@ -168,6 +184,26 @@ export function summarize(events: StampedEvent[]): Report {
         r.quota.readings++;
         if (e.hard) r.quota.hard++;
         break;
+      case "route": {
+        // ponytail: consecutive decisions of one peer and route are taken as one session between pins; that holds while each
+        // peer runs one session at a time (Pi, and local outside PII turns). An opaque session ordinal is the upgrade path.
+        const key = `${e.peer} ${e.route}`;
+        const s = (r.routes[key] ??= { decisions: 0, sessions: 0, stateless: 0, switches: 0, toolLoopSwitches: 0, planned: 0, plannedInToolLoops: 0, modes: [] });
+        s.decisions++;
+        if (e.staySwitch && !s.modes.includes(e.staySwitch)) s.modes.push(e.staySwitch);
+        if (e.stateless) s.stateless++;
+        if (e.reason === "new_pin" && !e.stateless) s.sessions++;
+        else if (lastTier.has(key) && lastTier.get(key) !== e.tier) {
+          s.switches++;
+          if (e.turnType === "tool_result") s.toolLoopSwitches++;
+        }
+        lastTier.set(key, e.tier);
+        if (e.plan === "switch") {
+          s.planned++;
+          if (e.turnType === "tool_result") s.plannedInToolLoops++;
+        }
+        break;
+      }
     }
   }
   r.overlaps.pairs = pairs.size;
@@ -205,6 +241,12 @@ export function formatReport(r: Report): string[] {
   const tasks = Object.entries(r.tasks).sort().map(([k, n]) => `${k} ${n}`).join(", ");
   lines.push(`task events: ${tasks || "none"}`);
   lines.push(`quota readings: ${r.quota.readings} (${r.quota.hard} hard limits)`);
+  for (const [key, s] of Object.entries(r.routes).sort(([a], [b]) => a.localeCompare(b))) {
+    const sessions = s.stateless ? `sessions unknown (${s.stateless} decision${s.stateless === 1 ? "" : "s"} without a session key)`
+      : s.sessions ? `${s.sessions} session${s.sessions === 1 ? "" : "s"}, ${(s.switches / s.sessions).toFixed(1)} model changes per session` : "sessions unknown (stay_switch off)";
+    const planner = s.modes.length ? `; planner (${s.modes.join(", ")}): ${s.planned} switches, ${s.plannedInToolLoops} inside tool loops` : "";
+    lines.push(`route ${key}: ${s.decisions} decisions, ${sessions}; ${s.switches} model change${s.switches === 1 ? "" : "s"}, ${s.toolLoopSwitches} inside tool loops${planner}`);
+  }
   return lines;
 }
 

package/src/hub/research.ts

@@ -0,0 +1,255 @@
+import { createHash } from "node:crypto";
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { StampedEvent } from "./events.ts";
+import { hubHome } from "./project.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";
+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. */
+const FAILED: ReadonlySet<string> = new Set(["regressed", "reverted", "incomplete", "wrong", "abandoned"]);
+
+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;
+  class: string | null; pii: boolean; outcome: "approved";
+  /** 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. */
+  wallMs: number | null;
+  /** Sum of the attributed turns' durations, the turns still open at the approval included. */
+  activeMs: number;
+  /** Owners in the order they held the task. */
+  owners: string[]; reviewer: string | null;
+  /** Times the task went to review, was sent back, passed or failed its check, was reported done. */
+  reviewRounds: number; changesRequested: number; checkPassed: number; checkFailed: number; dones: number;
+  /** Owner changes after the first owner, and the same counted by the board's move reason. */
+  reassignments: number; reassignedBy: Record<string, number>;
+  /** Approved on its first review with no failed check. */
+  firstPass: boolean;
+  stuck: number; overlaps: number; conflicts: number;
+  tests: { pass: number; fail: number };
+  /** Attributed tokens per peer and per #200 attribution rule; unattributed tokens are in no record. */
+  tokens: { total: number; byPeer: Record<string, number>; byAttribution: Record<string, number> };
+  usage: Record<string, PeerUsage>;
+  /** Provider-reported total tokens per served (else requested) model. */
+  usageByModel: Record<string, number>;
+  turns: number; filesChanged: number;
+  /** Model routes and served models seen for the task's attributed requests. */
+  models: string[];
+  writer: { version: string; source: "live" | "backfill" };
+}
+/** A person's later verdict on one task record: `createdAt` binds it to that task, not a later one with the same id. */
+export interface LabelRecord { schema: typeof RESEARCH_SCHEMA; kind: "label"; project: string; task: number; createdAt: string; label: Label; at: string }
+export type ResearchRecord = TaskRecord | LabelRecord;
+
+/** The store name for a project: a hash of its id, never its path. */
+export const projectKey = (projectId: string): string => createHash("sha256").update(projectId).digest("hex").slice(0, 16);
+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 ?? ""}`;
+
+type Acc = Omit<TaskRecord, "schema" | "kind" | "project" | "approvedAt" | "wallMs" | "firstPass" | "outcome" | "writer" | "models"> & {
+  models: Set<string>; approvedAt: string | null; lastState: string | 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 });
+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
+ * 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.
+ */
+export function taskRecords(events: StampedEvent[], projectId: string, writer: TaskRecord["writer"]): 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>();
+  for (const e of events) {
+    if (e.type === "task") {
+      // Ids restart after `ahub reset --all` archives the events, but a file that kept both starts the task anew.
+      if (e.event === "proposed" && tasks.get(e.id)?.createdAt) { earlier.push(tasks.get(e.id)!); tasks.delete(e.id); }
+      const a = acc(e.id);
+      a.class = e.class; if (e.pii) a.pii = true;
+      if (e.owner && e.owner !== a.owners.at(-1)) {
+        if (a.owners.length) { a.reassignments++; bump(a.reassignedBy, e.reason ?? "none"); }
+        a.owners.push(e.owner);
+      }
+      if (e.reviewer) a.reviewer = e.reviewer;
+      if (e.event === "proposed") a.createdAt ??= e.at;
+      if (e.state === "in_progress") a.startedAt ??= e.at;
+      if (e.event === "done") a.dones++;
+      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;
+      a.lastState = e.state;
+      continue;
+    }
+    const task = "task" in e && typeof e.task === "number" ? e.task : undefined;
+    if (task === undefined) continue;
+    const a = acc(task);
+    if ("pii" in e && e.pii === true) a.pii = true;
+    if (e.type === "tokens") { a.tokens.total += e.n; bump(a.tokens.byPeer, e.peer, e.n); bump(a.tokens.byAttribution, e.attribution ?? "unknown", e.n); }
+    else if (e.type === "turn_end") { a.turns++; a.activeMs += e.ms; a.filesChanged += e.files ?? 0; }
+    else if (e.type === "usage") {
+      const key = `${e.peer}\0${e.source}\0${e.id}`;
+      if (seenUsage.has(key)) continue;
+      seenUsage.add(key);
+      const u = a.usage[e.peer] ??= { input: null, output: null, cacheRead: null, total: null };
+      u.input = add(u.input, e.inputTokens); u.output = add(u.output, e.outputTokens); u.cacheRead = add(u.cacheRead, e.cacheReadTokens); u.total = add(u.total, e.totalTokens);
+      const model = e.servedModel ?? e.requestedModel;
+      if (model) a.models.add(String(model));
+      if (typeof e.totalTokens === "number" && Number.isFinite(e.totalTokens)) bump(a.usageByModel, String(model ?? "unknown"), e.totalTokens);
+    }
+    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 === "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, ...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,
+      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 });
+  }
+  return out.sort((x, y) => x.approvedAt.localeCompare(y.approvedAt) || x.task - y.task);
+}
+
+/** Every record in one store file; a line that does not parse is skipped. */
+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 []; }
+  });
+}
+/** 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));
+  const dir = researchDir(home);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((name) => name.endsWith(".jsonl")).sort().flatMap((name) => readStore(join(dir, name)));
+}
+
+/** Append task records the store does not hold yet (same task, by `recordKey`), and labels; returns how many were written. */
+export function appendRecords(projectId: string, records: ResearchRecord[], home = hubHome()): number {
+  if (!records.length) return 0;
+  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)));
+  if (!added.length) return 0;
+  appendFileSync(file, added.map((r) => JSON.stringify(r)).join("\n") + "\n", { mode: 0o600 });
+  chmodSync(file, 0o600);
+  return added.length;
+}
+
+/**
+ * The record a person's label is for. `created` (a record's `createdAt`, from `ahub research export`) names one exactly.
+ * Otherwise the current board's task with that id, found by its proposal in `events`, so a label never lands on an
+ * earlier task with the same id; an id this hub's events do not have (a task from before `ahub reset --all`) is the
+ * store's only record with that id. Throws why there is none, or which ones to choose from.
+ */
+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);
+  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(", ")})` : ""}`);
+  }
+  const proposed = events.filter((e) => e.type === "task" && e.id === task && e.event === "proposed").at(-1);
+  if (proposed) {
+    return mine.find((r) => r.createdAt === proposed.at)
+      ?? fail(`task #${task} has no research record yet: it is not approved, its record still waits for the turns that approved it, or it was approved while research was off (ahub research backfill builds that one)${mine.length ? `; an earlier task #${task} from before a reset is labelled with --created ${mine.map((r) => r.createdAt).join(" or ")}` : ""}`);
+  }
+  if (mine.length === 1) return mine[0]!;
+  if (!mine.length) throw new Error(records.some((r) => r.kind === "task" && r.task === task) ? `task #${task}'s research record has no proposal time (its proposal was not in the events), so it takes no label` : `no research record for task #${task}`);
+  throw new Error(`task #${task} is not on this hub's board and the store has ${mine.length} records with that id; name one with --created <time>: ${mine.map((r) => r.createdAt).join(", ")}`);
+}
+const fail = (message: string): never => { throw new Error(message); };
+
+const pct = (n: number, d: number) => d ? n / d : null;
+/** Linear interpolation between the closest ranks: the median of [100, 300] is 200. */
+function quantile(values: number[], q: number): number | null {
+  if (!values.length) return null;
+  const sorted = [...values].sort((a, b) => a - b), at = q * (sorted.length - 1), low = Math.floor(at);
+  return sorted[low]! + (sorted[Math.min(low + 1, sorted.length - 1)]! - sorted[low]!) * (at - low);
+}
+export interface Measures {
+  tasks: number; succeeded: number; failedByLabel: number;
+  successRate: number | null; firstPassRate: number | null; reworkRate: number | null; checkFailureRate: number | null;
+  tokensPerTask: { median: number | null; p90: number | null }; wallMsPerTask: { median: number | null; p90: number | null };
+}
+function measures(records: TaskRecord[], labels: Map<string, Label>): Measures {
+  const failed = records.filter((r) => FAILED.has(labels.get(recordKey(r)) ?? "")).length;
+  return { tasks: records.length, succeeded: records.length - failed, failedByLabel: failed,
+    successRate: pct(records.length - failed, records.length), firstPassRate: pct(records.filter((r) => r.firstPass).length, records.length),
+    reworkRate: pct(records.reduce((n, r) => n + r.changesRequested, 0), records.length),
+    checkFailureRate: pct(records.reduce((n, r) => n + r.checkFailed, 0), records.reduce((n, r) => n + r.checkFailed + r.checkPassed, 0)),
+    tokensPerTask: { median: quantile(records.map((r) => r.tokens.total), 0.5), p90: quantile(records.map((r) => r.tokens.total), 0.9) },
+    wallMsPerTask: { median: quantile(records.flatMap((r) => r.wallMs ?? []), 0.5), p90: quantile(records.flatMap((r) => r.wallMs ?? []), 0.9) } };
+}
+export interface ResearchReport { overall: Measures; byClass: Record<string, Measures>; byOwner: Record<string, Measures>; byProject: Record<string, Measures>; byModel: Record<string, Measures> }
+/**
+ * The derived measures, never stored as truth: each task counts once (its last record), and a person's latest label
+ * decides whether an approved task later failed. Records older than `since` (ms epoch, by approval) are left out.
+ */
+export function researchReport(records: ResearchRecord[], since = 0): ResearchReport {
+  const latest = new Map<string, TaskRecord>(), labels = new Map<string, Label>();
+  for (const r of records) {
+    const key = recordKey(r);
+    if (r.kind === "label") { labels.set(key, r.label); continue; }
+    if (Date.parse(r.approvedAt) >= since) latest.set(key, r);
+  }
+  const all = [...latest.values()];
+  const group = (keys: (r: TaskRecord) => string[]) => {
+    // A Map: a peer or model may be named `constructor`, which a plain object answers with an inherited value.
+    const out = new Map<string, TaskRecord[]>();
+    for (const r of all) for (const k of keys(r)) out.set(k, [...(out.get(k) ?? []), r]);
+    return Object.fromEntries([...out].sort(([a], [b]) => a.localeCompare(b)).map(([k, rs]) => [k, measures(rs, labels)]));
+  };
+  return { overall: measures(all, labels), byClass: group((r) => [r.class ?? "unknown"]), byOwner: group((r) => r.owners.length ? [...new Set(r.owners)] : ["none"]),
+    byProject: group((r) => [r.project]), byModel: group((r) => r.models.length ? r.models : ["unknown"]) };
+}
+
+const fmtPct = (v: number | null) => v === null ? "-" : `${Math.round(v * 100)}%`;
+const fmtNum = (v: number | null) => v === null ? "-" : String(Math.round(v));
+export function formatResearch(r: ResearchReport): string[] {
+  const row = (name: string, m: Measures) => `${name.padEnd(24)} ${String(m.tasks).padStart(5)}  ${fmtPct(m.successRate).padStart(7)}  ${fmtPct(m.firstPassRate).padStart(10)}  ${(m.reworkRate === null ? "-" : m.reworkRate.toFixed(2)).padStart(6)}  ${fmtPct(m.checkFailureRate).padStart(11)}  ${fmtNum(m.tokensPerTask.median).padStart(10)}  ${fmtNum(m.tokensPerTask.p90).padStart(10)}  ${(m.wallMsPerTask.median === null ? "-" : `${Math.round(m.wallMsPerTask.median / 60_000)}m`).padStart(8)}`;
+  const head = `${"".padEnd(24)} ${"tasks".padStart(5)}  ${"success".padStart(7)}  ${"first pass".padStart(10)}  ${"rework".padStart(6)}  ${"check fails".padStart(11)}  ${"tokens p50".padStart(10)}  ${"tokens p90".padStart(10)}  ${"wall p50".padStart(8)}`;
+  const section = (title: string, groups: Record<string, Measures>) => Object.keys(groups).length ? [``, title, head, ...Object.entries(groups).map(([k, m]) => row(k, m))] : [];
+  return [head, row("all approved tasks", r.overall), ...section("by class", r.byClass), ...section("by owner", r.byOwner), ...section("by model", r.byModel), ...section("by project", r.byProject)];
+}
+
+export const CSV_COLUMNS = ["project", "task", "class", "pii", "outcome", "createdAt", "startedAt", "approvedAt", "wallMs", "activeMs", "owners",
+  "reviewer", "reviewRounds", "changesRequested", "checkPassed", "checkFailed", "dones", "reassignments", "firstPass", "stuck", "overlaps", "conflicts",
+  "testsPass", "testsFail", "tokens", "turns", "filesChanged", "models", "label", "writerVersion", "writerSource"] as const;
+/** Task records as CSV with a header row, one row per record, each with the task's latest label; JSONL has every field. */
+export function toCsv(records: ResearchRecord[]): string {
+  const labels = new Map<string, Label>();
+  for (const r of records) if (r.kind === "label") labels.set(recordKey(r), r.label);
+  const cell = (v: unknown) => { const s = v === null || v === undefined ? "" : String(v); return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s; };
+  const rows = records.filter((r): r is TaskRecord => r.kind === "task").map((r) => [r.project, r.task, r.class, r.pii, r.outcome, r.createdAt, r.startedAt,
+    r.approvedAt, r.wallMs, r.activeMs, r.owners.join(" "), r.reviewer, r.reviewRounds, r.changesRequested, r.checkPassed, r.checkFailed, r.dones,
+    r.reassignments, r.firstPass, r.stuck, r.overlaps, r.conflicts, r.tests.pass, r.tests.fail, r.tokens.total, r.turns, r.filesChanged, r.models.join(" "),
+    labels.get(recordKey(r)) ?? "", r.writer.version, r.writer.source].map(cell).join(","));
+  return [CSV_COLUMNS.join(","), ...rows].join("\n") + "\n";
+}

package/src/hub/restart.ts

@@ -5,6 +5,7 @@ import type { BusSnapshot } from "./bus.ts";
 import type { PeerId, PeerState } from "./envelope.ts";
 import { MAX_HOP } from "./envelope.ts";
 import { validateJournalSnapshot } from "./delivery-journal.ts";
+import { atomicPrivateJSON } from "./recovery-store.ts";
 
 export const RESTART_SCHEMA_VERSION = 1;
 
@@ -96,6 +97,30 @@ export function removeRestartSnapshot(stateDir: string): void {
   catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
 }
 
+/**
+ * Peers whose saved native session id the restored daemon does not require back, each with the coordinator's
+ * reason (#206 reconnect-only, #215 fresh session). Fenced by operation: a file left by another operation waives nothing.
+ */
+export function readRecoveryWaivers(stateDir: string, operationId: string): Record<string, string> {
+  try {
+    const value = JSON.parse(readFileSync(join(stateDir, "recovery-waivers.json"), "utf8"));
+    if (value?.operationId !== operationId || !value.peers || typeof value.peers !== "object") return {};
+    return Object.fromEntries(Object.entries(value.peers).filter((entry): entry is [string, string] => typeof entry[1] === "string" && entry[1].length > 0));
+  } catch { return {}; }
+}
+
+export function waiveRecoveryPeers(stateDir: string, operationId: string, peers: Record<string, string>): void {
+  atomicPrivateJSON(join(stateDir, "recovery-waivers.json"), { operationId, peers: { ...readRecoveryWaivers(stateDir, operationId), ...peers } });
+}
+
+/** #215 stop-and-archive: keep an abandoned operation's committed snapshot for manual reconciliation; it is never replayed. */
+export function abandonRestartSnapshot(stateDir: string, operationId: string): void {
+  try { if (JSON.parse(readFileSync(restartPath(stateDir), "utf8"))?.operationId !== operationId) return; } catch { return; }
+  const archived = join(stateDir, `restart.abandoned.${createHash("sha256").update(operationId).digest("hex")}.json`);
+  renameSync(restartPath(stateDir), archived);
+  chmodSync(archived, 0o600);
+}
+
 /** Preserve an uncertain release outcome for manual reconciliation without making it authoritative on startup. */
 export function archiveRestartSnapshot(stateDir: string, operationId: string): void {
   renameSync(restartPath(stateDir), releasedRestartPath(stateDir, operationId));