@staix/agent-hub 0.34.0 → 0.35.0

package/src/hub/model-overrides.ts

@@ -0,0 +1,115 @@
+import { createHash } from "node:crypto";
+import { openHubDatabase, type Database } from "./db-schema.ts";
+import { isNativeModelToken } from "../adapters/model-token.ts";
+import type { ModelOverrideSelection } from "../adapters/registry-types.ts";
+
+export interface ModelOverrideRow { peer: string; model: string; setAt: number; by: "person" }
+export type ModelSource = "override" | "instance" | "launch" | "native default" | "native thread default (was override)";
+export interface RuntimeModelStatus {
+  peer: string;
+  effectiveModel: string | null;
+  source: ModelSource;
+  desiredModel: string | null;
+  pendingNextTurn: boolean;
+  unsupported?: { reasonCode: "unverified_setter" | "unmanaged_attachment" | "acp_setter_unavailable"; kind?: string; version?: string; reason: string; nextStep: string };
+}
+const MAX_OVERRIDE_ROWS = 128;
+const peerToken = (peer: unknown): peer is string => typeof peer === "string" && /^[a-z][a-z0-9-]{0,31}$/.test(peer);
+const invalid = () => new Error("model override state is invalid; inspect hub.db or clear the override with ahub model clear");
+function row(value: unknown): ModelOverrideRow {
+  if (!value || typeof value !== "object") throw invalid();
+  const entry = value as Record<string, unknown>;
+  if (!peerToken(entry.peer) || !isNativeModelToken(entry.model) || !Number.isSafeInteger(entry.set_at) || Number(entry.set_at) < 0 || entry.by !== "person") throw invalid();
+  return { peer: entry.peer, model: entry.model, setAt: Number(entry.set_at), by: "person" };
+}
+const columns = "CASE WHEN typeof(peer)='text' AND length(CAST(peer AS BLOB))<=32 THEN peer END AS peer,CASE WHEN typeof(model)='text' AND length(CAST(model AS BLOB))<=128 THEN model END AS model,CASE WHEN typeof(set_at)='integer' AND set_at>=0 THEN set_at END AS set_at,CASE WHEN typeof(\"by\")='text' AND \"by\"='person' THEN 'person' END AS \"by\"";
+/** Runtime state only: no configuration writes, native calls or authority grants. */
+export class ModelOverrides {
+  private readonly db: Database;
+  private readonly revisions = new Map<string, number>();
+  constructor(dbPath: string) {
+    this.db = openHubDatabase(dbPath, { create: true });
+    try { this.db.run('CREATE TABLE IF NOT EXISTS model_overrides(peer TEXT PRIMARY KEY,model TEXT NOT NULL,set_at INTEGER NOT NULL,"by" TEXT NOT NULL)'); }
+    catch (error) { this.db.close(); throw error; }
+  }
+  get(peer: string): ModelOverrideRow | undefined {
+    if (!peerToken(peer)) throw invalid();
+    const found = this.db.query(`SELECT ${columns} FROM model_overrides WHERE peer=?`).get(peer);
+    return found ? row(found) : undefined;
+  }
+  list(): ModelOverrideRow[] {
+    const rows = this.db.query(`SELECT ${columns} FROM model_overrides ORDER BY peer LIMIT ?`).all(MAX_OVERRIDE_ROWS + 1);
+    if (rows.length > MAX_OVERRIDE_ROWS) throw invalid();
+    return rows.map(row);
+  }
+  revision(peer: string): string { return JSON.stringify([this.revisions.get(peer) ?? 0, this.get(peer) ?? null]); }
+  set(peer: string, model: string, setAt = Date.now()): ModelOverrideRow {
+    if (!peerToken(peer) || !isNativeModelToken(model) || !Number.isSafeInteger(setAt) || setAt < 0) throw new Error("invalid model selection; use a peer id and a bounded native model token, then retry ahub model set");
+    if (!this.get(peer) && this.list().length >= MAX_OVERRIDE_ROWS) throw new Error("model override capacity reached; clear unused peer overrides before adding another");
+    this.db.query('INSERT INTO model_overrides(peer,model,set_at,"by") VALUES(?,?,?,?) ON CONFLICT(peer) DO UPDATE SET model=excluded.model,set_at=excluded.set_at,"by"=excluded."by"').run(peer, model, setAt, "person");
+    this.revisions.set(peer, (this.revisions.get(peer) ?? 0) + 1);
+    return { peer, model, setAt, by: "person" };
+  }
+  clear(peer: string): boolean {
+    if (!peerToken(peer)) throw invalid();
+    const changed = this.db.query("DELETE FROM model_overrides WHERE peer=?").run(peer).changes > 0;
+    if (changed) this.revisions.set(peer, (this.revisions.get(peer) ?? 0) + 1);
+    return changed;
+  }
+  hasRecords(): boolean { return this.db.query("SELECT 1 FROM model_overrides LIMIT 1").get() !== null; }
+  integrity(): { count: number; digest: string } {
+    const rows = this.list();
+    return { count: rows.length, digest: createHash("sha256").update(JSON.stringify(rows)).digest("hex") };
+  }
+  close(): void { this.db.close(); }
+}
+interface Captured {
+  owner: object;
+  turn: object;
+  revision: string;
+  model: string | undefined;
+  selection: ModelOverrideSelection;
+  retirementFenced: boolean;
+}
+/** Selected and acknowledged are separate. A later desired write never changes a turn's captured selection. */
+export class ModelOverrideLatches {
+  private readonly captured = new Map<string, Captured>();
+  private readonly acknowledged = new Map<string, { owner: object; revision: string | undefined; model: string | undefined; source: "override" | "native default" | "native thread default (was override)" }>();
+  constructor(private readonly store: ModelOverrides) {}
+  capture(peer: string, owner: object, turn: object, current: () => boolean): ModelOverrideSelection {
+    const previous = this.captured.get(peer);
+    if (previous?.owner === owner && previous.turn === turn) return previous.selection;
+    const revision = this.store.revision(peer), model = this.store.get(peer)?.model;
+    const capture: Captured = { owner, turn, revision, model, retirementFenced: false, selection: { model, applied: (nativeModel?: string) => {
+      if (this.captured.get(peer) !== capture) return;
+      try { if (!current()) return; } catch { return; }
+      const hint = model === undefined && isNativeModelToken(nativeModel) ? nativeModel : undefined;
+      const before = this.acknowledged.get(peer), wasOwned = hint !== undefined && before?.owner === owner && before.model === hint
+        && (before.source === "override" || before.source === "native thread default (was override)");
+      capture.retirementFenced = true;
+      this.acknowledged.set(peer, { owner, revision, model: model ?? hint, source: hint === undefined ? "override" : wasOwned ? "native thread default (was override)" : "native default" });
+    } } };
+    this.captured.set(peer, capture);
+    return capture.selection;
+  }
+  status(peer: string, owner: object | undefined, fallback: { model?: string; source: Exclude<ModelSource, "override"> }, unsupported?: RuntimeModelStatus["unsupported"]): RuntimeModelStatus {
+    const desired = this.store.get(peer), applied = this.acknowledged.get(peer), captured = this.captured.get(peer), revision = this.store.revision(peer);
+    const active = !unsupported && applied?.owner === owner ? applied : undefined;
+    const effective = active?.model;
+    return { peer, effectiveModel: effective ?? fallback.model ?? null, source: effective === undefined ? fallback.source : active!.source, desiredModel: desired?.model ?? null,
+      pendingNextTurn: !unsupported && ((desired !== undefined || active !== undefined) && active?.revision !== revision
+        || !!captured && captured.owner === owner && captured.revision !== revision),
+      ...(unsupported ? { unsupported } : {}) };
+  }
+  forget(peer: string): void { this.captured.delete(peer); this.acknowledged.delete(peer); }
+  end(peer: string, expectedTurn?: object, onlyUnacknowledged = false): boolean {
+    const capture = this.captured.get(peer);
+    if (!capture || expectedTurn !== undefined && capture.turn !== expectedTurn || onlyUnacknowledged && capture.retirementFenced) return false;
+    this.captured.delete(peer); return true;
+  }
+  observeNative(peer: string, owner: object, model: string): void {
+    if (!isNativeModelToken(model)) return;
+    const capture = this.captured.get(peer); if (capture && capture.owner === owner) capture.retirementFenced = true;
+    this.acknowledged.set(peer, { owner, model, source: "native default", revision: this.store.get(peer) ? undefined : this.store.revision(peer) });
+  }
+}

package/src/hub/native-hook-launch.ts

@@ -1,23 +1,28 @@
 /** Managed launch authority is ephemeral and scoped to one peer, daemon and native session. */
 export interface NativeHookLaunch {
   id: string;
+  home?: string;
   session?: string;
+  transcript?: string;
   generation?: string;
   baseline?: number;
   turn?: string;
   active: boolean;
   completed?: string;
+  transcriptPath?: string;
+  transcriptOffset?: number;
 }
 export class NativeHookLaunches {
   private readonly launches = new Map<string, NativeHookLaunch>();
   private readonly owners = new Map<string, object>();
-  begin(peer: string, owner: object): NativeHookLaunch {
+  begin(peer: string, owner: object, home?: string): NativeHookLaunch {
     if (this.launches.has(peer)) throw new Error("a managed native launch is already active; end it in its terminal first");
-    const launch: NativeHookLaunch = { id: crypto.randomUUID(), active: false };
+    const launch: NativeHookLaunch = { id: crypto.randomUUID(), active: false, ...(home ? { home } : {}) };
     this.launches.set(peer, launch);
     this.owners.set(peer, owner);
     return launch;
   }
+  current(peer: string): NativeHookLaunch | undefined { return this.launches.get(peer); }
   get(peer: string, id: unknown): NativeHookLaunch | undefined {
     const launch = this.launches.get(peer);
     return launch && typeof id === "string" && launch.id === id ? launch : undefined;
@@ -27,11 +32,15 @@ export class NativeHookLaunches {
     this.owners.delete(peer);
     return this.launches.delete(peer);
   }
-  endOwner(owner: object): void {
+  endOwner(owner: object): { peer: string; launch: NativeHookLaunch }[] {
+    const ended: { peer: string; launch: NativeHookLaunch }[] = [];
     for (const [peer, current] of this.owners) {
       if (current !== owner) continue;
+      const launch = this.launches.get(peer);
+      if (launch) ended.push({ peer, launch });
       this.launches.delete(peer);
       this.owners.delete(peer);
     }
+    return ended;
   }
 }

package/src/hub/operational-view.ts

@@ -12,7 +12,7 @@ export interface OperationalViewPorts {
 }
 /** Closed metadata receipts only. Unsupported nested records are withheld until given their own projection. */
 const EVENT_FIELDS: Record<string,readonly string[]>={
-  state:["peer","state"],hub_start:["instance"],native_thread:["peer","thread","fresh"],turn_start:["peer","turn"],native_turn_end:["peer","id"],
+  state:["peer","state"],hub_start:["instance"],native_thread:["peer","thread","fresh"],turn_start:["peer","turn"],native_turn_end:["peer","id","reason"],
   task:["id","event","by","state","owner","reviewer","class","profile","profileClass","role","pii","reason","release","priority","plannedStart","due"],
   tokens:["peer","n","task","attribution","pii"],
   usage:["peer","source","id","task","attribution","pii","reasoningTokens","measuredAt","inputTokens","outputTokens","cacheReadTokens","cacheWriteTokens","totalTokens"],
@@ -67,7 +67,7 @@ function metadataValue(type:string,key:string,value:unknown):boolean {
   if(key==="item")return oneOf(value,["task","summary","review note","handoff","note"]);
   if(key==="category")return oneOf(value,["name","student_id","phone","address","grade","health","other"]);
   if(key==="miss")return oneOf(value,["too long","off campus","timeout","unreadable","failed"]);
-  if(key==="source")return type==="pii_screen"?oneOf(value,["regex","screen","unknown","inherited"]):type==="usage"?oneOf(value,["omniroute","claude_transcript","claude_result","codex_appserver","kimi_wire","jcode_acp"]):identifier(value);
+  if(key==="source")return type==="pii_screen"?oneOf(value,["regex","screen","unknown","inherited"]):type==="usage"?oneOf(value,["omniroute","claude_transcript","claude_result","codex_appserver","kimi_wire","jcode_acp","agy_transcript"]):identifier(value);
   if(key==="measuredAt")return type==="context_pressure" || type==="quota_reset"?typeof value==="number"&&Number.isFinite(value):typeof value==="string"&&Number.isFinite(Date.parse(value));
   if(key==="window")return value===null || typeof value==="number"&&Number.isFinite(value)&&value>=0 || identifier(value);
   if(key==="priority")return value===null || typeof value==="number"&&Number.isFinite(value) || oneOf(value,["status","important","fyi"]);

package/src/hub/peers.ts

@@ -23,6 +23,11 @@ export interface OwnedToolsLaunch {
 
 /** Display-only identity for a live channel connection waiting for a person's handover. */
 export interface PeerStandbySession { id: string; pid?: number; since: number; }
+/**
+ * Display metadata about the CURRENT owner of an attached channel peer (#1310): who holds it, since when, and which native session the host has already verified. Never authentication,
+ * delivery, takeover or permission evidence, and never derived from a standby id, a process name, a title or attach order. Every field is bounded; none is text from the client.
+ */
+export interface PeerOwnerAttachment { ownerPid?: number; attachedAt: number; nativeSessionId?: string; }
 
 /** Opaque, generation-fenced claim produced by a peer's person-requested takeover port. */
 export interface PeerTakeoverClaim {
@@ -46,6 +51,8 @@ export interface PeerAdapter {
   readonly id: PeerId;
   /** Live waiting sessions, for display only; ids and pids grant no native identity or authority. */
   readonly standbySessions?: readonly PeerStandbySession[];
+  /** The current owner's attachment facts, for display only; absent unless a socket is attached and no newer claim is arriving (#1310). */
+  readonly ownerAttachment?: PeerOwnerAttachment;
   /** Person-authorized takeover port. The host still performs its own admission and claim fences. */
   takeover?(standbyId: string | undefined, eligible: (socket: object) => boolean): PeerTakeoverClaim | undefined;
   /** Exact transport ownership check for guarding a selected standby through its asynchronous preface. */
@@ -115,6 +122,10 @@ export interface PeerAdapter {
   stop(reason?: string): Promise<void>;
   /** Set by the bus. The peer said something worth sharing. */
   onMessage?: (body: string, opts?: EnvelopeOpts) => unknown;
+  /** Host-only Record guidance for the next owned headless turn; never native-client configuration. */
+  recordInstruction?: () => string | undefined;
+  /** Raw model answer boundary, separate from explicit send tools and diagnostics. */
+  onFinalAnswer?: (body: string, opts?: EnvelopeOpts, complete?: boolean) => unknown;
   /** Set by the bus. */
   onState?: (state: PeerState) => void;
   /** Set by the bus. A delivery that had resolved turned out not to reach the agent: put it back. */
@@ -135,6 +146,10 @@ export const DEFAULT_WATCHDOG_MS = 300_000;
 export abstract class BasePeer implements PeerAdapter {
   /** Returns a reason (a string) when the hub refused the message (issue #38). */
   onMessage?: (body: string, opts?: EnvelopeOpts) => unknown;
+  /** Host-only Record guidance for the next owned headless turn; never native-client configuration. */
+  recordInstruction?: () => string | undefined;
+  /** Raw model answer boundary, separate from explicit send tools and diagnostics. */
+  onFinalAnswer?: (body: string, opts?: EnvelopeOpts, complete?: boolean) => unknown;
   onState?: (state: PeerState) => void;
   onFailed?: (envs: Envelope[], failure?: { quota?: true; failureCause?: DeliveryFailureCause }) => void;
   onDelivery?: (receipt: DeliveryReceipt) => void;
@@ -152,6 +167,18 @@ export abstract class BasePeer implements PeerAdapter {
     return this._state;
   }
 
+  /** Decorate only a fixed prompt, once at the delivered-turn boundary. */
+  protected turnRecordPrompt(base: string): string {
+    let instruction: string | undefined;
+    try { instruction = this.recordInstruction?.(); } catch { return base; }
+    if (!instruction || base.includes(instruction)) return base;
+    return base ? `${base}\n\n${instruction}` : instruction;
+  }
+
+  protected finalAnswer(text: string, opts?: EnvelopeOpts, complete = true): unknown {
+    return this.onFinalAnswer ? this.onFinalAnswer(text, opts, complete) : this.onMessage?.(text, opts);
+  }
+
   /** Keep the active turn's inactivity bound; a changed setting belongs to the next busy turn. */
   configureWatchdog(ms: number): void {
     if (!Number.isFinite(ms) || ms <= 0 || ms > 2_147_483_647) throw new Error("invalid watchdog interval");

package/src/hub/permission-mode.ts

@@ -41,7 +41,7 @@ export function permissionGrant(peer: string, mode: PermissionMode, instances?:
 export const PI_EDIT_TOOLS = new Set(["edit", "write"]);
 /** Native agent policy files are never included in scoped automatic file grants. */
 export const AGENT_CONFIG_SEGMENTS: ReadonlySet<string> = new Set([".claude", ".codex", ".qwen", ".kimi", ".kimi-code", ".jcode", ".pi", ".mcp.json", ".agents", ".agent", "_agents", "_agent", ".gemini", ".grok", ".claude.json"]);
-export const INSTRUCTION_FILES: ReadonlySet<string> = new Set(["agents.md", "claude.md", "qwen.md"]);
+export const INSTRUCTION_FILES: ReadonlySet<string> = new Set(["agents.md", "claude.md", "qwen.md", "gemini.md"]);
 export const isInstructionPath = (path: string): boolean => path.split(/[\\/]/).some(segment => INSTRUCTION_FILES.has(foldSegment(segment)));
 export function instructionProtection(value: unknown): boolean {
   if (value === undefined) return false;

package/src/hub/person-figures.ts

@@ -0,0 +1,88 @@
+import type { StampedEvent } from "./events.ts";
+
+/**
+ * #1278: what the person was asked and did, per task, from the four events that now carry the token attribution rule (`task`, `attribution`): `permission`, `question`, `completion` and `agent_cli`.
+ * One accumulator serves `ahub report --by task` and the research record, so the two cannot show different numbers. Ids, counts and recorded durations only: none of these events holds a
+ * prompt, an option, a command or an answer.
+ *
+ * - An interaction counts for a task only when its event names one (`attribution` of `delivery` or `single_open`). `unattributed` is counted apart and never folded into a task.
+ * - Unknown is null, never 0: a log with no attributed person event at all (written before this version, or by a hub that never saw one) says nothing about any task, so every figure is null.
+ * - Minutes: `latencyMs.sum` adds only recorded latencies of PERSON-answered permissions and questions (an answer with a `surface`: the console, the dashboard, the terminal, acon). A person
+ *   answer with no latency reading raises `n` and `unknown` and adds nothing to `sum`. An automatic answer, an expiry and a cancellation are counted but are not the person's minutes.
+ * - `consoleConfirmations` stays null: the hub records no event for a console confirmation (the confirm step is the console's own, and its approval arrives as the permission's `answered`).
+ * Ceiling: a person interaction in a vendor TUI the hub cannot see is not observed here at all.
+ */
+export interface PermissionFigures { asked: number; allowed: number; denied: number; expired: number }
+export interface QuestionFigures { asked: number; answered: number; expired: number }
+export interface LatencyFigures { sum: number; n: number; unknown: number }
+export interface PersonFigures {
+  permissions: PermissionFigures | null;
+  questions: QuestionFigures | null;
+  completions: number | null;
+  cliRefusals: number | null;
+  consoleConfirmations: null;
+  latencyMs: LatencyFigures | null;
+}
+export const UNKNOWN_PERSON_FIGURES: Readonly<PersonFigures> = Object.freeze({ permissions: null, questions: null, completions: null, cliRefusals: null, consoleConfirmations: null, latencyMs: null });
+
+export interface PersonCounts {
+  permissions: PermissionFigures; questions: QuestionFigures; completions: number; cliRefusals: number; latencyMs: LatencyFigures;
+}
+export const emptyPersonCounts = (): PersonCounts => ({ permissions: { asked: 0, allowed: 0, denied: 0, expired: 0 }, questions: { asked: 0, answered: 0, expired: 0 }, completions: 0, cliRefusals: 0, latencyMs: { sum: 0, n: 0, unknown: 0 } });
+
+/** The four event types this module reads. */
+export const PERSON_EVENT_TYPES = ["permission", "question", "completion", "agent_cli"] as const;
+export type PersonEvent = Extract<StampedEvent, { type: (typeof PERSON_EVENT_TYPES)[number] }>;
+export const isPersonEvent = (e: StampedEvent): e is PersonEvent => (PERSON_EVENT_TYPES as readonly string[]).includes(e.type);
+
+const ALLOW = new Set(["allow_once", "allow_always"]), DENY = new Set(["reject_once", "reject_always"]);
+const recorded = (ms: unknown): ms is number => typeof ms === "number" && Number.isFinite(ms) && ms >= 0;
+
+/** Add one person event to a group of counts. */
+export function addPersonEvent(into: PersonCounts, e: PersonEvent): void {
+  if (e.type === "permission") {
+    if (e.event === "requested") into.permissions.asked++;
+    else if (e.event === "expired") into.permissions.expired++;
+    else if (e.event === "answered") {
+      if (e.option && ALLOW.has(e.option)) into.permissions.allowed++; else if (e.option && DENY.has(e.option)) into.permissions.denied++;
+      if (e.surface !== undefined) minutes(into, e.latencyMs);
+    }
+  } else if (e.type === "question") {
+    if (e.event === "asked") into.questions.asked++;
+    else if (e.event === "expired") into.questions.expired++;
+    else if (e.event === "answered") { into.questions.answered++; if (e.surface !== undefined) minutes(into, e.latencyMs); }
+  } else if (e.type === "completion") into.completions++;
+  else if (e.type === "agent_cli" && e.refused) into.cliRefusals++;
+}
+function minutes(into: PersonCounts, latencyMs: unknown): void {
+  into.latencyMs.n++;
+  if (recorded(latencyMs)) into.latencyMs.sum += latencyMs; else into.latencyMs.unknown++;
+}
+
+/**
+ * The figures of one task, the ONE place that decides unknown against zero, for the research record and `ahub report --by task` alike (#1298 review: the two must not disagree).
+ * `covered`: the log is known to attribute person events for this task (see `personCoverage`). A covered task with no event of its own is a known zero, which is the real and best answer for a
+ * task nobody was asked about, so `counts` missing reads as empty; an uncovered task is unknown whatever its counts say, because the log cannot say what happened before attribution.
+ */
+export const personFigures = (counts: PersonCounts | undefined, covered: boolean): PersonFigures => {
+  if (!covered) return { ...UNKNOWN_PERSON_FIGURES };
+  const c = counts ?? emptyPersonCounts();
+  return { permissions: c.permissions, questions: c.questions, completions: c.completions, cliRefusals: c.cliRefusals, consoleConfirmations: null, latencyMs: c.latencyMs };
+};
+
+/**
+ * Whether a task is covered: it began (its proposal, else its first start) at or after the first `hub_start` that attributes person events. `since` is that start's time, or null when no
+ * such start is in the log; `began` is the task's own first time, or undefined/NaN when the log does not say.
+ */
+export const personCoverage = (since: number | null, began: number | undefined): boolean => since !== null && began !== undefined && Number.isFinite(began) && began >= since;
+
+/**
+ * Whether a `hub_start` says the run attributes person events (#1278). A task is covered by the log when it began at or after the first such start: from then on every person interaction of
+ * the task was written with the rule's answer, so no event means none happened, which is a known 0. Before it, the log cannot say, and the task's person block is unknown. The first
+ * person event is NOT the marker: a hub that upgraded and saw no interaction for days would otherwise report its first tasks as unknown instead of as the zero they are.
+ */
+export const startsAttribution = (e: StampedEvent): boolean => e.type === "hub_start" && e.personAttribution === true;
+
+/** The task an attributed event names, or undefined for an unattributed or pre-attribution one. */
+export const personTask = (e: PersonEvent): number | undefined =>
+  (e.attribution === "delivery" || e.attribution === "single_open") && typeof e.task === "number" && Number.isSafeInteger(e.task) && e.task > 0 ? e.task : undefined;

package/src/hub/report.ts

@@ -1,5 +1,6 @@
 import { definitionOf } from "../adapters/registry.ts";
 import type { StampedEvent } from "./events.ts";
+import { addPersonEvent, emptyPersonCounts, isPersonEvent, personCoverage, personFigures, personTask, startsAttribution, UNKNOWN_PERSON_FIGURES, type PersonCounts, type PersonFigures } from "./person-figures.ts";
 
 export interface Report {
   from?: string;
@@ -256,7 +257,9 @@ const usageCounts = ["inputRecords", "outputRecords", "cacheReadRecords", "cache
 type TaskUsage = Omit<UsageCoverage, typeof usageCounters[number]> & Record<typeof usageCounters[number], number | null>;
 export interface TaskPeerReport { tokens: number | null; usage: TaskUsage }
 export interface TaskTotals { turns: number; peers: Record<string, TaskPeerReport> }
-export interface TaskSummary extends TaskTotals { class: string | null; outcome: string | null; wallMs: number | null; pii?: true }
+export interface TaskSummary extends TaskTotals { class: string | null; outcome: string | null; wallMs: number | null; pii?: true;
+  /** #1278: the person's interactions with the task (`src/hub/person-figures.ts`), null parts when the log does not cover it. A PII task counts here without any text, as everywhere. */
+  person: PersonFigures }
 export interface TaskReport {
   from?: string;
   to?: string;
@@ -265,6 +268,8 @@ export interface TaskReport {
   totals: { tokens: number; usageRecords: number };
   unattributed: TaskTotals & { tokens: number; usageRecords: number; tokenShare: number | null; usageShare: number | null };
   beforeAttribution: TaskTotals & { tokens: number; usageRecords: number };
+  /** #1278: person events by peer, and the remainder no task owns. Both are counts over the whole slice; `unattributed` is never folded into a task. */
+  person: { byPeer: Record<string, PersonCounts>; unattributed: PersonCounts; beforeAttribution: PersonCounts };
 }
 
 const taskTotals = (): TaskTotals => ({ turns: 0, peers: {} });
@@ -288,19 +293,27 @@ function addTaskUsage(peer: TaskPeerReport, e: Extract<StampedEvent, { type: "us
 export function summarizeByTask(events: StampedEvent[]): TaskReport {
   const r: TaskReport = { tasks: {}, classes: {}, totals: { tokens: 0, usageRecords: 0 },
     unattributed: { ...taskTotals(), tokens: 0, usageRecords: 0, tokenShare: null, usageShare: null },
-    beforeAttribution: { ...taskTotals(), tokens: 0, usageRecords: 0 } };
-  const task = (id: number) => r.tasks[String(id)] ??= { ...taskTotals(), class: null, outcome: null, wallMs: null };
+    beforeAttribution: { ...taskTotals(), tokens: 0, usageRecords: 0 },
+    person: { byPeer: {}, unattributed: emptyPersonCounts(), beforeAttribution: emptyPersonCounts() } };
+  const counts = new Map<number, PersonCounts>();
+  // #1278: a task is covered when it began at or after the first hub run that attributes person events (the research record's rule too); earlier ones are unknown, never 0.
+  let reportingSince: number | null = null;
+  const proposedAt = new Map<number, number>();
+  const task = (id: number) => r.tasks[String(id)] ??= { ...taskTotals(), class: null, outcome: null, wallMs: null, person: { ...UNKNOWN_PERSON_FIGURES } };
   const starts = new Map<number, number>(), approvals = new Map<number, number>();
   const seenUsage = new Set<string>();
   // Resolve latest class/outcome before rolling usage up: usage may precede the task's history in a slice.
   for (const e of events) {
     r.from ??= e.at; r.to = e.at;
+    if (startsAttribution(e) && reportingSince === null) reportingSince = Date.parse(e.at);
     if (e.type !== "task") continue;
     const t = task(e.id);
     t.class = e.class; t.outcome = e.state;
     if (e.pii) t.pii = true;
     const at = Date.parse(e.at);
     if (!Number.isFinite(at)) continue;
+    // The record's rule for when a task began: its proposal (or the pull from the backlog), else its first start. A backlog card's earlier `backlogged` event does not count.
+    if ((e.event === "proposed" || e.event === "backlog pulled") && !proposedAt.has(e.id)) proposedAt.set(e.id, at);
     if (e.state === "in_progress" && !starts.has(e.id)) starts.set(e.id, at);
     if (e.state === "approved" && !approvals.has(e.id)) approvals.set(e.id, at);
   }
@@ -310,6 +323,16 @@ export function summarizeByTask(events: StampedEvent[]): TaskReport {
     r.classes[t.class ?? "unknown"] ??= taskTotals();
   }
   for (const e of events) {
+    if (isPersonEvent(e)) {
+      // The same accumulator as the research record, so `report --by task` and the record show the same numbers.
+      const owner = personTask(e);
+      const group = owner !== undefined ? counts.get(owner) ?? counts.set(owner, emptyPersonCounts()).get(owner)! : e.attribution === undefined ? r.person.beforeAttribution : r.person.unattributed;
+      addPersonEvent(group, e);
+      addPersonEvent(r.person.byPeer[e.peer] ??= emptyPersonCounts(), e);
+      if (owner !== undefined && e.pii) task(owner).pii = true;
+      if (owner !== undefined) task(owner);
+      continue;
+    }
     if (e.type !== "tokens" && e.type !== "usage" && e.type !== "turn_end") continue;
     if (e.type === "usage") {
       const key = `${e.peer}\0${e.source}\0${e.id}`;
@@ -338,11 +361,19 @@ export function summarizeByTask(events: StampedEvent[]): TaskReport {
       else addTaskUsage(p, e);
     }
   }
+  for (const [id, t] of Object.entries(r.tasks)) t.person = personFigures(counts.get(Number(id)), personCoverage(reportingSince, proposedAt.get(Number(id)) ?? starts.get(Number(id))));
   r.unattributed.tokenShare = r.totals.tokens ? r.unattributed.tokens / r.totals.tokens : null;
   r.unattributed.usageShare = r.totals.usageRecords ? r.unattributed.usageRecords / r.totals.usageRecords : null;
   return r;
 }
 
+/** One line of a person's interactions, `unknown` where the log does not cover them; counts and minutes only. */
+export function formatPerson(p: PersonFigures): string {
+  if (p.permissions === null || p.questions === null || p.latencyMs === null) return "person unknown";
+  const l = p.latencyMs, mins = l.n === 0 ? "none answered" : `${(l.sum / 60_000).toFixed(1)} min over ${l.n - l.unknown}/${l.n} recorded`;
+  return `person: permissions ${p.permissions.asked} asked (${p.permissions.allowed} allowed, ${p.permissions.denied} denied, ${p.permissions.expired} expired), questions ${p.questions.asked} asked (${p.questions.answered} answered, ${p.questions.expired} expired), completions ${p.completions ?? "unknown"}, CLI refusals ${p.cliRefusals ?? "unknown"}, ${mins}`;
+}
+
 export function formatTaskReport(r: TaskReport): string[] {
   const lines = [`period: ${r.from ?? "-"} .. ${r.to ?? "-"}`];
   const peers = (group: TaskTotals) => Object.entries(group.peers).sort(([a], [b]) => a.localeCompare(b)).map(([id, p]) => {
@@ -351,11 +382,14 @@ export function formatTaskReport(r: TaskReport): string[] {
     return `  peer ${id}: tokens ${p.tokens ?? "unknown"}; ${counts}`;
   });
   for (const [id, t] of Object.entries(r.tasks).sort(([a], [b]) => Number(a) - Number(b))) {
-    lines.push(`task #${id}${t.pii ? " [pii]" : ""}: class ${t.class ?? "unknown"}, outcome ${t.outcome ?? "unknown"}, turns ${t.turns}, wall ${t.wallMs === null ? "unknown" : `${t.wallMs} ms`}`, ...peers(t));
+    lines.push(`task #${id}${t.pii ? " [pii]" : ""}: class ${t.class ?? "unknown"}, outcome ${t.outcome ?? "unknown"}, turns ${t.turns}, wall ${t.wallMs === null ? "unknown" : `${t.wallMs} ms`}`, `  ${formatPerson(t.person)}`, ...peers(t));
   }
   for (const [name, group] of Object.entries(r.classes).sort(([a], [b]) => a.localeCompare(b))) lines.push(`class ${name}: turns ${group.turns}`, ...peers(group));
   const share = (value: number | null) => value === null ? "unknown" : `${(value * 100).toFixed(1)}%`;
   lines.push(`unattributed: tokens ${r.unattributed.tokens}/${r.totals.tokens} (${share(r.unattributed.tokenShare)}), usage records ${r.unattributed.usageRecords}/${r.totals.usageRecords} (${share(r.unattributed.usageShare)}), turns ${r.unattributed.turns}`, ...peers(r.unattributed));
+  const total = r.person.unattributed;
+  lines.push(`person unattributed: ${total.permissions.asked} permissions asked, ${total.questions.asked} questions asked, ${total.completions} completions, ${total.cliRefusals} CLI refusals, never counted for a task`);
+  for (const [id, p] of Object.entries(r.person.byPeer).sort(([a], [b]) => a.localeCompare(b))) lines.push(`person peer ${id}: ${p.permissions.asked} permissions asked, ${p.questions.asked} questions asked, ${p.completions} completions, ${p.cliRefusals} CLI refusals`);
   lines.push(`before attribution: tokens ${r.beforeAttribution.tokens}, usage records ${r.beforeAttribution.usageRecords}, turns ${r.beforeAttribution.turns}`, ...peers(r.beforeAttribution));
   return lines;
 }

package/src/hub/research-dataset.ts

@@ -0,0 +1,158 @@
+import { chmodSync, existsSync, lstatSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { familyOf as builtinFamilyOf } from "../adapters/registry.ts";
+import { VERSION } from "../version.ts";
+import { readEvents, type StampedEvent } from "./events.ts";
+import { readInstanceConfig } from "./instance-config.ts";
+import { hubHome, realPath } from "./project.ts";
+import { latestTaskRecords, projectKey, closedAtOf, readStore, researchFile, type LabelRecord, type PeerUsage, type ResearchRecord, type TaskRecord } from "./research.ts";
+import { buildResearchQuality, type QualityReport } from "./research-quality.ts";
+import type { Addon } from "./tooling.ts";
+
+/**
+ * #1277 (#44): the research dataset, a projection of the record store and the event log into three files per project (`tasks.jsonl`, `manifest.json`, `quality.json`). It is built to
+ * leave the machine, so it is an allowlist: a peer is only ever a family name (an instance id such as `codex-review` is a name the person chose), and the fields that carry a
+ * project-chosen name (profile, role, session roles) are dropped. The records are already text-free, so a task title, a path or an envelope body is not here to leak; the
+ * privacy test proves it on a canary fixture instead of trusting that.
+ */
+export const MANIFEST_SCHEMA = "agent-hub.research-dataset/v1";
+export const UNKNOWN_FAMILY = "unknown";
+
+export interface DatasetProject { id: string; root: string; stateDir: string }
+export interface DatasetInput {
+  project: DatasetProject;
+  records: readonly ResearchRecord[];
+  events: readonly StampedEvent[];
+  /** Instance ids resolve to a family only through the project's own config; the registry default knows the shipped adapters. */
+  familyOf?: (peer: string) => string | undefined;
+}
+export interface DatasetOptions { since?: number; now?: () => number; hubVersion?: string; /** The directory the target must be inside; the person's home unless a test says otherwise. */ home?: string }
+export interface DatasetManifest {
+  schema: typeof MANIFEST_SCHEMA; hubVersion: string; projectKeyHash: string;
+  window: { since: string | null; until: string };
+  /** Family names only, sorted; `unknown` stands for a peer no family is known for. */
+  peers: string[];
+  counts: { tasks: number; approved: number; cancelled: number; labels: number };
+  recordedAt: string;
+}
+export interface DatasetResult { projectKeyHash: string; dir: string; counts: DatasetManifest["counts"] }
+
+/** Why a target directory is refused, or undefined when it is allowed. Both sides are compared as real paths: a symlink out of the home or into the project does not pass. */
+export function refuseTarget(target: string, projects: readonly { root: string; stateDir: string }[], home = homedir()): string | undefined {
+  const absolute = resolve(target);
+  // The nearest existing ancestor decides: the directory itself may not exist yet.
+  let existing = absolute; const rest: string[] = [];
+  while (!existsSync(existing)) { const up = dirname(existing); if (up === existing) return `no part of ${target} exists`; rest.unshift(basename(existing)); existing = up; }
+  const real = join(realPath(existing), ...rest), realHome = realPath(home);
+  if (real !== realHome && !real.startsWith(realHome + sep)) return `the dataset directory must be inside your home directory (${realHome})`;
+  if (real === realHome) return "the dataset directory must be a directory of its own, not the home directory itself";
+  for (const p of projects) {
+    for (const dir of [p.root, p.stateDir]) {
+      let inside: string; try { inside = realPath(dir); } catch { inside = resolve(dir); }
+      if (real === inside || real.startsWith(inside + sep) || inside.startsWith(real + sep)) return `the dataset directory must be outside the project and its state directory (${inside})`;
+    }
+  }
+  return undefined;
+}
+
+const family = (peer: string, familyOf: (peer: string) => string | undefined): string => familyOf(peer) ?? builtinFamilyOf(peer) ?? UNKNOWN_FAMILY;
+const sumNullable = (a: number | null, b: number | null): number | null => a === null && b === null ? null : (a ?? 0) + (b ?? 0);
+
+/** One task record as it goes into the dataset: every peer id folded into its family, fields that carry project-chosen names dropped. */
+export function datasetTask(r: TaskRecord, familyOf: (peer: string) => string | undefined): TaskRecord {
+  const fam = (peer: string) => family(peer, familyOf);
+  const { profile: _p, profileClass: _pc, role: _r, roleIdentity: _ri, sessionRoles: _sr, peers, tooling, ...rest } = r;
+  const byPeer: Record<string, number> = {};
+  for (const [peer, n] of Object.entries(r.tokens.byPeer)) byPeer[fam(peer)] = (byPeer[fam(peer)] ?? 0) + n;
+  const usage: Record<string, PeerUsage> = {};
+  for (const [peer, u] of Object.entries(r.usage)) {
+    const key = fam(peer), held = usage[key];
+    usage[key] = held ? { input: sumNullable(held.input, u.input), output: sumNullable(held.output, u.output), cacheRead: sumNullable(held.cacheRead, u.cacheRead), total: sumNullable(held.total, u.total) } : { ...u };
+  }
+  const out: TaskRecord = { ...rest, owners: r.owners.map(fam), reviewer: r.reviewer === null ? null : fam(r.reviewer), tokens: { ...r.tokens, byPeer: sortKeys(byPeer) }, usage: sortKeys(usage) };
+  if (peers) out.peers = [...new Set(peers.map(fam))].sort();
+  if (tooling) {
+    const byFamily: Record<string, Addon[]> = {};
+    // A family with two peers that had different add-ons reads as the union: the dataset only says which add-ons were around.
+    for (const [peer, addons] of Object.entries(tooling)) { const key = fam(peer), held = byFamily[key] ??= []; for (const a of addons) if (!held.some(h => h.name === a.name)) held.push(a); }
+    out.tooling = sortKeys(byFamily);
+  }
+  return out;
+}
+const sortKeys = <T>(o: Record<string, T>): Record<string, T> => Object.fromEntries(Object.entries(o).sort(([a], [b]) => a.localeCompare(b)));
+
+const datasetLabel = (l: LabelRecord, familyOf: (peer: string) => string | undefined): LabelRecord => l.by === undefined ? l : { ...l, by: family(l.by, familyOf) };
+
+/** Build one project's three files in memory; nothing is written. */
+export function buildDataset(input: DatasetInput, options: DatasetOptions = {}): { tasks: string; manifest: DatasetManifest; quality: QualityReport } {
+  const now = (options.now ?? Date.now)(), since = options.since ?? 0, familyOf = input.familyOf ?? (() => undefined);
+  const fam = (peer: string) => family(peer, familyOf);
+  const tasks = latestTaskRecords(input.records).filter(r => Date.parse(closedAtOf(r) ?? "") >= since);
+  const keep = new Set(tasks.map(r => `${r.task}\n${r.createdAt}`));
+  const labels = input.records.filter((r): r is LabelRecord => r.kind === "label" && keep.has(`${r.task}\n${r.createdAt}`));
+  const rows = [...tasks.map(r => datasetTask(r, familyOf)), ...labels.map(l => datasetLabel(l, familyOf))];
+  const peers = new Set<string>();
+  for (const r of tasks) { for (const o of r.owners) peers.add(fam(o)); if (r.reviewer) peers.add(fam(r.reviewer)); for (const p of r.peers ?? []) peers.add(fam(p)); for (const p of Object.keys(r.tokens.byPeer)) peers.add(fam(p)); }
+  const quality = buildResearchQuality(input.records, input.events, { ...(since > 0 ? { since } : {}), until: now }, familyOf);
+  return {
+    tasks: rows.map(r => JSON.stringify(r)).join("\n") + (rows.length ? "\n" : ""),
+    manifest: {
+      schema: MANIFEST_SCHEMA, hubVersion: options.hubVersion ?? VERSION, projectKeyHash: projectKey(input.project.id),
+      window: { since: since > 0 ? new Date(since).toISOString() : null, until: new Date(now).toISOString() }, peers: [...peers].sort(),
+      counts: { tasks: tasks.length, approved: tasks.filter(r => r.outcome === "approved").length, cancelled: tasks.filter(r => r.outcome === "cancelled").length, labels: labels.length },
+      recordedAt: new Date(now).toISOString(),
+    },
+    quality,
+  };
+}
+
+/** A file written whole: a temp file in the same directory, then a rename, so a reader never sees half of it. Owner-only. */
+function writeWhole(file: string, text: string): void {
+  const temp = `${file}.${process.pid}.tmp`;
+  writeFileSync(temp, text, { mode: 0o600 });
+  chmodSync(temp, 0o600);
+  renameSync(temp, file);
+}
+
+/**
+ * Write each project's dataset under `<target>/<projectKeyHash>/`. The target is checked against every given project (the ones that will be exported and the one the command ran in), not
+ * only the one being written. A project directory that is a symlink is refused: it could point anywhere the check did not look.
+ */
+export function exportResearchDataset(target: string, inputs: readonly DatasetInput[], options: DatasetOptions = {}, guard: readonly { root: string; stateDir: string }[] = inputs.map(i => i.project)): DatasetResult[] {
+  const refusal = refuseTarget(target, guard, options.home);
+  if (refusal) throw new Error(refusal);
+  mkdirSync(target, { recursive: true, mode: 0o700 });
+  const results: DatasetResult[] = [];
+  for (const input of inputs) {
+    const built = buildDataset(input, options), key = built.manifest.projectKeyHash, dir = join(target, key);
+    if (existsSync(dir) && lstatSync(dir).isSymbolicLink()) throw new Error(`${dir} is a symbolic link; remove it first`);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+    writeWhole(join(dir, "tasks.jsonl"), built.tasks);
+    writeWhole(join(dir, "quality.json"), JSON.stringify(built.quality, null, 2) + "\n");
+    // The manifest goes last: a directory with a manifest is a complete one.
+    writeWhole(join(dir, "manifest.json"), JSON.stringify(built.manifest, null, 2) + "\n");
+    results.push({ projectKeyHash: key, dir, counts: built.manifest.counts });
+  }
+  return results;
+}
+
+/** The family of a peer id through the project's own config (instances resolve there); undefined when the config cannot be read, then only the shipped adapters' families apply. */
+export function projectFamilyOf(root: string): ((peer: string) => string | undefined) | undefined {
+  try {
+    const config = readInstanceConfig(root);
+    return peer => config.catalog.familyOf(peer, config.instances);
+  } catch { return undefined; }
+}
+
+/**
+ * One registered project's records, events and family lookup, read-only. Instance ids resolve through that project's own config (`readInstanceConfig`); a config that cannot be read leaves
+ * the shipped adapters' families, and an id neither knows is `unknown`, never guessed from its spelling. Undefined when the project has no record file: it was never researched.
+ */
+export function datasetInputFor(project: DatasetProject, home = hubHome()): DatasetInput | undefined {
+  const file = researchFile(project.id, home);
+  if (!existsSync(file)) return undefined;
+  const familyOf = projectFamilyOf(project.root);
+  return { project, records: readStore(file), events: readEvents(join(project.stateDir, "events.jsonl")), ...(familyOf ? { familyOf } : {}) };
+}