@staix/agent-hub 0.12.22 → 0.12.24

package/src/hub/research.ts

@@ -1,8 +1,10 @@
 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 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";
 
 /**
  * #247: opt-in research records of how tasks went, built only from `events.jsonl` (ids, states, counts, tokens), so the
@@ -18,6 +20,11 @@ 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;
+  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";
   /** 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;
@@ -44,6 +51,12 @@ export interface TaskRecord {
   /** Model routes and served models seen for the task's attributed requests. */
   models: string[];
   writer: { version: string; source: "live" | "backfill" };
+  /** #248: the add-ons each peer that worked on the task had at its latest attach; a peer missing here is unknown. */
+  tooling?: Record<string, Addon[]>;
+  /** #248, with `tooling`: every peer with an event attributed to the task, fingerprinted or not. */
+  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 };
 }
 /** 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 }
@@ -56,15 +69,15 @@ export const researchFile = (projectId: string, home = hubHome()): string => joi
 /** 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;
+type Acc = Omit<TaskRecord, "schema" | "kind" | "project" | "approvedAt" | "wallMs" | "firstPass" | "outcome" | "writer" | "models" | "tooling" | "peers" | "briefs"> & {
+  models: Set<string>; approvedAt: string | null; lastState: string | null; tooling: Record<string, Addon[]>; peers: Map<string, number>; briefs: { delivered: number; withFail: number };
 };
 /** 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 });
+  approvedAt: null, lastState: null, tooling: keyed(), peers: new Map(), briefs: { delivered: 0, withFail: 0 } });
 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; };
 
@@ -77,18 +90,51 @@ export function taskRecords(events: StampedEvent[], projectId: string, writer: T
   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>();
+  // 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>();
+  const tooling = new Map<string, { attach: number; addons: Addon[] }>();
+  /** A peer that worked on the task carries the fingerprint of the attachment it worked in. */
+  /**
+   * `acted`: the peer did something for the task (an attributed turn, tokens, the actor of a board move). A peer only
+   * named on a move (the owner or reviewer an approval lists) joins the task once and never moves to a later
+   * attachment, where it did no work.
+   */
+  const involve = (a: Acc, peer: string | null | undefined, acted = true) => {
+    if (!peer || peer === "hub" || peer === "user" || (!acted && a.peers.has(peer))) return;
+    const now = attach.get(peer) ?? 0, f = tooling.get(peer);
+    a.peers.set(peer, now);
+    if (f?.attach === now) a.tooling[peer] = f.addons;
+    else delete a.tooling[peer]; // a fingerprint of an earlier attachment does not describe this work: unknown until one comes
+  };
   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 === "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); }
+      continue;
+    }
+    if (e.type === "tooling") {
+      const now = attach.get(e.peer) ?? 0;
+      tooling.set(e.peer, { attach: now, addons: e.addons });
+      for (const a of tasks.values()) if (a.peers.get(e.peer) === now) a.tooling[e.peer] = e.addons;
+      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.
-      if (e.event === "proposed" && tasks.get(e.id)?.createdAt) { earlier.push(tasks.get(e.id)!); tasks.delete(e.id); }
+      if ((e.event === "proposed" && tasks.has(e.id)) || (e.event === "backlogged" && tasks.has(e.id))) { 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;
+      for (const field of ["release", "priority", "plannedStart", "due"] as const) if (Object.hasOwn(e, field)) a[field] = e[field];
+      a.class = e.class; if (e.role && a.role === undefined) { a.role = e.role; if (e.event === "proposed" && e.roleIdentity) a.roleIdentity = e.roleIdentity; } if (e.profile) { a.profile = e.profile; a.profileClass = e.profileClass; } if (e.pii) a.pii = true;
+      if (proposed && e.role === a.role && e.roleIdentity && a.roleIdentity === undefined) a.roleIdentity = e.roleIdentity;
       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 (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++;
@@ -97,14 +143,19 @@ export function taskRecords(events: StampedEvent[], projectId: string, writer: T
       if (e.state === "changes_requested" && a.lastState !== "changes_requested") a.changesRequested++;
       if (e.state === "approved") a.approvedAt ??= e.at;
       a.lastState = e.state;
+      involve(a, e.by); involve(a, e.owner, false); involve(a, e.reviewer, false);
       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 ("peer" in e && typeof e.peer === "string") involve(a, e.peer);
     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 === "turn_end") {
+      a.turns++; a.activeMs += e.ms; a.filesChanged += e.files ?? 0;
+      if (e.preparedRoles !== undefined) (a.sessionRoles ??= []).push({ peer: e.peer, turn: e.turn, roles: e.preparedRoles?.map(role => ({ id: role.id, layer: role.layer, hash: role.hash })) ?? null });
+    }
     else if (e.type === "usage") {
       const key = `${e.peer}\0${e.source}\0${e.id}`;
       if (seenUsage.has(key)) continue;
@@ -117,6 +168,7 @@ 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 === "stuck") a.stuck++;
     else if (e.type === "overlap") a.overlaps++;
     else if (e.type === "conflict") a.conflicts++;
@@ -124,11 +176,12 @@ export function taskRecords(events: StampedEvent[], projectId: string, writer: T
   const out: TaskRecord[] = [];
   for (const a of [...earlier, ...tasks.values()]) {
     if (!a.approvedAt) continue;
-    const { approvedAt, lastState: _state, models, ...rest } = a;
+    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,
       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 });
+      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 } : {}) });
   }
   return out.sort((x, y) => x.approvedAt.localeCompare(y.approvedAt) || x.task - y.task);
 }
@@ -175,7 +228,11 @@ export function labelTarget(records: ResearchRecord[], events: StampedEvent[], t
   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);
+  const creation = events.findLast(e => e.type === "task" && e.id === task && ["proposed", "backlogged"].includes(e.event));
+  const proposed = creation?.type === "task" && creation.event === "backlogged"
+    ? events.slice(events.indexOf(creation) + 1).find(e => e.type === "task" && e.id === task && e.event === "backlog pulled")
+    : creation;
+  if (creation?.type === "task" && creation.event === "backlogged" && !proposed) fail(`task #${task} is backlog and has no execution proposal; name an earlier record with --created`);
   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 ")}` : ""}`);
@@ -207,19 +264,15 @@ function measures(records: TaskRecord[], labels: Map<string, Label>): Measures {
     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> }
+export interface ResearchReport { overall: Measures; byClass: Record<string, Measures>; byOwner: Record<string, Measures>; byProject: Record<string, Measures>; byModel: Record<string, Measures>;
+  /** #258 AC11: tasks whose brief carried a hub-memory fail note, a brief without one, or no brief recorded. */
+  byMemoryBrief: 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 { all, labels } = latestRecords(records, since);
   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[]>();
@@ -227,7 +280,8 @@ export function researchReport(records: ResearchRecord[], since = 0): ResearchRe
     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"]) };
+    byProject: group((r) => [r.project]), byModel: group((r) => r.models.length ? r.models : ["unknown"]),
+    byMemoryBrief: group((r) => [!r.briefs ? "no brief recorded" : r.briefs.withFail ? "a fail note in its brief" : "brief without a fail note"]) };
 }
 
 const fmtPct = (v: number | null) => v === null ? "-" : `${Math.round(v * 100)}%`;
@@ -236,7 +290,76 @@ 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)];
+  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), ...(Object.keys(r.byMemoryBrief).some((k) => k !== "no brief recorded") ? section("by memory brief", r.byMemoryBrief) : [])];
+}
+
+/** Each approved task once, its last record, and every task's latest label: what both reports count. */
+function latestRecords(records: ResearchRecord[], since: number): { all: TaskRecord[]; labels: Map<string, Label> } {
+  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);
+  }
+  return { all: [...latest.values()], labels };
+}
+
+/** The peers that worked on a task: every peer with an attributed event, else (older records) owners, reviewer and token peers. */
+const involved = (r: TaskRecord): string[] => [...new Set([...(r.peers ?? []), ...r.owners, ...(r.reviewer ? [r.reviewer] : []), ...Object.keys(r.tokens.byPeer)])].filter((p) => p !== "user");
+/** Own properties only: a peer may be named `constructor`, and a parsed record's object would answer with an inherited one. */
+const fingerprintOf = (r: TaskRecord, peer: string): Addon[] | undefined => r.tooling && Object.hasOwn(r.tooling, peer) ? r.tooling[peer] : undefined;
+
+type AddonMeasure = "successRate" | "firstPassRate" | "reworkRate" | "checkFailureRate" | "tokensMedian" | "wallMsMedian" | "collisionRate";
+const ADDON_MEASURES: AddonMeasure[] = ["successRate", "firstPassRate", "reworkRate", "checkFailureRate", "tokensMedian", "wallMsMedian", "collisionRate"];
+/** Every add-on measure of one set of tasks, computed once (a bootstrap calls this per resample). */
+function addonValues(rs: TaskRecord[], labels: Map<string, Label>): Record<AddonMeasure, number | null> {
+  const x = measures(rs, labels);
+  return { successRate: x.successRate, firstPassRate: x.firstPassRate, reworkRate: x.reworkRate, checkFailureRate: x.checkFailureRate,
+    tokensMedian: x.tokensPerTask.median, wallMsMedian: x.wallMsPerTask.median, collisionRate: pct(rs.reduce((n, r) => n + r.overlaps + r.conflicts, 0), rs.length) };
+}
+export interface AddonComparison {
+  addon: AddonName;
+  /** Tasks where a peer that worked on it had the add-on, where every such peer is known not to, and the rest. */
+  on: number; off: number; unknown: number;
+  measures: { measure: AddonMeasure; on: number | null; off: number | null; diff: number | null; low: number | null; high: number | null; inconclusive: boolean }[];
+}
+/**
+ * #248, observational: approved tasks with each add-on on against those with it off, by the tooling fingerprint each
+ * record carries. The difference is on minus off with a 95% bootstrap interval (seeded, so the same records give the
+ * same interval); below MIN_ATTEMPTS tasks on either side it is inconclusive. Field data shows association only: the
+ * peers, task mix and time differ between the sides. The causal side is `ahub bench` arms (docs/bench.md).
+ */
+export function addonReport(records: ResearchRecord[], since = 0, resamples = 1000, seed = 248): AddonComparison[] {
+  const { all, labels } = latestRecords(records, since);
+  return ADDONS.map((addon) => {
+    const side = { on: [] as TaskRecord[], off: [] as TaskRecord[], unknown: [] as TaskRecord[] };
+    for (const r of all) side[addonState(addon, involved(r).map((p) => fingerprintOf(r, p)))].push(r);
+    const random = mulberry32(seed);
+    const pick = (xs: TaskRecord[]) => Array.from({ length: xs.length }, () => xs[Math.floor(random() * xs.length)]!);
+    const samples = new Map<AddonMeasure, number[]>(ADDON_MEASURES.map((m) => [m, []]));
+    if (side.on.length && side.off.length) for (let i = 0; i < resamples; i++) {
+      const a = addonValues(pick(side.on), labels), b = addonValues(pick(side.off), labels);
+      for (const m of ADDON_MEASURES) { const x = a[m], y = b[m]; if (x !== null && y !== null) samples.get(m)!.push(x - y); }
+    }
+    const onValues = addonValues(side.on, labels), offValues = addonValues(side.off, labels);
+    return { addon, on: side.on.length, off: side.off.length, unknown: side.unknown.length, measures: ADDON_MEASURES.map((measure) => {
+      const on = onValues[measure], off = offValues[measure];
+      const s = samples.get(measure)!.sort((x, y) => x - y);
+      const rank = (q: number) => s[Math.min(s.length - 1, Math.max(0, Math.ceil(q * s.length) - 1))]!;
+      const diff = on !== null && off !== null ? on - off : null;
+      return { measure, on, off, diff, low: s.length ? rank(0.025) : null, high: s.length ? rank(0.975) : null,
+        inconclusive: diff === null || side.on.length < MIN_ATTEMPTS || side.off.length < MIN_ATTEMPTS };
+    }) };
+  });
+}
+export function formatAddons(rows: AddonComparison[]): string[] {
+  const fmt = (m: AddonMeasure, v: number | null) => v === null ? "-" : m === "tokensMedian" ? String(Math.round(v)) : m === "wallMsMedian" ? `${Math.round(v / 60_000)}m` : m === "reworkRate" || m === "collisionRate" ? v.toFixed(2) : `${Math.round(v * 100)}%`;
+  const out = ["add-on tasks with it on / off / unknown; on minus off with a 95% bootstrap interval (association, not cause)"];
+  for (const r of rows) {
+    out.push("", `${r.addon}: ${r.on} on, ${r.off} off, ${r.unknown} unknown`);
+    for (const m of r.measures) out.push(`  ${m.measure.padEnd(16)} on ${fmt(m.measure, m.on).padStart(6)}  off ${fmt(m.measure, m.off).padStart(6)}  diff ${fmt(m.measure, m.diff).padStart(6)} (${fmt(m.measure, m.low)} to ${fmt(m.measure, m.high)})${m.inconclusive ? `  inconclusive (fewer than ${MIN_ATTEMPTS} tasks on a side)` : ""}`);
+  }
+  return out;
 }
 
 export const CSV_COLUMNS = ["project", "task", "class", "pii", "outcome", "createdAt", "startedAt", "approvedAt", "wallMs", "activeMs", "owners",

package/src/hub/roles.ts

@@ -0,0 +1,123 @@
+import { createHash } from "node:crypto";
+import { constants, closeSync, fstatSync, lstatSync, openSync, readSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { sanitize } from "./envelope.ts";
+import { SHIPPED_ROLES } from "./shipped-roles.ts";
+
+export const ROLE_SECTIONS = ["Scope", "Not in scope", "Deliverables", "Hub use", "Review duties", "Evidence"] as const;
+const BASES = ["planner", "implementer", "verifier", "reviewer"];
+const CLASSES = ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"];
+const ID = /^[a-z][a-z0-9-]{0,47}$/;
+const PEER = /^[a-z][a-z0-9-]{0,31}$/;
+export interface CatalogRole {
+  id: string; name: string; group: string; summary: string; base: string[]; classes: string[]; source: string;
+  body: string; review: string; layer: "shipped" | "project"; hash: string;
+}
+export interface RoleCatalog { roles: Map<string, CatalogRole>; errors: { id: string; reason: string }[] }
+/** Flat headers are data, never YAML execution or authority configuration. */
+export function parseRole(text: string, stem: string, layer: CatalogRole["layer"]): CatalogRole {
+  if (Buffer.byteLength(text) > 8192 || text.includes("\r") || !ID.test(stem)) throw new Error("invalid role size, encoding or file id");
+  const match = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(text);
+  if (!match) throw new Error("expected a flat header and body");
+  const header: Record<string, string> = Object.create(null);
+  const keys = ["id", "name", "group", "summary", "base", "classes", "source"];
+  for (const line of match[1]!.split("\n")) {
+    const field = /^([a-z]+): (.+)$/.exec(line);
+    if (!field || !keys.includes(field[1]!) || header[field[1]!] !== undefined || /[\x00-\x1f\x7f]/.test(field[2]!)) throw new Error("invalid or duplicate header field");
+    header[field[1]!] = field[2]!;
+  }
+  if (keys.some(key => !header[key]) || header.id !== stem || !ID.test(header.group!) || header.name!.length > 80 || header.summary!.length > 160 || header.source!.length > 300) throw new Error("invalid header identity or limits");
+  const list = (key: string, allowed: string[]) => {
+    const values = header[key]!.split(",").map(v => v.trim());
+    if (!values.length || new Set(values).size !== values.length || values.some(v => !allowed.includes(v))) throw new Error(`invalid ${key}`);
+    return values;
+  };
+  const body = match[2]!.trimEnd();
+  if (!body || sanitize(body).length > 2000 || /```|~~~|^\t|^ {4}|^(?:\$\s|(?:bun|npm|npx|git|ssh|curl|wget|rm|bash|sh|python[0-9.]*)\s)/m.test(body)) throw new Error("invalid body size or command/code block");
+  for (const char of text) if ((char.codePointAt(0)! > 127 && /[\p{P}\p{S}\p{Z}\p{C}]/u.test(char)) || /[\x00-\x08\x0b-\x1f\x7f]/.test(char)) throw new Error("use plain ASCII punctuation and no controls/emoji");
+  const headings = [...body.matchAll(/^#{1,6} (.+)$/gm)];
+  if (headings.length !== ROLE_SECTIONS.length || headings.some(h => !h[0].startsWith("## "))) throw new Error("unexpected role heading or personality section");
+  const sections = [...body.matchAll(/^## (.+)$/gm)];
+  if (sections.length !== ROLE_SECTIONS.length || sections.some((s, i) => s[1] !== ROLE_SECTIONS[i])) throw new Error("expected the six ordered role sections");
+  for (let i = 0; i < sections.length; i++) {
+    const start = sections[i]!.index! + sections[i]![0].length;
+    const end = sections[i + 1]?.index ?? body.length;
+    if (!body.slice(start, end).trim()) throw new Error("empty role section");
+  }
+  const reviewStart = sections[4]!.index! + sections[4]![0].length;
+  const review = body.slice(reviewStart, sections[5]!.index).trim();
+  return { id: stem, name: header.name!, group: header.group!, summary: header.summary!, source: header.source!, base: list("base", BASES), classes: list("classes", CLASSES), body, review, layer, hash: createHash("sha256").update(text).digest("hex") };
+}
+function projectRole(file: string): string {
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const before = fstatSync(fd);
+    if (!before.isFile() || before.nlink !== 1 || before.size > 8192) throw new Error("role must be a bounded regular file");
+    const bytes = Buffer.alloc(8193); let length = 0, n = 0;
+    while ((n = readSync(fd, bytes, length, bytes.length - length, null)) > 0) { length += n; if (length > 8192) throw new Error("role exceeds file cap"); }
+    const after = fstatSync(fd);
+    if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || length !== after.size) throw new Error("role changed during read");
+    return bytes.subarray(0, length).toString("utf8");
+  } finally { closeSync(fd); }
+}
+export function loadRoleCatalog(cwd?: string): RoleCatalog {
+  const roles = new Map<string, CatalogRole>(), errors: RoleCatalog["errors"] = [];
+  for (const [id, text] of Object.entries(SHIPPED_ROLES)) {
+    try { roles.set(id, parseRole(text, id, "shipped")); } catch { errors.push({ id, reason: "invalid shipped role" }); }
+  }
+  if (!cwd) return { roles, errors };
+  try {
+    const config = join(cwd, ".agenthub"), dir = join(config, "roles");
+    for (const path of [config, dir]) { const stat = lstatSync(path); if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("unsafe role directory"); }
+    // ponytail: 64 flat project files, no recursive scan; explicit catalog index before larger collections.
+    const files = readdirSync(dir).filter(name => name.endsWith(".md")).sort();
+    if (files.length > 64) throw new Error("too many project roles");
+    for (const file of files) {
+      const id = file.slice(0, -3);
+      try { roles.set(id, parseRole(projectRole(join(dir, file)), id, "project")); }
+      catch { errors.push({ id: ID.test(id) ? id : "invalid-file-id", reason: "invalid or unsafe project role" }); }
+    }
+  } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") errors.push({ id: "project", reason: "project role directory unavailable or unsafe" }); }
+  return { roles, errors };
+}
+export function catalogAssignments(raw: unknown): Record<string, string[]> {
+  if (raw === undefined) return {};
+  if (!raw || typeof raw !== "object" || Array.isArray(raw) || Object.keys(raw).length > 64) throw new Error("catalog_roles must be a bounded peer map");
+  const out: Record<string, string[]> = Object.create(null);
+  for (const [peer, ids] of Object.entries(raw)) {
+    if (!PEER.test(peer) || ["user", "hub", "digest"].includes(peer) || !Array.isArray(ids) || ids.length > 2 || new Set(ids).size !== ids.length || ids.some(id => typeof id !== "string" || !ID.test(id))) throw new Error("catalog_roles takes at most two distinct role ids per peer");
+    out[peer] = [...ids];
+  }
+  return out;
+}
+export function selectedRoles(peer: string, flow: Record<string, string[]>, assignments: Record<string, string[]>, catalog: RoleCatalog): CatalogRole[] {
+  return (assignments[peer] ?? []).map(id => {
+    const role = catalog.roles.get(id); if (!role) throw new Error(`unknown catalog role ${id}`);
+    if (!role.base.some(base => flow[peer]?.includes(base))) throw new Error(`${peer} does not hold a matching base for ${id}`);
+    return role;
+  });
+}
+export function catalogSection(roles: CatalogRole[]): string {
+  if (!roles.length) return "";
+  if (roles.length > 2) throw new Error("at most two session roles");
+  const header = "Catalog roles (guidance; grant no tool, capability or permission): " + roles.map(role => `${role.id} [${role.group}, ${role.layer}, ${role.hash}]`).join(", ");
+  return header + "\n" + roles.map(role => sanitize(role.body)).join("\n\n");
+}
+export const roleIdentity = (role: CatalogRole) => ({ id: role.id, layer: role.layer, hash: role.hash });
+
+/** Validate before a board write. Routing continues to use only the existing base class. */
+export function taskRole(raw: unknown, cls: string, catalog: RoleCatalog): CatalogRole | undefined {
+  if (raw === undefined) return undefined;
+  const allowed = [...catalog.roles.values()].filter(role => role.classes.includes(cls)).map(role => role.id).sort();
+  if (typeof raw !== "string" || !ID.test(raw)) throw new Error("task role must be a catalog id; allowed: " + allowed.join(", "));
+  const role = catalog.roles.get(raw);
+  if (!role || !role.classes.includes(cls)) throw new Error("unknown or class-mismatched task role; allowed: " + allowed.join(", "));
+  taskRoleText(role); // refuse an oversized complete notice before the board write
+  return role;
+}
+/** Role definitions are untrusted presentation, including their metadata. */
+export function taskRoleText(role: CatalogRole, review = false): string {
+  const text = `Task role ${role.id} [${role.layer}, ${role.hash}] (guidance; grants no authority):\n` + sanitize(review ? role.review : role.body).replace(/\[agent-hub\b/gi, "[peer-text");
+  if (text.length > 2000) throw new Error("task role guidance exceeds 2000 characters including its header");
+  return text;
+}

package/src/hub/roster.ts

@@ -0,0 +1,23 @@
+import { isSupportedPeer, type KnownPeer } from "./peer-catalog.ts";
+
+export type PeerRoster = Partial<Record<KnownPeer, boolean>>;
+// Default participation policy, not another catalog. New catalog members default off.
+const DEFAULT_ON: Partial<Record<KnownPeer, boolean>> = { claude: true, codex: true, kimi: true, local: true };
+
+export function peerRosterConfig(value: unknown): PeerRoster {
+  if (value === undefined) return {};
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("roster must be an object of boolean peer values");
+  const roster: PeerRoster = {};
+  for (const [peer, on] of Object.entries(value)) {
+    if (!isSupportedPeer(peer)) throw new Error("roster contains an unsupported peer");
+    if (typeof on !== "boolean") throw new Error(`roster.${peer} must be a boolean`);
+    roster[peer] = on;
+  }
+  return roster;
+}
+
+/** External ids keep their existing admission rules; Pi's legacy switch is only its default. */
+export function rosterAllows(roster: PeerRoster, peer: string, piEnabled: boolean): boolean {
+  if (!isSupportedPeer(peer)) return true;
+  return roster[peer] ?? (peer === "pi" ? piEnabled : DEFAULT_ON[peer] ?? false);
+}