@staix/agent-hub 0.12.36 → 0.12.37

package/src/hub/memory-profile.ts

@@ -1,7 +1,7 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import {
-  CandidateStore, MemoryStore, realPath, memoryHome, resolveProfile,
+  CandidateStore, MemoryStore, realPath, memoryHome, memoryProjectKey, openShardStore, readShardedSelection, resolveAlias, resolveProfile, resolveShardProfile,
   type BoundProfile, type ProfileInput, type StoreOptions,
 } from "@staix/agent-mem";
 import packageJson from "../../package.json";
@@ -39,6 +39,14 @@ function assertLoadedAgentMem(): void {
 }
 export const MEMORY_PROFILE_UNAVAILABLE = "memory profile unavailable; inspect the selector and generation state, run ahub memory profile-check; use amem migrate --deactivate only to stop using the selected generation";
 const UNAVAILABLE = MEMORY_PROFILE_UNAVAILABLE;
+/** agent-mem#15 T2: a split marker that is not active (captured, malformed) is never read as an empty or legacy store. */
+export const MEMORY_SPLIT_INCOMPLETE = "memory home has a curated split that is not active; finish it with amem migrate --shards --resume, then restart the hub";
+/** Hub memory options: the project key selects this project's shard once the home is split. */
+/**
+ * Hub memory options. `project` is the bound (alias-resolved) key; `projectKey`, when given, is the raw key it came
+ * from, and the entry fence latches the binding unavailable once the alias log maps it elsewhere.
+ */
+export type ProfileMemoryOptions = Omit<StoreOptions, "memoryDir"> & { project?: string; projectKey?: string };
 
 /** No handle was opened; distinct from an unavailable, still-bound handle. */
 export interface UnboundMemoryProfileReceipt {
@@ -70,7 +78,25 @@ function canonicalHome(path: string): string {
 }
 function sameProfile(a: BoundProfile, b: BoundProfile): boolean {
   return a.home === b.home && a.dir === b.dir && a.kind === b.kind
-    && a.generation === b.generation && a.selectorRevision === b.selectorRevision;
+    && a.generation === b.generation && a.selectorRevision === b.selectorRevision
+    && !!a.sharded === !!b.sharded && a.shardKey === b.shardKey && !!a.shardUser === !!b.shardUser;
+}
+// lstat, not exists: a dangling or unreadable marker is still a marker and must fail closed.
+const splitMarked = (home: string) => lstatSync(join(home, "shards.json"), { throwIfNoEntry: false }) !== undefined;
+/** Refuse an inactive split before any shard read, so the remedy names resume rather than the generic profile check. */
+function assertActiveSplit(home: string): void {
+  try { readShardedSelection(home); } catch { throw new Error(MEMORY_SPLIT_INCOMPLETE); }
+}
+/**
+ * The one profile a binding may hold: this project's shard on a split home, the selected profile otherwise.
+ * ponytail: the entry fence re-checks the project shard only; the user overlay shares its selection and selector
+ * revision, so its own seal or machine drift goes unchecked. Add resolveShardProfile(home, { user: true }) if needed.
+ */
+function currentProfile(home: string, project: string | undefined): BoundProfile {
+  if (!splitMarked(home)) return resolveProfile(home);
+  assertActiveSplit(home);
+  if (!project) throw new Error(UNAVAILABLE);
+  return resolveShardProfile(home, { project });
 }
 function homeFor(opts: Pick<StoreOptions, "home">): string {
   return canonicalHome(opts.home === undefined ? memoryHome() : join(canonicalHome(opts.home), "memory"));
@@ -83,6 +109,14 @@ function receipt(profile: BoundProfile, state: MemoryProfileReceipt["state"], sk
   };
 }
 
+/**
+ * The project key agent-mem's own CLI binds: memoryProjectKey(cwd) through the person-reviewed alias log of the
+ * canonical memory home. The daemon and `ahub memory`/`ahub goal` use it so both open the same shard and rows.
+ */
+export function memoryProjectFor(cwd: string, opts: Pick<StoreOptions, "home"> = {}): string {
+  return resolveAlias(homeFor(opts), memoryProjectKey(cwd));
+}
+
 /** Inspect selection without constructing a store, index, or candidate sidecar. */
 export function selectedMemoryProfile(opts: StoreOptions = {}): MemoryProfileReceipt {
   assertLoadedAgentMem();
@@ -95,14 +129,20 @@ export class MemoryProfileBinding {
   readonly explicitProfile: ProfileInput;
   private readonly options: Pick<StoreOptions, "home">;
   private readonly directMemoryDir: string | undefined;
+  /** The shard key on a split home; unused on an unsplit one. */
+  private readonly project: string | undefined;
+  /** The raw key `project` was resolved from; an alias added later must not leave writes on the old key. */
+  private readonly projectKey: string | undefined;
   private unavailable = false;
 
-  constructor(opts: StoreOptions = {}, private readonly onUnavailable?: (neutralReason: string) => void, directMemoryDir?: string) {
+  constructor(opts: ProfileMemoryOptions = {}, private readonly onUnavailable?: (neutralReason: string) => void, directMemoryDir?: string) {
     assertLoadedAgentMem();
     this.options = { home: opts.home };
     this.directMemoryDir = directMemoryDir;
+    this.project = opts.project;
+    this.projectKey = opts.projectKey;
     this.home = directMemoryDir === undefined ? homeFor(this.options) : canonicalHome(directMemoryDir);
-    this.profile = Object.freeze({ ...resolveProfile(this.home) });
+    this.profile = Object.freeze({ ...currentProfile(this.home, this.project) });
     this.explicitProfile = this.profile.kind === "shared-v1" ? "shared-v1" : Object.freeze({ generation: this.profile.generation! });
   }
 
@@ -110,8 +150,9 @@ export class MemoryProfileBinding {
     if (this.unavailable) throw new Error(UNAVAILABLE);
     try {
       const currentHome = this.directMemoryDir === undefined ? homeFor(this.options) : canonicalHome(this.directMemoryDir);
-      const current = resolveProfile(currentHome);
+      const current = currentProfile(currentHome, this.project);
       if (currentHome !== this.home || !sameProfile(current, this.profile)) throw new Error(UNAVAILABLE);
+      if (this.projectKey !== undefined && resolveAlias(currentHome, this.projectKey) !== this.project) throw new Error(UNAVAILABLE);
     } catch {
       this.invalidate();
       throw new Error(UNAVAILABLE);
@@ -149,12 +190,27 @@ export class MemoryProfileBinding {
   }
 }
 
-export function openProfileMemory(opts: StoreOptions = {}, onUnavailable?: (neutralReason: string) => void): {
+export function openProfileMemory(opts: ProfileMemoryOptions = {}, onUnavailable?: (neutralReason: string) => void): {
   store: MemoryStore; binding: MemoryProfileBinding;
 } {
-  const binding = new MemoryProfileBinding(opts, onUnavailable);
-  binding.assertCurrent();
-  const raw = new MemoryStore({ ...opts, profile: binding.explicitProfile });
+  const { project, ...storeOptions } = opts;
+  const home = homeFor(opts);
+  let raw: MemoryStore, binding: MemoryProfileBinding;
+  if (splitMarked(home)) {
+    // agent-mem#15 T2: a plain MemoryStore refuses a split home. The shard store opens this project's shard (created on
+    // first use) with the user shard as its overlay; the binding is resolved after it, since a new shard has no seal yet.
+    assertActiveSplit(home);
+    if (!project) throw new Error(UNAVAILABLE);
+    // The canonical memory directory the binding resolves: a lexical home (a symlinked AGENTHUB_HOME or memory dir)
+    // would give the shard a different profile.home and dir than the binding compares against.
+    raw = openShardStore({ ...storeOptions, home: undefined, memoryDir: home, project });
+    try { binding = new MemoryProfileBinding(opts, onUnavailable); }
+    catch (error) { raw.close(); throw error; }
+  } else {
+    binding = new MemoryProfileBinding(opts, onUnavailable);
+    binding.assertCurrent();
+    raw = new MemoryStore({ ...storeOptions, profile: binding.explicitProfile });
+  }
   try {
     binding.assertCurrent();
     if (!sameProfile(raw.profile, binding.profile)) throw new Error(UNAVAILABLE);
@@ -172,7 +228,7 @@ export function openProfileMemory(opts: StoreOptions = {}, onUnavailable?: (neut
 export function bindProfileMemory(store: MemoryStore, onUnavailable?: (neutralReason: string) => void): {
   store: MemoryStore; binding: MemoryProfileBinding;
 } {
-  const binding = new MemoryProfileBinding({}, onUnavailable, store.profile.home);
+  const binding = new MemoryProfileBinding({ project: store.profile.shardKey }, onUnavailable, store.profile.home);
   binding.assertCurrent();
   if (!sameProfile(store.profile, binding.profile)) throw new Error(UNAVAILABLE);
   return { store, binding };

package/src/hub/planning.ts

@@ -1,3 +1,4 @@
+import type { ReleaseTrainData } from "./sdlc-release.ts";
 import type { Task } from "./board.ts";
 
 export const BACKLOG_SPLIT_SCREEN_TIMEOUT_MS = 8000;
@@ -28,6 +29,7 @@ export function planningWipLimits(input: unknown): Record<string, number> {
 export const RELEASE_STATES = ["planning", "active", "frozen", "shipped", "dropped"] as const;
 export type ReleaseState = (typeof RELEASE_STATES)[number];
 export interface Release {
+  train?: ReleaseTrainData;
   id: number; name: string; goal: string; order: number; state: ReleaseState;
   plannedStart: number | null; cut: number | null; ship: number | null;
   activatedAt: number | null; frozenAt: number | null; shippedAt: number | null;

package/src/hub/release-admission.ts

@@ -0,0 +1,64 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { spawn } from "node:child_process";
+import { hubGitSync } from "./git.ts";
+import { hostExecutable } from "./host-executable.ts";
+import { childEnv, stopOwnedProcess } from "./child-process.ts";
+import { detectTooling } from "./tooling.ts";
+
+export interface ReleaseHostAdmission { admitted: boolean; reason?: string; current?: () => boolean; close?: () => Promise<void> }
+const READY = "AHUB_RELEASE_SLOT_READY\n";
+const HOLD = 'process.stdout.write("AHUB_RELEASE_SLOT_READY\\n");process.stdin.resume();process.stdin.on("end",()=>process.exit(0));';
+/** Hold the installed controller's repository lease through the synchronous scope freeze. No caller command. */
+export function readReleaseHostAdmission(cwd: string): Promise<ReleaseHostAdmission> {
+  const common = hubGitSync(["rev-parse", "--path-format=absolute", "--git-common-dir"], { cwd, encoding: "utf8", timeout: 1000, maxBuffer: 4096 });
+  const directory = common.stdout?.trim();
+  if (common.status !== 0 || !directory) return Promise.resolve({ admitted: false, reason: "repository resource identity unavailable" });
+  const locked = () => existsSync(join(directory, "ahub-heavy.lock"));
+  if (locked()) return Promise.resolve({ admitted: false, reason: "repository heavy-job slot held" });
+  return new Promise(resolve => {
+    let executable: string;
+    try { executable = hostExecutable("dot", cwd); } catch { resolve({ admitted: false, reason: "host resource controller unavailable" }); return; }
+    const env = childEnv();
+    delete env.DOT_ADMISSION_SCOPE; // A long-lived daemon must not inherit an expired launcher lease.
+    const child = spawn(executable, ["admit", "--wait", "0s", "--json", "--", process.execPath, "-e", HOLD], { cwd, env, detached: true, stdio: ["pipe", "pipe", "pipe"] });
+    let output = "", bytes = 0, invalid = false, admitted = false;
+    const stop = () => { invalid = true; void stopOwnedProcess(child, { group: true }).catch(() => {}); };
+    // ponytail: one five-second metadata cut lease, never a build lease. Heavy preparation runs through its own admission.
+    const timer = setTimeout(() => { stop(); resolve({ admitted: false, reason: "host resource admission timed out" }); }, 5000);
+    child.stdin.on("error", () => {});
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", chunk => {
+      if (invalid) return;
+      output += chunk; bytes += Buffer.byteLength(chunk);
+      if (bytes > 16 * 1024 || !READY.startsWith(output) && output !== READY) { stop(); resolve({ admitted: false, reason: "host resource admission unknown" }); return; }
+      if (!admitted && output === READY && !locked()) {
+        admitted = true;
+        resolve({ admitted: true, current: () => !invalid && child.exitCode === null && child.signalCode === null && !locked(), close: async () => {
+          clearTimeout(timer);
+          if (child.exitCode === null && child.signalCode === null) {
+            await new Promise<void>(done => {
+              const grace = setTimeout(done, 500);
+              child.once("close", () => { clearTimeout(grace); done(); });
+              child.stdin.end();
+            });
+          }
+          await stopOwnedProcess(child, { group: true });
+        } });
+      }
+    });
+    child.stderr.on("data", (chunk: Buffer) => { bytes += chunk.length; if (bytes > 16 * 1024) stop(); });
+    child.once("error", () => { invalid = true; clearTimeout(timer); resolve({ admitted: false, reason: "host resource controller unavailable" }); });
+    child.once("close", async code => {
+      clearTimeout(timer); invalid = true;
+      if (admitted) return;
+      if (code === 75) { resolve({ admitted: false, reason: "host resource admission deferred (busy repository or pressure)" }); return; }
+      // Diagnose a failed invocation with the same bounded identity probe used by the tooling inventory (#351).
+      // This readback never grants admission or substitutes for the controller's held-lease handshake.
+      const tooling = await detectTooling("hub", { cwd, path: dirname(executable) }).catch(() => undefined);
+      resolve({ admitted: false, reason: tooling && !tooling.some(addon => addon.name === "dot-admit")
+        ? "host resource controller unavailable (dot is not the resource controller; install dot-admit or fix PATH)"
+        : "host resource admission unknown" });
+    });
+  });
+}

package/src/hub/reviewer-pool-config.ts

@@ -0,0 +1,11 @@
+export interface ReviewerPoolConfig { pool: string[]; rerotate: boolean }
+
+/** Kind order is project policy; capability and isolation evidence remain host-owned registry facts. */
+export function reviewerPoolConfig(raw: unknown, defaults: readonly string[], known: readonly string[]): ReviewerPoolConfig {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("review must be an object");
+  const value = raw as Record<string, unknown>;
+  const pool = value.pool === undefined ? defaults : value.pool;
+  if (!Array.isArray(pool) || pool.length < 1 || pool.length > 16 || pool.some(kind => typeof kind !== "string" || !/^[a-z][a-z0-9-]{0,31}$/.test(kind) || !known.includes(kind)) || new Set(pool).size !== pool.length) throw new Error("review.pool must list 1..16 distinct known kinds");
+  if (value.rerotate !== undefined && typeof value.rerotate !== "boolean") throw new Error("review.rerotate must be a boolean");
+  return { pool: [...pool], rerotate: value.rerotate === true };
+}

package/src/hub/reviewer-pool.ts

@@ -0,0 +1,70 @@
+export type ReviewerPoolReason = "rotation" | "implementer skip" | "unavailable skip" | "same-family fallback";
+export interface ReviewerPoolCandidate { id: string; kind: string; family: string; blocked?: string }
+export interface ReviewerPoolInput {
+  pool: readonly string[];
+  candidates: readonly ReviewerPoolCandidate[];
+  implementerFamily?: string;
+  seed: number;
+  continuityFamily?: string;
+  rerotate?: boolean;
+  failed?: readonly string[];
+}
+export interface ReviewerPoolSelection {
+  reviewer: string | null;
+  family?: string;
+  reason?: ReviewerPoolReason;
+  walk: readonly { id: string; kind: string; family: string; reason: string }[];
+  blocked?: "no reviewer can run";
+}
+
+/** Pure selection: caller supplies declared candidates and current availability, never inferred authority. */
+export function selectReviewerPool(input: ReviewerPoolInput): ReviewerPoolSelection {
+  const kinds = [...new Set(input.pool)];
+  const walk: { id: string; kind: string; family: string; reason: string }[] = [];
+  if (!kinds.length) return { reviewer: null, walk, blocked: "no reviewer can run" };
+  const seed = Number.isSafeInteger(input.seed) ? input.seed : 0;
+  const start = ((seed % kinds.length) + kinds.length) % kinds.length;
+  const rotated = [...kinds.slice(start), ...kinds.slice(0, start)];
+  const slots = rotated.flatMap(kind => {
+    const declared = input.candidates.filter(candidate => candidate.kind === kind).sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+    return declared.length ? declared : [{ id: "", kind, family: "", blocked: "no declared reviewer" }];
+  });
+  let ordered = slots;
+  // Preserve the rotated order within each family, including sibling instance ids.
+  const continuity = !input.rerotate && input.continuityFamily !== undefined && input.continuityFamily !== input.implementerFamily;
+  if (continuity) ordered = [...ordered.filter(candidate => candidate.family === input.continuityFamily), ...ordered.filter(candidate => candidate.family !== input.continuityFamily)];
+  const failed = new Set(input.failed ?? []);
+  let skippedOwner = false, skippedUnavailable = false;
+  const unavailable = (candidate: ReviewerPoolCandidate) => failed.has(candidate.id) ? "start failed for this review" : candidate.blocked;
+  const record = (candidate: ReviewerPoolCandidate, reason: string) => { walk.push({ id: candidate.id, kind: candidate.kind, family: candidate.family, reason }); };
+  for (const candidate of ordered) {
+    if (!candidate.id) {
+      skippedUnavailable = true;
+      record(candidate, "no declared reviewer");
+      continue;
+    }
+    if (input.implementerFamily !== undefined && candidate.family === input.implementerFamily) {
+      skippedOwner = true;
+      record(candidate, "implementer skip");
+      continue;
+    }
+    const blocked = unavailable(candidate);
+    if (blocked !== undefined) {
+      skippedUnavailable = true;
+      record(candidate, `unavailable skip: ${blocked}`);
+      continue;
+    }
+    const reason: ReviewerPoolReason = skippedUnavailable ? "unavailable skip" : skippedOwner ? "implementer skip" : "rotation";
+    record(candidate, `selected (${continuity && candidate.family === input.continuityFamily ? "continuity" : reason})`);
+    return { reviewer: candidate.id, family: candidate.family, reason, walk };
+  }
+  // The caller supplies separate fresh reviewer instances; this does not authorize an implementer's own session.
+  for (const candidate of ordered) {
+    if (!candidate.id || input.implementerFamily === undefined || candidate.family !== input.implementerFamily) continue;
+    const blocked = unavailable(candidate);
+    if (blocked !== undefined) { record(candidate, `unavailable skip: ${blocked}`); continue; }
+    record(candidate, "selected (same-family fallback)");
+    return { reviewer: candidate.id, family: candidate.family, reason: "same-family fallback", walk };
+  }
+  return { reviewer: null, walk, blocked: "no reviewer can run" };
+}

package/src/hub/routing.ts

@@ -1,3 +1,4 @@
+import { selectReviewerPool, type ReviewerPoolSelection } from "./reviewer-pool.ts";
 import { ADAPTERS, definitionOf, kindOf, familyOf } from "../adapters/registry.ts";
 import { readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
@@ -288,6 +289,8 @@ export const peerEntry = <T>(map: Readonly<Record<string, T>> | undefined, peer:
 export type RoutingRefusalCode = "instance" | "family" | "tests" | "spec" | "roster" | "pull-only" | "not-attached" | "excluded" | "owner-admission" | "offline" | "paused" | "failing" | "pii" | "policy";
 export interface RoutingRefusal { peer: PeerId; role: "owner" | "reviewer"; code: RoutingRefusalCode; reason: string }
 export interface Assignment {
+  reviewSelection?: ReviewerPoolSelection;
+  reviewBlocked?: true;
   /** A same-family reviewer was chosen only because no other family was eligible. */
   sameFamilyFallback?: true;
   /** #223 R5: the planner reviews because the declared reviewer-only instance was not eligible. */
@@ -309,7 +312,7 @@ export interface Assignment {
  * prints its trace. `states`: effective bus states of attached peers (a peer that is not in the map is not attached).
  */
 export function assign(
-  task: Pick<Task, "class" | "signals" | "reserved"> & Partial<Pick<Task, "state" | "title" | "detail" | "refs" | "external">>,
+  task: Pick<Task, "class" | "signals" | "reserved"> & Partial<Pick<Task, "state" | "title" | "detail" | "refs" | "external" | "id" | "sdlc" | "history">>,
   states: Record<PeerId, PeerState>,
   routing: Routing,
   opts: InstanceRoutingOptions & {
@@ -324,6 +327,7 @@ export function assign(
     pullOnly?: PeerId[];
     namedOwner?: PeerId;
     namedReviewer?: PeerId;
+    reviewPool?: { pool: readonly string[]; rerotate?: boolean; failed?: readonly string[]; required?: boolean };
     candidates?: PeerId[];
     notReviewer?: PeerId;
     waitsFor?: number[];
@@ -364,6 +368,8 @@ export function assign(
   const refusals = new Map<string, RoutingRefusal>();
   const blocked = (peer: PeerId, role: "owner" | "reviewer"): string | undefined => {
     const deny = (code: RoutingRefusalCode, reason: string): string => { refusals.set(`${role}:${peer}`, { peer, role, code, reason }); return reason; };
+    const unavailable = role === "reviewer" ? definitionOf(peer, opts.instances)?.reviewer?.unavailable : undefined;
+    if (unavailable) return deny("policy", unavailable);
     if (role === "owner" && opts.capabilities && !pii) {
       const caps = peerEntry(opts.capabilities, peer);
       if (needsTests && !caps?.tests) return deny("tests", `missing tests: ${caps?.testsReason ?? "capability unavailable"}`);
@@ -462,6 +468,8 @@ export function assign(
   let reviewer: PeerId | undefined;
   let sameFamilyFallback = false;
   let plannerFallback = false;
+  let reviewSelection: ReviewerPoolSelection | undefined;
+  let reviewBlocked = false;
   if (task.class !== "review") {
     if (pii) trace.push("reviewer: user (pii: no second on-prem peer; ahub review <id> <verdict>)");
     else {
@@ -475,7 +483,38 @@ export function assign(
       const sameFamily = (peer: PeerId) => ownerFamily !== undefined && familyOf(peer, opts.instances) === ownerFamily;
       const independent = ownerFamily === undefined ? [] : automatic.filter(peer => peer !== reviewOwner && !blocked(peer, "reviewer") && !sameFamily(peer));
       const named = opts.namedReviewer;
-      if (named !== undefined && named !== reviewOwner && !blocked(named, "reviewer") && sameFamily(named) && independent.length) {
+      const declaredPool = opts.reviewPool && named === undefined ? Object.keys(opts.instances ?? {}).flatMap(id => {
+        const roles = peerEntry(opts.roles, id), definition = definitionOf(id, opts.instances);
+        const kind = kindOf(id, opts.instances), family = familyOf(id, opts.instances);
+        if (roles?.length !== 1 || roles[0] !== "reviewer" || !definition?.routing?.reviewOnly || !kind || !family) return [];
+        const reason = id === reviewOwner ? "is the owner" : definition.reviewer?.unavailable ?? blocked(id, "reviewer")
+          ?? (states[id] === "paused" ? "paused" : undefined)
+          ?? peerEntry(opts.held, id)
+          ?? ((peerEntry(opts.quota, id)?.headroom ?? Infinity) <= 0 ? "quota exhausted" : undefined);
+        return [{ id, kind, family, ...(reason === undefined ? {} : { blocked: reason }) }];
+      }) : [];
+      if (declaredPool.length || opts.reviewPool?.required && named === undefined) {
+        for (const candidate of declaredPool) if (!opts.reviewPool!.pool.includes(candidate.kind)) trace.push(`  reviewer pool candidate ${candidate.id} (${candidate.family}): unavailable skip: ${candidate.blocked ?? "kind outside configured pool"}`);
+        const last = task.history?.findLast(entry => entry.event === "changes_requested");
+        const continuityFamily = last && "reviewerFamily" in last && typeof last.reviewerFamily === "string" ? last.reviewerFamily : last ? familyOf(last.by, opts.instances) : undefined;
+        const pr = task.sdlc?.pr;
+        const seed = typeof pr === "number" && Number.isSafeInteger(pr) && pr > 0 ? pr : task.id ?? 0;
+        reviewSelection = selectReviewerPool({ pool: opts.reviewPool!.pool, candidates: declaredPool, seed, implementerFamily: ownerFamily, continuityFamily, rerotate: opts.reviewPool!.rerotate, failed: opts.reviewPool!.failed });
+        for (const row of reviewSelection.walk) trace.push(row.id ? `  reviewer pool candidate ${row.id} (${row.family}): ${row.reason}` : `  reviewer pool kind ${row.kind}: ${row.reason}`);
+        reviewer = reviewSelection.reviewer ?? "user";
+        if (reviewSelection.blocked) {
+          trace.push("blocked: no reviewer can run");
+          // Optional defaults retain the legacy planner escape when no fresh reviewer can run.
+          const planners = opts.reviewPool?.required ? [] : automatic.filter(peer => peer !== reviewOwner && peerEntry(opts.roles, peer)?.includes("planner") && !definitionOf(peer, opts.instances)?.routing?.reviewOnly && !blocked(peer, "reviewer"));
+          const otherFamily = planners.filter(peer => !sameFamily(peer));
+          const planner = pick(otherFamily.length ? otherFamily : planners, "reviewer", reviewOwner);
+          if (planner) {
+            reviewer = planner;
+            plannerFallback = true;
+            trace.push(`  planner fallback: no declared reviewer-only instance is eligible; ${planner} reviews`);
+          } else reviewBlocked = true;
+        }
+      } else if (named !== undefined && named !== reviewOwner && !blocked(named, "reviewer") && sameFamily(named) && independent.length) {
         const reason = `same family as ${reviewOwner}; eligible other-family reviewer available`;
         refusals.set(`reviewer:${named}`, { peer: named, role: "reviewer", code: "family", reason });
         trace.push(`  reviewer candidate ${named}: skipped, ${reason}`);
@@ -505,7 +544,7 @@ export function assign(
   const piBackend = policy?.pi_backend;
   if (owner && definitionOf(owner, opts.instances)?.routing?.trace === "route") trace.push(`route: ${route ?? "(none)"}, fixed_model ${fixedModel}`);
   if (owner && definitionOf(owner, opts.instances)?.routing?.trace === "backend") trace.push(`${definitionOf(owner, opts.instances)!.routing!.backendLabel} decision: backend ${piBackend ?? "dgx"}${task.signals.includes("long_context") ? `, context limit ${piBackend === "mlx" ? routing.pi.mlx_max_context_tokens : routing.pi.dgx_max_context_tokens}` : ""}`);
-  return { ...(sameFamilyFallback ? { sameFamilyFallback: true as const } : {}), ...(plannerFallback ? { plannerFallback: true as const } : {}), ...(owner ? { owner } : {}), ...(pii ? { reviewer: "user" } : reviewer ? { reviewer } : {}), ...(route ? { route } : {}), fixedModel, ...(piBackend ? { piBackend } : {}), ...(unreserved ? { unreserved } : {}), ...(refusals.size ? { refusals: [...refusals.values()] } : {}), trace };
+  return { ...(reviewSelection ? { reviewSelection } : {}), ...(reviewBlocked ? { reviewBlocked: true as const } : {}), ...(sameFamilyFallback ? { sameFamilyFallback: true as const } : {}), ...(plannerFallback ? { plannerFallback: true as const } : {}), ...(owner ? { owner } : {}), ...(pii ? { reviewer: "user" } : reviewer ? { reviewer } : {}), ...(route ? { route } : {}), fixedModel, ...(piBackend ? { piBackend } : {}), ...(unreserved ? { unreserved } : {}), ...(refusals.size ? { refusals: [...refusals.values()] } : {}), trace };
 }
 
 /**

package/src/hub/sdlc-release.ts

@@ -1,3 +1,5 @@
+import type { Task } from "./board.ts";
+import type { Release } from "./planning.ts";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { childEnv, stopOwnedProcess } from "./child-process.ts";
@@ -123,3 +125,114 @@ export async function readReleaseReadiness(root: string, repo: string, liveIssue
   report.blockers.push("native acceptance and person release decision unverified");
   return report;
 }
+
+export type HotfixCause = "loss" | "security_privacy" | "upgrade_start_blocked" | "core_flow_no_workaround";
+export interface ReleaseTrainData {
+  hotfix?: { cause: HotfixCause; reason: string };
+  scope?: number[];
+  history: { at: number; by: string; event: "configured" | "cut" | "shipped"; scope?: number[]; ciRuns?: number; reviews?: number }[];
+}
+export const RELEASE_TRAIN_HISTORY_LIMIT = 256;
+const HOTFIX_CAUSES: readonly string[] = ["loss", "security_privacy", "upgrade_start_blocked", "core_flow_no_workaround"];
+const trainObject = (value: unknown): Record<string, unknown> => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("release train: expected an object");
+  return value as Record<string, unknown>;
+};
+const trainKeys = (value: Record<string, unknown>, keys: readonly string[]) => {
+  if (Object.keys(value).some(key => !keys.includes(key))) throw new Error("release train: unknown field");
+};
+const trainScope = (value: unknown): number[] => {
+  // ponytail: 1000 tasks per release; raise together with bounded report readers if larger trains are needed.
+  if (!Array.isArray(value) || value.length > 1000 || value.some(id => !Number.isSafeInteger(id) || id < 1) || new Set(value).size !== value.length) throw new Error("release train: invalid scope");
+  return [...value].sort((a, b) => a - b);
+};
+
+/** Structural validation only: the Tasks boundary screens reason text and establishes caller authority. */
+export function releaseTrainData(input: unknown): ReleaseTrainData {
+  const raw = trainObject(input); trainKeys(raw, ["hotfix", "scope", "history"]);
+  const result: ReleaseTrainData = { history: [] };
+  if (raw.hotfix !== undefined) {
+    const hotfix = trainObject(raw.hotfix); trainKeys(hotfix, ["cause", "reason"]);
+    if (typeof hotfix.cause !== "string" || !HOTFIX_CAUSES.includes(hotfix.cause) || typeof hotfix.reason !== "string" || !hotfix.reason.trim() || Buffer.byteLength(hotfix.reason) > 1000) throw new Error("release train: invalid hotfix cause or reason");
+    result.hotfix = { cause: hotfix.cause as HotfixCause, reason: hotfix.reason.trim() };
+  }
+  if (raw.scope !== undefined) result.scope = trainScope(raw.scope);
+  // ponytail: 256 recorded train events; archive settled release evidence before increasing this ceiling.
+  if (!Array.isArray(raw.history) || raw.history.length > RELEASE_TRAIN_HISTORY_LIMIT) throw new Error("release train: invalid history");
+  result.history = raw.history.map(value => {
+    const row = trainObject(value); trainKeys(row, ["at", "by", "event", "scope", "ciRuns", "reviews"]);
+    if (!Number.isSafeInteger(row.at) || (row.at as number) < 1 || (row.at as number) > 8_640_000_000_000_000 || typeof row.by !== "string" || !/^[a-z][a-z0-9-]{0,63}$/.test(row.by) || !["configured", "cut", "shipped"].includes(String(row.event))) throw new Error("release train: invalid history event");
+    const event: ReleaseTrainData["history"][number] = { at: row.at as number, by: row.by, event: row.event as "configured" | "cut" | "shipped" };
+    if (row.scope !== undefined) event.scope = trainScope(row.scope);
+    for (const key of ["ciRuns", "reviews"] as const) if (row[key] !== undefined) {
+      if (!Number.isSafeInteger(row[key]) || (row[key] as number) < 0 || (row[key] as number) > 1_000_000) throw new Error("release train: invalid resource count");
+      event[key] = row[key] as number;
+    }
+    return event;
+  });
+  if (result.history.some((row, index) => index > 0 && row.at < result.history[index - 1]!.at)) throw new Error("release train: history dates are out of order");
+  return result;
+}
+
+const storedTrain = (release: Release): ReleaseTrainData | undefined => {
+  const raw = (release as Release & { train?: ReleaseTrainData }).train;
+  if (raw === undefined) return undefined;
+  try { return releaseTrainData(raw); } catch { return undefined; }
+};
+
+/** Board metadata only; a trigger is a request to cut, never release authorization or native readiness. */
+export function releaseTrainReadiness(release: Release, tasks: Task[], now = Date.now()) {
+  const train = storedTrain(release), assigned = tasks.filter(task => task.release === release.id), frozen = ["frozen", "shipped"].includes(release.state);
+  const scope = frozen ? train?.scope : assigned.map(task => task.id);
+  const blockers: string[] = [];
+  if ((release as Release & { train?: ReleaseTrainData }).train !== undefined && !train) blockers.push("release train evidence unknown");
+  if (!scope) blockers.push("release scope unknown");
+  else if (!scope.length) blockers.push("release scope empty");
+  if (frozen && scope && JSON.stringify([...scope].sort((a, b) => a - b)) !== JSON.stringify(assigned.map(task => task.id).sort((a, b) => a - b))) blockers.push("frozen release scope changed");
+  const rows = new Map(tasks.map(task => [task.id, task]));
+  const states = (scope ?? []).map(id => {
+    const task = rows.get(id), state = task?.state ?? "unknown", ready = state === "approved";
+    if (!task) blockers.push(`task #${id}: scope evidence unknown`);
+    else if (task.release !== release.id) blockers.push(`task #${id}: release assignment changed`);
+    if (!ready) blockers.push(`task #${id}: not approved`);
+    return { id, state, ready };
+  });
+  const trigger: "tasks_approved" | "planned_date" | "waiting" = states.length && states.every(task => task.ready) && !blockers.length ? "tasks_approved"
+    : release.cut !== null && Number.isFinite(now) && release.cut <= now ? "planned_date" : "waiting";
+  return { trigger, tasks: states, blockers };
+}
+
+/** Counts are explicit recorded event deltas, not inferred from successful gates or absent history. */
+export function releaseMetrics(releases: Release[], tasks: Task[]) {
+  const unknown = new Set<number>(), shipped: { id: number; at: number }[] = [];
+  const approvalToReleaseMs: { release: number; task: number; ms: number | null }[] = [];
+  let hotfixCount = 0, knownKinds = 0, ciRuns = 0, reviews = 0, ciKnown = true, reviewsKnown = true;
+  const byTask = new Map(tasks.map(task => [task.id, task]));
+  const settled = releases.filter(release => release.state === "shipped");
+  for (const release of settled) {
+    const train = storedTrain(release);
+    if (!train?.history.length) { unknown.add(release.id); ciKnown = false; reviewsKnown = false; continue; }
+    knownKinds++;
+    if (train.hotfix) hotfixCount++;
+    for (const key of ["ciRuns", "reviews"] as const) {
+      const recorded = train.history.flatMap(event => event[key] === undefined ? [] : [event[key]!]);
+      if (!recorded.length) { unknown.add(release.id); if (key === "ciRuns") ciKnown = false; else reviewsKnown = false; }
+      else if (key === "ciRuns") ciRuns += recorded.reduce((sum, value) => sum + value, 0);
+      else reviews += recorded.reduce((sum, value) => sum + value, 0);
+    }
+    const event = [...train.history].reverse().find(row => row.event === "shipped");
+    if (!event || release.shippedAt !== event.at) { unknown.add(release.id); continue; }
+    shipped.push({ id: release.id, at: event.at });
+    const scope = train.scope ?? [...train.history].reverse().find(row => row.event === "cut")?.scope;
+    if (!scope) { unknown.add(release.id); continue; }
+    for (const id of scope) {
+      const task = byTask.get(id), approved = task?.history.findLast(row => row.at <= event.at && (row.event === "approved" || row.event === "done" && task.state === "approved" && task.reviewer === null))?.at ?? null;
+      const ms = approved !== null && approved <= event.at ? event.at - approved : null;
+      if (ms === null) unknown.add(release.id);
+      approvalToReleaseMs.push({ release: release.id, task: id, ms });
+    }
+  }
+  shipped.sort((a, b) => a.at - b.at || a.id - b.id);
+  const intervals = shipped.length !== releases.filter(release => release.state === "shipped").length ? [] : shipped.slice(1).map((row, index) => ({ from: shipped[index]!.id, to: row.id, ms: row.at - shipped[index]!.at }));
+  return { intervals, approvalToReleaseMs, hotfixCount: knownKinds === settled.length && knownKinds > 0 ? hotfixCount : null, hotfixRate: knownKinds === settled.length && knownKinds > 0 ? hotfixCount / knownKinds : null, ciRuns: ciKnown && settled.length ? ciRuns : null, reviews: reviewsKnown && settled.length ? reviews : null, unknown: [...unknown].sort((a, b) => a - b) };
+}