@staix/agent-hub 0.12.45 → 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/hub-tools.ts

@@ -1,3 +1,4 @@
+import { redFirstSchema } from "./test-integrity.ts";
 import { SDLC_STAGES } from "./sdlc.ts";
 import { projectProfile, profileData, PROFILE_CLASS_NAMES, type ProfileName, type ProfileSelection } from "./profiles.ts";
 import { catalogSection, type CatalogRole } from "./roles.ts";
@@ -191,12 +192,21 @@ export function profileTaskTools(profile: ProfileSelection = "dev", stages?: rea
       if (criteria) {
         const { phase, ...current } = fields as { phase: { properties: Record<string, unknown> } } & Record<string, unknown>;
         const { tasks: _retiredImport, ...checklist } = phase.properties;
-        fields = { ...current, criteria: { ...phase, properties: checklist, required: ["id", "criteria"] } };
+        fields = { ...current, redFirst: redFirstSchema, criteria: { ...phase, properties: checklist, required: ["id", "criteria"] } };
       }
       properties.receipt = { ...receipt, properties: fields };
     }
     if (customProfile && tool.name === "hub_task_propose") properties.class = { type: "string", enum: [...new Set([...Object.keys(data.classes), ...PROFILE_CLASS_NAMES.filter(v => projectProfile("dev").classes[v])])] };
     if (customProfile && properties.plan && tool.name !== "hub_task_accept") properties.plan = { ...plan, properties: { ...Object.fromEntries(data.plan_keys.map(key => [key, plan.properties[key as keyof typeof plan.properties] ?? list(key === "sections" ? "document heading anchors, such as report.md#methods" : key === "sources" ? "citation ids, DOI or source URL ids" : "short claim ids to verify")])) } };
+    if (customProfile && tool.name === "hub_task_done" && data.name !== "dev") {
+      const summaryProp = properties.summary as { type: string; description: string };
+      properties.summary = {
+        ...summaryProp,
+        description: data.name === "research" || data.name === "writing"
+          ? "changed deliverables, provenance, checks and unknowns"
+          : "what changed, why, and the check or verification you ran with its result",
+      };
+    }
     if (customProfile && tool.name === "hub_backlog_split") {
       const parts = properties.parts as { items: { properties: Record<string, unknown> } };
       const selectedPlan = { ...plan, properties: { ...Object.fromEntries(data.plan_keys.map(key => [key, plan.properties[key as keyof typeof plan.properties] ?? list(key === "sections" ? "document heading anchors, such as report.md#methods" : key === "sources" ? "citation ids, DOI or source URL ids" : "short claim ids to verify")])) } };
@@ -210,6 +220,18 @@ export function profileTaskTools(profile: ProfileSelection = "dev", stages?: rea
       const parts = properties.parts as { items: { properties: { plan: { properties: Record<string, unknown> } } } };
       properties.parts = { ...parts, items: { ...parts.items, properties: { ...parts.items.properties, plan: { ...parts.items.properties.plan, properties: { ...parts.items.properties.plan.properties, ...costPlanProperties, ...evidencePlanProperties } } } } };
     }
-    return { ...tool, ...(customProfile && tool.name === "hub_task_propose" ? { description: tool.description + ` Selected profile ${data.name}: ${Object.keys(data.classes).join(", ")}. Routing uses their existing base classes.` } : {}), inputSchema: { ...tool.inputSchema, properties } };
+    let description = tool.description;
+    if (customProfile && tool.name === "hub_task_propose") {
+      description = tool.description + ` Selected profile ${data.name}: ${Object.keys(data.classes).join(", ")}. Routing uses their existing base classes.`;
+    } else if (customProfile && tool.name === "hub_review" && data.name !== "dev") {
+      const reviewAction = data.name === "research" || data.name === "writing"
+        ? "assess scope, provenance and unsupported claims against the task's plan or detail"
+        : "assess the deliverables against the task's plan or detail";
+      description = `Give your verdict on a task you were asked to review: ${reviewAction}, read the check result (hub_task_show has it, with the done summary), and list what is unmet. The verdict notifies the task owner; no duplicate hub_send chat is needed. Consecutive changes_requested verdicts (three by default, \`tasks.escalate_after\`) move the task to another peer.`;
+    } else if (customProfile && tool.name === "hub_task_done" && data.name !== "dev") {
+      const summaryLabel = data.name === "research" || data.name === "writing" ? "deliverables, provenance and checks" : "deliverables and checks";
+      description = `Mark your task finished. It goes to its reviewer with your summary (${summaryLabel}) and refs; no duplicate hub_send chat is needed. When the project configures a check for its class, the hub runs it first and the result comes as a task message: a failed check keeps the task with you.`;
+    }
+    return { ...tool, description, inputSchema: { ...tool.inputSchema, properties } };
   });
 }

package/src/hub/inbox-polling.ts

@@ -0,0 +1,25 @@
+/** Advisory only: reading an inbox is never refused. */
+export class InboxPolling {
+  // ponytail: counters reset on restart; persist only if restarts hide real polling.
+  private readonly streaks = new Map<string, { reads: number[]; noticed: boolean }>();
+
+  reset(peer: string): void { this.streaks.delete(peer); }
+
+  read(peer: string, empty: boolean, assigned: boolean, now: number): { count: number; minutes: number; notice: boolean } | undefined {
+    if (!empty || assigned) { this.reset(peer); return; }
+    let streak = this.streaks.get(peer);
+    const last = streak?.reads.at(-1);
+    if (!streak || last === undefined || now < last || now - last > 10 * 60_000) {
+      streak = { reads: [], noticed: false };
+      this.streaks.set(peer, streak);
+    }
+    streak.reads = streak.reads.filter(at => now - at <= 10 * 60_000);
+    // ponytail: advice counts at most 64 recent reads; use time buckets if full high-rate counts become useful.
+    if (streak.reads.length === 64) streak.reads.shift();
+    streak.reads.push(now);
+    if (streak.reads.length < 3) return;
+    const notice = !streak.noticed;
+    streak.noticed = true;
+    return { count: streak.reads.length, minutes: Math.floor((now - streak.reads[0]!) / 60_000), notice };
+  }
+}

package/src/hub/instances.ts

@@ -1,4 +1,7 @@
 import { types } from "node:util";
+import { statSync } from "node:fs";
+import { dirname, isAbsolute, resolve, sep } from "node:path";
+import { canonicalPath, realPath } from "./project.ts";
 import { defaultPeerRoles, definitionOf, type AdapterDefinition, type StartForm, type ProjectAdapterCatalog } from "../adapters/registry.ts";
 import { isPermissionMode, type PermissionMode } from "./permission-mode.ts";
 
@@ -10,7 +13,17 @@ export interface InstanceConfig {
   review_mode?: "fresh";
   worktree?: string;
   readOnly?: boolean;
+  /** Jcode instances only (#685): their own native data home, and optional model selection. Machine-local, never editable from settings. */
+  jcode_home?: string;
+  provider?: string;
+  model?: string;
+  provider_profile?: string;
 }
+const JCODE_FIELDS = ["jcode_home", "provider", "model", "provider_profile"] as const;
+/** At most this many extra Jcode instances per project (#685). */
+export const MAX_JCODE_INSTANCES = 8;
+/** A flag value jcode takes as one argv word: bounded, printable, no spaces. */
+const NATIVE_WORD = /^[A-Za-z0-9][A-Za-z0-9._:/@+-]{0,127}$/;
 export type InstancesConfig = Readonly<Record<string, InstanceConfig>>;
 export interface InstanceCatalogEntry { id: string; kind: string; definition: AdapterDefinition; config?: InstanceConfig }
 const MAX_INSTANCES = 64;
@@ -41,6 +54,58 @@ function roles(value: unknown, field: string): string[] {
   return out;
 }
 
+/** The Jcode-only fields of one declaration (#685). Only the validated values are copied; nothing is read twice. */
+function jcodeInstanceFields(entry: Record<string, PropertyDescriptor>, path: string): Partial<InstanceConfig> {
+  const home: unknown = entry.jcode_home?.value;
+  if (typeof home !== "string" || !isAbsolute(home) || !home.trim() || Buffer.byteLength(home) > 4096 || /\p{Cc}/u.test(home)) return fail(`${path}.jcode_home`, "is required: a nonempty control-free absolute path of at most 4096 UTF-8 bytes, other than the base Jcode's home");
+  const out: Partial<InstanceConfig> = { jcode_home: home };
+  for (const key of ["provider", "model", "provider_profile"] as const) {
+    const present = entry[key];
+    if (!present) continue;
+    const word: unknown = present.value;
+    if (typeof word !== "string" || !NATIVE_WORD.test(word)) return fail(`${path}.${key}`, "must be one bounded printable word without spaces");
+    out[key] = word;
+  }
+  if (entry.start_mode && entry.start_mode.value !== "headless") return fail(`${path}.start_mode`, "a Jcode instance starts headless");
+  return out;
+}
+
+/**
+ * The directory a home names, as the disk sees it (#685 review): symlinks and system aliases (`/tmp` and `/private/tmp`) resolved with
+ * `realPath` (never `realpathSync`, which Bun fails on a backslash path), and for a home that does not exist yet the nearest existing
+ * ancestor resolved the same way. Compared case-folded when the volume folds case, so a case-only alias is the same home.
+ */
+function canonicalHome(home: string): { path: string; key: string; identity?: string } {
+  let path: string;
+  try { path = realPath(home); } catch { path = canonicalPath(home); }
+  const stat = (target: string) => { try { return statSync(target); } catch { return undefined; } };
+  let existing = path;
+  while (!stat(existing) && dirname(existing) !== existing) existing = dirname(existing);
+  const info = stat(path), anchor = stat(existing);
+  const swapped = existing.replace(/[A-Za-z]/g, letter => letter === letter.toLowerCase() ? letter.toUpperCase() : letter.toLowerCase());
+  const alias = swapped !== existing ? stat(swapped) : undefined;
+  const folds = !!anchor && !!alias && alias.ino === anchor.ino && alias.dev === anchor.dev;
+  return { path, key: folds ? path.toLowerCase() : path, ...(info ? { identity: `${info.dev}:${info.ino}` } : {}) };
+}
+/**
+ * One native data home per Jcode (#685): an instance may not use the base Jcode's home, another instance's, or one nested
+ * inside either (their stores would overlap), however the path is spelled: a symlink, a system alias or a case-only alias of one
+ * is the same home. Run once with the loaded base `jcode_home`.
+ */
+export function checkJcodeInstanceHomes(declarations: InstancesConfig | undefined, baseHome: string): void {
+  const homes: { id: string; key: string; identity?: string }[] = [{ id: "the base Jcode", ...canonicalHome(baseHome) }];
+  for (const [id, config] of Object.entries(declarations ?? {})) {
+    if (config.jcode_home === undefined) continue; // only a native-home kind carries one
+    const home = canonicalHome(config.jcode_home);
+    for (const other of homes) {
+      const label = other.id === "the base Jcode" ? "base" : other.id;
+      if (home.key === other.key || (home.identity !== undefined && home.identity === other.identity)) return fail(`instances.${id}.jcode_home`, other.id === "the base Jcode" ? "must differ from the base Jcode's home" : `is the same home as ${label}`);
+      if (home.key.startsWith(`${other.key}${sep}`) || other.key.startsWith(`${home.key}${sep}`)) return fail(`instances.${id}.jcode_home`, `is nested inside or around ${other.id === "the base Jcode" ? "the base Jcode's home" : `${label}'s home`}`);
+    }
+    homes.push({ id, ...home });
+  }
+}
+
 /** Declaration support is explicit policy, independent of the native MCP binding mechanism. */
 export function supportsHeadlessInstances(definition: AdapterDefinition): boolean {
   return definition.instances?.mode === "headless" && !!definition.start.create && definition.start.forms.includes("headless");
@@ -57,11 +122,14 @@ export function validateInstances(raw: unknown, catalog: ProjectAdapterCatalog):
   const result: Record<string, InstanceConfig> = Object.create(null);
   if (raw === undefined) return Object.freeze(result);
   const declarations = fields(raw, "instances");
+  let jcodeCount = 0;
   if (Object.keys(declarations).length > MAX_INSTANCES) return fail("instances", "at most 64 extra instances are supported");
   for (const [id, descriptor] of Object.entries(declarations)) {
     if (!PEER_ID.test(id) || RESERVED.has(id) || resolve(id)) return fail("instances", "ids must be nonreserved extra instance ids, not builtin ids");
     const path = `instances.${id}`, entry = fields(descriptor.value, path);
-    if (Object.keys(entry).some(key => !["kind", "roles", "start_mode", "permission_mode", "worktree", "review_mode", "readOnly"].includes(key))) return fail(path, "unsupported field");
+    const declaredKind: unknown = entry.kind?.value;
+    const jcodeFields = typeof declaredKind === "string" && resolve(declaredKind)?.instances?.nativeHome === true;
+    if (Object.keys(entry).some(key => !["kind", "roles", "start_mode", "permission_mode", "worktree", "review_mode", "readOnly", ...(jcodeFields ? JCODE_FIELDS : [])].includes(key))) return fail(path, "unsupported field");
     const kind: unknown = entry.kind?.value;
     if (typeof kind !== "string") return fail(`${path}.kind`, "must name a native kind");
     const definition = resolve(kind), prefix = `${kind}-`;
@@ -102,6 +170,10 @@ export function validateInstances(raw: unknown, catalog: ProjectAdapterCatalog):
       if (entry.readOnly.value && entry.permission_mode) return fail(`${path}.permission_mode`, "read-only instances cannot select a permission mode");
     }
     const value: InstanceConfig = { kind, ...(entry.review_mode ? { review_mode: "fresh" as const } : {}) };
+    if (jcodeFields) {
+      if (++jcodeCount > MAX_JCODE_INSTANCES) return fail("instances", `at most ${MAX_JCODE_INSTANCES} extra Jcode instances are supported per project`);
+      Object.assign(value, jcodeInstanceFields(entry, path));
+    }
     if (entry.readOnly) value.readOnly = entry.readOnly.value as boolean;
     if (entry.roles) { value.roles = roles(entry.roles.value, `${path}.roles`); Object.freeze(value.roles); }
     if (entry.start_mode) {