@staix/agent-hub 0.12.35 → 0.12.37

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,8 +289,12 @@ 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. */
+  plannerFallback?: true;
   refusals?: RoutingRefusal[];
   owner?: PeerId;
   reviewer?: PeerId;
@@ -307,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 & {
@@ -322,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[];
@@ -362,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"}`);
@@ -374,6 +382,7 @@ export function assign(
     if (opts.exclude?.includes(peer)) return deny("excluded", "excluded (declined or replaced)");
     if (role === "owner" && opts.excludeOwners?.includes(peer)) return deny("owner-admission", "owner admission: WIP or delivery hold");
     const adapter = definitionOf(peer, opts.instances);
+    if (role === "owner" && adapter?.routing?.reviewOnly) return deny("owner-admission", "owner admission: a review-only instance owns no task");
     if (role === "owner" && needsTests && adapter && adapter.kind !== peer) {
       if (!peerEntry(opts.roles, peer)?.includes("implementer")) return deny("owner-admission", "owner admission: declared write owner requires the current implementer role");
       if (peerEntry(opts.ownerIsolation, peer) !== true) return deny("owner-admission", "owner admission: declared write owner requires a verified isolated execution root");
@@ -458,6 +467,9 @@ 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 {
@@ -471,11 +483,53 @@ 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}`);
-      } else reviewer = pick(named === undefined ? independent.length ? independent : automatic : [named], "reviewer", reviewOwner, named === undefined);
+      } else {
+        // #223 R1: a declared instance that reviews and does not plan goes first, busy or not.
+        const holds = (peer: PeerId, role: string) => opts.roles?.[peer]?.includes(role) === true;
+        const dedicated = (peer: PeerId) => !!opts.instances && Object.hasOwn(opts.instances, peer) && holds(peer, "reviewer") && !holds(peer, "planner");
+        const pool = independent.length ? independent : automatic;
+        const ready = named === undefined ? pool.filter(peer => dedicated(peer) && peer !== reviewOwner && !blocked(peer, "reviewer")) : [];
+        reviewer = pick(named === undefined ? ready.length ? ready : pool : [named], "reviewer", reviewOwner, named === undefined);
+        if (named === undefined && !ready.length && reviewer && holds(reviewer, "planner") && Object.keys(opts.roles ?? {}).some(dedicated)) {
+          plannerFallback = true;
+          trace.push(`  planner fallback: no declared reviewer-only instance is eligible; ${reviewer} reviews`);
+        }
+      }
       if (reviewer && sameFamily(reviewer)) {
         sameFamilyFallback = true;
         trace.push(`  same-family fallback: ${reviewer} and ${reviewOwner} share ${ownerFamily}; no eligible other family`);
@@ -490,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 } : {}), ...(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) };
+}

package/src/hub/sdlc.ts

@@ -1,3 +1,4 @@
+import type { CostPlan } from "./cost-governance.ts";
 import { criteriaReceipt, type CriteriaReceipt, type CriteriaView, type LegacyPhaseReceipt } from "./workflow.ts";
 import { constants, openSync, fstatSync, readSync, closeSync } from "node:fs";
 import { join } from "node:path";
@@ -29,11 +30,21 @@ export interface StageDefinition { base: SdlcBaseStage; actor: string; entry_gat
 export type SdlcMode = "off" | "advise" | "enforce";
 /** `workflow: "gsd-lite"` marks the retired setting during its window (#481 S8): every task then needs a criteria checklist. */
 export interface SdlcConfig { workflow?: "gsd-lite"; mode: SdlcMode; requiredChecks: string[]; stages: SdlcStage[]; definitions?: Record<string, StageDefinition>; deprecations?: string[]; }
+export interface PlanReviewReceipt {
+  planner: string;
+  planningRevision: number;
+  recordedAt: number;
+  scope?: CostPlan;
+  issue?: PlanIssueMetadata;
+}
 export interface SdlcReceipt {
   stage: SdlcStage;
+  planReview?: PlanReviewReceipt;
   criteria?: CriteriaReceipt;
   /** Stored before #481 S8 and read as `criteria`; never written again. */
   phase?: LegacyPhaseReceipt;
+  /** The person's spec acceptance (#481 S1): set only by Tasks.acceptSpec, never by hub_sdlc_record. */
+  acceptance?: SpecAcceptance;
   repo?: string;
   issue?: number;
   pr?: number;
@@ -181,6 +192,8 @@ export function sdlcReceipt(value: unknown, previous: SdlcReceipt | undefined =
     if (!["passed", "failed", "unknown"].includes(String(raw.localResult))) throw new Error("sdlc receipt.localResult: expected passed, failed or unknown");
     next.localResult = raw.localResult as SdlcReceipt["localResult"];
   }
+  // An acceptance names one spec issue; relinking the receipt to another drops it (#481 S1).
+  if (next.repo !== previous.repo || next.issue !== previous.issue) delete next.acceptance;
   // A new artifact cannot inherit another PR's review or local gate.
   if (next.repo !== previous.repo || next.pr !== previous.pr) {
     delete next.head; delete next.observed;
@@ -199,7 +212,7 @@ export function parsePrEvidence(value: unknown): PrEvidence {
     const name = c.name ?? c.context;
     if (typeof name !== "string" || !name || name.length > 120) throw new Error("PR readback: invalid check identity");
     const native = c.conclusion ?? c.state;
-    const state = native === "SUCCESS" ? "passed" : ["FAILURE", "ERROR", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED"].includes(String(native)) ? "failed" : ["PENDING", "QUEUED", "IN_PROGRESS"].includes(String(c.status ?? native)) ? "pending" : "unknown";
+    const state = ["PENDING", "QUEUED", "IN_PROGRESS"].includes(String(c.status ?? native)) ? "pending" : native === "SUCCESS" ? "passed" : ["FAILURE", "ERROR", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED"].includes(String(native)) ? "failed" : "unknown";
     return { name, state } as PrEvidence["checks"][number];
   });
   const paths = p.files.map((f: Record<string, unknown>) => { if (typeof f.path !== "string" || !f.path || f.path.length > 1000) throw new Error("PR readback: invalid file identity"); return f.path; });
@@ -210,10 +223,26 @@ export function parsePrEvidence(value: unknown): PrEvidence {
     ...(sha(p.mergeCommit?.oid) ? { mergeCommit: p.mergeCommit.oid } : {}) };
 }
 
-export interface SdlcStatus { playbook?: string; criteria?: CriteriaView; mode: SdlcMode; stage: SdlcStage; definition?: StageDefinition; entry?: string[]; exit?: string[]; blockers: string[]; ready: boolean; actor: string; next: string; }
+/** Issue identity and edit times only; no body is fetched or stored. `lastEditedAt` moves on a body edit, not on comments. */
+export interface SpecEdit { lastEditedAt: string | null; updatedAt: string }
+export interface SpecAcceptance extends SpecEdit { repo: string; issue: number; acceptedAt: number }
+export type SpecState = "missing" | "current" | "changed" | "unknown";
+/** Whether the receipt's spec issue is accepted at its current body. `edit` undefined means the readback failed. */
+export function specState(receipt: SdlcReceipt | undefined, edit: SpecEdit | undefined): SpecState {
+  const accepted = receipt?.acceptance;
+  if (!accepted || accepted.repo !== receipt?.repo || accepted.issue !== receipt?.issue) return "missing";
+  if (!edit) return "unknown";
+  return edit.lastEditedAt === accepted.lastEditedAt ? "current" : "changed";
+}
+export const SPEC_STATE_TEXT: Record<Exclude<SpecState, "current">, string> = {
+  missing: "spec acceptance missing: the person runs ahub sdlc accept <task> --issue <n>",
+  changed: "spec changed after acceptance: the person re-accepts with ahub sdlc accept <task> --issue <n>",
+  unknown: "spec edit time unknown: the issue could not be read",
+};
+export interface SdlcStatus { spec?: { issue: number; state: SpecState }; playbook?: string; criteria?: CriteriaView; mode: SdlcMode; stage: SdlcStage; definition?: StageDefinition; entry?: string[]; exit?: string[]; blockers: string[]; ready: boolean; actor: string; next: string; }
 /** The acceptance-criteria checklist (#481 S8, Compliance pass) counts once recorded, and on every task under the retired gsd-lite setting. Off keeps #257's output. */
 export const criteriaRequired = (config: SdlcConfig, receipt: SdlcReceipt | undefined): boolean => config.workflow === "gsd-lite" || (config.mode !== "off" && !!checklistOf(receipt));
-export function sdlcStatus(config: SdlcConfig, receipt: SdlcReceipt | undefined, evidence?: PrEvidence, criteria?: CriteriaView): SdlcStatus {
+export function sdlcStatus(config: SdlcConfig, receipt: SdlcReceipt | undefined, evidence?: PrEvidence, criteria?: CriteriaView, specEdit?: SpecEdit): SdlcStatus {
   const stage = receipt?.stage ?? config.stages[0] ?? "spec", blockers: string[] = [];
   const definition = stageDefinition(config, stage);
   if (!definition) blockers.push("lifecycle stage definition unknown");
@@ -239,7 +268,9 @@ export function sdlcStatus(config: SdlcConfig, receipt: SdlcReceipt | undefined,
   const custom = config.definitions && definition ? stageGates(definition, blockers, [...viewBlockers, ...staleHead]) : undefined;
   if (custom) for (const blocker of [...custom.entry, ...custom.exit]) if (!blockers.includes(blocker)) blockers.push(blocker);
   const shown = criteria && (criteriaRequired(config, receipt) || definition && [...definition.entry_gates, ...definition.exit_gates].includes("criteria"));
-  return { ...(config.mode !== "off" && definition && playbookStage(definition.base) ? { playbook: playbookStage(definition.base) } : {}), ...(shown ? { criteria } : {}), ...(custom ? { definition, ...custom } : {}), mode: config.mode, stage, blockers, ready: blockers.length === 0,
+  // Shown, not counted as a readiness blocker: the spec gate is build entry (#481 S1).
+  const spec = config.mode !== "off" && receipt?.issue ? { spec: { issue: receipt.issue, state: specState(receipt, specEdit) } } : {};
+  return { ...spec, ...(config.mode !== "off" && definition && playbookStage(definition.base) ? { playbook: playbookStage(definition.base) } : {}), ...(shown ? { criteria } : {}), ...(custom ? { definition, ...custom } : {}), mode: config.mode, stage, blockers, ready: blockers.length === 0,
     actor: !definition ? "person" : shown && criteria.blockers.length ? "reviewer/person" : config.definitions ? definition.actor : baseActor(definition.base),
     next: blockers[0] ?? "person may inspect merge readiness; no automatic merge" };
 }
@@ -279,6 +310,20 @@ export const sdlcGh: SdlcGh = (args, timeoutMs = 10_000, cwd, maxOutputBytes = 2
   child.once("close", code => { clearTimeout(timer); resolve({ code: failed ? 1 : code ?? 1, stdout: failed ? "" : stdout }); });
 });
 
+/** Read-only, fixed argv: the issue's edit times, never its body. */
+export async function readSpecEdit(repoName: string, issue: number, run: SdlcGh = sdlcGh): Promise<SpecEdit | undefined> {
+  if (!repo(repoName) || !id(issue)) return undefined;
+  const [owner, name] = repoName.split("/");
+  try {
+    const out = await run(["api", "graphql", "-f", "query=query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){issue(number:$number){number lastEditedAt updatedAt}}}", "-f", `owner=${owner}`, "-f", `name=${name}`, "-F", `number=${issue}`]);
+    if (out.code !== 0) return undefined;
+    const found = JSON.parse(out.stdout)?.data?.repository?.issue;
+    const stamp = (v: unknown) => typeof v === "string" && v.length <= 40 && !Number.isNaN(Date.parse(v));
+    if (found?.number !== issue || !stamp(found.updatedAt) || (found.lastEditedAt !== null && !stamp(found.lastEditedAt))) return undefined;
+    return { lastEditedAt: found.lastEditedAt, updatedAt: found.updatedAt };
+  } catch { return undefined; }
+}
+
 export async function readSdlcPr(receipt: SdlcReceipt, run: SdlcGh = sdlcGh): Promise<PrEvidence | undefined> {
   if (!repo(receipt.repo) || !id(receipt.pr)) return undefined;
   try {
@@ -298,3 +343,159 @@ export async function readSdlcPr(receipt: SdlcReceipt, run: SdlcGh = sdlcGh): Pr
     return parsePrEvidence(p);
   } catch { return undefined; }
 }
+
+export interface PlanIssueMetadata {
+  repo: string;
+  issue: number;
+  state: "OPEN" | "CLOSED";
+  /** Body edit time; comment activity must never invalidate a plan review. */
+  editedAt: string;
+  /** Nullable GitHub body edit field, retained to compare independent S1 acceptance evidence. */
+  lastEditedAt?: string | null;
+}
+
+/** Metadata only: never request issue bodies or comments for a planning receipt. */
+export async function readPlanIssueMetadata(repository: string, number: number, run: SdlcGh = sdlcGh): Promise<PlanIssueMetadata | undefined> {
+  if (!repo(repository) || !id(number)) return undefined;
+  const [owner, name] = repository.split("/");
+  try {
+    const result = await run(["api", "graphql", "-f", "query=query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){issue(number:$number){number state createdAt lastEditedAt}}}", "-f", `owner=${owner}`, "-f", `name=${name}`, "-F", `number=${number}`], 10_000, undefined, 8 * 1024);
+    if (result.code !== 0 || Buffer.byteLength(result.stdout) > 8 * 1024) return undefined;
+    const response = JSON.parse(result.stdout);
+    if (response.errors !== undefined) return undefined;
+    const issue = response.data?.repository?.issue;
+    if (!issue || issue.number !== number || !["OPEN", "CLOSED"].includes(issue.state)) return undefined;
+    const editedAt = issue.lastEditedAt === null ? issue.createdAt : issue.lastEditedAt;
+    if (typeof editedAt !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/.test(editedAt) || !Number.isFinite(Date.parse(editedAt))) return undefined;
+    return { repo: repository, issue: number, state: issue.state, editedAt, lastEditedAt: issue.lastEditedAt };
+  } catch { return undefined; }
+}
+
+/** A complete resolved-thread snapshot already proves there is no pending unanswered bot thread. */
+export function reviewReadinessFromEvidence(evidence: PrEvidence | undefined, expected: string | undefined, required: readonly string[]): ReviewReadiness | undefined {
+  if (!evidence || evidence.unresolved !== 0) return undefined;
+  const checks = required.length ? [...required] : ["check (ubuntu-latest)", "check (macos-latest)", "seeded guards"];
+  if (!checks.every(name => evidence.checks.some(check => check.name === name)) || evidence.checks.some(check => check.state === "unknown")) return undefined;
+  const blockers: string[] = [];
+  if (!expected || !sha(expected)) blockers.push("review head missing");
+  else if (evidence.head !== expected) blockers.push("review head changed");
+  if (evidence.state !== "OPEN") blockers.push("review PR is not open");
+  if (!checks.every(name => { const matched = evidence.checks.filter(check => check.name === name); return matched.length === 1 && matched[0]?.state === "passed"; })) blockers.push("exact-head full CI is not green");
+  return { head: evidence.head, ready: blockers.length === 0, blockers };
+}
+
+export interface ReviewReadiness { head?: string; ready: boolean; blockers: string[]; reusedRun?: number }
+/** Metadata-only pre-review admission; no remote body or comment text is requested. */
+export async function readReviewReadiness(receipt: SdlcReceipt, expected: string | undefined, run: SdlcGh = sdlcGh, requiredChecks: readonly string[] = []): Promise<ReviewReadiness> {
+  const unknown = (): ReviewReadiness => ({ ready: false, blockers: ["review readiness unavailable"] });
+  if (!repo(receipt.repo) || !id(receipt.pr)) return unknown();
+  const [owner, name] = receipt.repo.split("/");
+  const query = "query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){headRefOid state commits(last:1){nodes{commit{oid tree{oid} statusCheckRollup{contexts(first:100){nodes{... on CheckRun{name status conclusion} ... on StatusContext{context state}} pageInfo{hasNextPage}}}}}} reviewThreads(first:100){nodes{isResolved comments(first:100){nodes{author{__typename} createdAt} pageInfo{hasNextPage}}} pageInfo{hasNextPage}}}}}";
+  try {
+    const deadline = performance.now() + 20_000;
+    const bounded: SdlcGh = (args, timeout, cwd, cap) => performance.now() < deadline
+      ? run(args, Math.max(1, Math.min(timeout ?? 10_000, deadline - performance.now())), cwd, cap)
+      : Promise.resolve({ code: 1, stdout: "" });
+    const args = ["api", "graphql", "-f", `query=${query}`, "-f", `owner=${owner}`, "-f", `name=${name}`, "-F", `number=${receipt.pr}`];
+    const response = await bounded(args, 10_000, undefined, 512 * 1024);
+    if (response.code !== 0 || Buffer.byteLength(response.stdout) > 512 * 1024) return unknown();
+    const parsed = JSON.parse(response.stdout), pr = parsed.data?.repository?.pullRequest;
+    if (parsed.errors || !pr || !sha(pr.headRefOid)) return unknown();
+    const blockers: string[] = [];
+    if (!expected || !sha(expected)) blockers.push("review head missing");
+    else if (pr.headRefOid !== expected) blockers.push("review head changed");
+    if (pr.state !== "OPEN") blockers.push("review PR is not open");
+    const commit = pr.commits?.nodes?.[0]?.commit;
+    if (!commit || commit.oid !== pr.headRefOid) blockers.push("review head changed");
+    const contexts = commit?.statusCheckRollup?.contexts;
+    const nodes: unknown[] | undefined = contexts?.nodes;
+    const full = requiredChecks.length ? [...requiredChecks] : ["check (ubuntu-latest)", "check (macos-latest)", "seeded guards"];
+    let reusedRun: number | undefined;
+    if (contexts?.pageInfo?.hasNextPage !== false || !Array.isArray(nodes) || nodes.length > 100
+      || !full.every(name => {
+        const matches = (nodes as { name?: string; context?: string; status?: string; conclusion?: string; state?: string }[]).filter(node => (node?.name ?? node?.context) === name);
+        return matches.length === 1 && (matches[0]?.name ? matches[0].status === "COMPLETED" && matches[0].conclusion === "SUCCESS" : matches[0]?.state === "SUCCESS");
+      })) blockers.push("exact-head full CI is not green");
+    if (blockers.includes("exact-head full CI is not green") && contexts?.pageInfo?.hasNextPage === false && Array.isArray(nodes)
+      && full.every(name => { const matches = (nodes as { name?: string; conclusion?: string }[]).filter(node => node?.name === name); return matches.length === 1 && matches[0]?.conclusion === "SKIPPED"; }) && sha(commit?.tree?.oid)) {
+      reusedRun = await identicalTreeGate(receipt.repo, commit.tree.oid, bounded, full);
+      if (reusedRun !== undefined) {
+        // Proof reads can await several API calls: recheck the complete head/check/thread snapshot before admission.
+        const after = await bounded(args, 10_000, undefined, 512 * 1024);
+        try { if (after.code !== 0 || JSON.stringify(JSON.parse(after.stdout)?.data?.repository?.pullRequest) !== JSON.stringify(pr)) reusedRun = undefined; }
+        catch { reusedRun = undefined; }
+        if (reusedRun !== undefined) blockers.splice(blockers.indexOf("exact-head full CI is not green"), 1);
+      }
+    }
+    const threads = pr.reviewThreads;
+    if (threads?.pageInfo?.hasNextPage !== false || !Array.isArray(threads.nodes) || threads.nodes.length > 100) blockers.push("bot review thread evidence unavailable");
+    else for (const thread of threads.nodes) {
+      if (thread?.isResolved === true) continue;
+      if (thread?.isResolved !== false) { blockers.push("bot review thread evidence unavailable"); continue; }
+      const comments = thread?.comments;
+      if (comments?.pageInfo?.hasNextPage !== false || !Array.isArray(comments.nodes) || comments.nodes.length > 100
+        || comments.nodes.some((comment: { author?: { __typename?: string }; createdAt?: string }) => !["Bot", "User"].includes(comment?.author?.__typename ?? "") || !Number.isFinite(Date.parse(comment.createdAt ?? "")))) {
+        blockers.push("bot review thread evidence unavailable"); continue;
+      }
+      let unanswered = false;
+      for (const comment of comments.nodes) {
+        if (comment.author.__typename === "Bot") unanswered = true;
+        else if (comment.author.__typename === "User") unanswered = false;
+      }
+      if (unanswered) blockers.push("bot review threads unanswered");
+    }
+    return { head: pr.headRefOid, ready: blockers.length === 0, blockers: [...new Set(blockers)], ...(reusedRun !== undefined ? { reusedRun } : {}) };
+  } catch { return unknown(); }
+}
+
+/** Same proof floor as scripts/ci-gates.mjs: the identical tree includes the workflow itself. No skipped proof. */
+async function identicalTreeGate(repository: string, tree: string, run: SdlcGh, required: readonly string[]): Promise<number | undefined> {
+  try {
+    const list = await run(["api", `repos/${repository}/actions/workflows/check.yml/runs?status=success&per_page=20`, "--jq", "{total_count,workflow_runs:[.workflow_runs[]|{id,event,conclusion,head_sha}]}"], 10_000, undefined, 64 * 1024);
+    if (list.code !== 0) return;
+    const runs = JSON.parse(list.stdout)?.workflow_runs;
+    if (!Array.isArray(runs) || runs.length > 20) return;
+    for (const candidate of runs) {
+      if (!id(candidate?.id) || candidate.conclusion !== "success" || !["pull_request", "push"].includes(candidate.event) || !sha(candidate.head_sha)) continue;
+      const commit = await run(["api", `repos/${repository}/git/commits/${candidate.head_sha}`, "--jq", "{tree:{sha:.tree.sha}}"], 10_000, undefined, 4096);
+      if (commit.code !== 0 || JSON.parse(commit.stdout)?.tree?.sha !== tree) continue;
+      const jobs = await run(["api", `repos/${repository}/actions/runs/${candidate.id}/jobs?per_page=100`, "--jq", '{total_count,jobs:[.jobs[]|{name,conclusion,reused:any(.steps[]?; .name=="Reuse verified identical-tree full gate" and .conclusion=="success")}]}'], 10_000, undefined, 32 * 1024);
+      if (jobs.code !== 0) continue;
+      const proof = JSON.parse(jobs.stdout);
+      if (!Array.isArray(proof.jobs) || proof.jobs.length > 100 || proof.total_count !== proof.jobs.length) continue;
+      if (required.every(name => {
+        const found = proof.jobs.filter((job: { name?: string }) => job?.name === name); return found.length === 1 && found[0]?.conclusion === "success" && found[0]?.reused !== true;
+      })) return candidate.id;
+    }
+  } catch { return; }
+}
+
+/** PR cost evidence excludes titles, bodies and comment text; unknown/truncated coverage never becomes zero. */
+export async function readPrCostHistory(repository: string, number: number, run: SdlcGh = sdlcGh): Promise<import("./cost-governance.ts").CostPr | undefined> {
+  if (!repo(repository) || !id(number)) return;
+  const [owner, name] = repository.split("/");
+  try {
+    const query = "query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){number state headRefOid mergedAt commits(first:100){nodes{commit{oid}} pageInfo{hasNextPage}} reviews(first:100){nodes{databaseId commit{oid}} pageInfo{hasNextPage}}}}}";
+    const reply = await run(["api", "graphql", "-f", `query=${query}`, "-f", `owner=${owner}`, "-f", `name=${name}`, "-F", `number=${number}`], 10_000, undefined, 128 * 1024);
+    if (reply.code !== 0) return;
+    const parsed = JSON.parse(reply.stdout), pr = parsed.data?.repository?.pullRequest;
+    if (parsed.errors || pr?.number !== number || !["OPEN", "CLOSED", "MERGED"].includes(pr.state)) return;
+    const result: import("./cost-governance.ts").CostPr = { repo: repository, pr: number, state: pr.state, complete: false,
+      ...(typeof pr.mergedAt === "string" && Number.isFinite(Date.parse(pr.mergedAt)) ? { mergedAt: Date.parse(pr.mergedAt) } : {}) };
+    if (pr.state !== "MERGED") return result; // Cost metrics count merged PRs, not an active work queue.
+    const reviews = pr.reviews, commits = pr.commits;
+    const reviewComplete = reviews?.pageInfo?.hasNextPage === false && Array.isArray(reviews.nodes) && reviews.nodes.length <= 100 && reviews.nodes.every((node: { databaseId?: number }) => id(node?.databaseId));
+    const commitComplete = commits?.pageInfo?.hasNextPage === false && Array.isArray(commits.nodes) && commits.nodes.length <= 100 && sha(pr.headRefOid) && commits.nodes.every((node: { commit?: { oid?: string } }) => sha(node?.commit?.oid));
+    if (reviewComplete) result.reviews = new Set(reviews.nodes.map((review: { databaseId?: unknown }) => review.databaseId).filter((id: unknown) => Number.isSafeInteger(id))).size;
+    const heads = new Set<string>([pr.headRefOid, ...(commits?.nodes ?? []).map((node: { commit?: { oid?: string } }) => node?.commit?.oid), ...(reviews?.nodes ?? []).map((node: { commit?: { oid?: string } }) => node?.commit?.oid)].filter(sha));
+    const checks = await run(["api", `repos/${repository}/actions/workflows/check.yml/runs?per_page=100`, "--jq", "{total_count,workflow_runs:[.workflow_runs[]|{id,run_attempt,head_sha,pull_requests:[.pull_requests[].number]}]}"], 10_000, undefined, 128 * 1024);
+    if (checks.code !== 0) return result;
+    const runs = JSON.parse(checks.stdout);
+    if (!Array.isArray(runs.workflow_runs) || runs.workflow_runs.length > 100 || !Number.isSafeInteger(runs.total_count) || runs.total_count < runs.workflow_runs.length) return result;
+    const linked = runs.workflow_runs.filter((row: { head_sha?: string; pull_requests?: number[] }) => heads.has(row.head_sha ?? "") || Array.isArray(row.pull_requests) && row.pull_requests.includes(number));
+    if (linked.some((row: { id?: number; run_attempt?: number }) => !id(row.id) || !id(row.run_attempt))) return result;
+    result.ciRuns = linked.map((row: { id: number; run_attempt: number }) => ({ id: row.id, attempt: row.run_attempt }));
+    result.complete = reviewComplete && commitComplete && runs.total_count === runs.workflow_runs.length;
+    return result;
+  } catch { return; }
+}

package/src/hub/status-roster.ts

@@ -6,3 +6,13 @@ export function rosterInStatus(status: unknown, peer: string): boolean | undefin
   const row = rows.find((r: unknown) => !!r && typeof r === "object" && (r as { peer?: unknown }).peer === peer) as { on?: unknown } | undefined;
   return typeof row?.on === "boolean" ? row.on : undefined;
 }
+
+/**
+ * The plugin bundle the running daemon verifies Jcode's project MCP entry against. The launcher writes this path rather
+ * than its own copy: the CLI on PATH and the daemon can come from different installs, and the daemon compares the whole
+ * entry. undefined for a hub that sends none or a path that is not that bundle (an older hub, a malformed reply).
+ */
+export function bundleInStatus(status: unknown): string | undefined {
+  const value = (status as { pluginBundle?: unknown } | undefined)?.pluginBundle;
+  return typeof value === "string" && value.startsWith("/") && /[\\/]plugins[\\/]agent-hub[\\/]server\.js$/.test(value) ? value : undefined;
+}