@staix/agent-hub 0.12.44 → 0.12.45

package/src/hub/hub-tools.ts

@@ -17,10 +17,26 @@ const refs = {
   additionalProperties: false,
 } as const;
 const list = (description: string) => ({ type: "array", items: str, description }) as const;
+const reviewFindings = {
+  type: "array", maxItems: 64,
+  description: "Head-bound findings; open Important findings carry across heads until explicitly fixed, false_positive or person-accepted; omission never settles them. Nits stay on their head. accepted is person-only and requires rationale. Nit count is capped by sdlc.max_nits (default 5).",
+  items: { type: "object", properties: {
+    id: { type: "string", minLength: 1, maxLength: 96, pattern: "^[A-Za-z0-9._:-]+$" },
+    pass: { type: "string", enum: ["bugs", "security", "compliance"] },
+    severity: { type: "string", enum: ["important", "nit"] },
+    path: { type: "string", minLength: 1, maxLength: 512 },
+    disposition: { type: "string", enum: ["open", "fixed", "false_positive", "accepted"] },
+    rationale: { type: "string", minLength: 1, maxLength: 2048 },
+  }, required: ["id", "pass", "severity", "disposition"], additionalProperties: false },
+} as const;
 const costPlanProperties = {
   review: { type: "object", properties: { scope: { type: "string", enum: ["none", "delta", "full"] }, reviewers: { type: "integer", minimum: 0, maximum: 8 } }, required: ["scope", "reviewers"], additionalProperties: false },
   ci: { type: "string", enum: ["focused", "full", "reuse"] },
 } as const;
+const evidencePlanProperties = {
+  proof: { type: "array", maxItems: 32, items: { type: "string", maxLength: 512 }, description: "test paths or check names planned to prove the change" },
+  risks: { type: "array", maxItems: 32, items: { type: "string", maxLength: 512 }, description: "short risks to check during implementation and review" },
+} as const;
 const plan = {
   type: "object",
   description: "what you will change, before you start. Owners of open tasks on the same files or symbols see it, and get a notice when your task is done.",
@@ -75,7 +91,7 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_task_done", "Mark your task finished. It goes to its reviewer with your summary and refs; no duplicate hub_send chat is needed. When the project configures a check for its class, the hub runs it first and the result comes as a task message: a failed check keeps the task with you.", { id, summary: { type: "string", description: "what changed, why, and the check you ran with its result" }, refs }, ["id", "summary"]),
   tool("hub_sdlc_record", "Record artifact ids or claimed local checks on your task. This grants no authority or external-check evidence. Only its owner/reviewer or the person may record; only its reviewer/person may name a reviewed head or phase checklist. Phase evidence refs are content hashes, not external verification.", { id, receipt: { type: "object", properties: { stage: { type: "string", enum: ["spec", "plan", "implement", "review", "verify", "merge", "release"] }, repo: str, issue: id, pr: id, localHead: str, localResult: { type: "string", enum: ["passed", "failed", "unknown"] }, reviewedHead: str, phase: { type: "object", properties: { id: str, head: str, tasks: { type: "array", maxItems: 64, items: { type: "object", properties: { id, after: { type: "array", maxItems: 16, items: id } }, required: ["id", "after"], additionalProperties: false } }, criteria: { type: "array", maxItems: 32, items: { type: "object", properties: { id: str, required: { type: "boolean" }, result: { type: "string", enum: ["verified", "failed", "unverified"] }, refs: { type: "array", maxItems: 8, items: str } }, required: ["id", "required", "result", "refs"], additionalProperties: false } } }, required: ["id", "tasks", "criteria"], additionalProperties: false } }, additionalProperties: false } }, ["id", "receipt"]),
   tool("hub_task_list", "The task board. PII tasks show as [pii].", { state: { type: "string", enum: ["proposed", "in_progress", "in_review", "approved", "changes_requested", "cancelled"] }, ready: { type: "boolean", description: "only proposed tasks with nothing left to wait for" } }),
-  tool("hub_review", "Give your verdict on a task you were asked to review: map the changed signatures and call sites to the task's plan or detail, read the check result (hub_task_show has it, with the done summary), and list what is unmet. The verdict notifies the task owner; no duplicate hub_send chat is needed. Consecutive changes_requested verdicts (three by default, `tasks.escalate_after`) move the task to another peer.", { id, head: { type: "string", description: "full SHA actually reviewed; enforce binds approval to the current PR head" }, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str, unmet: { type: "array", items: str, description: "each requirement of the plan or detail that the change does not meet" }, coverage: { type: "object", description: "the review brief's reviewable paths you read (reviewed) and any you did not (skipped, each with a reason); in enforce an approval must account for every one", properties: { reviewed: { type: "array", items: str }, skipped: { type: "array", items: { type: "object", properties: { path: str, reason: str }, required: ["path", "reason"] } } } } }, ["id", "verdict"]),
+  tool("hub_review", "Give your verdict on a task you were asked to review: map the changed signatures and call sites to the task's plan or detail, read the check result (hub_task_show has it, with the done summary), and list what is unmet. The verdict notifies the task owner; no duplicate hub_send chat is needed. Consecutive changes_requested verdicts (three by default, `tasks.escalate_after`) move the task to another peer.", { id, head: { type: "string", description: "full SHA actually reviewed; enforce binds approval to the current PR head" }, findings: reviewFindings, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str, unmet: { type: "array", items: str, description: "each requirement of the plan or detail that the change does not meet" }, coverage: { type: "object", description: "the review brief's reviewable paths you read (reviewed) and any you did not (skipped, each with a reason); in enforce an approval must account for every one", properties: { reviewed: { type: "array", items: str }, skipped: { type: "array", items: { type: "object", properties: { path: str, reason: str }, required: ["path", "reason"] } } } } }, ["id", "verdict"]),
   tool("hub_checkpoint", "Answer a checkpoint request from the hub (quota or context window pressure): what you were doing, what is half done, what whoever continues must know. Write the same to .agenthub/checkpoint.md first if you can.", { summary: str, request_id: { type: "string", description: "The request id supplied by a context checkpoint request; required for context checkpoints" } }, ["summary"]),
   tool("hub_memory_search", "Search daemon-scoped visible memory, fails first. Query <=200 UTF-8 bytes; default 8, max 20 lines; whole output <=4 KB. Incomplete excerpts are marked. No project argument.", { query: { type: "string", maxLength: 200, description: "At most 200 UTF-8 bytes, enforced by the daemon" }, limit: { type: "integer", minimum: 1, maximum: 20 } }, ["query"]),
   tool("hub_memory_show", "Read up to 8 visible memory ids or unique prefixes (6..64 UTF-8 bytes each). Original ids redirect; unavailable ids share one refusal. Whole output <=8 KB.", { ids: { type: "array", minItems: 1, maxItems: 8, items: { type: "string", minLength: 6, maxLength: 64, description: "6 to 64 UTF-8 bytes" } } }, ["ids"]),
@@ -180,19 +196,19 @@ export function profileTaskTools(profile: ProfileSelection = "dev", stages?: rea
       properties.receipt = { ...receipt, properties: fields };
     }
     if (customProfile && tool.name === "hub_task_propose") properties.class = { type: "string", enum: [...new Set([...Object.keys(data.classes), ...PROFILE_CLASS_NAMES.filter(v => projectProfile("dev").classes[v])])] };
-    if (customProfile && properties.plan && tool.name !== "hub_task_accept") properties.plan = { ...plan, properties: Object.fromEntries(data.plan_keys.map(key => [key, plan.properties[key as keyof typeof plan.properties] ?? list(key === "sections" ? "document heading anchors, such as report.md#methods" : key === "sources" ? "citation ids, DOI or source URL ids" : "short claim ids to verify")])) };
+    if (customProfile && properties.plan && tool.name !== "hub_task_accept") properties.plan = { ...plan, properties: { ...Object.fromEntries(data.plan_keys.map(key => [key, plan.properties[key as keyof typeof plan.properties] ?? list(key === "sections" ? "document heading anchors, such as report.md#methods" : key === "sources" ? "citation ids, DOI or source URL ids" : "short claim ids to verify")])) } };
     if (customProfile && tool.name === "hub_backlog_split") {
       const parts = properties.parts as { items: { properties: Record<string, unknown> } };
-      const selectedPlan = { ...plan, properties: Object.fromEntries(data.plan_keys.map(key => [key, plan.properties[key as keyof typeof plan.properties] ?? list(key === "sections" ? "document heading anchors, such as report.md#methods" : key === "sources" ? "citation ids, DOI or source URL ids" : "short claim ids to verify")])) };
+      const selectedPlan = { ...plan, properties: { ...Object.fromEntries(data.plan_keys.map(key => [key, plan.properties[key as keyof typeof plan.properties] ?? list(key === "sections" ? "document heading anchors, such as report.md#methods" : key === "sources" ? "citation ids, DOI or source URL ids" : "short claim ids to verify")])) } };
       properties.parts = { ...parts, items: { ...parts.items, properties: { ...parts.items.properties, plan: selectedPlan } } };
     }
     if (criteria && properties.plan) {
       const current = properties.plan as { properties: Record<string, unknown> };
-      properties.plan = { ...current, properties: { ...current.properties, ...costPlanProperties } };
+      properties.plan = { ...current, properties: { ...current.properties, ...costPlanProperties, ...evidencePlanProperties } };
     }
     if (criteria && tool.name === "hub_backlog_split") {
       const parts = properties.parts as { items: { properties: { plan: { properties: Record<string, unknown> } } } };
-      properties.parts = { ...parts, items: { ...parts.items, properties: { ...parts.items.properties, plan: { ...parts.items.properties.plan, properties: { ...parts.items.properties.plan.properties, ...costPlanProperties } } } } };
+      properties.parts = { ...parts, items: { ...parts.items, properties: { ...parts.items.properties, plan: { ...parts.items.properties.plan, properties: { ...parts.items.properties.plan.properties, ...costPlanProperties, ...evidencePlanProperties } } } } };
     }
     return { ...tool, ...(customProfile && tool.name === "hub_task_propose" ? { description: tool.description + ` Selected profile ${data.name}: ${Object.keys(data.classes).join(", ")}. Routing uses their existing base classes.` } : {}), inputSchema: { ...tool.inputSchema, properties } };
   });

package/src/hub/instance-config.ts

@@ -1,6 +1,9 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { createProjectAdapterCatalog, defaultPeerRoles, definitionOf, type ProjectAdapterCatalog } from "../adapters/registry.ts";
+import { createProjectAdapterCatalog, defaultPeerRoles, definitionOf, type ProjectAdapterCatalog, type AdapterDefinition } from "../adapters/registry.ts";
+import { readAdapterModuleDeclarations, type AdapterModuleDeclaration } from "../adapters/external-modules.ts";
+import { externalMetadataDefinitions } from "../adapters/external-metadata.ts";
+import { readControl, stateDirFor } from "./control-client.ts";
 import { conductorPeer } from "./conductor.ts";
 import { configRefusal } from "./config-trust.ts";
 import { validateInstances, type InstancesConfig } from "./instances.ts";
@@ -18,13 +21,15 @@ export function readInstanceConfigLayers(cwd: string): InstanceConfigLayer[] {
 
 /** Declaration authority is file provenance, never a suffix or a claim made by a native child. */
 export interface InstanceRoleConfig {
+  adapter_modules?: readonly AdapterModuleDeclaration[];
   adapters?: Readonly<Record<string, import("../adapters/configured-acp.ts").ConfiguredAcpAdapterConfig>>;
   instances?: InstancesConfig;
   catalog: ProjectAdapterCatalog;
   ignored: string[];
 }
-export function readInstanceConfig(cwd: string, layers: readonly InstanceConfigLayer[] = readInstanceConfigLayers(cwd)): InstanceRoleConfig {
-  const ignored: string[] = [];
+export function readInstanceConfig(cwd: string, layers: readonly InstanceConfigLayer[] = readInstanceConfigLayers(cwd), externalDefinitions?: readonly AdapterDefinition[]): InstanceRoleConfig {
+  const moduleConfig = readAdapterModuleDeclarations(cwd, layers);
+  const ignored: string[] = [...moduleConfig.ignored];
   let adapters: Readonly<Record<string, import("../adapters/configured-acp.ts").ConfiguredAcpAdapterConfig>> | undefined, rawInstances: unknown;
   for (const { name, raw } of layers) {
     const keys = ["adapters", "instances"].filter(key => raw[key] !== undefined);
@@ -34,9 +39,16 @@ export function readInstanceConfig(cwd: string, layers: readonly InstanceConfigL
     if (raw.adapters !== undefined) adapters = raw.adapters as Readonly<Record<string, import("../adapters/configured-acp.ts").ConfiguredAcpAdapterConfig>>;
     if (raw.instances !== undefined) rawInstances = raw.instances;
   }
-  const catalog = createProjectAdapterCatalog(adapters);
+  let external = externalDefinitions;
+  if (external === undefined) {
+    // Metadata discovery is optional: retained recovery receipts may name a project that no longer exists.
+    let metadata;
+    try { metadata = readControl(stateDirFor(cwd))?.externalAdapters; } catch { /* no running catalog available */ }
+    external = externalMetadataDefinitions(metadata);
+  }
+  const catalog = createProjectAdapterCatalog(adapters, external);
   const instances = validateInstances(rawInstances, catalog);
-  return { ...(adapters !== undefined ? { adapters } : {}), ...(Object.keys(instances).length ? { instances } : {}), catalog, ignored };
+  return { ...(moduleConfig.modules.length ? { adapter_modules: moduleConfig.modules } : {}), ...(adapters !== undefined ? { adapters } : {}), ...(Object.keys(instances).length ? { instances } : {}), catalog, ignored };
 }
 
 /** Capture ordinary role policy and trusted instance declarations together, without loading daemon configuration. */

package/src/hub/instance-execution.ts

@@ -6,17 +6,29 @@ import { realPath } from "./project.ts";
 import { validateInstances, type InstancesConfig } from "./instances.ts";
 
 const refuse = (reason: string): never => { throw new Error(`instance execution workspace refused: ${reason}`); };
-const GIT_TIMEOUT_MS = 5000, GIT_OUTPUT_BYTES = 1024 * 1024;
-function git(cwd: string, args: string[]): string {
-  const result = hubGitSync(["-C", cwd, ...args], { encoding: "utf8", timeout: GIT_TIMEOUT_MS, maxBuffer: GIT_OUTPUT_BYTES });
-  if (result.error || result.status !== 0) return refuse("Git workspace evidence unavailable");
-  return result.stdout;
+// #225: this runs synchronously on the daemon's event loop (an extra-instance start, turn_revert), and a resolution makes up to four git
+// calls. One allowance covers all of them, so the loop is held for at most GIT_BUDGET_MS in git however many calls remain; a call that
+// finds the allowance spent refuses without starting git. ponytail: the calls stay synchronous because the CLI and recovery callers are
+// synchronous by contract; an async twin for the two daemon call sites is the upgrade if a typical resolution ever costs more than a few ms
+// (measured about 15 ms for four calls on a warm local repository).
+const GIT_BUDGET_MS = 5000, GIT_OUTPUT_BYTES = 1024 * 1024;
+type Gitter = (cwd: string, args: string[]) => string;
+function gitWithin(budgetMs: number, clock: () => number, run: typeof hubGitSync = hubGitSync): Gitter {
+  const deadline = clock() + budgetMs;
+  return (cwd, args) => {
+    const left = Math.floor(deadline - clock());
+    if (left <= 0) return refuse("Git workspace evidence unavailable");
+    const result = run(["-C", cwd, ...args], { encoding: "utf8", timeout: left, maxBuffer: GIT_OUTPUT_BYTES });
+    if (result.error || result.status !== 0) return refuse("Git workspace evidence unavailable");
+    return result.stdout;
+  };
 }
-const commonDirectory = (cwd: string): string => realPath(git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]).replace(/\n$/, ""));
+const commonDirectory = (git: Gitter, cwd: string): string => realPath(git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]).replace(/\n$/, ""));
 
 /** Point-in-time read only. No worktree is created, repaired or chosen implicitly. */
-export function resolveInstanceExecutionCwd(projectRoot: string, id: string, declarations: InstancesConfig | undefined, roles: readonly string[], adapterCatalog: ProjectAdapterCatalog): string {
+export function resolveInstanceExecutionCwd(projectRoot: string, id: string, declarations: InstancesConfig | undefined, roles: readonly string[], adapterCatalog: ProjectAdapterCatalog, budgetMs = GIT_BUDGET_MS, clock: () => number = () => performance.now(), run: typeof hubGitSync = hubGitSync): string {
   if (adapterCatalog.definitionOf(id)) return projectRoot;
+  const git = gitWithin(budgetMs, clock, run);
   const declaration = validateInstances(declarations, adapterCatalog)[id];
   if (!declaration) return refuse("extra instance is not declared");
   const implementer = roles.includes("implementer");
@@ -41,7 +53,7 @@ export function resolveInstanceExecutionCwd(projectRoot: string, id: string, dec
     try { return realPath(path) === cwd; } catch { return false; }
   });
   if (matches.length !== 1 || matches[0]!.some(field => field === "prunable" || field.startsWith("prunable "))) return refuse("directory is not an available registered project worktree");
-  if (commonDirectory(root) !== commonDirectory(cwd)) return refuse("worktree belongs to a different Git repository");
+  if (commonDirectory(git, root) !== commonDirectory(git, cwd)) return refuse("worktree belongs to a different Git repository");
   const top = git(cwd, ["rev-parse", "--show-toplevel"]).replace(/\n$/, "");
   if (realPath(top) !== cwd) return refuse("directory is not the registered worktree root");
   if (implementer && !matches[0]!.some(field => field.startsWith("branch refs/heads/") && field.length > "branch refs/heads/".length)) return refuse("an implementer worktree requires an attached branch");

package/src/hub/instances.ts

@@ -65,7 +65,8 @@ export function validateInstances(raw: unknown, catalog: ProjectAdapterCatalog):
     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}-`;
-    if (!definition) return fail(`${path}.kind`, "unknown native kind");
+    if (!definition) return fail(`${path}.kind`, "unknown native kind (external adapter instances are unsupported in A4)");
+    if (catalog.externalDefinitions.some(item => item.kind === kind)) return fail(`${path}.kind`, "external adapter instances are unsupported in A4");
     if (!id.startsWith(prefix) || !/^[a-z0-9][a-z0-9-]*$/.test(id.slice(prefix.length))) return fail(path, "id must be <kind>-<name>");
     const declaredRoles = entry.roles ? roles(entry.roles.value, `${path}.roles`) : [];
     const reviewer = (definition.reviewerVariant ?? definition).reviewer;

package/src/hub/peers.ts

@@ -1,4 +1,5 @@
 import type { Envelope, EnvelopeOpts, PeerId, PeerState } from "./envelope.ts";
+import type { PermissionMode } from "./permission-mode.ts";
 
 export interface DeliveryReceipt {
   id: string;
@@ -11,6 +12,14 @@ export interface DeliveryReceipt {
 export interface PeerAdapter {
   readonly id: PeerId;
   readonly state: PeerState;
+  /** Host-observed native session identity. An absent port permits owner-token fallback; undefined means unknown. */
+  readonly sessionGeneration?: string | number;
+  /** Defaults to fencing checkpoints when the generation port exists; native legacy exceptions opt out explicitly. */
+  readonly checkpointUsesSessionGeneration?: boolean;
+  /** Effective native approval state; absent peers retain the hub-managed choice. */
+  readonly permissionModeState?: PermissionMode | "unknown" | "unmanaged";
+  /** Resolve only after native acknowledgement. This changes approval frequency, never the sandbox. */
+  setPermissionMode?(mode: PermissionMode): Promise<void>;
   /** A peer the hub drives itself (Pi, the local worker). It cannot be trusted to rate its own urgency: the bus caps it. */
   readonly hubNative?: boolean;
   /** Never handed a delivery: its queue waits for `Bus.pull` (a Claude session that cannot show channel pushes, issue #205). */

package/src/hub/plan-conformance.ts

@@ -0,0 +1,83 @@
+import { createHash } from "node:crypto";
+import { types } from "node:util";
+
+export interface PlanConformance {
+  state: "covered" | "departure" | "unknown";
+  head?: string;
+  outside: string[];
+  untouched: string[];
+}
+/** Repository-relative literal names only. A star is a filename character, never a glob operator. */
+function pathIdentity(raw: unknown): string | undefined {
+  if (typeof raw !== "string" || !raw || raw.length > 1000 || /[\p{Cc}\p{Cf}]/u.test(raw)
+    || raw.startsWith("/") || raw.startsWith("\\") || /^[A-Za-z]:/.test(raw)) return undefined;
+  const path = raw.replace(/^(\.\/)+/, "").replace(/\/{2,}/g, "/").replace(/\/+$/, "") || ".";
+  if (path === "." || path.split("/").some(part => part === "." || part === "..")) return undefined;
+  return path;
+}
+const covers = (planned: string, changed: string) => changed === planned || changed.startsWith(`${planned}/`);
+
+/** A complete file inventory is independent of any plan or coverage claim. */
+export function completePlanInventory(evidence: { head: string; paths: readonly string[]; pathsComplete?: boolean; typesComplete?: boolean } | undefined): string[] | undefined {
+  if (!evidence || typeof evidence.head !== "string" || !/^[a-f0-9]{40}$/.test(evidence.head) || evidence.pathsComplete !== true || evidence.typesComplete !== true || !Array.isArray(evidence.paths) || evidence.paths.length > 1000) return undefined;
+  const paths: string[] = [], seen = new Set<string>();
+  for (const raw of evidence.paths) {
+    const path = pathIdentity(raw); if (path === undefined || seen.has(path)) return undefined;
+    seen.add(path); paths.push(path);
+  }
+  return paths;
+}
+
+/** Compare current complete PR file metadata with the current plan; never inspect patches or the filesystem. */
+export function planConformance(planPaths: readonly string[] | undefined, evidence: { head: string; paths: readonly string[]; pathsComplete?: boolean; typesComplete?: boolean } | undefined): PlanConformance {
+  const head = typeof evidence?.head === "string" && /^[a-f0-9]{40}$/.test(evidence.head) ? evidence.head : undefined;
+  const unknown: PlanConformance = { state: "unknown", ...(head ? { head } : {}), outside: [], untouched: [] };
+  const changed = completePlanInventory(evidence);
+  if (!head || changed === undefined
+    || !Array.isArray(planPaths) || !planPaths.length || planPaths.length > 1000) return unknown;
+  const planned: string[] = [], seenPlan = new Set<string>();
+  for (const raw of planPaths) {
+    const path = pathIdentity(raw); if (path === undefined) return unknown;
+    if (!seenPlan.has(path)) { seenPlan.add(path); planned.push(path); }
+  }
+  const outside = changed.filter(path => !planned.some(plan => covers(plan, path)));
+  const untouched = planned.filter(plan => !changed.some(path => covers(plan, path)));
+  return { state: outside.length ? "departure" : "covered", head, outside, untouched };
+}
+
+/** Hash plain plan data without invoking accessors/toJSON; object key order is immaterial, list order is not. */
+export function planFingerprint(plan: unknown): string {
+  const seen = new Set<object>();
+  const fail = (): never => { throw new Error("invalid plan fingerprint data"); };
+  const encode = (value: unknown, depth: number): string => {
+    if (depth > 64) return fail();
+    if (value === undefined) return "undefined";
+    if (value === null || typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
+    if (typeof value === "number") return Number.isFinite(value) ? JSON.stringify(value) : fail();
+    if (typeof value !== "object" || types.isProxy(value) || seen.has(value)) return fail();
+    seen.add(value);
+    try {
+      if (Array.isArray(value)) {
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        if (Reflect.ownKeys(descriptors).length !== value.length + 1) return fail();
+        return "[" + Array.from({ length: value.length }, (_, index) => {
+          const descriptor = descriptors[String(index)];
+          return descriptor && Object.hasOwn(descriptor, "value") ? encode(descriptor.value, depth + 1) : fail();
+        }).join(",") + "]";
+      }
+      if (![Object.prototype, null].includes(Object.getPrototypeOf(value))) return fail();
+      const keys = Reflect.ownKeys(value); if (keys.some(key => typeof key !== "string")) return fail();
+      return "{" + (keys as string[]).sort().map(key => {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key)!;
+        if (!Object.hasOwn(descriptor, "value") || !descriptor.enumerable) return fail();
+        return JSON.stringify(key) + ":" + encode(descriptor.value, depth + 1);
+      }).join(",") + "}";
+    } finally { seen.delete(value); }
+  };
+  return createHash("sha256").update(encode(plan, 0)).digest("hex");
+}
+
+/** Approval blockers only; untouched planned files are advisory. */
+export function planConformanceBlockers(plan: (PlanConformance & { accepted?: boolean }) | undefined): string[] {
+  return !plan ? [] : plan.state === "unknown" ? ["plan conformance unknown"] : plan.state === "departure" && !plan.accepted ? ["plan conformance: changed files outside the plan"] : [];
+}

package/src/hub/review-findings.ts

@@ -0,0 +1,104 @@
+import { types } from "node:util";
+import { sanitize } from "./envelope.ts";
+
+export interface ReviewFinding {
+  id: string;
+  pass: "bugs" | "security" | "compliance";
+  severity: "important" | "nit";
+  path?: string;
+  disposition: "open" | "fixed" | "false_positive" | "accepted";
+  rationale?: string;
+}
+export interface ReviewFindingSet { head?: string; items: ReviewFinding[] }
+export interface ReviewFindingTally { important: number; nit: number; openImportant: number; openNit: number; fixed: number; falsePositive: number; accepted: number }
+export const DEFAULT_MAX_NITS = 5;
+const MAX_ITEMS = 64, MAX_BYTES = 64 * 1024;
+const fail = (reason: string): never => { throw new Error("review findings: " + reason); };
+function fields(raw: unknown): Record<string, PropertyDescriptor> {
+  if (!raw || typeof raw !== "object" || types.isProxy(raw) || Array.isArray(raw)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(raw)) || Object.getOwnPropertySymbols(raw).length) return fail("plain own-data finding required");
+  const descriptors: Record<string, PropertyDescriptor> = Object.assign(Object.create(null), Object.getOwnPropertyDescriptors(raw));
+  if (Object.values(descriptors).some(field => !Object.hasOwn(field, "value") || !field.enumerable)) return fail("accessors and hidden fields refused");
+  if (Object.keys(descriptors).some(key => !["id", "pass", "severity", "path", "disposition", "rationale"].includes(key))) return fail("unknown finding field");
+  return descriptors;
+}
+function text(raw: unknown, max: number, path: boolean): string {
+  if (typeof raw !== "string" || !raw.trim() || Buffer.byteLength(raw) > max
+    || path && /[\p{Cc}\p{Cf}]/u.test(raw)) return fail("invalid bounded finding text");
+  const clean = sanitize(raw.trim());
+  if (Buffer.byteLength(clean) > max) return fail("sanitized finding text exceeds its bound");
+  return clean;
+}
+/** Supplied findings are validated independently of lifecycle mode, before any board effect. */
+export function parseReviewFindings(raw: unknown, options: { person: boolean; maxNits: number }): ReviewFinding[] {
+  if (typeof options.person !== "boolean" || !Number.isSafeInteger(options.maxNits) || options.maxNits < 0 || options.maxNits > MAX_ITEMS) return fail("invalid finding authority or nit limit");
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw) || types.isProxy(raw) || Object.getPrototypeOf(raw) !== Array.prototype
+    || Object.getOwnPropertySymbols(raw).length || raw.length > MAX_ITEMS) return fail("at most 64 own-data findings required");
+  const descriptors: Record<string, PropertyDescriptor> = Object.assign(Object.create(null), Object.getOwnPropertyDescriptors(raw));
+  if (Object.keys(descriptors).length !== raw.length + 1) return fail("dense finding array required");
+  const ids = new Set<string>();
+  const result = Array.from({ length: raw.length }, (_, index): ReviewFinding => {
+    const entry = descriptors[String(index)];
+    if (!entry || !Object.hasOwn(entry, "value") || !entry.enumerable) return fail("finding array accessors refused");
+    const item = fields(entry.value), id: unknown = item.id?.value, pass: unknown = item.pass?.value;
+    const severity: unknown = item.severity?.value, disposition: unknown = item.disposition?.value;
+    if (typeof id !== "string" || !/^[A-Za-z0-9._:-]+$/.test(id) || Buffer.byteLength(id) > 96 || ids.has(id)) return fail("invalid or duplicate finding id");
+    ids.add(id);
+    if (pass !== "bugs" && pass !== "security" && pass !== "compliance") return fail("invalid finding pass");
+    if (severity !== "important" && severity !== "nit") return fail("invalid finding severity");
+    if (disposition !== "open" && disposition !== "fixed" && disposition !== "false_positive" && disposition !== "accepted") return fail("invalid finding disposition");
+    const path = item.path ? text(item.path.value, 512, true) : undefined;
+    const rationale = item.rationale ? text(item.rationale.value, 2048, false) : undefined;
+    if (disposition === "accepted" && (!options.person || !rationale)) return fail("accepted findings require a person and rationale");
+    return { id, pass, severity, disposition, ...(path !== undefined ? { path } : {}), ...(rationale !== undefined ? { rationale } : {}) };
+  });
+  if (result.filter(item => item.severity === "nit").length > options.maxNits) return fail("nit limit exceeded");
+  if (Buffer.byteLength(JSON.stringify(result)) > MAX_BYTES) return fail("finding report exceeds 64 KiB");
+  return result;
+}
+
+/** Prefer live artifact identity, skipping malformed historical candidates rather than hiding a valid fallback. */
+export function findingHead(receipt?: { head?: string; reviewedHead?: string; localHead?: string }, evidence?: { head: string }, commit?: string): string | undefined {
+  return [evidence?.head, receipt?.head, receipt?.reviewedHead, receipt?.localHead, commit]
+    .find((head): head is string => typeof head === "string" && /^[a-f0-9]{40}$/.test(head));
+}
+
+/**
+ * Nits belong only to their head bucket, including the explicit undefined bucket.
+ * Open Important is an obligation across heads until an explicit disposition resolves its ID globally.
+ */
+export function findingsForHead(sets: readonly ReviewFindingSet[], head?: string): ReviewFinding[] {
+  interface Entry { item: ReviewFinding; order: number }
+  const current = new Map<string, Entry>(), important = new Map<string, Entry>();
+  let order = 0;
+  for (const set of sets) for (const item of set.items) {
+    const key = item.id, position = order++;
+    if (set.head === head) current.set(key, { item: { ...current.get(key)?.item, ...item }, order: position });
+    const prior = important.get(key);
+    if (item.severity === "important") {
+      important.set(key, { item: { ...prior?.item, ...item }, order: position });
+    } else if (prior && (prior.item.disposition === "open" || item.disposition !== "open")) {
+      // A nit/open reclassification cannot discharge Important. An explicit disposition can.
+      important.set(key, { item: { ...prior.item, ...item, severity: "important" }, order: position });
+    }
+  }
+  for (const [key, entry] of important) {
+    if (entry.item.disposition === "open") current.set(key, entry);
+    else {
+      const seen = current.get(key);
+      // Settling on B also settles older A when A is queried again. A later new nit/open remains a head-local nit.
+      if (seen?.item.disposition === "open" && seen.order <= entry.order) current.delete(key);
+    }
+  }
+  return [...current.values()].map(entry => ({ ...entry.item }));
+}
+export function findingTally(items: readonly ReviewFinding[]): ReviewFindingTally {
+  const tally: ReviewFindingTally = { important: 0, nit: 0, openImportant: 0, openNit: 0, fixed: 0, falsePositive: 0, accepted: 0 };
+  for (const item of items) {
+    tally[item.severity]++;
+    if (item.disposition === "open") tally[item.severity === "important" ? "openImportant" : "openNit"]++;
+    else tally[item.disposition === "false_positive" ? "falsePositive" : item.disposition]++;
+  }
+  return tally;
+}

package/src/hub/roster.ts

@@ -1,15 +1,41 @@
 import { definitionOf as builtinDefinitionOf, type ProjectAdapterCatalog, type KindMap } from "../adapters/registry.ts";
-import { defaultRosterEnabled as builtinDefaultRosterEnabled } from "../adapters/registry.ts";
+import { validateInstances } from "./instances.ts";
+import { defaultRosterEnabled as builtinDefaultRosterEnabled, createProjectAdapterCatalog as builtinCatalog } from "../adapters/registry.ts";
 
 export type PeerRoster = Partial<Record<string, boolean>>;
 
-export function peerRosterConfig(value: unknown, instances?: KindMap, catalog?: ProjectAdapterCatalog): PeerRoster {
+/**
+ * A roster key of an instance that was declared, put on the roster and later undeclared (#225). It has the shape a declaration
+ * could have had (`<builtin kind>-<name>`, the rule validateInstances applies to an id) and no definition now, so it grants and
+ * refuses nothing: the config still loads and `ahub roster remove` can delete it. Anything else stays an unsupported peer.
+ */
+export function staleInstanceKey(peer: string, catalog: ProjectAdapterCatalog | undefined): boolean {
+  const definitionOf = catalog?.definitionOf ?? builtinDefinitionOf;
+  if (!/^[a-z][a-z0-9-]{0,31}$/.test(peer) || definitionOf(peer)) return false; // a reserved id (user, hub, digest) never starts with a kind and a dash
+  if (!catalog) return false;
+  return catalog.definitions.some(kind => peer.startsWith(`${kind.kind}-`) && /^[a-z0-9][a-z0-9-]*$/.test(peer.slice(kind.kind.length + 1)) && canDeclareInstance(peer, kind.kind, catalog) && !catalog.externalDefinitions.some(item => item.kind === kind.kind));
+}
+
+/** The declarations a person can write for an extra instance of a kind: validateInstances decides which of them its definition takes. */
+const DECLARATION_SHAPES: readonly Record<string, unknown>[] = [
+  { roles: ["implementer"], start_mode: "headless" }, { roles: ["reviewer"], start_mode: "headless" }, { roles: ["reviewer"] }, { roles: ["planner"] },
+];
+
+/** Whether validateInstances would take `<kind>-<name>` for this kind under any declaration, so the answer cannot drift from its policy. */
+function canDeclareInstance(id: string, kind: string, catalog: ProjectAdapterCatalog): boolean {
+  return DECLARATION_SHAPES.some(shape => { try { validateInstances({ [id]: { kind, ...shape } }, catalog); return true; } catch { return false; } });
+}
+
+export function peerRosterConfig(value: unknown, instances?: KindMap, catalog?: ProjectAdapterCatalog, inertUnknown = false): PeerRoster {
   const definitionOf = catalog?.definitionOf ?? builtinDefinitionOf;
   if (value === undefined) return {};
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("roster must be an object of boolean peer values");
   const roster: PeerRoster = {};
+  const requireKnownPeer = (peer: string) => {
+    if (!definitionOf(peer, instances) && !staleInstanceKey(peer, catalog ?? builtinCatalog())) throw new Error("roster contains an unsupported peer");
+  };
   for (const [peer, on] of Object.entries(value)) {
-    if (!definitionOf(peer, instances)) throw new Error("roster contains an unsupported peer");
+    if (!inertUnknown || !/^[a-z][a-z0-9-]{0,31}$/.test(peer)) requireKnownPeer(peer);
     if (typeof on !== "boolean") throw new Error(`roster.${peer} must be a boolean`);
     roster[peer] = on;
   }
@@ -17,10 +43,10 @@ export function peerRosterConfig(value: unknown, instances?: KindMap, catalog?:
 }
 
 /** External ids keep their existing admission rules; Pi's legacy switch is only its default. */
-export function rosterAllows(roster: PeerRoster, peer: string, piEnabled: boolean, instances: KindMap | undefined, catalog: ProjectAdapterCatalog): boolean {
+export function rosterAllows(roster: PeerRoster, peer: string, piEnabled: boolean, instances: KindMap | undefined, catalog: ProjectAdapterCatalog, inertUnknown = false): boolean {
   const definitionOf = catalog.definitionOf;
   const defaultRosterEnabled = (id: string, enabled: boolean) => !builtinDefinitionOf(id) ? catalog.definitionOf(id)?.defaultOnRoster ?? false : builtinDefaultRosterEnabled(id, enabled);
   const definition = definitionOf(peer, instances);
-  if (!definition) return true; // External clients do not acquire a native kind from a project declaration.
+  if (!definition) return !inertUnknown || !Object.hasOwn(roster, peer); // Only a captured module scope makes unresolved rows inert; legacy external clients keep their admission rules.
   return roster[peer] ?? (definition.kind === peer ? defaultRosterEnabled(peer, piEnabled) : true);
 }

package/src/hub/sdlc-queue.ts

@@ -1,7 +1,9 @@
+import { planConformance, planConformanceBlockers } from "./plan-conformance.ts";
+import { findingsForHead, findingHead, findingTally, type ReviewFindingSet, type ReviewFindingTally } from "./review-findings.ts";
 import type { CriteriaView } from "./workflow.ts";
 import { parsePrEvidence, readSdlcPr, sdlcGh, sdlcStatus, type PrEvidence, type SdlcConfig, type SdlcGh, type SdlcReceipt } from "./sdlc.ts";
-export interface DeliveryTask { id: number; after: number[]; private: boolean; receipt?: SdlcReceipt; phase?: CriteriaView; }
-export interface MergeQueueRow { pr: number; tasks: number[]; head?: string; private?: true; ready: boolean; blockers: string[]; after: number[]; }
+export interface DeliveryTask { plan?: { paths?: string[]; revision: number; fingerprint: string; accepted: { repo: string; pr: number; head: string; revision: number; fingerprint: string; paths: string[] }[] }; findings?: readonly ReviewFindingSet[]; id: number; after: number[]; private: boolean; receipt?: SdlcReceipt; phase?: CriteriaView; }
+export interface MergeQueueRow { planConformance?: { task?: number; state: string; outside: number; untouched: number; accepted: boolean }[]; findings?: ReviewFindingTally; pr: number; tasks: number[]; head?: string; private?: true; ready: boolean; blockers: string[]; after: number[]; }
 export interface MergeConflict { left: number; right: number; files: number; order: "dependency" | "person_required"; }
 export interface MergeQueue { repo: string; rows: MergeQueueRow[]; order: number[]; unordered?: number[]; conflicts: MergeConflict[]; complete: boolean; truncated: boolean; }
 const validRepo = (value: string) => /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(value) && !value.startsWith("-");
@@ -49,15 +51,28 @@ export async function readMergeQueue(repo: string, config: SdlcConfig, tasks: De
   for (const pr of ids) {
     const holders = tasks.filter(t => sameRepo(t.receipt?.repo) && t.receipt?.pr === pr); links.set(pr, holders);
     const row: MergeQueueRow = { pr, tasks: holders.some(t => t.private) ? [] : holders.map(t => t.id), ready: false, blockers: [], after: [] }; result.rows.push(row);
-    if (holders.some(t => t.private)) { row.private = true; row.blockers.push("private lifecycle evidence unavailable"); continue; }
+    if (holders.some(t => t.private)) { row.private = true; if (config.mode !== "off") row.planConformance = [{ state: "unknown", outside: 0, untouched: 0, accepted: false }]; row.blockers.push("private lifecycle evidence unavailable"); continue; }
     const read = await readSdlcPr(holders[0]?.receipt ?? { stage: config.stages[0] ?? "spec", repo, pr }, bounded);
     if (!read || read.state !== "OPEN") { row.blockers.push("current PR evidence unknown or no longer open"); continue; }
     evidence.set(pr, read); row.head = read.head;
+    for (const holder of holders) {
+      const items = findingsForHead(holder.findings ?? [], findingHead(holder.receipt, read));
+      if (!items.length) continue;
+      const tally = findingTally(items);
+      row.findings ??= findingTally([]);
+      for (const key of Object.keys(tally) as (keyof ReviewFindingTally)[]) row.findings[key] += tally[key];
+    }
     if (!read.pathsComplete) row.blockers.push("PR file coverage is incomplete or unknown");
     if (read.draft !== false) row.blockers.push("PR is draft or draft status is unknown");
     if (!read.base) row.blockers.push("PR target branch is unknown");
     const linked = holders.length ? holders : [undefined];
-    for (const holder of linked) row.blockers.push(...sdlcStatus(config, holder?.receipt, read, holder?.phase).blockers);
+    if (config.mode === "enforce" && row.findings?.openImportant) row.blockers.push("open important review findings: " + row.findings.openImportant);
+    for (const holder of linked) {
+      const conformance = holder?.plan ? { ...planConformance(holder.plan.paths, read), accepted: holder.plan.accepted.some(item => item.repo === holder.receipt?.repo && item.pr === holder.receipt?.pr && item.head === read.head && item.revision === holder.plan!.revision && item.fingerprint === holder.plan!.fingerprint && JSON.stringify([...item.paths].sort()) === JSON.stringify([...read.paths].sort())) } : undefined;
+      if (holder && conformance && config.mode !== "off") (row.planConformance ??= []).push({ task: holder.id, state: conformance.state, outside: conformance.outside.length, untouched: conformance.untouched.length, accepted: conformance.accepted });
+      row.blockers.push(...sdlcStatus(config, holder?.receipt, read, holder?.phase).blockers);
+      if (config.mode === "enforce") row.blockers.push(...planConformanceBlockers(conformance));
+    }
   }
   const dependencyEvidence = new Map<number, PrEvidence | undefined>(); let dependencyReads = 0;
   for (const row of result.rows) {

package/src/hub/sdlc-release.ts

@@ -4,7 +4,22 @@ import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { childEnv, stopOwnedProcess } from "./child-process.ts";
 import { hubGitSync } from "./git.ts";
-import { sdlcGh, type SdlcGh } from "./sdlc.ts";
+import type { SdlcGh } from "./sdlc.ts";
+// Standalone document evidence does not need lifecycle/review code; load the default remote reader only when used.
+let importDiagnosticShown = false;
+const sdlcGh: SdlcGh = async (...args) => {
+  let reader: typeof import("./sdlc.ts");
+  try { reader = await import("./sdlc.ts"); }
+  catch {
+    if (!importDiagnosticShown) {
+      importDiagnosticShown = true;
+      try { console.warn("sdlc: release evidence reader unavailable (lifecycle import failed)"); } catch { /* a diagnostic cannot turn unknown evidence into an exception */ }
+    }
+    return { code: 1, stdout: "" };
+  }
+  try { return await reader.sdlcGh(...args); }
+  catch { return { code: 1, stdout: "" }; }
+};
 export interface DocEvidence { schemaVersion: 1; head?: string; version?: string; documents: { path?: string; state: "fresh" | "stale" | "nonancestor" | "unknown"; verifiedAgainst?: string; commits?: number; dirty?: boolean }[]; errors: number; fresh: boolean; }
 export interface ReleaseReadiness { repo: string; head?: string; version?: string; tag?: string; tagCommit?: string; commits: string[]; mergedPrs: { pr: number; commit: string }[]; documents?: DocEvidence; liveIssues: { id: number; state: "open" | "closed" | "unknown" }[]; blockers: string[]; sourceReady: boolean; native: "unverified"; ready: false; }
 export type ReleaseGit = (args: string[]) => { code: number; stdout: string };