@staix/agent-hub 0.12.45 → 0.14.0

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}-`;
@@ -81,16 +149,24 @@ export function validateInstances(raw: unknown, catalog: ProjectAdapterCatalog):
     const runtime = freshReviewer ? definition.reviewerVariant ?? definition : definition;
     const unavailableReviewer = freshReviewer && !!(definition.reviewerVariant ?? definition).reviewer?.unavailable;
     if (!unavailableReviewer && runtime.instances?.mode !== "external" && !supportsHeadlessInstances(runtime)) return fail(`${path}.kind`, definition.reviewerVariant ? 'unsupported; this kind only declares headless reviewer instances with roles exactly ["reviewer"]' : "unsupported; explicit external instance policy or a headless instance policy with a headless factory is required");
+    if (declaredRoles.includes("planner") && definition.projection?.plannerEligible !== true) return fail(`${path}.roles`, "this kind cannot plan");
     if (external) {
       const declared = entry.roles ? roles(entry.roles.value, `${path}.roles`) : [];
       // #223: a headless one is the kind's reviewer variant, one fresh hub-run session per review request.
       if (entry.start_mode && definition.reviewerVariant) {
+        const reviewerRoles = declared.length === 1 && declared[0] === "reviewer";
+        // #525 R1: a headless writer is the kind's implementer variant, which arrives with slice 525-4; until then it is refused.
+        if (!reviewerRoles && declared.includes("implementer") && declared.every(role => role === "implementer" || role === "verifier")) return fail(`${path}.start_mode`, "headless Claude implementer is not available in this release");
+        if (!reviewerRoles) return fail(`${path}.roles`, "a headless channel-kind instance is a reviewer: roles must be exactly [\"reviewer\"]");
         if (entry.worktree) return fail(path, "a headless reviewer reads the project checkout: worktree is not supported");
-        if (declared.length !== 1 || declared[0] !== "reviewer") return fail(`${path}.roles`, "a headless channel-kind instance is a reviewer: roles must be exactly [\"reviewer\"]");
       } else {
-        if (entry.start_mode || entry.worktree) return fail(path, "a channel instance starts only from the person's terminal (ahub <kind> --as <id>): start_mode and worktree are not supported; a headless reviewer declares roles [\"reviewer\"] and start_mode \"headless\"");
+        if (entry.start_mode) return fail(`${path}.start_mode`, "a channel instance starts only from the person's terminal (ahub <kind> --as <id>); a headless reviewer declares roles [\"reviewer\"] and start_mode \"headless\"");
         const allowed = definition.instances?.roles ?? definition.roles;
-        if (!declared.length || declared.some(role => !allowed.includes(role))) return fail(`${path}.roles`, "a channel instance must declare its roles: reviewer and/or planner");
+        if (!declared.length || declared.some(role => !allowed.includes(role))) return fail(`${path}.roles`, `a channel instance must declare its roles within: ${allowed.join(", ")}`);
+        // #525 R1: an implementer or verifier writes, so it needs its own worktree; a planner or reviewer reads the project checkout.
+        const writes = declared.includes("implementer") || declared.includes("verifier");
+        if (writes && !entry.worktree) return fail(`${path}.worktree`, "an implementer or verifier channel instance needs its own worktree");
+        if (!writes && entry.worktree) return fail(`${path}.worktree`, "a planner or reviewer channel instance reads the project checkout: worktree is not supported");
       }
     } else {
       const allowed = runtime.instances?.roles;
@@ -102,6 +178,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) {
@@ -145,5 +225,7 @@ export function effectiveInstanceRoles(id: string, declarations: InstancesConfig
   if (!definition) throw new Error(`${id}: no declared native instance`);
   const declaration = declarations && Object.hasOwn(declarations, id) ? declarations[id] : undefined;
   const ownRoles = (key: string): readonly string[] | undefined => Object.hasOwn(policyRoles, key) ? policyRoles[key] : undefined;
-  return [...(declaration?.roles ?? ownRoles(id) ?? ownRoles(definition.kind) ?? definition.roles)];
+  const roles = declaration?.roles ?? ownRoles(id) ?? ownRoles(definition.kind) ?? definition.roles;
+  // #525 R1: a roles entry keyed by an instance id skips loadConductorPolicy's kind check, so planner is gated here too.
+  return roles.filter(role => role !== "planner" || definition.projection?.plannerEligible === true);
 }

package/src/hub/manager.ts

@@ -8,7 +8,7 @@ import { spawn } from "node:child_process";
 import { ControlClient, PROTOCOL, RECOVERY_SOURCE_PROTOCOLS } from "./control-client.ts";
 import { Registry, type Project } from "./registry.ts";
 import { hubHome } from "./project.ts";
-import { startDashboard } from "./ui.ts";
+import { startDashboard, dashboardView } from "./ui.ts";
 import { projectChain } from "@staix/agent-mem";
 import type { ProjectInspection } from "./lifecycle.ts";
 import { MAX_COMMAND_MS } from "../cli/terminal-recovery.ts";
@@ -164,7 +164,7 @@ export async function startManager(options: ManagerOptions = {}): Promise<Manage
         else if (deliveryRead) nominalMs = 30_000;
         const timeoutMs = options.forwardTimeoutMs?.(String(input.action), nominalMs) ?? nominalMs;
         const result = await client.request(input.action === "snapshot"
-          ? { t: "ui_snapshot", after: input.after ?? 0, ...(input.memory !== undefined ? { memory: input.memory } : {}) }
+          ? { t: "ui_snapshot", after: input.after ?? 0, ...(input.memory !== undefined ? { memory: input.memory } : {}), ...(dashboardView(input.view) ? { view: input.view } : {}) }
           : { t: "ui_action", action: input, instanceId: input.instanceId }, timeoutMs);
         // ControlClient resolves its deadline as this exact sentinel; a hub refusal stays a known failure.
         if (["start_peer", "backlog_split"].includes(String(input.action)) && result.ok === false && result.error === `no answer from the hub within ${Math.round(timeoutMs / 1000)} s`) {

package/src/hub/profiles.ts

@@ -10,6 +10,7 @@ export type ProfileName = (typeof PROFILE_NAMES)[number];
 export interface ProjectProfile {
   name: string; classes: Record<string, string>; plan_keys: string[]; role_text: Record<string, string>;
   catalog_roles: Record<string, string[]>; agents: string; example_checks: string[];
+  review_checklist?: string[];
 }
 const PROFILES: Record<ProfileName, ProjectProfile> = { dev, research, writing, general };
 export function profileName(raw: unknown): ProfileName {
@@ -34,10 +35,10 @@ export function resolveProfile(raw?: unknown, overrides?: unknown): ProjectProfi
   const original = projectProfile(raw);
   if (overrides === undefined) return original;
   if (!overrides || typeof overrides !== "object" || Array.isArray(overrides)) throw new Error("profile_overrides must be an object");
-  const data = overrides as Record<string, unknown>, allowed = new Set(["classes", "plan_keys", "role_text", "catalog_roles", "agents", "example_checks"]);
+  const data = overrides as Record<string, unknown>, allowed = new Set(["classes", "plan_keys", "role_text", "catalog_roles", "agents", "example_checks", "review_checklist"]);
   if (Object.keys(data).some(key => !allowed.has(key))) throw new Error("unknown profile override field");
   if (!Object.keys(data).length) return original;
-  const result: ProjectProfile = { ...original, classes: { ...original.classes }, plan_keys: [...original.plan_keys], role_text: { ...original.role_text }, catalog_roles: Object.fromEntries(Object.entries(original.catalog_roles).map(([peer, ids]) => [peer, [...ids]])), example_checks: [...original.example_checks] };
+  const result: ProjectProfile = { ...original, classes: { ...original.classes }, plan_keys: [...original.plan_keys], role_text: { ...original.role_text }, catalog_roles: Object.fromEntries(Object.entries(original.catalog_roles).map(([peer, ids]) => [peer, [...ids]])), example_checks: [...original.example_checks], ...(original.review_checklist ? { review_checklist: [...original.review_checklist] } : {}) };
   const text = (value: unknown, cap: number): string => { if (typeof value !== "string" || value.length > cap) throw new Error("profile text is missing or oversized"); return sanitize(value); };
   if (data.classes !== undefined) {
     if (!data.classes || typeof data.classes !== "object" || Array.isArray(data.classes) || Object.keys(data.classes).length > 32) throw new Error("profile classes must be a bounded base-class map");
@@ -63,6 +64,10 @@ export function resolveProfile(raw?: unknown, overrides?: unknown): ProjectProfi
     if (!Array.isArray(data.example_checks) || data.example_checks.length > 16) throw new Error("profile example_checks must be a bounded display list");
     result.example_checks = data.example_checks.map(value => text(value, 2000));
   }
+  if (data.review_checklist !== undefined) {
+    if (!Array.isArray(data.review_checklist) || !data.review_checklist.length || data.review_checklist.length > 16 || data.review_checklist.some(value => typeof value !== "string" || !value.trim() || value.length > 500)) throw new Error("profile review_checklist must be bounded checklist lines");
+    result.review_checklist = data.review_checklist.map(value => sanitize(value.trim()));
+  }
   return result;
 }
 

package/src/hub/release-worktree.ts

@@ -0,0 +1,56 @@
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, readlinkSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import type { ReleaseGit } from "./sdlc-release.ts";
+
+/** Filter-free tracked checkout comparison. Unknown or transformed content refuses. */
+// ponytail: 4096 entries, 4 MiB/file, 32 MiB total and 250 ms; larger/gitlink/transformed checkouts require a future bounded artifact attestation.
+export function releaseTrackedClean(root: string, git: ReleaseGit): boolean {
+  const start = performance.now(), deadline = () => performance.now() - start <= 250;
+  const run = (args: string[]) => {
+    if (!deadline()) return;
+    const result = git(args);
+    return deadline() && result.code === 0 && Buffer.byteLength(result.stdout) <= 2 * 1024 * 1024 ? result.stdout : undefined;
+  };
+  try {
+    const base = resolve(root);
+    if (!lstatSync(base).isDirectory() || lstatSync(base).isSymbolicLink()) return false;
+    if (run(["diff-index", "--cached", "--quiet", "--no-ext-diff", "--no-textconv", "HEAD", "--"]) === undefined) return false;
+    const inventory = run(["ls-files", "--stage", "-z"]);
+    if (inventory === undefined || inventory && !inventory.endsWith("\0")) return false;
+    const entries = inventory ? inventory.slice(0, -1).split("\0") : [];
+    if (entries.length > 4096) return false;
+    let total = 0;
+    for (const entry of entries) {
+      if (!deadline()) return false;
+      const match = /^([0-7]{6}) ([0-9a-f]{40}) ([0-3])\t([\s\S]+)$/.exec(entry);
+      if (!match) return false;
+      const [, mode, oid, stage, name] = match;
+      if (stage !== "0" || !["100644", "100755", "120000"].includes(mode!)) return false;
+      if (!name || name.length > 4096 || name.startsWith("/") || name.includes("\\") || name.split("/").some(part => !part || part === "." || part === "..") || /[\p{Cc}]/u.test(name)) return false;
+      const file = resolve(base, name), within = relative(base, file);
+      if (!within || within === ".." || within.startsWith("../")) return false;
+      for (let parent = dirname(file); parent !== base; parent = dirname(parent)) {
+        if (!deadline()) return false;
+        const info = lstatSync(parent);
+        if (!info.isDirectory() || info.isSymbolicLink()) return false;
+      }
+      const before = lstatSync(file);
+      if (before.size > 4 * 1024 * 1024 || total + before.size > 32 * 1024 * 1024) return false;
+      let bytes: Buffer;
+      if (mode === "120000") {
+        if (!before.isSymbolicLink()) return false;
+        bytes = readlinkSync(file, { encoding: "buffer" });
+      } else {
+        if (!before.isFile() || before.isSymbolicLink() || !!(before.mode & 0o111) !== (mode === "100755")) return false;
+        bytes = readFileSync(file);
+      }
+      total += bytes.length;
+      if (bytes.length > 4 * 1024 * 1024 || total > 32 * 1024 * 1024 || !deadline()) return false;
+      const after = lstatSync(file);
+      if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) return false;
+      if (createHash("sha1").update(`blob ${bytes.length}\0`).update(bytes).digest("hex") !== oid) return false;
+    }
+    return deadline();
+  } catch { return false; }
+}

package/src/hub/review-brief.ts

@@ -1,5 +1,7 @@
+import type { CodeFactResult, CodeSymbol } from "./code-facts.ts";
 import { childEnv } from "./child-process.ts";
 import { hubGitSync } from "./git.ts";
+import { symbolsOverlap } from "./symbol-normalizer.ts";
 
 /**
  * #520: the review brief ahub builds itself, in place of `ocr delegate preview` and `rule`. Every reviewer gets the same
@@ -10,6 +12,7 @@ import { hubGitSync } from "./git.ts";
 export interface BriefFile { path: string; status: string; oldPath?: string; insertions?: number; deletions?: number }
 export interface BriefExcluded { path: string; status: string; oldPath?: string; reason: string }
 export interface ReviewBrief {
+  symbols?: { state: "known" | "unknown"; complete?: boolean; files: {path:string; symbols:CodeSymbol[]}[]; planned: string[]; unplanned: string[]; unseen: string[] };
   head: string;
   /** The default branch the head is compared with: origin/HEAD, origin/main or origin/master. */
   base: string;
@@ -149,6 +152,38 @@ function attributes(cwd: string, source: string, paths: string[]): Map<string, {
   return out;
 }
 
+/** One plan name against one changed name: a qualified pair must be equal, otherwise the last segments are. Shared with the console's task detail (#684 2b). */
+export const planSymbolMatches = (left: string, right: string): boolean => symbolsOverlap(left, right);
+/** Project derived names through the host metadata screen before comparing or rendering them. */
+export function withCodeSymbols(brief:ReviewBrief,result:CodeFactResult<CodeSymbol[]>,plan:readonly string[]|undefined,publicMetadataText:(text:string)=>boolean):ReviewBrief {
+  const unknown={...brief,symbols:{state:"unknown" as const,files:[],planned:[],unplanned:[],unseen:[]}};
+  if(result.state!=="known")return unknown;
+  try {
+    const paths=new Set(brief.reviewable.map(file=>file.path));
+    const changed=result.value.filter(s=>!s.ambiguous && paths.has(s.path) && publicMetadataText(s.path) && publicMetadataText(s.name) && publicMetadataText(s.kind));
+    const planned=(plan??[]).filter(name=>publicMetadataText(name));
+    const matches=planSymbolMatches;
+    const names=[...new Set(changed.map(s=>s.name))];
+    return {...brief,symbols:{state:"known",complete:changed.length===result.value.length && brief.withheld===0,files:[...paths].map(path=>({path,symbols:changed.filter(s=>s.path===path)})),
+      planned:names.filter(name=>planned.some(p=>matches(p,name))),unplanned:names.filter(name=>!planned.some(p=>matches(p,name))),unseen:planned.filter(p=>!names.some(name=>matches(p,name)))}};
+  } catch { return unknown; }
+}
+
+function renderCodeSymbols(brief:ReviewBrief):string[] {
+  const symbols=brief.symbols;
+  if(!symbols)return [];
+  if(symbols.state === "unknown")return ["Changed symbols: unknown (optional code facts unavailable)."];
+  const lines=[
+    "Changed symbols (advisory; change: unknown):",
+    ...symbols.files.flatMap(file=>file.symbols.length ? file.symbols.map(symbol=>`- ${file.path}: ${symbol.name} (${symbol.kind}, lines ${symbol.line}${symbol.endLine === undefined ? "..unknown" : `..${symbol.endLine}`}; change: unknown)`) : [`- ${file.path}: no changed symbol observed`]),
+    `Changed and planned: ${symbols.planned.join(", ") || "none observed"}`,
+    `Changed, not planned: ${symbols.unplanned.join(", ") || "none observed"}`,
+    `Planned, not seen as changed: ${symbols.unseen.join(", ") || "none observed"}`,
+    "Ceiling: ripwire 0.6.7 does not report deleted symbols; these lists never establish plan conformance.",
+  ];
+  return Buffer.byteLength(lines.join("\n"))<=16000 ? lines : ["Changed symbols: unknown (advice exceeds 16000 bytes)."];
+}
+
 /** The brief as review text: what every reviewer reads and how it accounts for its coverage. */
 export function renderReviewBrief(brief: ReviewBrief): string {
   const file = (f: BriefFile) => `- ${f.oldPath ? `${f.oldPath} -> ` : ""}${f.path} (${f.status}${f.insertions !== undefined ? `, +${f.insertions} -${f.deletions}` : ""})`;
@@ -156,6 +191,7 @@ export function renderReviewBrief(brief: ReviewBrief): string {
     `Review brief: head ${brief.head} against ${brief.base} (merge base ${brief.mergeBase.slice(0, 12)}); ${brief.reviewable.length} reviewable, ${brief.excluded.length} excluded${brief.withheld ? `, ${brief.withheld} withheld by the privacy policy` : ""}.`,
     ...(brief.reviewable.length ? ["Reviewable:", ...brief.reviewable.map(file)] : ["Reviewable: none (record why in the note)."]),
     ...(brief.excluded.length ? ["Excluded (still read their diff when it matters):", ...brief.excluded.map(e => `- ${e.oldPath ? `${e.oldPath} -> ` : ""}${e.path} (${e.status}): ${e.reason}`)] : []),
+    ...renderCodeSymbols(brief),
     ...(brief.unlisted.length ? ["Not in the brief's list, read directly:", ...brief.unlisted.map(path => `- ${path}`)] : []),
     ...brief.ruleGroups.filter(g => g.sources.length).map(g => `Rules ${g.sources.join(" + ")} apply to: ${brief.ruleGroups.length === 1 ? "every reviewable file" : g.paths.join(", ")}`),
     ...(brief.rulesMissing.length ? ["Configured rules not loaded (read them in the repository):", ...brief.rulesMissing.map(m => `- ${m.source}: ${m.reason}`)] : []),

package/src/hub/sdlc-metrics.ts

@@ -0,0 +1,260 @@
+// #481 S7: SDLC metrics and deterministic control bands. Pure: board history in, numbers out. No I/O, no clock, no model.
+// A metric that cannot be derived is `unknown` and counted as such, never 0.
+// `first_pass_check` reads the hub's own completion check (`check passed` / `check failed` at hub_task_done), not PR CI: it is unknown where completion checks are off.
+
+export const BAND_METRICS = ["acceptance_to_plan_ms", "acceptance_to_first_review_ms", "first_pass_approval", "rework_rounds", "first_pass_check", "stale_head_re_reviews"] as const;
+export type BandMetric = typeof BAND_METRICS[number];
+export const BAND_TIERS = ["ok", "log", "diagnose", "propose"] as const;
+export type BandTier = typeof BAND_TIERS[number];
+
+/** The slice of a board task the metrics read. History entries carry ids, times and event names only. */
+export interface MetricTask {
+  id: number;
+  private?: boolean;
+  /** `requestHead` is the head a `done` asked review for (reviewCost.head); `verdictHead` the head a verdict was bound to (reviewFindings.head). Compared for equality only, never printed. */
+  history: { at: number; event: string; requestHead?: string; verdictHead?: string }[];
+}
+
+/** Per-task values; `null` is unknown. */
+export interface TaskSample {
+  id: number;
+  /** When the sample counts: its first verdict, else its acceptance, else its first event. */
+  at: number;
+  /** When the task was approved, else null: `rework_rounds` and `stale_head_re_reviews` are final only then, and sit at this time in their series. */
+  approved_at: number | null;
+  acceptance_to_plan_ms: number | null;
+  acceptance_to_first_review_ms: number | null;
+  acceptance_to_merge_ms: number | null;
+  first_pass_approval: 0 | 1 | null;
+  rework_rounds: number | null;
+  first_pass_check: 0 | 1 | null;
+  same_head_ci_reruns: number | null;
+  stale_head_re_reviews: number | null;
+}
+
+export interface Summary { n: number; unknown: number; mean: number | null; median: number | null; p90: number | null; max: number | null }
+export interface StallCounts { open: number; byKind: Record<string, number>; doneWithoutWrites: number }
+export interface BandConfig { window: number; minSamples: number; logSigma: number; diagnoseSigma: number; proposeSigma: number; driftRun: number; minDelta: number }
+export type BandsConfig = Partial<Record<BandMetric, BandConfig>>;
+export interface BandResult {
+  metric: BandMetric;
+  tier: BandTier;
+  /** Why the tier is what it is, in fixed words and numbers only. */
+  reason: string;
+  baseline: number;
+  mean: number | null;
+  sd: number | null;
+  last: number | null;
+  z: number | null;
+  /** The task that produced the last value: the breach's evidence. */
+  lastTask: number | null;
+  /** The task whose value started the run of non-ok values this one belongs to, else null: one breach episode has one card. */
+  episode: number | null;
+}
+
+/** Which way is worse. A rate that falls and a time that grows are both breaches. */
+export const BAD_DIRECTION: Record<BandMetric, "up" | "down"> = {
+  acceptance_to_plan_ms: "up", acceptance_to_first_review_ms: "up", first_pass_approval: "down", rework_rounds: "up", first_pass_check: "down", stale_head_re_reviews: "up",
+};
+const HOUR = 3_600_000;
+/** Per-metric floor on the absolute deviation, so a flat baseline does not make every wobble a breach. */
+export const DEFAULT_MIN_DELTA: Record<BandMetric, number> = {
+  acceptance_to_plan_ms: HOUR, acceptance_to_first_review_ms: HOUR, first_pass_approval: 0.5, rework_rounds: 1, first_pass_check: 0.5, stale_head_re_reviews: 1,
+};
+/** Per-metric floor on the baseline deviation: a flat baseline (every value the same) must not turn one step into thousands of deviations. */
+export const SD_FLOOR: Record<BandMetric, number> = {
+  acceptance_to_plan_ms: HOUR / 2, acceptance_to_first_review_ms: HOUR / 2, first_pass_approval: 0.5, rework_rounds: 0.5, first_pass_check: 0.5, stale_head_re_reviews: 0.5,
+};
+export const DEFAULT_BAND: Omit<BandConfig, "minDelta"> = { window: 20, minSamples: 8, logSigma: 2, diagnoseSigma: 3, proposeSigma: 4, driftRun: 6 };
+
+const first = (task: MetricTask, events: readonly string[], after = -Infinity) => task.history.find(entry => entry.at >= after && events.includes(entry.event));
+const VERDICTS = ["approved", "changes_requested"];
+
+/**
+ * Review rounds whose verdict was bound to a different head than the review was requested for: the head moved while the review ran.
+ * Known only for a round with both heads recorded; a task with no such round is unknown, never 0. (A `done` after an `approved` is not
+ * evidence: the board cannot produce one.)
+ * ponytail: the request head is `reviewCost.head` (the commit the done named first) while a verdict's head prefers the lifecycle receipt's
+ * `head`/`localHead` over `refs.commit` (`findingHead`), so a receipt head that differs from the commit can read as stale. Ceiling: a
+ * spurious stale round for a task whose receipt head and commit disagree; the upgrade is one shared head rule for both sides.
+ */
+function staleHeadRounds(history: MetricTask["history"]): number | null {
+  let pending: string | undefined, known = false, stale = 0;
+  for (const entry of history) {
+    if (entry.event === "done") pending = entry.requestHead;
+    else if (VERDICTS.includes(entry.event)) {
+      if (pending !== undefined && entry.verdictHead !== undefined) { known = true; if (entry.verdictHead !== pending) stale++; }
+      pending = undefined;
+    }
+  }
+  return known ? stale : null;
+}
+
+/** One task's values from its own history. A private task never reaches here. */
+export function taskSample(task: MetricTask, extra: { mergedAt?: number; ciReruns?: number | null } = {}): TaskSample {
+  const history = [...task.history].filter(entry => Number.isFinite(entry.at) && entry.at >= 0).sort((a, b) => a.at - b.at);
+  const view: MetricTask = { id: task.id, history };
+  const accepted = first(view, ["accepted"]);
+  const spec = first(view, ["spec accepted"]);
+  const plan = spec ? first(view, ["plan reviewed"], spec.at) : undefined;
+  const verdict = accepted ? first(view, VERDICTS, accepted.at) : first(view, VERDICTS);
+  const dones = history.filter(entry => entry.event === "done");
+  const ci = first(view, ["check passed", "check failed"]);
+  const approvedAt = history.find(entry => entry.event === "approved")?.at ?? null;
+  return {
+    id: task.id,
+    at: verdict?.at ?? accepted?.at ?? history[0]?.at ?? 0,
+    approved_at: approvedAt,
+    acceptance_to_plan_ms: spec && plan ? plan.at - spec.at : null,
+    acceptance_to_first_review_ms: accepted && verdict ? verdict.at - accepted.at : null,
+    acceptance_to_merge_ms: accepted && extra.mergedAt !== undefined && Number.isFinite(extra.mergedAt) && extra.mergedAt >= accepted.at ? extra.mergedAt - accepted.at : null,
+    first_pass_approval: verdict ? (verdict.event === "approved" ? 1 : 0) : null,
+    // Rework grows with every round, so it is a value only once the task is approved: a task still in flight has no final one, and a
+    // provisional point would move at each verdict and could start a second breach episode inside one shift.
+    rework_rounds: dones.length && approvedAt !== null ? history.filter(entry => entry.event === "changes_requested").length : null,
+    first_pass_check: ci ? (ci.event === "check passed" ? 1 : 0) : null,
+    same_head_ci_reruns: extra.ciReruns === undefined ? null : extra.ciReruns,
+    stale_head_re_reviews: approvedAt !== null ? staleHeadRounds(history) : null,
+  };
+}
+
+const percentile = (sorted: number[], p: number) => sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(p * sorted.length) - 1))]!;
+export function summarize(values: readonly (number | null)[]): Summary {
+  const known = values.filter((value): value is number => value !== null && Number.isFinite(value)).sort((a, b) => a - b);
+  const unknown = values.length - known.length;
+  if (!known.length) return { n: 0, unknown, mean: null, median: null, p90: null, max: null };
+  const mean = known.reduce((sum, value) => sum + value, 0) / known.length;
+  return { n: known.length, unknown, mean: round(mean), median: round(percentile(known, 0.5)), p90: round(percentile(known, 0.9)), max: known.at(-1)! };
+}
+const round = (value: number) => Math.round(value * 1000) / 1000;
+
+/** The values of one metric in the order they happened, unknown ones left out. */
+export function series(samples: readonly TaskSample[], metric: BandMetric): { value: number; task: number }[] {
+  const final = metric === "rework_rounds" || metric === "stale_head_re_reviews";
+  const when = (sample: TaskSample) => final ? sample.approved_at ?? sample.at : sample.at;
+  return [...samples].sort((a, b) => when(a) - when(b) || a.id - b.id).flatMap(sample => sample[metric] === null ? [] : [{ value: sample[metric] as number, task: sample.id }]);
+}
+
+/**
+ * The newest value against the `window` values before it: mean, population standard deviation, and a tier from how many
+ * deviations the newest value sits on the bad side. A run of `driftRun` newest values all more than one deviation on the bad
+ * side is a drift and is at least `diagnose`. With fewer than `minSamples` before it, nothing fires.
+ */
+export function controlBands(points: readonly { value: number; task: number }[], metric: BandMetric, config: BandConfig): BandResult {
+  const baselineCount = Math.max(0, Math.min(config.window, points.length - 1));
+  const none = (reason: string, extra: Partial<BandResult> = {}): BandResult => ({ metric, tier: "ok", reason, baseline: baselineCount, mean: null, sd: null, last: points.at(-1)?.value ?? null, z: null, lastTask: points.at(-1)?.task ?? null, episode: null, ...extra });
+  if (points.length < 2 || baselineCount < config.minSamples) return none(`baseline of ${baselineCount} is below the ${config.minSamples} needed`);
+  const last = points.at(-1)!, base = points.slice(-1 - baselineCount, -1).map(point => point.value);
+  const mean = base.reduce((sum, value) => sum + value, 0) / base.length;
+  const sd = Math.sqrt(base.reduce((sum, value) => sum + (value - mean) ** 2, 0) / base.length);
+  const sign = BAD_DIRECTION[metric] === "up" ? 1 : -1;
+  const deviation = sign * (last.value - mean);
+  const z = deviation <= 0 ? 0 : deviation / Math.max(sd, SD_FLOOR[metric]);
+  const result = { metric, baseline: base.length, mean: round(mean), sd: round(sd), last: last.value, z: round(Math.min(z, 1e6)), lastTask: last.task, episode: null as number | null };
+  const drifting = deviation >= config.minDelta && deviation > 0 && points.length - 1 >= config.driftRun && points.slice(-config.driftRun).every(point => sign * (point.value - mean) > sd);
+  let tier: BandTier = "ok", reason = `${round(Math.min(z, 1e6))} deviations on the bad side`;
+  if (deviation >= config.minDelta && deviation > 0) {
+    if (z >= config.proposeSigma) { tier = "propose"; reason = `${round(Math.min(z, 1e6))} deviations beyond the baseline (propose at ${config.proposeSigma})`; }
+    else if (z >= config.diagnoseSigma) { tier = "diagnose"; reason = `${round(z)} deviations beyond the baseline (diagnose at ${config.diagnoseSigma})`; }
+    else if (z >= config.logSigma) { tier = "log"; reason = `${round(z)} deviations beyond the baseline (log at ${config.logSigma})`; }
+  }
+  if (drifting && BAND_TIERS.indexOf(tier) < BAND_TIERS.indexOf("diagnose")) { tier = "diagnose"; reason = `the last ${config.driftRun} values are all more than one deviation on the bad side`; }
+  return { ...result, tier, reason };
+}
+
+/** How far back an episode is searched. ponytail: a run longer than this restarts its key every sample, so the open-card rule in Tasks holds it to one card. */
+export const EPISODE_LOOKBACK = 200;
+/**
+ * `controlBands` for the newest value, plus the breach episode it belongs to: the trailing run of values whose own tier (computed from
+ * the values before each, with nothing after) was not `ok`. The episode is the task that started the run, so a sustained shift keeps one
+ * key for as long as it lasts, and it is derived from history alone, so it survives a restart.
+ */
+export function controlEpisode(points: readonly { value: number; task: number }[], metric: BandMetric, config: BandConfig): BandResult {
+  const now = controlBands(points, metric, config);
+  if (now.tier === "ok") return now;
+  let start = points.length - 1;
+  for (let end = points.length - 2; end >= 0 && points.length - 1 - end <= EPISODE_LOOKBACK; end--) {
+    if (controlBands(points.slice(0, end + 1), metric, config).tier === "ok") break;
+    start = end;
+  }
+  return { ...now, episode: points[start]!.task };
+}
+
+export interface MetricsReport {
+  since: number | null;
+  tasks: number;
+  withheldPrivate: number;
+  metrics: {
+    acceptance_to_plan_ms: Summary; acceptance_to_first_review_ms: Summary; acceptance_to_merge_ms: Summary;
+    first_pass_approval: { n: number; unknown: number; rate: number | null };
+    rework_rounds: Summary;
+    first_pass_check: { n: number; unknown: number; rate: number | null };
+    same_head_ci_reruns: Summary;
+    stale_head_re_reviews: Summary;
+  };
+  stalls: StallCounts;
+  bands: BandResult[] | "off";
+}
+
+const rate = (values: readonly (number | null)[]) => {
+  const known = values.filter((value): value is number => value !== null);
+  return { n: known.length, unknown: values.length - known.length, rate: known.length ? round(known.reduce((sum, value) => sum + value, 0) / known.length) : null };
+};
+
+/**
+ * The whole report from board tasks. `since` keeps samples that count at or after it; `mergedAt` and `ciReruns` come from bounded
+ * PR readbacks keyed by task id and are optional. Private tasks are counted as withheld and read for nothing else.
+ */
+export function sdlcMetrics(tasks: readonly MetricTask[], opts: { since?: number; bands?: BandsConfig; stalls?: StallCounts; mergedAt?: Readonly<Record<number, number>>; ciReruns?: Readonly<Record<number, number | null>> } = {}): MetricsReport {
+  const visible = tasks.filter(task => !task.private);
+  const all = visible.map(task => taskSample(task, { mergedAt: opts.mergedAt?.[task.id], ciReruns: opts.ciReruns?.[task.id] }));
+  const samples = opts.since === undefined ? all : all.filter(sample => sample.at >= opts.since!);
+  const bands: BandResult[] | "off" = opts.bands && Object.keys(opts.bands).length
+    ? BAND_METRICS.flatMap(metric => opts.bands![metric] ? [controlEpisode(series(samples, metric), metric, opts.bands![metric]!)] : [])
+    : "off";
+  return {
+    since: opts.since ?? null, tasks: samples.length, withheldPrivate: tasks.length - visible.length,
+    metrics: {
+      acceptance_to_plan_ms: summarize(samples.map(s => s.acceptance_to_plan_ms)), acceptance_to_first_review_ms: summarize(samples.map(s => s.acceptance_to_first_review_ms)),
+      acceptance_to_merge_ms: summarize(samples.map(s => s.acceptance_to_merge_ms)),
+      first_pass_approval: rate(samples.map(s => s.first_pass_approval)), rework_rounds: summarize(samples.map(s => s.rework_rounds)),
+      first_pass_check: rate(samples.map(s => s.first_pass_check)), same_head_ci_reruns: summarize(samples.map(s => s.same_head_ci_reruns)),
+      stale_head_re_reviews: summarize(samples.map(s => s.stale_head_re_reviews)),
+    },
+    stalls: opts.stalls ?? { open: 0, byKind: {}, doneWithoutWrites: 0 }, bands,
+  };
+}
+
+const BAND_KEYS = ["window", "min_samples", "log_sigma", "diagnose_sigma", "propose_sigma", "drift_run", "min_delta"] as const;
+/**
+ * `[bands.<metric>]` tables of sdlc.toml. Every field is optional and bounded; an unknown metric or field is refused with its
+ * path, and the tiers must be ordered log <= diagnose <= propose so a breach never skips a tier it is meant to pass through.
+ */
+export function bandsConfig(value: unknown): BandsConfig {
+  if (value === undefined) return {};
+  const fail = (path: string, why: string): never => { throw new Error(`sdlc.bands${path}: ${why}`); };
+  if (!value || typeof value !== "object" || Array.isArray(value)) return fail("", "expected a table");
+  const out: BandsConfig = {};
+  for (const [metric, raw] of Object.entries(value as Record<string, unknown>)) {
+    if (!(BAND_METRICS as readonly string[]).includes(metric)) fail(`.${metric}`, `unknown metric (use ${BAND_METRICS.join(", ")})`);
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) fail(`.${metric}`, "expected a table");
+    const row = raw as Record<string, unknown>;
+    for (const key of Object.keys(row)) if (!(BAND_KEYS as readonly string[]).includes(key)) fail(`.${metric}.${key}`, "unknown field");
+    const number = (key: typeof BAND_KEYS[number], fallback: number, min: number, max: number, integer: boolean) => {
+      const given = row[key] ?? fallback;
+      if (typeof given !== "number" || !Number.isFinite(given) || given < min || given > max || integer && !Number.isSafeInteger(given)) fail(`.${metric}.${key}`, `expected ${integer ? "an integer" : "a number"} from ${min} to ${max}`);
+      return given as number;
+    };
+    const m = metric as BandMetric;
+    const config: BandConfig = {
+      window: number("window", DEFAULT_BAND.window, 4, 200, true), minSamples: number("min_samples", DEFAULT_BAND.minSamples, 3, 200, true),
+      logSigma: number("log_sigma", DEFAULT_BAND.logSigma, 0.5, 20, false), diagnoseSigma: number("diagnose_sigma", DEFAULT_BAND.diagnoseSigma, 0.5, 20, false),
+      proposeSigma: number("propose_sigma", DEFAULT_BAND.proposeSigma, 0.5, 20, false), driftRun: number("drift_run", DEFAULT_BAND.driftRun, 3, 50, true),
+      minDelta: number("min_delta", DEFAULT_MIN_DELTA[m], 0, 1e12, false),
+    };
+    if (config.minSamples > config.window) fail(`.${metric}.min_samples`, "must not exceed window");
+    if (!(config.logSigma <= config.diagnoseSigma && config.diagnoseSigma <= config.proposeSigma)) fail(`.${metric}`, "tiers must be ordered log_sigma <= diagnose_sigma <= propose_sigma");
+    out[m] = config;
+  }
+  return out;
+}