@staix/agent-hub 0.12.34 → 0.12.36

package/src/hub/review-brief.ts

@@ -0,0 +1,175 @@
+import { childEnv } from "./child-process.ts";
+import { hubGitSync } from "./git.ts";
+
+/**
+ * #520: the review brief ahub builds itself, in place of `ocr delegate preview` and `rule`. Every reviewer gets the same
+ * one: the changed files of the head against its merge base with the checkout's HEAD, the files left out and why, the
+ * review rules that apply to each file, and the files the plain name list shows that the brief does not. Only git is
+ * read, bounded; nothing here touches the board.
+ */
+export interface BriefFile { path: string; status: string; oldPath?: string; insertions?: number; deletions?: number }
+export interface BriefExcluded { path: string; status: string; oldPath?: string; reason: string }
+export interface ReviewBrief {
+  head: string;
+  /** The default branch the head is compared with: origin/HEAD, origin/main or origin/master. */
+  base: string;
+  mergeBase: string;
+  reviewable: BriefFile[];
+  excluded: BriefExcluded[];
+  /** Changes left out by the privacy policy, both sides of a move included; counted, never named. */
+  withheld: number;
+  /** Rule files by name (REVIEW.md, then `ahub-review-rules` attribute values) with their text at the merge base. */
+  rules: { source: string; text: string }[];
+  /** Configured rule files the brief could not load, with why: the reviewer reads them in the repository. */
+  rulesMissing: { source: string; reason: string }[];
+  /** Reviewable paths grouped by the rule sources that apply to them. */
+  ruleGroups: { sources: string[]; paths: string[] }[];
+  /** Paths in the plain name list of the range that the brief does not list: read them directly. */
+  unlisted: string[];
+}
+export interface BriefPolicy { privatePath(path: string): boolean; nameable(text: string): boolean }
+
+const MAX_FILES = 500, RULE_BYTES = 32_000, MAX_RULE_FILES = 8;
+const LOCKFILES = new Set(["bun.lock", "bun.lockb", "package-lock.json", "yarn.lock", "pnpm-lock.yaml", "Cargo.lock", "poetry.lock", "uv.lock", "go.sum", "composer.lock", "Gemfile.lock"]);
+const HEX = /^[0-9a-f]{7,40}$/i;
+
+/** Every diff of the brief reads attributes from the trusted tree, never the checkout (a head's `* -diff` cannot mark its own files binary). */
+const attrFrom = (source?: string) => source ? [`--attr-source=${source}`] : [];
+const git = (cwd: string, args: string[]) => hubGitSync(["-C", cwd, ...args], { encoding: "utf8", env: childEnv(process.env), maxBuffer: 16 * 1024 * 1024, timeout: 15_000 });
+
+/**
+ * The changes of `HEAD...head` as groups: one path, or both sides of a rename or copy. A caller that must not show a
+ * private file withholds a whole group when any side is private, so content never shows up under a public name.
+ * ponytail: git's 50% similarity decides what counts as a move.
+ */
+export function changedPathGroups(cwd: string, head: string, base = "HEAD", attrSource?: string): { status: string; paths: string[] }[] | undefined {
+  const r = git(cwd, [...attrFrom(attrSource), "diff", "--no-ext-diff", "--no-textconv", "--relative", "-M", "-C", "--find-copies-harder", "--name-status", "-z", `${base}...${head}`, "--"]);
+  if (r.status !== 0 || typeof r.stdout !== "string") return undefined;
+  const fields = r.stdout.split("\0"), groups: { status: string; paths: string[] }[] = [];
+  for (let i = 0; i < fields.length - 1;) {
+    const status = fields[i++]!, sides = /^[RC]/.test(status) ? 2 : 1;
+    groups.push({ status, paths: fields.slice(i, i + sides) }); i += sides;
+  }
+  return groups;
+}
+
+export function buildReviewBrief(cwd: string, head: unknown, policy: BriefPolicy): ReviewBrief | { unavailable: string } {
+  if (typeof head !== "string" || !HEX.test(head)) return { unavailable: "the task names no commit" };
+  const full = git(cwd, ["rev-parse", "--verify", "-q", `${head}^{commit}`]);
+  if (full.status !== 0 || typeof full.stdout !== "string") return { unavailable: `commit ${head} is not in this checkout` };
+  const commit = full.stdout.trim();
+  // A reliable base only: the remote's default branch. The checkout's HEAD may be the head itself (an empty inventory)
+  // or another session's branch.
+  const from = ["origin/HEAD", "origin/main", "origin/master"].find(ref => git(cwd, ["rev-parse", "--verify", "-q", `${ref}^{commit}`]).status === 0);
+  if (!from) return { unavailable: "no default branch (origin/HEAD, origin/main or origin/master) to compare with" };
+  const base = git(cwd, ["merge-base", from, commit]);
+  if (base.status !== 0 || typeof base.stdout !== "string") return { unavailable: `commit ${head} shares no history with ${from}` };
+  const mergeBase = base.stdout.trim();
+  const groups = changedPathGroups(cwd, commit, from, mergeBase);
+  if (!groups) return { unavailable: `the changes of ${head} could not be read` };
+  if (!groups.length) return { unavailable: `commit ${head} has no changes against ${from}` };
+  const shown = groups.filter(g => !g.paths.some(path => policy.privatePath(path) || !policy.nameable(path)));
+  if (shown.length > MAX_FILES) return { unavailable: `${shown.length} changed files, over the brief's ${MAX_FILES}` };
+  const withheld = groups.length - shown.length;
+  const counts = numstat(cwd, commit, from, mergeBase);
+  // Attributes and rules come from the merge base: a change cannot lift its own review obligations (a head that marks
+  // everything generated, or edits REVIEW.md, is still reviewed under the rules it is merging into).
+  // Both sides of a move: renaming a reviewed file to a generated or unscoped name must not shed its obligations.
+  const attrs = attributes(cwd, mergeBase, [...new Set(shown.flatMap(g => g.paths))]);
+  if (!counts || !attrs) return { unavailable: `the file details of ${head} could not be read` };
+  const reviewable: BriefFile[] = [], excluded: BriefExcluded[] = [];
+  for (const g of shown) {
+    const path = g.paths.at(-1)!, count = counts.get(path);
+    const sides = { status: g.status[0]!, ...(g.paths.length === 2 ? { oldPath: g.paths[0]! } : {}) };
+    // Excluded only when every side is: a move keeps the source's obligation.
+    const sideReason = (p: string) => attrs.get(p)?.generated ? "generated (linguist-generated)" : LOCKFILES.has(p.split("/").at(-1)!) ? "lockfile" : undefined;
+    const reasons = g.paths.map(sideReason);
+    const reason = count?.binary ? "binary" : reasons.every(Boolean) ? reasons.at(-1) : undefined;
+    if (reason) { excluded.push({ path, ...sides, reason }); continue; }
+    reviewable.push({ path, ...sides, ...(count && !count.binary ? { insertions: count.insertions, deletions: count.deletions } : {}) });
+  }
+  const ruleText = new Map<string, string>(), rulesMissing = new Map<string, string>();
+  const readRule = (source: string): boolean => {
+    if (ruleText.has(source)) return true;
+    if (rulesMissing.has(source)) return false;
+    // A private or non-nameable rule path is not named either: it is left out silently.
+    if (policy.privatePath(source) || !policy.nameable(source)) return false;
+    if (ruleText.size >= MAX_RULE_FILES) { rulesMissing.set(source, `over the brief's ${MAX_RULE_FILES} rule files`); return false; }
+    const r = git(cwd, ["show", `${mergeBase}:${source}`]);
+    if (r.status !== 0 || typeof r.stdout !== "string") { rulesMissing.set(source, "not found at the merge base"); return false; }
+    // Screened whole, before any cut: a rule file that matches a private-data pattern is named but not shown.
+    if (!policy.nameable(r.stdout)) { ruleText.set(source, "(withheld: it matches a private-data pattern; read it in the repository)"); return true; }
+    const bytes = Buffer.from(r.stdout, "utf8");
+    ruleText.set(source, bytes.length > RULE_BYTES ? `${bytes.subarray(0, RULE_BYTES).toString("utf8")}\n[cut at ${RULE_BYTES} bytes]` : r.stdout);
+    return true;
+  };
+  const root = readRule("REVIEW.md");
+  const byKey = new Map<string, { sources: string[]; paths: string[] }>();
+  for (const file of reviewable) {
+    // The rules of every side apply, so a move out of a scoped directory keeps its rule file.
+    const scoped = [...new Set([file.oldPath, file.path].flatMap(p => { const r = p ? attrs.get(p)?.rules : undefined; return r ? [r] : []; }))];
+    const sources = [...(root ? ["REVIEW.md"] : []), ...scoped.filter(readRule)];
+    const key = sources.join("\0");
+    (byKey.get(key) ?? byKey.set(key, { sources, paths: [] }).get(key)!).paths.push(file.path);
+  }
+  // Cross-check with the plain name list (no rename detection), as OCR's list is checked against the PR's.
+  const plain = git(cwd, [...attrFrom(mergeBase), "diff", "--relative", "--no-renames", "--name-only", "-z", `${from}...${commit}`, "--"]);
+  if (plain.status !== 0 || typeof plain.stdout !== "string") return { unavailable: `the name list of ${head} could not be read` };
+  const listed = new Set(shown.flatMap(g => g.paths)), hidden = new Set(groups.filter(g => !shown.includes(g)).flatMap(g => g.paths));
+  const unlisted = plain.stdout.split("\0").filter(path => path && !listed.has(path) && !hidden.has(path));
+  return { head: commit, base: from, mergeBase, reviewable, excluded, withheld, rules: [...ruleText].map(([source, text]) => ({ source, text })), rulesMissing: [...rulesMissing].map(([source, reason]) => ({ source, reason })), ruleGroups: [...byKey.values()], unlisted };
+}
+
+function numstat(cwd: string, head: string, base: string, attrSource: string): Map<string, { insertions: number; deletions: number; binary: boolean }> | undefined {
+  const out = new Map<string, { insertions: number; deletions: number; binary: boolean }>();
+  const r = git(cwd, [...attrFrom(attrSource), "diff", "--no-ext-diff", "--no-textconv", "--relative", "-M", "-C", "--find-copies-harder", "--numstat", "-z", `${base}...${head}`, "--"]);
+  if (r.status !== 0 || typeof r.stdout !== "string") return undefined;
+  // -z: "ins\tdel\tpath\0", or for a move "ins\tdel\t\0old\0new\0"; a binary file has "-" counts.
+  const fields = r.stdout.split("\0");
+  for (let i = 0; i < fields.length - 1;) {
+    const [ins = "", del = "", path = ""] = fields[i++]!.split("\t");
+    const target = path || (i++, fields[i++] ?? "");
+    out.set(target, { insertions: Number(ins) || 0, deletions: Number(del) || 0, binary: ins === "-" });
+  }
+  return out;
+}
+
+function attributes(cwd: string, source: string, paths: string[]): Map<string, { generated?: boolean; rules?: string }> | undefined {
+  const out = new Map<string, { generated?: boolean; rules?: string }>();
+  if (!paths.length) return out;
+  const r = hubGitSync(["-C", cwd, "check-attr", "-z", "--stdin", `--source=${source}`, "linguist-generated", "ahub-review-rules"], { input: paths.join("\0") + "\0", encoding: "utf8", env: childEnv(process.env), maxBuffer: 4 * 1024 * 1024, timeout: 15_000 });
+  if (r.status !== 0 || typeof r.stdout !== "string") return undefined;
+  const f = r.stdout.split("\0");
+  for (let i = 0; i + 2 < f.length; i += 3) {
+    const [path, attr, value] = [f[i]!, f[i + 1]!, f[i + 2]!], entry = out.get(path) ?? {};
+    if (attr === "linguist-generated" && (value === "set" || value === "true")) entry.generated = true;
+    if (attr === "ahub-review-rules" && value !== "unspecified" && value !== "unset" && value !== "set" && !value.startsWith("/") && !value.split("/").includes("..")) entry.rules = value;
+    out.set(path, entry);
+  }
+  return out;
+}
+
+/** The brief as review text: what every reviewer reads and how it accounts for its coverage. */
+export function renderReviewBrief(brief: ReviewBrief): string {
+  const file = (f: BriefFile) => `- ${f.oldPath ? `${f.oldPath} -> ` : ""}${f.path} (${f.status}${f.insertions !== undefined ? `, +${f.insertions} -${f.deletions}` : ""})`;
+  return [
+    `Review brief: head ${brief.head} against ${brief.base} (merge base ${brief.mergeBase.slice(0, 12)}); ${brief.reviewable.length} reviewable, ${brief.excluded.length} excluded${brief.withheld ? `, ${brief.withheld} withheld by the privacy policy` : ""}.`,
+    ...(brief.reviewable.length ? ["Reviewable:", ...brief.reviewable.map(file)] : ["Reviewable: none (record why in the note)."]),
+    ...(brief.excluded.length ? ["Excluded (still read their diff when it matters):", ...brief.excluded.map(e => `- ${e.oldPath ? `${e.oldPath} -> ` : ""}${e.path} (${e.status}): ${e.reason}`)] : []),
+    ...(brief.unlisted.length ? ["Not in the brief's list, read directly:", ...brief.unlisted.map(path => `- ${path}`)] : []),
+    ...brief.ruleGroups.filter(g => g.sources.length).map(g => `Rules ${g.sources.join(" + ")} apply to: ${brief.ruleGroups.length === 1 ? "every reviewable file" : g.paths.join(", ")}`),
+    ...(brief.rulesMissing.length ? ["Configured rules not loaded (read them in the repository):", ...brief.rulesMissing.map(m => `- ${m.source}: ${m.reason}`)] : []),
+    ...brief.rules.map(r => `--- ${r.source} ---\n${r.text.trimEnd()}`),
+    `Coverage: pass hub_review coverage {reviewed: [paths], skipped: [{path, reason}]} naming every reviewable path above.`,
+  ].join("\n");
+}
+
+/** The reviewable paths a verdict's coverage does not account for: reviewed, or skipped with a reason. */
+export function coverageGap(brief: ReviewBrief, coverage: unknown): string[] {
+  const c = coverage && typeof coverage === "object" && !Array.isArray(coverage) ? coverage as { reviewed?: unknown; skipped?: unknown } : {};
+  const accounted = new Set<string>([
+    ...(Array.isArray(c.reviewed) ? c.reviewed.filter((p): p is string => typeof p === "string") : []),
+    ...(Array.isArray(c.skipped) ? c.skipped.flatMap(s => s && typeof s === "object" && typeof (s as { path?: unknown }).path === "string" && typeof (s as { reason?: unknown }).reason === "string" && (s as { reason: string }).reason.trim() ? [(s as { path: string }).path] : []) : []),
+  ]);
+  return brief.reviewable.map(f => f.path).filter(path => !accounted.has(path));
+}

package/src/hub/roster.ts

@@ -1,14 +1,14 @@
-import { definitionOf } from "../adapters/registry.ts";
+import { definitionOf, type KindMap } from "../adapters/registry.ts";
 import { defaultRosterEnabled } from "../adapters/registry.ts";
 
 export type PeerRoster = Partial<Record<string, boolean>>;
 
-export function peerRosterConfig(value: unknown): PeerRoster {
+export function peerRosterConfig(value: unknown, instances?: KindMap): PeerRoster {
   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 = {};
   for (const [peer, on] of Object.entries(value)) {
-    if (!definitionOf(peer)) throw new Error("roster contains an unsupported peer");
+    if (!definitionOf(peer, instances)) throw new Error("roster contains an unsupported peer");
     if (typeof on !== "boolean") throw new Error(`roster.${peer} must be a boolean`);
     roster[peer] = on;
   }
@@ -16,7 +16,8 @@ export function peerRosterConfig(value: unknown): PeerRoster {
 }
 
 /** External ids keep their existing admission rules; Pi's legacy switch is only its default. */
-export function rosterAllows(roster: PeerRoster, peer: string, piEnabled: boolean): boolean {
-  if (!definitionOf(peer)) return true;
-  return roster[peer] ?? defaultRosterEnabled(peer, piEnabled);
+export function rosterAllows(roster: PeerRoster, peer: string, piEnabled: boolean, instances?: KindMap): boolean {
+  const definition = definitionOf(peer, instances);
+  if (!definition) return true; // External clients do not acquire a native kind from a project declaration.
+  return roster[peer] ?? (definition.kind === peer ? defaultRosterEnabled(peer, piEnabled) : true);
 }

package/src/hub/routing.ts

@@ -1,4 +1,4 @@
-import { ADAPTERS, definitionOf } from "../adapters/registry.ts";
+import { ADAPTERS, definitionOf, kindOf, familyOf } from "../adapters/registry.ts";
 import { readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { CLASSES, type Task, type TaskClass } from "./board.ts";
@@ -109,14 +109,54 @@ const TEMPLATE = join(import.meta.dir, "..", "..", "templates", "routing.toml");
 export const LOCAL: PeerId = "local";
 export const PI: PeerId = "pi";
 
+/** Startup-bound project data, never inferred from a suffix or read from configuration here. */
+export interface InstanceRoutingOptions {
+  instances?: Readonly<Record<string, { kind: string }>>;
+  wip?: Record<string, number>;
+  load?: Record<string, number>;
+  /** Positive host verification of the live extra runtime's noncanonical execution root. */
+  ownerIsolation?: Readonly<Record<string, boolean>>;
+}
+const hasInstances = (opts: InstanceRoutingOptions): boolean => !!opts.instances && Object.keys(opts.instances).length > 0;
+function siblingOrder(states: Readonly<Record<string, PeerState>>, opts: InstanceRoutingOptions): (a: string, b: string) => number {
+  const count = (map: Record<string, number> | undefined, id: string) => {
+    const value = peerEntry(map, id);
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+  };
+  return (a, b) => Number(states[a] !== "idle") - Number(states[b] !== "idle") || count(opts.wip, a) - count(opts.wip, b) || count(opts.load, a) - count(opts.load, b);
+}
+/** A class kind expands once; an explicitly declared instance remains an exact id. */
+function expandClassPeers(peers: readonly PeerId[], states: Readonly<Record<string, PeerState>>, opts: InstanceRoutingOptions): PeerId[] {
+  if (!hasInstances(opts)) return [...peers];
+  return [...new Set(peers.flatMap(peer => {
+    const kind = kindOf(peer, opts.instances);
+    return kind && kind === peer ? [peer, ...Object.keys(opts.instances!).filter(id => kindOf(id, opts.instances) === kind)].sort(siblingOrder(states, opts)) : [peer];
+  }))];
+}
+/** Quota/adaptive policy retains kind slots; sibling workload chooses only within that kind's slots. */
+function orderSiblingSlots(peers: PeerId[], states: Readonly<Record<string, PeerState>>, opts: InstanceRoutingOptions): PeerId[] {
+  if (!hasInstances(opts)) return peers;
+  const groups = new Map<string, number[]>(), out = [...peers];
+  for (const [index, peer] of peers.entries()) {
+    const kind = kindOf(peer, opts.instances);
+    if (kind) { const slots = groups.get(kind) ?? []; slots.push(index); groups.set(kind, slots); }
+  }
+  for (const slots of groups.values()) {
+    const sorted = slots.map(index => peers[index]!).sort(siblingOrder(states, opts));
+    slots.forEach((index, position) => { out[index] = sorted[position]!; });
+  }
+  return out;
+}
+
 /** The quota/roster relay keeps its native preference order, then the class's original tail. */
-export function relayCandidates(classPeers: readonly PeerId[], pii: boolean): PeerId[] {
+export function relayCandidates(classPeers: readonly PeerId[], pii: boolean, opts: InstanceRoutingOptions & { states?: Readonly<Record<string, PeerState>> } = {}): PeerId[] {
   const preferred = ADAPTERS.filter(adapter => adapter.routing?.handoffPriority !== undefined)
     .sort((a, b) => a.routing!.handoffPriority! - b.routing!.handoffPriority!);
-  return [
+  const candidates = [
     ...preferred.filter(adapter => !pii || adapter.trust.onPrem).map(adapter => adapter.kind),
-    ...classPeers.filter(peer => definitionOf(peer)?.routing?.handoffPriority === undefined),
+    ...classPeers.filter(peer => definitionOf(peer, opts.instances)?.routing?.handoffPriority === undefined),
   ].filter((peer): peer is PeerId => !!peer);
+  return expandClassPeers(candidates, opts.states ?? {}, opts);
 }
 
 /**
@@ -245,9 +285,13 @@ export function detectSignals(task: Pick<Task, "title" | "detail" | "refs">, rou
 /** A peer's entry in a peer-indexed map: own keys only, so a peer named `constructor` is never an inherited Object member. */
 export const peerEntry = <T>(map: Readonly<Record<string, T>> | undefined, peer: string): T | undefined => (map && Object.hasOwn(map, peer) ? map[peer] : undefined);
 
-export type RoutingRefusalCode = "tests" | "spec" | "roster" | "pull-only" | "not-attached" | "excluded" | "owner-admission" | "offline" | "paused" | "failing" | "pii" | "policy";
+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 {
+  /** 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;
@@ -268,7 +312,7 @@ export function assign(
   task: Pick<Task, "class" | "signals" | "reserved"> & Partial<Pick<Task, "state" | "title" | "detail" | "refs" | "external">>,
   states: Record<PeerId, PeerState>,
   routing: Routing,
-  opts: {
+  opts: InstanceRoutingOptions & {
     capabilities?: Record<PeerId, PeerCapabilities>;
     repository?: string;
     exclude?: PeerId[];
@@ -301,13 +345,14 @@ export function assign(
 ): Assignment {
   if (task.state === "cancelled" || task.state === "approved") return { trace: [`${task.state}: closed; not routed`] };
   if (task.state === "backlog") return { trace: ["backlog: not routed; pull into To Do first"] };
+  const instanceMode = hasInstances(opts);
   const policy = routing.classes[task.class];
   const trace: string[] = [`class ${task.class}${policy ? "" : " (no [classes] entry: only an explicit owner can take it)"}`, `signals: ${task.signals.join(", ") || "none"}`];
   // Which file each of this class's values comes from (#269), only when the machine-local overlay sets one.
   const local = Object.keys(routing.sources ?? {}).filter((key) => key.startsWith(`classes.${task.class}.`)).map((key) => key.slice(`classes.${task.class}.`.length));
   if (local.length) trace.push(`policy source: ${local.join(", ")} from ${OVERLAY_FILE}; the rest from routing.toml`);
   // A reserved owner (issue #207) is offered the task first. Named candidates (an assign, an escalation, a relay) replace it.
-  const reserved = opts.candidates ? undefined : task.reserved ?? undefined;
+  const reserved = opts.candidates || instanceMode && opts.namedOwner !== undefined ? undefined : task.reserved ?? undefined;
   // Readiness is an input like peer states (issue #34): a task that waits for others goes to nobody yet.
   if (opts.waitsFor?.length) return { trace: [...trace, `blocked: waits for ${opts.waitsFor.map((id) => `#${id}`).join(", ")} (not approved)`, ...(reserved ? [`reserved owner ${reserved}: offered first once it is ready`] : [])] };
   const pii = task.signals.includes("pii_path") || (task.signals.includes("pii") && routing.constraints.pii === "local_only");
@@ -330,12 +375,18 @@ export function assign(
     if (!Object.hasOwn(states, peer)) return deny("not-attached", "not attached");
     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");
+    }
     if (states[peer] === "offline") return deny("offline", "offline");
     if (states[peer] === "paused" && routing.constraints.budget_paused === "skip_peer") return deny("paused", "paused");
     const failing = peerEntry(opts.failing, peer);
     if (failing) return deny("failing", `failing: ${failing}`);
-    if (pii && definitionOf(peer)?.trust.onPrem !== true) return deny("pii", "pii: on-prem peers only");
-    const nativeRouting = definitionOf(peer)?.routing;
+    if (pii && definitionOf(peer, opts.instances)?.trust.onPrem !== true) return deny("pii", "pii: on-prem peers only");
+    const nativeRouting = definitionOf(peer, opts.instances)?.routing;
     if (nativeRouting?.localAllowedRefusal && policy?.local_allowed === false) return deny("policy", nativeRouting.localAllowedRefusal);
     if (nativeRouting?.longContext === "backend-limit" && task.signals.includes("long_context")) {
       const backend = policy?.pi_backend ?? "dgx";
@@ -383,16 +434,16 @@ export function assign(
     return role === "reviewer" ? byRecord(ranked, owner) : ranked;
   };
 
-  const pick = (list: PeerId[], role: "owner" | "reviewer", not?: PeerId): PeerId | undefined => {
+  const pick = (list: PeerId[], role: "owner" | "reviewer", not?: PeerId, sortSiblings = false): PeerId | undefined => {
     const ok: PeerId[] = [];
     for (const peer of list) {
       const why = peer === not ? "is the owner" : blocked(peer, role);
       trace.push(`  ${role} candidate ${peer}: ${why ? `skipped, ${why}` : states[peer]}`);
       if (!why) ok.push(peer);
     }
-    const ranked = rank(ok, role, not);
+    const ranked = sortSiblings ? orderSiblingSlots(rank(ok, role, not), states, opts) : rank(ok, role, not);
     // Demotion applies to local and Pi too: a demoted one loses its place ahead of the cloud peers.
-    const localTier = ranked.filter((p) => definitionOf(p)?.routing?.preferredTier === true && !(role === "owner" && peerEntry(opts.demoted, p)));
+    const localTier = ranked.filter((p) => definitionOf(p, opts.instances)?.routing?.preferredTier === true && !(role === "owner" && peerEntry(opts.demoted, p)));
     if (localTier.length) return localTier.find((p) => states[p] === "idle") ?? localTier[0]; // local/Pi stays ahead of an idle cloud peer
     return ranked.find((p) => states[p] === "idle") ?? ranked[0];
   };
@@ -401,13 +452,16 @@ export function assign(
   const unreserved = reserved ? blocked(reserved, "owner") : undefined;
   if (reserved) trace.push(`reserved owner ${reserved}: ${unreserved ? `not honored, ${unreserved}; routing proceeds` : "honored"}`);
   // Never the task's current owner by default: a decline or an escalation has to reach the next peer in the list.
-  const wanted = reserved && !unreserved ? [reserved] : opts.candidates ?? policy?.peers ?? [];
-  const owner = pick(wanted, "owner");
+  const automaticOwner = !(reserved && !unreserved) && opts.candidates === undefined && !(instanceMode && opts.namedOwner !== undefined);
+  const wanted = reserved && !unreserved ? [reserved] : opts.candidates ?? (instanceMode && opts.namedOwner !== undefined ? [opts.namedOwner] : expandClassPeers(policy?.peers ?? [], states, opts));
+  const owner = pick(wanted, "owner", undefined, automaticOwner);
   trace.push(owner ? `owner: ${owner}` : "owner: none available, task stays proposed (ahub task assign <id> <peer>)");
   const ownerHold = owner ? peerEntry(opts.held, owner) : undefined;
   if (ownerHold) trace.push(`  hold: ${owner}'s queue is held: ${ownerHold} (it receives the task once the hold is resolved)`);
 
   let reviewer: PeerId | undefined;
+  let sameFamilyFallback = false;
+  let plannerFallback = false;
   if (task.class !== "review") {
     if (pii) trace.push("reviewer: user (pii: no second on-prem peer; ahub review <id> <verdict>)");
     else {
@@ -415,7 +469,32 @@ export function assign(
       const classPeers = routing.classes.review?.peers ?? [];
       const rolePeers = Object.keys(opts.roles ?? {}).filter((p) => opts.roles![p]!.includes("reviewer"));
       trace.push(opts.namedReviewer === undefined ? `  reviewer candidates: [classes.review] peers ${classPeers.join(", ") || "none"}${rolePeers.length ? `; reviewer role ${rolePeers.join(", ")}` : ""}` : `  reviewer candidate explicitly named: ${opts.namedReviewer}`);
-      reviewer = pick(opts.namedReviewer === undefined ? [...new Set([...classPeers, ...rolePeers])] : [opts.namedReviewer], "reviewer", owner ?? opts.notReviewer);
+      const reviewOwner = owner ?? opts.notReviewer;
+      const automatic = [...new Set([...expandClassPeers(classPeers, states, opts), ...rolePeers])];
+      const ownerFamily = instanceMode && reviewOwner ? familyOf(reviewOwner, opts.instances) : undefined;
+      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 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 {
+        // #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`);
+      }
       trace.push(reviewer ? `reviewer: ${reviewer}` : "reviewer: none, done will approve directly");
       const reviewerHold = reviewer ? peerEntry(opts.held, reviewer) : undefined;
       if (reviewerHold) trace.push(`  hold: ${reviewer}'s queue is held: ${reviewerHold} (it receives the review once the hold is resolved)`);
@@ -424,9 +503,9 @@ export function assign(
   const route = policy?.route ?? routing.local.route;
   const fixedModel = policy?.fixed_model ?? routing.local.fixed_model;
   const piBackend = policy?.pi_backend;
-  if (owner && definitionOf(owner)?.routing?.trace === "route") trace.push(`route: ${route ?? "(none)"}, fixed_model ${fixedModel}`);
-  if (owner && definitionOf(owner)?.routing?.trace === "backend") trace.push(`${definitionOf(owner)!.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 { ...(owner ? { owner } : {}), ...(pii ? { reviewer: "user" } : reviewer ? { reviewer } : {}), ...(route ? { route } : {}), fixedModel, ...(piBackend ? { piBackend } : {}), ...(unreserved ? { unreserved } : {}), ...(refusals.size ? { refusals: [...refusals.values()] } : {}), trace };
+  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 };
 }
 
 /**

package/src/hub/sdlc-queue.ts

@@ -1,6 +1,6 @@
-import type { PhaseView } from "./workflow.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?: PhaseView; }
+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 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; }