@staix/agent-hub 0.12.44 → 0.13.0

package/src/hub/dogfood-read.ts

@@ -0,0 +1,199 @@
+import { closeSync, constants, fstatSync, openSync, readSync } from "node:fs";
+import { join } from "node:path";
+import { Database } from "bun:sqlite";
+import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
+import { readPrCostHistory, sdlcGh, type SdlcGh } from "./sdlc.ts";
+import { dogfoodScorecard, missing, source, type DogfoodTask, type DogfoodPr, type FeatureEvidence, type Source } from "./dogfood.ts";
+import type { HistoryEntry } from "./board.ts";
+import type { StampedEvent } from "./events.ts";
+
+export const DOGFOOD_BYTE_CAP = 16 * 1024 * 1024;
+const MAX_TASKS = 500, MAX_PRS = 16, MAX_CI_HEADS = 8, MAX_CI_READS = 32;
+const date = (value: unknown): number | undefined => typeof value === "string" && Number.isFinite(Date.parse(value)) ? Date.parse(value) : undefined;
+const id = (value: unknown): value is number => Number.isSafeInteger(value) && (value as number) > 0;
+const repoName = (value: unknown): value is string => typeof value === "string" && /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(value) && !value.startsWith("-");
+
+/** Read at most cap bytes; keep complete lines from the tail, never follow a FIFO or grow with an appender. */
+export function dogfoodLines(file: string, cap = DOGFOOD_BYTE_CAP): Source<string[]> {
+  let fd: number | undefined;
+  try {
+    if (!Number.isSafeInteger(cap) || cap < 1 || cap > DOGFOOD_BYTE_CAP) return missing([]);
+    fd = openSync(file, constants.O_RDONLY | constants.O_NONBLOCK);
+    const stat = fstatSync(fd);
+    if (!stat.isFile()) return missing([]);
+    const start = Math.max(0, stat.size - cap), bytes = Buffer.alloc(Math.min(cap, stat.size));
+    const n = readSync(fd, bytes, 0, bytes.length, start);
+    let text = bytes.subarray(0,n).toString("utf8");
+    if (start) { const newline = text.indexOf("\n"); text = newline < 0 ? "" : text.slice(newline + 1); }
+    const whole = text.endsWith("\n") || !text;
+    if (!whole) text = text.slice(0,Math.max(0,text.lastIndexOf("\n") + 1));
+    return source(text.split("\n").filter(Boolean), !start && n === stat.size && whole);
+  } catch { return missing([]); }
+  finally { if (fd !== undefined) closeSync(fd); }
+}
+export function dogfoodEvents(lines: Source<string[]>, since: number, until: number): Source<StampedEvent[]> {
+  const out: StampedEvent[] = []; let complete = lines.complete;
+  for (const line of lines.data) {
+    try {
+      const e = JSON.parse(line);
+      if (!e || typeof e !== "object" || e.v !== 1 || typeof e.type !== "string" || date(e.at) === undefined) { complete = false; continue; }
+      const number = (n:unknown) => typeof n === "number" && Number.isFinite(n) && n >= 0;
+      const peer = typeof e.peer === "string" && /^[a-z][a-z0-9-]{0,63}$/.test(e.peer) && !Object.hasOwn(Object.prototype,e.peer);
+      const malformed = ["tokens","usage","turn_end","task","overflow","undeliverable"].includes(e.type) &&
+        (e.type === "task" ? !id(e.id) || typeof e.class !== "string" || typeof e.event !== "string" || typeof e.state !== "string" : !peer ||
+          e.type === "tokens" && !number(e.n) || e.type === "turn_end" && !number(e.ms) ||
+          e.type === "usage" && (typeof e.id !== "string" || typeof e.source !== "string") ||
+          ["overflow","undeliverable"].includes(e.type) && typeof e.id !== "string");
+      if (malformed) {complete=false;continue;}
+      const at = e.type === "usage" && date(e.measuredAt) !== undefined ? date(e.measuredAt)! : date(e.at)!;
+      if (at >= since && at <= until) out.push({ ...e, at: new Date(at).toISOString() });
+    } catch { complete = false; }
+  }
+  return { data: out, available: lines.available, complete };
+}
+/** Bounded read-only board snapshot. Select no task title/detail or history note into the result. */
+export function dogfoodTasks(file: string): Source<DogfoodTask[]> {
+  let db: Database | undefined;
+  try {
+    db = new Database(file, { readonly: true });
+    db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
+    const rows = db.query(`SELECT id, (sdlc IS NOT NULL AND length(sdlc) > 65536) AS receipt_cut, CASE WHEN length(sdlc) <= 65536 THEN sdlc END AS sdlc,
+      CASE WHEN length(signals) <= 65536 THEN signals END AS signals,
+      CASE WHEN length(history) <= 131072 THEN history END AS history FROM tasks ORDER BY id DESC LIMIT ?`).all(MAX_TASKS + 1) as { id: number; receipt_cut: number; sdlc: string | null; signals: string | null; history: string | null }[];
+    let complete = rows.length <= MAX_TASKS, bytes = 0;
+    const tasks: DogfoodTask[] = [];
+    for (const row of rows.slice(0,MAX_TASKS)) {
+      if (row.receipt_cut) complete = false;
+      bytes += (row.sdlc?.length ?? 0) + (row.signals?.length ?? 0) + (row.history?.length ?? 0);
+      if (bytes > DOGFOOD_BYTE_CAP) { complete = false; break; }
+      try {
+        const signals = JSON.parse(row.signals ?? "null"), history = JSON.parse(row.history ?? "null"), receipt = JSON.parse(row.sdlc ?? "{}");
+        if (!id(row.id) || !Array.isArray(signals) || !Array.isArray(history)) { complete = false; continue; }
+        if (history.length > 4096) { complete = false; continue; }
+        const clean: HistoryEntry[] = [];
+        for (const h of history) {
+          if (!h || !Number.isFinite(h.at) || typeof h.event !== "string") { complete = false; continue; }
+          clean.push({ at: h.at, by: "hub", event: h.event, ...(h.reviewCost && typeof h.reviewCost === "object" ? { reviewCost: { ...(h.reviewCost.review && ["none","delta","full"].includes(h.reviewCost.review.scope) ? {review:{scope:h.reviewCost.review.scope,reviewers:1}} : {}) } } : {}), ...(Array.isArray(h.reviewFindings?.items) ? { reviewFindings: { items:h.reviewFindings.items.filter((f:any)=>f && typeof f.id === "string" && ["important","nit"].includes(f.severity)).map((f:any)=>({id:f.id,severity:f.severity,pass:"bugs",disposition:"open"})) } } : {}) });
+        }
+        tasks.push({ id: row.id, pii: signals.includes("pii") || signals.includes("pii_path"), ...(repoName(receipt?.repo) ? { repo: receipt.repo } : {}), ...(id(receipt?.pr) ? { pr: receipt.pr } : {}), history: clean });
+      } catch { complete = false; }
+    }
+    return source(tasks, complete);
+  } catch { return missing([]); }
+  finally { db?.close(); }
+}
+/** Journal terminal retention is finite: these are retained rows, never whole-window delivery totals. */
+export function dogfoodJournal(file: string, since: number, until: number): Source<{digests:number;held:number;rows:number}> {
+  let db: Database | undefined;
+  try {
+    db = new Database(file, { readonly: true });
+    db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
+    const rows = db.query(`SELECT state, CASE WHEN length(out_json) <= 262144 THEN
+      (SELECT COUNT(*) FROM json_each(out_json) WHERE json_extract(value,'$.from')='digest') END AS digests
+      FROM deliveries WHERE created_at >= ? AND created_at <= ? ORDER BY created_at DESC LIMIT 10001`).all(since,until) as {state:string;digests:number|null}[];
+    return source({rows:Math.min(rows.length,10000),digests:rows.slice(0,10000).reduce((n,r)=>n+(r.digests??0),0),held:rows.slice(0,10000).filter(r=>r.state === "needs_review").length},rows.length<=10000 && rows.every(r=>r.digests!==null));
+  } catch { return missing({digests:0,held:0,rows:0}); }
+  finally {db?.close();}
+}
+const connection = (value: any): any[] | undefined => value?.pageInfo?.hasNextPage === false && Array.isArray(value.nodes) && value.nodes.length <= 100 ? value.nodes : undefined;
+/** Reuse S10 cost readback; supplementary reads carry timestamps/ids only, never comment or issue bodies. */
+export async function dogfoodPrs(repo: string, tasks: Source<DogfoodTask[]>, since: number, until: number, run: SdlcGh = sdlcGh): Promise<Source<DogfoodPr[]>> {
+  if (!repoName(repo) || !tasks.available || !tasks.complete) return missing([]); // unknown privacy inventory forbids remote per-PR reads
+  const deadline = performance.now() + 20000;
+  const gh: SdlcGh = (args, timeout, cwd, cap) => performance.now() < deadline
+    ? run(args, Math.max(1,Math.min(timeout ?? 5000,deadline-performance.now())),cwd,Math.min(cap ?? 128*1024,128*1024)) : Promise.resolve({code:1,stdout:""});
+  const parse = async (args: string[]) => { try { const r = await gh(args); return r.code === 0 ? JSON.parse(r.stdout) : undefined; } catch { return undefined; } };
+  const list = await parse(["pr","list","--repo",repo,"--state","merged","--search",`merged:>=${new Date(since).toISOString()}`,"--limit","100","--json","number,mergedAt,createdAt"]);
+  if (!Array.isArray(list)) return missing([]);
+  const hidden = new Set(tasks.data.filter(t => t.pii && (!t.repo || t.repo.toLowerCase() === repo.toLowerCase())).map(t => t.pr));
+  const visible = list.filter(p => id(p?.number) && date(p.mergedAt) !== undefined && date(p.mergedAt)! <= until && !hidden.has(p.number));
+  let complete = list.length < 100 && list.every(p => id(p?.number) && date(p.mergedAt) !== undefined) && visible.length <= MAX_PRS;
+  // Read recent PRs first: their complete recorded head sets usually fit before
+  // the shared deadline. Repository-wide CI volume never consumes this budget.
+  visible.sort((a,b)=>date(b.mergedAt)!-date(a.mergedAt)!);
+  const projection = "{total_count,workflow_runs:[.workflow_runs[]|{id,run_attempt,event,head_sha,created_at,conclusion,pull_requests:[.pull_requests[]|{number}]}]}";
+  const validRun = (r:any) => r?.event === "pull_request" && id(r?.id) && id(r?.run_attempt) && typeof r?.head_sha === "string" && /^[a-f0-9]{40}$/.test(r.head_sha)
+    && date(r.created_at) !== undefined && (r.conclusion === null || typeof r.conclusion === "string")
+    && Array.isArray(r.pull_requests) && r.pull_requests.length <= 100 && r.pull_requests.every((p:any)=>id(p?.number));
+  const sha = (v:unknown):v is string => typeof v === "string" && /^[a-f0-9]{40}$/.test(v);
+  let ciReads = 0;
+  const rows: DogfoodPr[] = [];
+  for (const item of visible.slice(0,MAX_PRS)) {
+    let heads: string[] | undefined, runs: any[] = [], runsComplete = false;
+    const cost = await readPrCostHistory(repo,item.number,async(args,t,c,cap) => {
+      if (args.some(arg => arg.startsWith(`repos/${repo}/actions/workflows/check.yml/runs?`))) {
+        if (!heads || heads.length>MAX_CI_HEADS || ciReads+heads.length>MAX_CI_READS) return {code:1,stdout:""};
+        const collected:any[] = [], seen = new Set<number>();
+        for (const head of heads) {
+          ciReads++;
+          const endpoint=`repos/${repo}/actions/workflows/check.yml/runs?per_page=100&event=pull_request&head_sha=${head}&created=${new Date(since).toISOString()}..${new Date(until).toISOString()}`;
+          const part = await parse(["api",endpoint,"--jq",projection]);
+          if (!part || !Number.isSafeInteger(part.total_count) || part.total_count<0 || !Array.isArray(part.workflow_runs)
+            || part.total_count!==part.workflow_runs.length || part.workflow_runs.length>100
+            || !part.workflow_runs.every((r:any)=>validRun(r) && r.head_sha===head)) return {code:1,stdout:""};
+          for (const row of part.workflow_runs) {
+            if (seen.has(row.id)) return {code:1,stdout:""};
+            seen.add(row.id);collected.push(row);
+          }
+          if (collected.length>100) return {code:1,stdout:""};
+        }
+        runs=collected;runsComplete=true;
+        return {code:0,stdout:JSON.stringify({total_count:runs.length,workflow_runs:runs.map((r:any)=>({id:r.id,run_attempt:r.run_attempt,head_sha:r.head_sha,pull_requests:r.pull_requests.map((p:any)=>p.number)}))})};
+      }
+      const reply = await gh(args,t,c,cap);
+      try {
+        const body = JSON.parse(reply.stdout), pr=body?.data?.repository?.pullRequest;
+        const commits=connection(pr?.commits),reviews=connection(pr?.reviews);
+        if (reply.code===0 && !body.errors && pr?.number===item.number && sha(pr.headRefOid) && commits && reviews
+          && commits.every(n=>sha(n?.commit?.oid)) && reviews.every(n=>id(n?.databaseId) && sha(n?.commit?.oid))) {
+          heads=[...new Set<string>([pr.headRefOid,...commits.map(n=>n.commit.oid),...reviews.map(n=>n.commit.oid)])];
+        }
+      } catch { /* Missing or incomplete recorded heads cannot certify CI. */ }
+      return reply;
+    });
+    const row: DogfoodPr = cost ?? {repo,pr:item.number,state:"MERGED",mergedAt:date(item.mergedAt),complete:false};
+    const linked = runsComplete ? runs.filter((r:any)=>date(r.created_at)!<=row.mergedAt!) : [];
+    if (runsComplete) {
+      const earliest=[...linked].sort((a,b)=>date(a.created_at)!-date(b.created_at)!)[0];
+      if (date(item.createdAt)!>=since && date(item.createdAt)!<=until && earliest?.run_attempt===1
+        && ["success","failure","cancelled","timed_out"].includes(earliest.conclusion)) row.firstPassCi=earliest.conclusion==="success";
+      row.sameHeadReruns=linked.reduce((n,r)=>n+r.run_attempt-1,0);
+    }
+    const [owner,name] = repo.split("/");
+    const detail = await parse(["api","graphql","-f",`query=query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){reviewThreads(first:100){pageInfo{hasNextPage} nodes{comments(first:1){nodes{createdAt author{login}}}}} timelineItems(first:100,itemTypes:[CROSS_REFERENCED_EVENT]){pageInfo{hasNextPage} nodes{... on CrossReferencedEvent{source{... on Issue{number createdAt labels(first:100){pageInfo{hasNextPage} nodes{name}}}}}}}}}}`,"-f",`owner=${owner}`,"-f",`name=${name}`,"-F",`number=${item.number}`]);
+    const pr = detail?.errors ? undefined : detail?.data?.repository?.pullRequest;
+    const threads = connection(pr?.reviewThreads), references = connection(pr?.timelineItems);
+    if (threads && threads.every(t => date(t?.comments?.nodes?.[0]?.createdAt) !== undefined && typeof t.comments.nodes[0].author?.login === "string")) row.connectorThreads = threads.flatMap(t => /^(?:chatgpt-codex-connector|chatgpt-codex-connector\[bot\])$/.test(t.comments.nodes[0].author.login) ? [date(t.comments.nodes[0].createdAt)!] : []);
+    if (references && references.every(r => id(r?.source?.number) && date(r.source.createdAt) !== undefined && connection(r.source.labels)?.every(label=>typeof label?.name === "string"))) row.bugIssues = [...new Map(references.flatMap(r => connection(r.source.labels)!.some(label => label.name === "bug") ? [[r.source.number,{id:r.source.number,at:date(r.source.createdAt)!}] as const] : [])).values()];
+    if (!row.complete || !pr) complete = false;
+    rows.push(row);
+  }
+  return source(rows,complete);
+}
+/** Row ordinals bind to this invocation's docs file; titles/state prose never enter the exported receipt. */
+export function dogfoodFeatures(file: string): Source<FeatureEvidence[]> {
+  const text = dogfoodLines(file,128*1024);
+  const mappings: [RegExp,string[],string[]?][] = [
+    [/Message bus/,["envelope","overflow"]], [/Task board/,["task"]], [/Overlap/,["overlap"]],
+    [/WIP caps/,["task"],["ready held"]], [/Task sweep/,["task"],["idle sweep","escalated"]], [/Turn-free/,["cohort"]],
+    [/Shared memory/,["memory_brief"]],
+    [/Quota budgets/,["quota","budget_pause","budget_resume","quota_reset"]], [/Token usage/,["tokens","usage"]],
+    [/Context gate/,["context_pressure"]], [/Permission modes/,["permission"]], [/PII routing/,["pii_screen"]],
+    [/Settings reload/,["settings"]], [/Release authorization/,["release_authorization"]],
+  ];
+  const rows = text.data.filter(line=>line.startsWith("| ") && !line.startsWith("| Feature ") && !line.startsWith("| ---"));
+  return {available:text.available,complete:text.complete,data:rows.map((row,index)=>{const rule=mappings.find(([re])=>re.test(row.split("|")[1] ?? ""));return {id:index+1,types:rule?.[1] ?? null,...(rule?.[2] ? {taskEvents:rule[2]} : {})};})};
+}
+export async function readDogfood(root: string, stateDir: string, since: number, until = Date.now(), run: SdlcGh = sdlcGh) {
+  const tasks = dogfoodTasks(join(stateDir,"hub.db"));
+  let repo = "";
+  try { const r = await run(["repo","view","--json","nameWithOwner"],5000,root,8192); if (r.code === 0) repo = JSON.parse(r.stdout).nameWithOwner; } catch { /* unknown */ }
+  const events = dogfoodEvents(dogfoodLines(join(stateDir,"events.jsonl")),since,until);
+  const log = dogfoodLines(join(stateDir,"hub.log"));
+  log.data = log.data.filter(line => {
+    const at=date(line.slice(0,24));
+    if (at === undefined) { log.complete = false; return false; }
+    return at >= since && at <= until;
+  });
+  return dogfoodScorecard({since,until,tasks,events,log,journal:dogfoodJournal(join(stateDir,"hub.db"),since,until),prs:await dogfoodPrs(repo,tasks,since,until,run),features:dogfoodFeatures(join(root,"docs/dogfood.md"))});
+}

package/src/hub/dogfood.ts

@@ -0,0 +1,163 @@
+import { costMetrics, type CostPr, type CostTask } from "./cost-governance.ts";
+import type { HistoryEntry } from "./board.ts";
+import { parseSince } from "./events.ts";
+import type { StampedEvent } from "./events.ts";
+import { summarize, summarizeByTask, type TaskPeerReport } from "./report.ts";
+
+
+export function dogfoodSince(args: string[], now = Date.now()): number {
+  let since: number | undefined, dogfood = false, json = false;
+  const fail = (): never => {throw new Error("usage: ahub report --dogfood [--since 7d|<iso>] [--json]");};
+  for(let i=0;i<args.length;i++) {
+    const arg=args[i];
+    if(arg==="--dogfood" && !dogfood) dogfood=true;
+    else if(arg==="--json" && !json) json=true;
+    else if(arg==="--since" && since===undefined) {const value=parseSince(args[++i] ?? "",now);if(value===undefined)fail();since=value;}
+    else fail();
+  }
+  if(!dogfood)fail();
+  return since ?? now-7*86400000;
+}
+
+export interface Source<T> { data: T; complete: boolean; available: boolean }
+export const source = <T>(data: T, complete = true): Source<T> => ({ data, complete, available: true });
+export const missing = <T>(data: T): Source<T> => ({ data, complete: false, available: false });
+export interface DogfoodTask { id: number; repo?: string; pr?: number; pii: boolean; history: HistoryEntry[] }
+export interface DogfoodPr extends CostPr {
+  firstPassCi?: boolean;
+  sameHeadReruns?: number;
+  connectorThreads?: number[];
+  bugIssues?: { id: number; at: number }[];
+}
+export interface FeatureEvidence { id: number; types: string[] | null; taskEvents?: string[] }
+export interface DogfoodInput {
+  since: number; until: number;
+  events: Source<StampedEvent[]>; tasks: Source<DogfoodTask[]>; prs: Source<DogfoodPr[]>;
+  journal?: Source<{ digests: number; held: number; rows: number }>;
+  log: Source<string[]>; features: Source<FeatureEvidence[]>;
+}
+export interface Metric { value: number | null; samples: number }
+const metric = (value: number, known: boolean, samples = 1): Metric => ({ value: known ? value : null, samples });
+const known = (s: Source<unknown>) => s.available && s.complete;
+const positive = (n: unknown): n is number => Number.isSafeInteger(n) && (n as number) > 0;
+const finite = (n: unknown): n is number => typeof n === "number" && Number.isFinite(n) && n >= 0;
+const identity = (repo: string, pr: number) => `${repo.toLowerCase()}#${pr}`;
+const validPeer = (peer: string) => /^[a-z][a-z0-9-]{0,63}$/.test(peer) && !Object.hasOwn(Object.prototype, peer);
+function peers(input: Record<string, TaskPeerReport>) {
+  return Object.fromEntries(Object.entries(input).filter(([id]) => validPeer(id)).map(([id, p]) => [id, {
+    tokens: p.tokens, input: p.usage.inputTokens, output: p.usage.outputTokens,
+    cacheRead: p.usage.cacheReadTokens, cacheWrite: p.usage.cacheWriteTokens, total: p.usage.totalTokens,
+    records: p.usage.records, inputRecords: p.usage.inputRecords, outputRecords: p.usage.outputRecords,
+    cacheReadRecords: p.usage.cacheReadRecords, cacheWriteRecords: p.usage.cacheWriteRecords, totalRecords: p.usage.totalRecords,
+  }]));
+}
+function percentiles(values: number[]) {
+  const sorted = values.filter(finite).sort((a, b) => a - b);
+  const at = (q: number) => sorted.length ? sorted[Math.max(0, Math.ceil(q * sorted.length) - 1)]! : null;
+  return { samples: sorted.length, p50: at(.5), p95: at(.95), p99: at(.99) };
+}
+
+/** Metadata projections only: never return task titles, notes, model/provider names or log fragments. */
+export function dogfoodScorecard(input: DogfoodInput) {
+  const events = input.events.data.filter(e => Date.parse(e.at) >= input.since && Date.parse(e.at) <= input.until);
+  const inWindow = (at: number) => at >= input.since && at <= input.until;
+  const tasks = input.tasks.data;
+  const hidden = new Set(tasks.filter(t => t.pii && t.repo && positive(t.pr)).map(t => identity(t.repo!, t.pr!)));
+  const prs = input.prs.data.filter(p => p.state === "MERGED" && finite(p.mergedAt) && inWindow(p.mergedAt)
+    && /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(p.repo) && positive(p.pr) && !hidden.has(identity(p.repo, p.pr)));
+  const costTasks: CostTask[] = tasks.flatMap(t => t.repo && positive(t.pr) ? [{ repo: t.repo, pr: t.pr, private: t.pii, history: t.history }] : []);
+  const costs = costMetrics(costTasks, prs);
+  const rows = prs.map(pr => {
+    const linked = tasks.filter(t => !t.pii && t.repo && positive(t.pr) && identity(t.repo, t.pr!) === identity(pr.repo, pr.pr));
+    const histories = linked.flatMap(t => t.history).filter(h => h.at <= pr.mergedAt!).sort((a,b) => a.at - b.at);
+    const timelines = linked.map(t => {
+      const history=t.history.filter(h=>h.at<=pr.mergedAt!).sort((a,b)=>a.at-b.at);
+      return {approval:history.findLast(h=>h.event==="approved")?.at,
+        proposed:history.find(h=>h.event==="proposed" || h.event==="backlog pulled")?.at,
+        done:history.findLast(h=>h.event==="done")?.at,
+        first:history.find(h=>h.event==="approved" || h.event==="changes_requested")?.event};
+    });
+    // PR readiness requires every linked task; an earlier member's approval is not the PR approval.
+    const all = (key:"approval"|"proposed"|"done") => timelines.length && timelines.every(t=>t[key]!==undefined);
+    const firstApproval = all("approval") ? Math.max(...timelines.map(t=>t.approval!)) : undefined;
+    const proposed = all("proposed") ? Math.min(...timelines.map(t=>t.proposed!)) : undefined;
+    const done = all("done") ? Math.max(...timelines.map(t=>t.done!)) : undefined;
+    const findings = new Set(histories.flatMap(h => h.reviewFindings?.items.filter(f => f.severity === "important").map(f => f.id) ?? []));
+    const cost = costs.rows.find(c => identity(c.repo, c.pr) === identity(pr.repo, pr.pr));
+    const ciCost = cost ?? costMetrics([{repo:pr.repo,pr:pr.pr,history:[]}],[pr]).rows[0];
+    const boardKnown = known(input.tasks) && linked.length > 0;
+    const delta = (end: number | undefined, start: number | undefined) => end !== undefined && start !== undefined && end >= start ? end - start : null;
+    return { repo: pr.repo.toLowerCase(), pr: pr.pr, tasks: linked.map(t => t.id).sort((a,b) => a-b), mergedAt: pr.mergedAt!,
+      proposeToApproveMs: boardKnown ? delta(firstApproval, proposed) : null,
+      doneToMergeMs: boardKnown ? delta(pr.mergedAt, done) : null,
+      reviewRounds: boardKnown ? cost?.reviewRounds ?? null : null,
+      firstPassApproval: boardKnown && timelines.every(t=>t.first) ? Number(timelines.every(t=>t.first === "approved")) : null,
+      escalations: boardKnown ? histories.filter(h => h.event === "escalated").length : null,
+      importantFindings: boardKnown ? findings.size : null,
+      connectorThreadsAfterApproval: firstApproval !== undefined && pr.connectorThreads !== undefined ? pr.connectorThreads.filter(at => at > firstApproval && at <= input.until).length : null,
+      bugIssuesWithin14d: pr.bugIssues?.filter(issue => issue.at >= pr.mergedAt! && issue.at <= Math.min(input.until,pr.mergedAt! + 14 * 86400000)).length ?? null,
+      bugObservationDays: Math.min(14, Math.max(0, (input.until - pr.mergedAt!) / 86400000)),
+      firstPassCi: pr.firstPassCi === undefined ? null : Number(pr.firstPassCi),
+      ciRuns: pr.complete ? ciCost?.ciRuns ?? null : null,
+      ciReruns: pr.complete ? ciCost?.ciReruns ?? null : null,
+      sameHeadReruns: pr.sameHeadReruns ?? null,
+    };
+  });
+  const accounting = events.filter(e => {
+    if (e.type === "task") return positive(e.id) && /^[a-z_]{1,32}$/.test(e.class) && !Object.hasOwn(Object.prototype,e.class);
+    if (e.type !== "tokens" && e.type !== "usage" && e.type !== "turn_end") return false;
+    if (!validPeer(e.peer) || e.task !== undefined && !positive(e.task)) return false;
+    if (e.type === "tokens") return finite(e.n);
+    if (e.type === "turn_end") return finite(e.ms);
+    return typeof e.id === "string" && typeof e.source === "string";
+  });
+  const taskReport = summarizeByTask(accounting);
+  const costPerTask = Object.entries(taskReport.tasks).filter(([id]) => positive(Number(id))).map(([id,t]) => ({ task: Number(id), pii: Number(!!t.pii || !!tasks.find(x => x.id === Number(id))?.pii), peers: peers(t.peers) }));
+  const costPerPr = rows.map(row => {
+    const linked = new Set(row.tasks);
+    const selected = accounting.filter(e => "task" in e && typeof e.task === "number" && linked.has(e.task));
+    const summary = summarizeByTask(selected);
+    const merged: Record<string, TaskPeerReport> = {};
+    // Reuse the report's class grouping solely as an accumulator, never expose the class text.
+    for (const [id,p] of Object.entries(summary.classes).flatMap(([,c]) => Object.entries(c.peers))) {
+      const previous = merged[id];
+      if (!previous) merged[id] = structuredClone(p);
+      else {
+        previous.tokens = previous.tokens === null || p.tokens === null ? null : previous.tokens + p.tokens;
+        for (const k of Object.keys(previous.usage) as (keyof TaskPeerReport["usage"])[]) {
+          const a = previous.usage[k], b = p.usage[k];
+          previous.usage[k] = (a === null || b === null ? null : a + b) as never;
+        }
+      }
+    }
+    return { repo: row.repo, pr: row.pr, peers: row.tasks.length && known(input.tasks) ? peers(merged) : null };
+  });
+  const logs = input.log.data;
+  const countLog = (pattern: RegExp) => logs.filter(line => pattern.test(line)).length;
+  const eventCount = (type: string) => events.filter(e => e.type === type).length;
+  const eventMetric = (type: string) => metric(eventCount(type), known(input.events), events.length);
+  const logMetric = (pattern: RegExp) => metric(countLog(pattern), known(input.log), logs.length);
+  const gates = {
+    S1: /spec acceptance|spec.*(?:missing|changed|unknown|accepted|edited)/i, S2: /plan conformance/i,
+    S3: /important finding/i, S4: /test integrity:/i, S9: /plan not reviewed|plan review issue|planner plan/i,
+  };
+  const advice = logs.filter(line => /SDLC .* advice:|premature review:|plan.*advice:|task .*: (?:plan not reviewed since |plan review issue )/.test(line));
+  return {
+    schemaVersion: 1, since: input.since, until: input.until,
+    sources: Object.fromEntries((["events","tasks","prs","log","features"] as const).map(key => [key, { available: input[key].available, complete: input[key].complete, records: input[key].data.length }])),
+    flow: { prs: rows, coverage: { mergedPrs: rows.length, linkedPrs: rows.filter(r => r.tasks.length).length } },
+    quality: { adviseBlockers: Object.fromEntries(Object.entries(gates).map(([gate,re]) => [gate, metric(advice.filter(line => re.test(line)).length, known(input.log), advice.length)])), realBlockers: null },
+    cost: { eventSourceComplete: known(input.events), usageComplete: known(input.events) && accounting.some(e=>e.type === "usage") && summarize(accounting).usage.completeCoverage, attributionComplete: known(input.events) && accounting.filter(e=>e.type === "tokens" || e.type === "usage").every(e=>e.attribution !== undefined && e.attribution !== "unattributed" && e.task !== undefined), perTask: costPerTask, perPr: costPerPr, unattributed: peers(taskReport.unattributed.peers), beforeAttribution: peers(taskReport.beforeAttribution.peers) },
+    delivery: { envelopeToDeliveryMs: percentiles([]), digests: {value: input.journal && known(input.journal) ? input.journal.data.digests : null, scope: "retained_journal"}, overflow: eventMetric("overflow"), undeliverable: eventMetric("undeliverable"), held: {value: input.journal && known(input.journal) ? input.journal.data.held : null, scope: "retained_journal"}, emptyInboxPollingStreaks: logMetric(/is polling an empty inbox with no task \(\d+ empty reads in \d+ min\)/) },
+    performance: { controlRequestMs: percentiles([]), connectionTimeouts: null, snapshotBudgetExhaustions: null, snapshotBudgetNotices: logMetric(/snapshot unavailable:.*budget/i), cpu: percentiles([]), rss: percentiles([]),
+      errors: { database: logMetric(/database contention|SQLITE_BUSY/), storage: logMetric(/delivery storage|journal unavailable/), transport: logMetric(/transport.*(?:failed|error)|connection.*(?:failed|error)/i) } },
+    adoption: input.features.data.map(feature => ({ id: feature.id, events: feature.types && known(input.events) ? events.filter(e => feature.types!.includes(e.type) && (!feature.taskEvents || e.type === "task" && feature.taskEvents.includes(e.event))).length : null })),
+    journalSource: input.journal ? {available:input.journal.available,complete:input.journal.complete,rows:input.journal.data.rows} : {available:false,complete:false,rows:0},
+    piiTasks: known(input.tasks) ? tasks.filter(t => t.pii).length : null,
+  };
+}
+export type DogfoodScorecard = ReturnType<typeof dogfoodScorecard>;
+/** A stable readable receipt; null is explicitly unknown in both formats. */
+export function formatDogfood(report: DogfoodScorecard): string[] {
+  return JSON.stringify(report, (_key,value) => value === null ? "unknown" : value, 2).split("\n");
+}

package/src/hub/envelope.ts

@@ -14,7 +14,7 @@ export interface Envelope {
   kind: Kind;
   priority: Priority;
   body: string; // agent conclusions only, never tool noise
-  refs?: { repo?: string; branch?: string; commit?: string; paths?: string[]; task?: string; reviewRevision?: string; taskOffer?: number; taskCancelled?: number; taskRecipient?: "owner" | "reviewer" | "planner"; backlog?: number[]; supervision?: boolean; supervisionKey?: string; boundedCheck?: string; budgetResume?: string; budgetResumeMoves?: { id: number; title: string; to: PeerId | null; role: "owner" | "reviewer" }[]; budgetResumeEarlier?: string[] };
+  refs?: { repo?: string; branch?: string; commit?: string; paths?: string[]; task?: string; reviewRevision?: string; taskOffer?: number; taskCancelled?: number; taskRecipient?: "owner" | "reviewer" | "planner"; backlog?: number[]; supervision?: boolean; supervisionKey?: string; completedFor?: number; boundedCheck?: string; budgetResume?: string; budgetResumeMoves?: { id: number; title: string; to: PeerId | null; role: "owner" | "reviewer" }[]; budgetResumeEarlier?: string[] };
   /** The body must not be shown outside its recipients: console tail and log print a stub instead (PII tasks). */
   private?: boolean;
   ts: number;

package/src/hub/events.ts

@@ -13,6 +13,7 @@ export const EVENTS_SCHEMA = 1;
  * ids, routing and sizes, tasks carry ids and states, so the file can be exported without leaking what agents wrote.
  */
 export type HubEvent =
+  | { type: "release_authorization"; by: "user"; authorization: string; commit: string; version: string; docsDigest: string; documents: number }
   | { type: "permission_mode"; peer: string; from: import("./permission-mode.ts").PermissionMode; to: import("./permission-mode.ts").PermissionMode }
   | { type: "role"; peer?: string; task?: number; actor: string; stage: "prepared" | "assigned"; roles: { id: string; layer: "shipped" | "project"; hash: string }[] }
   /** A settings change (#269): the registry key, the bounded registry values before/after and their source; an optional person reason is sanitized and capped at 400 UTF-8 bytes. */
@@ -50,7 +51,7 @@ export type HubEvent =
   | { type: "hook_stats"; peer: string; n: number; startupMs: number; hubMs: number; maxStartupMs: number }
   | { type: "cohort"; id: number; event: "formed" | "joined" | "lifted"; silent: boolean; tasks: number[]; owners: string[] }
   | ({ type: "tokens"; peer: string; n: number } & Partial<TaskAttribution>)
-  | ({ type: "usage"; peer: string; source: "omniroute" | "claude_transcript"; id: string; measuredAt?: string; requestedModel?: string; servedModel?: string; provider?: string; inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number; totalTokens?: number } & Partial<TaskAttribution>)
+  | ({ type: "usage"; peer: string; source: "omniroute" | "claude_transcript" | "codex_appserver"; id: string; reasoningTokens?: number; measuredAt?: string; requestedModel?: string; servedModel?: string; provider?: string; inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number; totalTokens?: number } & Partial<TaskAttribution>)
   | { type: "planning"; by: string; task?: number; release?: number; fields: string[]; revision: number }
   | { type: "task"; id: number; event: string; by: string; state: string; owner: string | null; reviewer: string | null; class: string; profile?: string; profileClass?: string; role?: string; roleIdentity?: { id: string; layer: "shipped" | "project"; hash: string }; pii: boolean; reason?: string; release?: number | null; priority?: number | null; plannedStart?: number | null; due?: number | null }
   | { type: "overlap"; task: number; owner: string; others: { task: number; owner: string; paths: string[]; symbols?: string[] }[] }
@@ -58,7 +59,15 @@ export type HubEvent =
   | ({ type: "pii_screen" } & ScreenRecord)
   | { type: "conflict"; peer: string; task?: number; other: number; owner: string; paths: string[]; concurrent: boolean; turns?: [string, string] }
   | { type: "context_pressure"; peer: string; source: string; measuredAt: number; used: number; window: number | null }
-  | { type: "quota"; peer: string; windows: { id: string; used: number; resetsAt?: number }[]; hard: boolean; measuredAt?: string };
+  | { type: "quota"; peer: string; windows: { id: string; used: number; resetsAt?: number }[]; hard: boolean; measuredAt?: string }
+  /**
+   * The limit ledger (#683 U1): additive, ids and numbers only, no PROTOCOL bump (a reader that does not know a type ignores it).
+   * `by` is who ended or began the pause: the coordinator (`hub`) or the console user (`person`, an override).
+   */
+  | { type: "budget_pause"; peer: string; reason: string; window: string; resetsAt: number; by: "hub" | "person" }
+  | { type: "budget_resume"; peer: string; reason: string; window: string; resetsAt: number; by: "hub" | "person" }
+  /** A window's reset, derived from two readings of one window id: `resetsAt` moved forward, or `used` fell by 0.5 or more. */
+  | { type: "quota_reset"; peer: string; window: string; cause: "resets_at_moved" | "used_dropped"; resetsAt?: number; previousResetsAt?: number; used: number; previousUsed: number; measuredAt?: string };
 
 export type StampedEvent = HubEvent & { v: number; at: string };
 

package/src/hub/facts.ts

@@ -1,7 +1,7 @@
 import { repoGitArgs, repoGitEnv, type Repo } from "./snapshots.ts";
 import { isHubWritePath } from "./permission-mode.ts";
 import { createHash, randomUUID } from "node:crypto";
-import { closeSync, constants, fstatSync, mkdirSync, openSync, readSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { closeSync, constants, fstatSync, mkdirSync, openSync, readSync, rmSync, statSync, writeFileSync, type Stats } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { sanitize, type PeerId } from "./envelope.ts";
 import { isDenied } from "../local/deny.ts";
@@ -24,6 +24,22 @@ import { realPath } from "./project.ts";
 const MAX_BYTES = 256 * 1024;
 /** Larger files that are not read are hashed for the HEAD comparison while all of them in one comparison total this much or less; beyond it, none is compared. */
 const HASHED_BYTES = 64 * 1024 * 1024;
+/**
+ * A large file whose last change (ctime) is this recent may still be rewritten with the same stat: Linux before 6.13
+ * stamps files from a coarse clock, so a same-size rewrite within one tick keeps size, mtime, ctime and inode (#428).
+ * Such a file is named by its bytes, as git treats a racily clean entry: at most RACY_HASH_MAX_BYTES each, hashed once
+ * per version in a public entry point, RACY_BURST_BYTES in all per store (Facts instance) per event-loop turn (the hooks
+ * run on the daemon's loop). The HEAD comparison keeps its own bound (HASHED_BYTES) and is not limited by these.
+ * ponytail: ceilings, each falling back to the stat-only stamp (no claim either way): a racy file over the per-file cap,
+ * or past the turn's budget, misses a same-size rewrite within one timestamp tick; a racy file first seen past the
+ * budget (kept stat-only) reads as changed once when a later turn hashes it with the same bytes; a file written continuously never settles and is hashed at every look, within that budget; FAT's 2 s mtime
+ * is the widest covered; a settled file made racy with the same bytes (chmod, `cp -p`, touch) reads as changed once; a
+ * version first seen racy costs an open and a stat at every later look (largeBlob's cache answers). A per-file history
+ * of racy versions if any of these matters.
+ */
+const RACY_MS = 2000;
+const RACY_HASH_MAX_BYTES = 4 * 1024 * 1024;
+const RACY_BURST_BYTES = 16 * 1024 * 1024;
 /** Changed lines shown in one fact, all files together; the rest is counted and the files named. */
 export const MAX_LINES = 60;
 /** What Claude Code's Read returns by default: the first 2000 lines, each cut at 2000 characters. */
@@ -145,6 +161,10 @@ export class Facts {
   private readonly seenDropped = new Map<PeerId, Set<string>>();
   /** Git blob ids of large files, by path, with the stat they were taken at. */
   private readonly largeBlobs = new Map<string, { stamp: string; blob: string }>();
+  /** Blob ids of racy large files hashed in the current boundary, by path and stat (#428). */
+  private racyMemo = new Map<string, string>();
+  /** Bytes of racy large files left to hash in this event-loop turn. */
+  private racyLeft?: { bytes: number };
   /** Directories each peer acknowledged being told were cut: once per session, not at every boundary. */
   private readonly cutTold = new Map<PeerId, Set<string>>();
   /**
@@ -217,7 +237,7 @@ export class Facts {
    * ponytail: a directory swapped between the containment check and the open is followed once; an fd-relative walk
    * (openat per component) closes that if it matters.
    */
-  private load(file: string): Omit<Version, "seq"> {
+  private load(file: string, statOnly = false): Omit<Version, "seq"> {
     if (this.rel(join(this.root, file)) !== file) return { hash: "missing" };
     const projected = this.o.projection?.(join(this.root, file));
     if (projected) return { hash: projected.rawHash, blob: projected.rawBlob, text: projected.text, projected: true };
@@ -226,7 +246,10 @@ export class Facts {
       fd = openSync(join(this.root, file), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
       const st = fstatSync(fd);
       if (!st.isFile()) return { hash: "missing" }; // a directory, a device or a fifo: never read
-      if (st.size > MAX_BYTES) return { hash: `large:${st.size}:${st.mtimeMs}` };
+      if (st.size > MAX_BYTES) {
+        const blob = statOnly ? undefined : this.racyBlob(file, fd, st);
+        return blob ? { hash: `large:${st.size}:${st.mtimeMs}:${blob}`, blob } : { hash: `large:${st.size}:${st.mtimeMs}` };
+      }
       const buf = Buffer.alloc(st.size);
       let got = 0;
       while (got < buf.length) {
@@ -317,13 +340,17 @@ export class Facts {
     const seen = files.filter((f) => head.has(f)).map((f) => [f, version(f)] as const);
     const large = seen.reduce((n, [, v]) => n + (v?.hash.startsWith("large:") ? Number(v.hash.split(":")[1]) : 0), 0);
     return new Set(seen.filter(([f, v]) => {
-      const blob = v?.blob ?? (v?.hash.startsWith("large:") && large <= HASHED_BYTES ? this.largeBlob(f, v.hash) : undefined);
+      const blob = !v?.hash.startsWith("large:") ? v?.blob : large <= HASHED_BYTES ? v.blob ?? this.largeBlob(f, v.hash, true) : undefined;
       return blob !== undefined && blob === head.get(f);
     }).map(([f]) => f));
   }
 
   /** Git's blob id of a file too large to load, streamed; undefined for anything that is not a small enough regular file. */
-  private largeBlob(file: string, observed: string): string | undefined {
+  /**
+   * `head`: for the HEAD comparison, which bounds its own hashing (HASHED_BYTES): a racy file is streamed whatever the
+   * racy cap and the turn's budget, uncached. Otherwise a racy file goes through racyBlob's limits.
+   */
+  private largeBlob(file: string, observed: string, head = false): string | undefined {
     if (this.rel(join(this.root, file)) !== file) return undefined;
     let fd: number | undefined;
     try {
@@ -333,13 +360,10 @@ export class Facts {
       // A file that stays stat-dirty but equal to HEAD is looked at again at every boundary: hashed once per version.
       const stamp = `${st.ino}:${st.size}:${st.mtimeMs}:${st.ctimeMs}`, known = this.largeBlobs.get(file);
       if (known?.stamp === stamp) return known.blob;
-      const h = createHash("sha1").update(`blob ${st.size}\0`);
-      const buf = Buffer.alloc(1024 * 1024);
-      let got = 0;
-      for (let n = 0; got < st.size && (n = readSync(fd, buf, 0, buf.length, got)) > 0; got += n) h.update(buf.subarray(0, n));
-      if (got !== st.size) return undefined; // changed while read: no claim
-      const blob = h.digest("hex");
-      this.largeBlobs.set(file, { stamp, blob });
+      // A racy stamp may name other bytes later: never cached.
+      if (Date.now() - st.ctimeMs < RACY_MS) return head ? this.racyMemo.get(racyKey(file, st)) ?? streamBlob(fd, st.size) : this.racyBlob(file, fd, st);
+      const blob = streamBlob(fd, st.size);
+      if (blob) this.largeBlobs.set(file, { stamp, blob });
       return blob;
     } catch {
       return undefined;
@@ -348,6 +372,22 @@ export class Facts {
     }
   }
 
+  /** A racy large file's blob id (#428), or undefined when it is settled, over the per-file cap or past the turn's budget. */
+  private racyBlob(file: string, fd: number, st: Stats): string | undefined {
+    if (Date.now() - st.ctimeMs >= RACY_MS || st.size > RACY_HASH_MAX_BYTES) return undefined;
+    const key = racyKey(file, st), known = this.racyMemo.get(key);
+    if (known) return known;
+    if (!this.racyLeft) {
+      const turn = this.racyLeft = { bytes: RACY_BURST_BYTES };
+      setImmediate(() => { if (this.racyLeft === turn) this.racyLeft = undefined; });
+    }
+    if (st.size > this.racyLeft.bytes) return undefined;
+    this.racyLeft.bytes -= st.size;
+    const blob = streamBlob(fd, st.size);
+    if (blob) this.racyMemo.set(key, blob);
+    return blob;
+  }
+
   /** `file` is covered again: an offer still unread that named it as dropped must not spend the notice of a later drop. */
   private coveredAgain(peer: PeerId, notice: "untracked" | "unfollowed", file: string): void {
     for (const o of this.offers.get(peer) ?? []) if (o[notice]?.includes(file)) o[notice] = o[notice]!.filter((f) => f !== file);
@@ -357,6 +397,7 @@ export class Facts {
   private boundary(): void {
     this.expanded = new Map();
     this.expandedCut = new Set();
+    this.racyMemo = new Map(); // not per turn: a rewrite between two entry points of one turn is another version
   }
 
   /** `peer` worked on `file`; `seen` is the file as it was when it did, the baseline if it has no view of it yet. */
@@ -463,6 +504,12 @@ export class Facts {
     const now = this.load(file);
     const was = this.latest.get(file);
     if (was && was.hash === now.hash) return was;
+    // Seen while racy (named by its bytes), now with the same stat but no blob (settled, or past the turn's budget): the
+    // same version if the bytes are, or when they cannot be hashed now (no claim).
+    if (was?.blob && was.hash === `${now.hash}:${was.blob}`) {
+      const blob = this.largeBlob(file, now.hash);
+      if (blob === undefined || blob === was.blob) return was;
+    }
     const version = { ...now, seq: ++this.seq };
     this.latest.set(file, version);
     if (was) {
@@ -720,7 +767,9 @@ export class Facts {
     // does, nor what they wrote before or after (a member settling keeps its files in the set).
     const written = windows.flatMap((w) => [...(this.writes.get(w.peer) ?? [])].filter(([, times]) => times.some((t) => t >= w.since && (w.until === undefined || t <= w.until))).map(([file]) => file));
     const files = [...new Set([...this.expand(paths.flatMap((p) => { const r = this.rel(p); return r ? [r] : []; }), true), ...written])].sort();
-    for (const file of files) h.update(file).update("\0").update(this.load(file).hash).update("\0");
+    // ponytail: a large file counts by its stat, racy or not, so the target does not move when it settles; a same-size
+    // rewrite within one timestamp tick does not move it either (observe() sees that one).
+    for (const file of files) h.update(file).update("\0").update(this.load(file, true).hash).update("\0");
     return h.digest("hex");
   }
 
@@ -871,3 +920,17 @@ export function codexEffect(before: string | undefined, now: { hash: string; tex
   const observed = changedLines(diff(before, now.text));
   return reported.length > 0 && reported.length === observed.length && reported.every((l, i) => l === observed[i]);
 }
+
+/** Git's blob id of the `size` bytes `fd` reads, streamed; undefined when fewer were read (changed while read). */
+function streamBlob(fd: number, size: number): string | undefined {
+  const h = createHash("sha1").update(`blob ${size}\0`);
+  const buf = Buffer.alloc(1024 * 1024);
+  let got = 0;
+  for (let n = 0; got < size && (n = readSync(fd, buf, 0, buf.length, got)) > 0; got += n) h.update(buf.subarray(0, n));
+  return got === size ? h.digest("hex") : undefined;
+}
+
+/** A racy large file's version within one boundary: its path and every stat field. */
+function racyKey(file: string, st: Stats): string {
+  return `${file}\0${st.ino}:${st.size}:${st.mtimeMs}:${st.ctimeMs}`;
+}