@staix/agent-hub 0.12.36 → 0.12.38

package/src/hub/envelope.ts

@@ -14,7 +14,7 @@ export interface Envelope {
   kind: Kind;
   priority: Priority;
   body: string; // agent conclusions only, never tool noise
-  refs?: { repo?: string; branch?: string; commit?: string; paths?: string[]; task?: string; taskOffer?: number; taskCancelled?: number; taskRecipient?: "owner" | "reviewer" | "planner"; backlog?: number[]; supervision?: boolean; supervisionKey?: string; boundedCheck?: string; budgetResume?: string; budgetResumeMoves?: { id: number; title: string; to: PeerId | null; role: "owner" | "reviewer" }[]; budgetResumeEarlier?: string[] };
+  refs?: { repo?: string; branch?: string; commit?: string; paths?: string[]; task?: string; reviewRevision?: string; taskOffer?: number; taskCancelled?: number; taskRecipient?: "owner" | "reviewer" | "planner"; backlog?: number[]; supervision?: boolean; supervisionKey?: string; boundedCheck?: string; budgetResume?: string; budgetResumeMoves?: { id: number; title: string; to: PeerId | null; role: "owner" | "reviewer" }[]; budgetResumeEarlier?: string[] };
   /** The body must not be shown outside its recipients: console tail and log print a stub instead (PII tasks). */
   private?: boolean;
   ts: number;

package/src/hub/host-executable.ts

@@ -2,7 +2,7 @@ import { isAbsolute, relative } from "node:path";
 import { realPath } from "./project.ts";
 
 /** A repo-writable PATH shim is not a host-owned authenticated capability. No caller-selected binary. */
-export function hostExecutable(name: "gh" | "container" | "git", projectDir: string, path = process.env.PATH ?? ""): string {
+export function hostExecutable(name: "gh" | "container" | "git" | "dot", projectDir: string, path = process.env.PATH ?? ""): string {
   const found = Bun.which(name, { PATH: path });
   if (!found || !isAbsolute(found)) throw new Error(`${name} unavailable`);
   const target = realPath(found), inside = relative(realPath(projectDir), target);

package/src/hub/hub-tools.ts

@@ -61,6 +61,11 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_backlog_pull", "Reserve a WIP slot and pull ready unpinned backlog work into To Do at its current revision. Preserves person order/reservations and frozen scope; pending unowned work can be undone with hub_backlog_undo.", { id, revision: { type: "integer", minimum: 0 }, reason: { type: "string", minLength: 1, maxLength: 1000 } }, ["id", "revision", "reason"]),
   tool("hub_backlog_split", "Split unstarted backlog work into two to eight staged parts. The original card retains integration/acceptance and depends on the children. Use after for existing prerequisite ids and afterParts for earlier zero-based part indexes. Latest unused unchanged children can be undone with hub_backlog_undo.", { id, revision: { type: "integer", minimum: 0 }, reason: { type: "string", minLength: 1, maxLength: 1000 }, parts: { type: "array", minItems: 2, maxItems: 8, items: { type: "object", properties: { title: { type: "string", minLength: 1, maxLength: 300 }, detail: { type: "string", maxLength: 8000 }, class: str, refs, plan, after: { type: "array", maxItems: 64, uniqueItems: true, items: { type: "integer", minimum: 1 } }, afterParts: { type: "array", maxItems: 8, uniqueItems: true, items: { type: "integer", minimum: 0 } } }, required: ["title"], additionalProperties: false } } }, ["id", "revision", "reason", "parts"]),
   tool("hub_backlog_undo", "Undo your latest planning change at its current revision. Refuses intervening changes and another actor's edit.", { id, revision: { type: "integer", minimum: 1 } }, ["id", "revision"]),
+  tool("hub_release_new", "Create a future release planning row. Planner/person only; no activation, publish or release authorization.", { name: { type: "string", minLength: 1, maxLength: 64 }, goal: { type: "string", minLength: 1, maxLength: 1000 }, order: { type: "integer", minimum: 0 } }, ["name", "goal", "order"]),
+  tool("hub_release_report", "Read a planned release's task readiness and recorded metrics. Planner/person only. A due date never waives unfinished scope.", { id }, ["id"]),
+  tool("hub_release_assign", "Assign or move only a task's release, retaining its execution state and owner. Planner/person only; requires a reason and current planning revision. Frozen scope refuses.", { id, revision: { type: "integer", minimum: 0 }, release: { type: ["integer", "null"], minimum: 1 }, reason: { type: "string", minLength: 1, maxLength: 1000 } }, ["id", "revision", "release", "reason"]),
+  tool("hub_release_configure", "Configure/activate a release train or record a hotfix cause. Planner/person only. At most one train is active/frozen; planning rows are future trains.", { id, revision: { type: "integer", minimum: 0 }, state: { type: "string", enum: ["active"] }, cut: { type: "integer", minimum: 1 }, hotfix: { type: "object", properties: { cause: { type: "string", enum: ["loss", "security_privacy", "upgrade_start_blocked", "core_flow_no_workaround"] }, reason: { type: "string", minLength: 1, maxLength: 1000 } }, required: ["cause", "reason"], additionalProperties: false } }, ["id", "revision"]),
+  tool("hub_release_cut", "Freeze an active release's approved scope after host resource admission and fresh peer quota checks. Unknown evidence defers; no publish, tag, upgrade or authorization.", { id, revision: { type: "integer", minimum: 0 } }, ["id", "revision"]),
   tool("hub_release_list", "Read public release scope and planned/actual dates for phased planning. Configured planners only.", {}),
 
   tool("hub_task_propose", "Put a piece of work on the shared task board. The hub assigns an owner by class (routing.toml) unless you name one. Classes: plan, implement, bulk_edit, test, review, summarize, triage. Name the class when you know it; without one the hub tries to pick it. Name yourself as owner to claim work nobody assigned you: it starts in progress. Put the paths the work touches in refs, and when you claim work, a plan; the hub says when they overlap another open task.", { title: str, class: { type: "string", enum: ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"] }, detail: str, role: { type: "string", description: "catalog role id for this task class; guidance only, no routing or authority change" }, refs, plan, owner: { type: "string", description: "peer id; yours to claim the work, omit to let the hub route it. With after, the owner is reserved: offered the task first once it is ready" }, after: { type: "array", items: { type: "integer" }, description: "ids of tasks that must be approved first; until then this one waits, offered to nobody, and cannot be claimed" }, backlog: { type: "boolean", description: "stage unoffered work; owner is only a reservation, even when naming yourself" }, urgent: { type: "boolean", description: "hand it over even when its owner is paused for quota only briefly" }, goal: { type: "string", description: "id of this project's long-term task (ahub goal list) the work is part of" } }, ["title"]),

package/src/hub/instances.ts

@@ -7,6 +7,7 @@ export interface InstanceConfig {
   roles?: string[];
   start_mode?: StartForm;
   permission_mode?: PermissionMode;
+  review_mode?: "fresh";
   worktree?: string;
 }
 export type InstancesConfig = Readonly<Record<string, InstanceConfig>>;
@@ -48,15 +49,24 @@ export function validateInstances(raw: unknown): InstancesConfig {
   for (const [id, descriptor] of Object.entries(declarations)) {
     if (!PEER_ID.test(id) || RESERVED.has(id) || definitionOf(id)) return fail("instances", "ids must be nonreserved extra instance ids, not builtin ids");
     const path = `instances.${id}`, entry = fields(descriptor.value, path);
-    if (Object.keys(entry).some(key => !["kind", "roles", "start_mode", "permission_mode", "worktree"].includes(key))) return fail(path, "unsupported field");
+    if (Object.keys(entry).some(key => !["kind", "roles", "start_mode", "permission_mode", "worktree", "review_mode"].includes(key))) return fail(path, "unsupported field");
     const kind: unknown = entry.kind?.value;
     if (typeof kind !== "string") return fail(`${path}.kind`, "must name a native kind");
     const definition = definitionOf(kind), prefix = `${kind}-`;
     if (!definition) return fail(`${path}.kind`, "unknown native kind");
     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;
+    const reviewerOnly = entry.start_mode?.value === "headless" && declaredRoles.length === 1 && declaredRoles[0] === "reviewer";
+    if (entry.review_mode && (entry.review_mode.value !== "fresh" || !reviewerOnly || !reviewer)) return fail(`${path}.review_mode`, "fresh requires reviewer-only roles, headless mode and a declared fresh-review capability");
+    const freshReviewer = reviewerOnly && !!reviewer && (reviewer.declaration === "automatic" || entry.review_mode?.value === "fresh");
+    if (definition.routing?.reviewOnly && !freshReviewer) return fail(path, "a review-only kind requires headless roles exactly [\"reviewer\"]");
+    if (freshReviewer && entry.worktree) return fail(`${path}.worktree`, "a fresh reviewer reads the project checkout: worktree is not supported");
+    if (freshReviewer && entry.permission_mode) return fail(`${path}.permission_mode`, "a fresh reviewer has a fixed read-only policy");
     // #450 I3: a channel-plugin kind (Claude) runs only in the person's terminal, so it reviews or plans and never owns writes.
     const channel = definition.identity.mcp === "channel-plugin";
-    if (!channel && (!definition.start.create || !definition.start.forms.includes("headless") || !["env", "acp-session"].includes(definition.identity.mcp))) return fail(`${path}.kind`, "unsupported; a headless factory with env or ACP-session identity, or a channel-plugin kind, is required, not project-file identity");
+    const unavailableReviewer = freshReviewer && !!(definition.reviewerVariant ?? definition).reviewer?.unavailable;
+    if (!channel && !unavailableReviewer && (!definition.start.create || !definition.start.forms.includes("headless") || !["env", "acp-session"].includes(definition.identity.mcp))) return fail(`${path}.kind`, "unsupported; a headless factory with env or ACP-session identity, or a channel-plugin kind, is required, not project-file identity");
     if (channel) {
       const declared = entry.roles ? roles(entry.roles.value, `${path}.roles`) : [];
       // #223: a headless one is the kind's reviewer variant, one fresh hub-run session per review request.
@@ -68,7 +78,7 @@ export function validateInstances(raw: unknown): InstancesConfig {
         if (!declared.length || declared.some(role => role !== "reviewer" && role !== "planner")) return fail(`${path}.roles`, "a channel instance must declare its roles: reviewer and/or planner");
       }
     }
-    const value: InstanceConfig = { kind };
+    const value: InstanceConfig = { kind, ...(entry.review_mode ? { review_mode: "fresh" as const } : {}) };
     if (entry.roles) { value.roles = roles(entry.roles.value, `${path}.roles`); Object.freeze(value.roles); }
     if (entry.start_mode) {
       if (entry.start_mode.value !== "headless") return fail(`${path}.start_mode`, "I2 extra instances require headless mode");

package/src/hub/memory-profile.ts

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

package/src/hub/native-hook-launch.ts

@@ -0,0 +1,37 @@
+/** Managed launch authority is ephemeral and scoped to one peer, daemon and native session. */
+export interface NativeHookLaunch {
+  id: string;
+  session?: string;
+  generation?: string;
+  baseline?: number;
+  turn?: string;
+  active: boolean;
+  completed?: string;
+}
+export class NativeHookLaunches {
+  private readonly launches = new Map<string, NativeHookLaunch>();
+  private readonly owners = new Map<string, object>();
+  begin(peer: string, owner: object): NativeHookLaunch {
+    if (this.launches.has(peer)) throw new Error("a managed native launch is already active; end it in its terminal first");
+    const launch: NativeHookLaunch = { id: crypto.randomUUID(), active: false };
+    this.launches.set(peer, launch);
+    this.owners.set(peer, owner);
+    return launch;
+  }
+  get(peer: string, id: unknown): NativeHookLaunch | undefined {
+    const launch = this.launches.get(peer);
+    return launch && typeof id === "string" && launch.id === id ? launch : undefined;
+  }
+  end(peer: string, id: unknown): boolean {
+    if (!this.get(peer, id)) return false;
+    this.owners.delete(peer);
+    return this.launches.delete(peer);
+  }
+  endOwner(owner: object): void {
+    for (const [peer, current] of this.owners) {
+      if (current !== owner) continue;
+      this.launches.delete(peer);
+      this.owners.delete(peer);
+    }
+  }
+}

package/src/hub/peer-catalog.ts

@@ -6,14 +6,13 @@ export { SUPPORTED_PEERS } from "../adapters/registry.ts";
 /** Native peers the hub knows; membership checks share the registry. */
 export const KNOWN_PEERS = ["claude", "codex", "kimi", "pi", "local"] as const;
 /** Optional production peers are added explicitly; legacy defaults remain stable. */
-export const OPTIONAL_PEERS = ["qwen", "jcode"] as const;
+export const OPTIONAL_PEERS = ["qwen", "jcode", "agy"] as const;
 export type KnownPeer = typeof SUPPORTED_PEERS[number];
 
 export const isKnownPeer = (value: unknown): value is KnownPeer =>
   typeof value === "string" && !!definitionOf(value) && !definitionOf(value)!.optional;
 
-export const isSupportedPeer = (value: unknown): value is KnownPeer =>
-  typeof value === "string" && !!definitionOf(value);
+export { isSupportedPeer } from "../adapters/registry.ts";
 
 // Policy and historical projection order belong to the registry; public compatibility exports remain intact.
 export { defaultPeerRoles, PLANNER_PEERS } from "../adapters/registry.ts";

package/src/hub/planning.ts

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

package/src/hub/release-admission.ts

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

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

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

package/src/hub/reviewer-pool.ts

@@ -0,0 +1,76 @@
+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" };
+  // A configured kind without any declaration cannot take a modulo share from actual reviewers.
+  // Blocked declarations still own their slot: current availability never changes the denominator.
+  const declaredKinds = kinds.filter(kind => input.candidates.some(candidate => candidate.kind === kind));
+  const undeclared = kinds.filter(kind => !declaredKinds.includes(kind)).map(kind => ({ id: "", kind, family: "", reason: "no declared reviewer" }));
+  const finish = (selection: Omit<ReviewerPoolSelection, "walk">): ReviewerPoolSelection => ({ ...selection, walk: [...walk, ...undeclared] });
+  if (!declaredKinds.length) return finish({ reviewer: null, blocked: "no reviewer can run" });
+  const seed = Number.isSafeInteger(input.seed) ? input.seed : 0;
+  const start = ((seed % declaredKinds.length) + declaredKinds.length) % declaredKinds.length;
+  const rotated = [...declaredKinds.slice(start), ...declaredKinds.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;
+  });
+  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 finish({ reviewer: candidate.id, family: candidate.family, reason });
+  }
+  // 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 finish({ reviewer: candidate.id, family: candidate.family, reason: "same-family fallback" });
+  }
+  return finish({ reviewer: null, blocked: "no reviewer can run" });
+}

package/src/hub/routing.ts

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