@staix/agent-hub 0.12.33 → 0.12.35

package/src/hub/execution-budget.ts

@@ -1,3 +1,4 @@
+import { definitionOf, type KindMap } from "../adapters/registry.ts";
 import { Database } from "bun:sqlite";
 import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 
@@ -41,7 +42,7 @@ const validLimits = (raw: ExecutionBudgetLimits): ExecutionBudgetLimits => {
 /** Persistent, cross-turn execution meter. Each admission and increment is one SQLite transaction. */
 export class ExecutionBudget {
   private readonly db: Database;
-  constructor(path: string) {
+  constructor(path: string, private readonly instances?: KindMap) {
     this.db = new Database(path, { create: true });
     this.db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
     this.db.run("PRAGMA journal_mode = WAL");
@@ -56,7 +57,7 @@ export class ExecutionBudget {
     if (input.kind === "task" && (!Number.isSafeInteger(input.taskId) || input.taskId! < 1)) throw new Error("task budget requires a positive task id");
     const peers = [...new Set(input.peers.filter((p) => typeof p === "string" && p.length > 0))].sort();
     if (!peers.length) throw new Error("execution budget requires at least one peer");
-    const unsupported = peers.filter((peer) => peer !== "pi" && peer !== "local");
+    const unsupported = peers.filter((peer) => !definitionOf(peer, this.instances)?.budget?.instrumented);
     if (unsupported.length) throw new Error(`execution budgets require instrumented peers (pi, local); unsupported: ${unsupported.join(", ")}`);
     const limits = validLimits(input.limits ?? {});
     if (!Object.keys(limits).length) throw new Error("execution budget requires at least one supported limit");

package/src/hub/hub-tools.ts

@@ -1,10 +1,13 @@
 import { SDLC_STAGES } from "./sdlc.ts";
 import { projectProfile, profileData, PROFILE_CLASS_NAMES, type ProfileName, type ProfileSelection } from "./profiles.ts";
 import { catalogSection, type CatalogRole } from "./roles.ts";
-import { SUPPORTED_PEERS, defaultPeerRoles } from "./peer-catalog.ts";
+import { CONDUCTOR_START_PEERS, defaultPeerRoles } from "../adapters/registry.ts";
 // The hub's task tools, defined once: the MCP server (Claude plugin, Kimi, Codex) and the local worker both read this.
 import { NOTE_KINDS } from "./envelope.ts";
 
+/** Shared communication rule for channel and tool-only sessions. */
+export const ACTIONABLE_MESSAGE_INSTRUCTION = "Do not use [FYI] for PR ready, done, submitted, ruling needed, blocker, or changed contract or path messages: each requires action from the recipient. Use [FYI] only for progress or information that needs no action. hub_task_done and hub_review already notify the assigned recipients; no duplicate hub_send chat is needed.";
+
 const str = { type: "string" } as const;
 const id = { type: "integer", description: "task id" } as const;
 const refs = {
@@ -60,10 +63,10 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_task_accept", "Take a task that was assigned to you, with your plan for it.", { id, plan: acceptPlan }, ["id"]),
   tool("hub_task_cancel", "Cancel unaccepted proposed/backlog work you proposed as its configured planner; accepted work is person-only. Keeps history and does not stop a native turn or delete files.", { id, reason: str, superseded_by: str, revision: { type: "integer", minimum: 0 } }, ["id", "reason"]),
   tool("hub_task_decline", "Pass on a task assigned to you; the hub offers it to the next peer.", { id, reason: str }, ["id"]),
-  tool("hub_task_done", "Mark your task finished. It goes to its reviewer with your summary and refs. 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_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. Two changes_requested in a row 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" } }, ["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" }, 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" } }, ["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"]),
@@ -80,7 +83,7 @@ export const CONDUCTOR_TOOLS: HubTool[] = [
   tool("hub_task_show", "Read a task's public view and history, its done summary and check result included. PII tasks remain stubs. Only the conductor and the task's current owner and reviewer may use this tool.", { id }, ["id"]),
   tool("hub_task_assign", "Name an owner (default role) or reviewer. Only the conductor may name a reviewer through this tool. A proposer may redirect an unaccepted proposed task's owner; a task that still waits reserves that owner. Pull-only peers receive work when named or when they claim it. With an explicit capabilities list, the conductor needs assign capability for either role, the proposer only to give ownership to another peer.", { id, peer: str, role: { type: "string", enum: ["owner", "reviewer"] } }, ["id", "peer"]),
   tool("hub_task_escalate", "Escalate a task through the normal task flow, as the conductor. Requires assign capability when explicitly listed.", { id }, ["id"]),
-  tool("hub_peer_start", "Start local, kimi, qwen, jcode, pi, claude or codex in the start mode a person set for it; you cannot choose the mode. A headless peer starts at once. A TUI peer (claude, and pi and codex by default) opens in a terminal with a fixed command; when the hub cannot open a terminal the call fails with the command for the person to run.", { peer: { type: "string", enum: ["local", "kimi", "pi", ...SUPPORTED_PEERS.filter(peer => !["local", "kimi", "pi"].includes(peer))] } }, ["peer"]),
+  tool("hub_peer_start", "Start local, kimi, qwen, jcode, pi, claude or codex in the start mode a person set for it; you cannot choose the mode. A headless peer starts at once. A TUI peer (claude, and pi and codex by default) opens in a terminal with a fixed command; when the hub cannot open a terminal the call fails with the command for the person to run.", { peer: { type: "string", enum: CONDUCTOR_START_PEERS } }, ["peer"]),
   tool("hub_peer_hold", "Hold a peer's deliveries as the conductor. This hold is separate from the person's hold and budget pauses.", { peer: str }, ["peer"]),
   tool("hub_peer_release", "Release only the conductor hold you placed. Never lifts a person's hold or a budget pause.", { peer: str }, ["peer"]),
 ];
@@ -105,16 +108,24 @@ export function roleContract(peer: string, roles: Record<string, string[]> = DEF
 }
 
 /** Profile schemas are data over the existing tools; dev retains the exact existing definitions. */
-export function profileTaskTools(profile: ProfileSelection = "dev", stages?: readonly string[]): HubTool[] {
+/** `criteria`: an enabled lifecycle, whose receipts take the #481 S8 checklist whatever its stage list. */
+export function profileTaskTools(profile: ProfileSelection = "dev", stages?: readonly string[], criteria = false): HubTool[] {
   const customStages = stages && (stages.length !== SDLC_STAGES.length || stages.some((s, i) => s !== SDLC_STAGES[i]));
   const customProfile = !(profile === "dev" || profileData(profile) === projectProfile("dev"));
-  if (!customStages && !customProfile) return TASK_TOOLS;
+  if (!customStages && !customProfile && !criteria) return TASK_TOOLS;
   const data = profileData(profile);
   return TASK_TOOLS.map(tool => {
     const properties = { ...tool.inputSchema.properties };
-    if (customStages && tool.name === "hub_sdlc_record") {
+    if ((customStages || criteria) && tool.name === "hub_sdlc_record") {
       const receipt = properties.receipt as { type: string; properties: Record<string, unknown>; additionalProperties: boolean };
-      properties.receipt = { ...receipt, properties: { ...receipt.properties, stage: { type: "string", enum: [...(stages ?? SDLC_STAGES)] } } };
+      let fields: Record<string, unknown> = { ...receipt.properties, ...(customStages ? { stage: { type: "string", enum: [...(stages ?? SDLC_STAGES)] } } : {}) };
+      // #481 S8: only an enabled lifecycle (whose daemon accepts it) advertises the criteria checklist; off and older daemons keep phase.
+      if (criteria) {
+        const { phase, ...current } = fields as { phase: { properties: Record<string, unknown> } } & Record<string, unknown>;
+        const { tasks: _retiredImport, ...checklist } = phase.properties;
+        fields = { ...current, criteria: { ...phase, properties: checklist, required: ["id", "criteria"] } };
+      }
+      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")])) };

package/src/hub/instance-budget.ts

@@ -0,0 +1,73 @@
+import type { Budget, BudgetHooks, Moved, PauseRecord } from "./budget.ts";
+
+export type BudgetAccountMembers = (account: string) => readonly string[];
+type Headroom = ReturnType<Budget["headroom"]>;
+
+/** Membership comes only from the host's startup-bound registry/declarations, never from model text. */
+function memberIds(account: string, members: BudgetAccountMembers): string[] {
+  const ids = [...new Set(members(account))];
+  return ids.length ? ids : [account]; // unknown external peers retain their singleton behavior
+}
+
+/** Per task/role the latest move is authoritative; retrying a failed fanout cannot grow duplicate history. */
+function mergeMoves(...groups: readonly Moved[][]): Moved[] {
+  return [...new Map(groups.flat().map(move => [JSON.stringify([move.id, move.role]), move])).values()];
+}
+
+/** Wrap the daemon's existing per-peer callbacks. Its canHandOff predicate must exclude account siblings. */
+export function instanceBudgetHooks(base: BudgetHooks, members: BudgetAccountMembers, account: (peer: string) => string): BudgetHooks {
+  const ids = (peer: string) => memberIds(account(peer), members);
+  // A failed handoff leaves the core pause unmarked. Preserve completed work until its retry or resume notice;
+  // one entry per board task/role bounds this state by the host's task board, rather than by retry count.
+  const partialMoves = new Map<string, Moved[]>();
+  const summaries = async (peer: string, request: (member: string) => Promise<string | undefined>, deduplicate = false): Promise<string | undefined> => {
+    const peers = ids(peer);
+    if (peers.length === 1) return request(peers[0]!);
+    const parts = await Promise.all(peers.map(async member => {
+      const text = await request(member).catch(() => undefined);
+      return text === undefined || text.length === 0 ? undefined : { member, text };
+    }));
+    const groups = new Map<string, { members: string[]; text: string }>();
+    for (const part of parts) if (part) {
+      const key = deduplicate ? part.text : part.member;
+      const group = groups.get(key);
+      if (group) group.members.push(part.member);
+      else groups.set(key, { members: [part.member], text: part.text });
+    }
+    return [...groups.values()].map(part => `[${part.members.join(", ")}]\n${part.text}`).join("\n\n") || undefined;
+  };
+  return {
+    ...base,
+    account,
+    pause(peer) { for (const member of ids(peer)) base.pause(member); },
+    resume(peer) { for (const member of ids(peer)) base.resume(member); },
+    requestCheckpoint: peer => summaries(peer, member => base.requestCheckpoint(member)),
+    platformContext: peer => summaries(peer, member => base.platformContext(member), true),
+    attached: peer => ids(peer).some(member => base.attached(member)),
+    canHandOff: peer => ids(peer).some(member => base.canHandOff(member)),
+    async handoff(peer, context, urgentOnly) {
+      const peers = ids(peer);
+      if (peers.length === 1) return base.handoff(peers[0]!, context, urgentOnly);
+      const key = account(peer);
+      let moved = partialMoves.get(key) ?? [];
+      for (const member of peers) {
+        const current = await base.handoff(member, context, urgentOnly);
+        moved = mergeMoves(moved, current);
+        partialMoves.set(key, moved);
+      }
+      partialMoves.delete(key);
+      return moved;
+    },
+    resumed(record) {
+      const key = account(record.peer), peers = ids(record.peer), partial = partialMoves.get(key);
+      const resumed: PauseRecord = partial ? { ...record, moved: mergeMoves(record.moved, partial) } : record;
+      for (const member of peers) base.resumed(member === resumed.peer ? resumed : { ...resumed, peer: member });
+      partialMoves.delete(key);
+    },
+  };
+}
+
+/** Routing sees each declared member's account window; the underlying quota store still keeps it once. */
+export function projectBudgetHeadroom(rows: Headroom, members: BudgetAccountMembers): Headroom {
+  return Object.fromEntries(Object.entries(rows).flatMap(([account, reading]) => memberIds(account, members).map(member => [member, reading])));
+}

package/src/hub/instance-config.ts

@@ -0,0 +1,47 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { defaultPeerRoles } from "../adapters/registry.ts";
+import { conductorPeer } from "./conductor.ts";
+import { configRefusal } from "./config-trust.ts";
+import { validateInstances, type InstancesConfig } from "./instances.ts";
+
+export const INSTANCE_CONFIG_FILES = ["config.json", "config.local.json"] as const;
+export interface InstanceConfigLayer { name: typeof INSTANCE_CONFIG_FILES[number]; raw: Record<string, unknown> }
+
+/** One source capture can feed declaration validation and the ordinary config loader. */
+export function readInstanceConfigLayers(cwd: string): InstanceConfigLayer[] {
+  return INSTANCE_CONFIG_FILES.flatMap(name => {
+    try { return [{ name, raw: JSON.parse(readFileSync(join(cwd, ".agenthub", name), "utf8")) as Record<string, unknown> }]; }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return []; throw error; }
+  });
+}
+
+/** Declaration authority is file provenance, never a suffix or a claim made by a native child. */
+export function readInstanceConfig(cwd: string, layers: readonly InstanceConfigLayer[] = readInstanceConfigLayers(cwd)): { instances?: InstancesConfig; ignored: string[] } {
+  const ignored: string[] = [];
+  let instances: InstancesConfig | undefined;
+  for (const { name, raw } of layers) {
+    const checked = validateInstances(raw.instances);
+    if (!Object.keys(checked).length) continue;
+    if (name !== "config.local.json") { ignored.push(`instances in .agenthub/${name} ignored: instances are machine-local config.local.json declarations`); continue; }
+    const refusal = configRefusal(cwd, name);
+    if (refusal) ignored.push(`instances in .agenthub/${name} ignored: ${refusal}`);
+    else instances = checked;
+  }
+  return { ...(instances ? { instances } : {}), ignored };
+}
+
+/** Capture ordinary role policy and trusted instance declarations together, without loading daemon configuration. */
+export function readInstanceRoleConfig(cwd: string, layers: readonly InstanceConfigLayer[] = readInstanceConfigLayers(cwd)): { instances?: InstancesConfig; roles: Record<string, string[]>; ignored: string[] } {
+  const declarationConfig = readInstanceConfig(cwd, layers);
+  const roles = defaultPeerRoles(false);
+  for (const name of INSTANCE_CONFIG_FILES) {
+    const raw = layers.find(layer => layer.name === name)?.raw;
+    if (raw?.roles !== undefined) {
+      conductorPeer(raw.roles); // Preserve the ordinary loader's ids, role-list and conductor validation exactly.
+      for (const [id, list] of Object.entries(raw.roles as Record<string, string[]>)) roles[id] = [...list];
+    }
+  }
+  conductorPeer(roles);
+  return { ...declarationConfig, roles };
+}

package/src/hub/instance-execution.ts

@@ -0,0 +1,50 @@
+import { lstatSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { definitionOf } from "../adapters/registry.ts";
+import { hubGitSync } from "./git.ts";
+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;
+}
+const commonDirectory = (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[]): string {
+  if (definitionOf(id)) return projectRoot;
+  const declaration = validateInstances(declarations)[id];
+  if (!declaration) return refuse("extra instance is not declared");
+  const implementer = roles.includes("implementer");
+  if (!declaration.worktree) {
+    if (implementer) return refuse("an extra implementer requires an explicit managed worktree");
+    return projectRoot;
+  }
+  let root: string, cwd: string;
+  try {
+    root = realPath(projectRoot);
+    cwd = realPath(resolve(root, declaration.worktree));
+    if (!lstatSync(root).isDirectory() || !lstatSync(cwd).isDirectory()) return refuse("workspace is not a directory");
+  } catch { return refuse("workspace paths are unavailable"); }
+  const expected = join(root, ".worktrees", id);
+  // Compare a real path with the exact canonical project child, so a symlink cannot move this boundary elsewhere.
+  if (cwd !== expected) return refuse("worktree must be the exact managed instance directory");
+  const inventory = git(root, ["worktree", "list", "--porcelain", "-z"]);
+  const records = inventory.split("\0\0").filter(Boolean).map(record => record.split("\0").filter(Boolean));
+  const matches = records.filter(record => {
+    const path = record.find(field => field.startsWith("worktree "))?.slice("worktree ".length);
+    if (!path) return false;
+    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");
+  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");
+  // ponytail: this read cannot bind the branch to a task or make path swaps atomic; task/start authority must recheck before effects.
+  return cwd;
+}

package/src/hub/instances.ts

@@ -0,0 +1,100 @@
+import { types } from "node:util";
+import { ADAPTERS, defaultPeerRoles, definitionOf, type AdapterDefinition, type StartForm } from "../adapters/registry.ts";
+import { isPermissionMode, type PermissionMode } from "./permission-mode.ts";
+
+export interface InstanceConfig {
+  kind: string;
+  roles?: string[];
+  start_mode?: StartForm;
+  permission_mode?: PermissionMode;
+  worktree?: string;
+}
+export type InstancesConfig = Readonly<Record<string, InstanceConfig>>;
+export interface InstanceCatalogEntry { id: string; kind: string; definition: AdapterDefinition; config?: InstanceConfig }
+const MAX_INSTANCES = 64;
+const FLOW_ROLES = new Set(["planner", "implementer", "verifier", "reviewer", "conductor"]);
+const PEER_ID = /^[a-z][a-z0-9-]{0,31}$/;
+const RESERVED = new Set(["user", "hub", "digest"]);
+const fail = (field: string, reason: string): never => { throw new Error(`${field}: ${reason}`); };
+
+/** Inspect only ordinary own data descriptors; accessors, proxies, symbols and custom prototypes are not config. */
+function fields(value: unknown, field: string): Record<string, PropertyDescriptor> {
+  if (!value || typeof value !== "object" || types.isProxy(value) || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value)) || Object.getOwnPropertySymbols(value).length) return fail(field, "must be a plain own-data object");
+  const descriptors: Record<string, PropertyDescriptor> = Object.assign(Object.create(null), Object.getOwnPropertyDescriptors(value));
+  if (Object.values(descriptors).some(entry => !Object.hasOwn(entry, "value") || !entry.enumerable)) return fail(field, "must contain enumerable data fields only");
+  return descriptors;
+}
+function roles(value: unknown, field: string): string[] {
+  if (!Array.isArray(value) || types.isProxy(value) || Object.getPrototypeOf(value) !== Array.prototype || Object.getOwnPropertySymbols(value).length) return fail(field, "must be a role array");
+  const descriptors: Record<string, PropertyDescriptor> = Object.assign(Object.create(null), Object.getOwnPropertyDescriptors(value));
+  const length = descriptors.length?.value;
+  if (!Number.isSafeInteger(length) || length > FLOW_ROLES.size || Object.keys(descriptors).length !== length + 1) return fail(field, "invalid role array");
+  const out: string[] = [];
+  for (let index = 0; index < length; index++) {
+    const descriptor = descriptors[String(index)];
+    if (!descriptor || !Object.hasOwn(descriptor, "value") || !descriptor.enumerable || typeof descriptor.value !== "string" || !FLOW_ROLES.has(descriptor.value) || out.includes(descriptor.value)) return fail(field, "roles must be known and unique");
+    out.push(descriptor.value);
+  }
+  return out;
+}
+
+/** Pure I2 declaration validation. Physical worktree and startup authority checks belong to the bound host. */
+export function validateInstances(raw: unknown): InstancesConfig {
+  const result: Record<string, InstanceConfig> = Object.create(null);
+  if (raw === undefined) return Object.freeze(result);
+  const declarations = fields(raw, "instances");
+  if (Object.keys(declarations).length > MAX_INSTANCES) return fail("instances", "at most 64 extra instances are supported");
+  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");
+    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>");
+    if (!definition.start.create || !definition.start.forms.includes("headless") || !["env", "acp-session"].includes(definition.identity.mcp)) return fail(`${path}.kind`, "unsupported in I2; a headless factory with env or ACP-session identity is required, not channel-only or project-file identity");
+    const value: InstanceConfig = { kind };
+    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");
+      value.start_mode = "headless";
+    }
+    if (entry.permission_mode) {
+      if (!isPermissionMode(entry.permission_mode.value)) return fail(`${path}.permission_mode`, "must be ask, ask-when-needed or never-ask");
+      value.permission_mode = entry.permission_mode.value;
+    }
+    if (entry.worktree) {
+      const worktree: unknown = entry.worktree.value;
+      if (typeof worktree !== "string" || !worktree.trim() || Buffer.byteLength(worktree) > 4096 || /\p{Cc}/u.test(worktree)) return fail(`${path}.worktree`, "must be a nonempty control-free path of at most 4096 UTF-8 bytes");
+      value.worktree = worktree;
+    }
+    result[id] = Object.freeze(value);
+  }
+  return Object.freeze(result);
+}
+
+/** Each call derives a fresh project-local projection, without registration or suffix discovery. */
+export function instanceCatalog(declarations?: InstancesConfig): readonly InstanceCatalogEntry[] {
+  const instances = validateInstances(declarations);
+  return Object.freeze([
+    ...ADAPTERS.map(definition => Object.freeze({ id: definition.kind, kind: definition.kind, definition })),
+    ...Object.entries(instances).map(([id, config]) => Object.freeze({ id, kind: config.kind, definition: definitionOf(config.kind)!, config })),
+  ]);
+}
+export function instancePeerIds(declarations?: InstancesConfig): string[] { return instanceCatalog(declarations).map(entry => entry.id); }
+export function instanceDefaultRoles(declarations?: InstancesConfig, includeOptional = true): Record<string, string[]> {
+  const result = defaultPeerRoles(includeOptional);
+  for (const [id, config] of Object.entries(validateInstances(declarations))) result[id] = [...(config.roles ?? definitionOf(config.kind)!.roles)];
+  return result;
+}
+
+/** One precedence rule for startup, native launch and recovery; ordinary roles may use the instance id or its kind. */
+export function effectiveInstanceRoles(id: string, declarations: InstancesConfig | undefined, policyRoles: Readonly<Record<string, readonly string[]>>): string[] {
+  const definition = definitionOf(id, declarations);
+  if (!definition) throw new Error(`${id}: no declared native instance`);
+  const declaration = declarations && Object.hasOwn(declarations, id) ? declarations[id] : undefined;
+  const ownRoles = (key: string): readonly string[] | undefined => Object.hasOwn(policyRoles, key) ? policyRoles[key] : undefined;
+  return [...(declaration?.roles ?? ownRoles(id) ?? ownRoles(definition.kind) ?? definition.roles)];
+}

package/src/hub/lifecycle-schema.ts

@@ -1,17 +1,21 @@
 import { ControlClient } from "./control-client.ts";
 import { SDLC_STAGES } from "./sdlc.ts";
 /** The daemon owns the active definition. Unavailable reads never invent a project-file stage set. */
-export async function activeLifecycleStages(stateDir: string, peer: string, projectRoot: string, active?: ControlClient): Promise<string[] | undefined> {
+/** The active stage ids and whether the lifecycle is enabled (`criteria`, #481 S8); an older daemon never says so. */
+export async function activeLifecycle(stateDir: string, peer: string, projectRoot: string, active?: ControlClient): Promise<{ stages: string[]; criteria: boolean } | undefined> {
   let client: ControlClient | undefined;
   try {
     client = active ?? await ControlClient.connect(stateDir, { role: "tools", peer, projectRoot }, 1000);
     const reply = await client.request({ t: "status" }, 1000);
     if (reply.t !== "status" || !reply.status || typeof reply.status !== "object" || Array.isArray(reply.status)) return undefined;
     // A live older daemon has the fixed seven-stage contract and no optional metadata field.
-    if (!Object.hasOwn(reply.status, "lifecycleStages")) return [...SDLC_STAGES];
+    if (!Object.hasOwn(reply.status, "lifecycleStages")) return { stages: [...SDLC_STAGES], criteria: false };
     const stages: unknown = reply.status.lifecycleStages;
     if (!Array.isArray(stages) || !stages.length || stages.length > 32 || stages.some(s => typeof s !== "string" || !/^[a-z][a-z0-9_-]{0,47}$/.test(s)) || new Set(stages).size !== stages.length) return undefined;
-    return [...stages] as string[];
+    return { stages: [...stages] as string[], criteria: reply.status.lifecycleCriteria === true };
   } catch { return undefined; }
   finally { if (client !== active) client?.close(); }
 }
+export async function activeLifecycleStages(stateDir: string, peer: string, projectRoot: string, active?: ControlClient): Promise<string[] | undefined> {
+  return (await activeLifecycle(stateDir, peer, projectRoot, active))?.stages;
+}

package/src/hub/peer-catalog.ts

@@ -1,4 +1,5 @@
-import { definitionOf } from "../adapters/registry.ts";
+import { definitionOf, SUPPORTED_PEERS } from "../adapters/registry.ts";
+export { SUPPORTED_PEERS } from "../adapters/registry.ts";
 
 // ponytail: older staged coordinators read these literal declarations to probe target support.
 // A2 replaces that source probe with a published capability before deleting the compatibility exports.
@@ -6,7 +7,6 @@ import { definitionOf } from "../adapters/registry.ts";
 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 SUPPORTED_PEERS = [...KNOWN_PEERS, ...OPTIONAL_PEERS] as const;
 export type KnownPeer = typeof SUPPORTED_PEERS[number];
 
 export const isKnownPeer = (value: unknown): value is KnownPeer =>
@@ -15,14 +15,5 @@ export const isKnownPeer = (value: unknown): value is KnownPeer =>
 export const isSupportedPeer = (value: unknown): value is KnownPeer =>
   typeof value === "string" && !!definitionOf(value);
 
-// Policy metadata, not a membership list. Preserve DEFAULT_ROLES' existing key order.
-const ROLE_ORDER: readonly KnownPeer[] = ["claude", "codex", "kimi", "local", "pi", "qwen", "jcode"];
-
-/** Each caller owns its role arrays; changing a project's defaults cannot change another's. */
-export function defaultPeerRoles(includeOptional = false): Record<string, string[]> {
-  return Object.fromEntries(ROLE_ORDER.filter(peer => includeOptional || !definitionOf(peer)!.optional)
-    .map(peer => [peer, [...definitionOf(peer)!.roles]]));
-}
-
-/** #455: who may hold the planner role, in the order automatic assignment tries them; the hub-sandboxed pi and local never plan. */
-export const PLANNER_PEERS = ["claude", "codex", "kimi", "qwen", "jcode"] as const;
+// 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/permission-mode.ts

@@ -1,5 +1,4 @@
-import { isSupportedPeer } from "./peer-catalog.ts";
-import { definitionOf } from "../adapters/registry.ts";
+import { definitionOf, type KindMap } from "../adapters/registry.ts";
 import { lstatSync } from "node:fs";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 
@@ -9,39 +8,37 @@ export type PermissionMode = typeof PERMISSION_MODES[number];
 export { KIMI_MODE_IDS } from "../adapters/definitions/kimi-native.ts";
 export { QWEN_MODE_IDS } from "../adapters/definitions/qwen-native.ts";
 export const isPermissionMode = (value: unknown): value is PermissionMode => typeof value === "string" && (PERMISSION_MODES as readonly string[]).includes(value);
-export function permissionDefaults(value: unknown): Record<string, PermissionMode> {
+export function permissionDefaults(value: unknown, instances?: KindMap): Record<string, PermissionMode> {
   if (value === undefined) return {};
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("permission_modes must be an object with ask, ask-when-needed or never-ask values");
   const result: Record<string, PermissionMode> = {};
   for (const [peer, mode] of Object.entries(value)) {
-    if (!isSupportedPeer(peer)) throw new Error(`permission_modes.${peer}: unsupported peer`);
-    if (peer === "jcode") throw new Error("Jcode native policy is unmanaged; no hub permission_modes.jcode mapping exists");
+    const definition = typeof peer === "string" ? definitionOf(peer, instances) : undefined;
+    if (!definition) throw new Error(`permission_modes.${peer}: unsupported peer`);
+    if (definition.permission.unmanaged) throw new Error(`${definition.displayName} native policy is unmanaged; no hub permission_modes.${peer} mapping exists`);
     if (!isPermissionMode(mode)) throw new Error(`permission_modes.${peer} must be ask, ask-when-needed or never-ask`);
     result[peer] = mode;
   }
   return result;
 }
 /** Approval frequency does not create a common sandbox across native peers. */
-export function permissionBoundary(peer: string): string {
-  if (peer === "jcode") return "jcode: native policy unmanaged; NO hub sandbox; approvals belong to its native tools";
-  if (peer === "pi" || peer === "local") return `${peer}: inside hub sandbox, path guard and denylist`;
-  if (peer === "claude" || peer === "codex") return `${peer}: native vendor bounds; no hub sandbox`;
+export function permissionBoundary(peer: string, instances?: KindMap): string {
+  const definition = definitionOf(peer, instances);
+  if (definition?.permission.unmanaged) return `${peer}: native policy unmanaged; NO hub sandbox; approvals belong to its native tools`;
+  if (definition?.trust.hubSandboxed) return `${peer}: inside hub sandbox, path guard and denylist`;
+  if (definition?.transport === "claude-channel" || definition?.transport === "codex-appserver") return `${peer}: native vendor bounds; no hub sandbox`;
   return `${peer}: runs its own tools; NO hub sandbox`;
 }
 /** What a mode lets a peer do without asking, in one line a person reads before choosing it (#269). */
-export function permissionGrant(peer: string, mode: PermissionMode): string {
-  const grant = definitionOf(peer)?.permission.grants?.[mode];
+export function permissionGrant(peer: string, mode: PermissionMode, instances?: KindMap): string {
+  const grant = definitionOf(peer, instances)?.permission.grants?.[mode];
   if (grant !== undefined) return grant;
-  if (peer === "jcode") return "no verified hub mode mapping; native policy only";
-  if (mode === "ask") return peer === "codex" ? "the session's own approval policy applies again" : peer === "kimi" ? "Kimi asks as it does on its own" : peer === "claude" ? "Claude's own permission rules decide" : "every write, edit and shell command asks";
-  if (peer === "kimi") return mode === "never-ask" ? "Kimi's auto mode: nothing asks" : "Kimi's yolo mode: it asks only where it judges it must";
-  if (peer === "codex") return mode === "never-ask" ? "approval policy never on every turn: nothing asks" : "approval policy on-request on every turn";
-  if (peer === "claude") return mode === "never-ask" ? "every tool runs without asking" : "file tools on project files run without asking, outside .agenthub, .git and agent configuration; other tools keep Claude's own rules";
+  if (mode === "ask") return "every write, edit and shell command asks";
   return mode === "never-ask" ? "every tool runs without asking, inside the hub sandbox and path guard" : "write and edit inside the project run without asking; shell and git writes still ask";
 }
 export const PI_EDIT_TOOLS = new Set(["edit", "write"]);
 /** Native agent policy files are never included in scoped automatic file grants. */
-export const AGENT_CONFIG_SEGMENTS: ReadonlySet<string> = new Set([".claude", ".codex", ".qwen", ".kimi", ".kimi-code", ".jcode", ".pi", ".mcp.json", ".agents", ".claude.json"]);
+export const AGENT_CONFIG_SEGMENTS: ReadonlySet<string> = new Set([".claude", ".codex", ".qwen", ".kimi", ".kimi-code", ".jcode", ".pi", ".mcp.json", ".agents", ".agent", "_agents", "_agent", ".gemini", ".grok", ".claude.json"]);
 export const INSTRUCTION_FILES: ReadonlySet<string> = new Set(["agents.md", "claude.md", "qwen.md"]);
 export const isInstructionPath = (path: string): boolean => path.split(/[\\/]/).some(segment => INSTRUCTION_FILES.has(foldSegment(segment)));
 export function instructionProtection(value: unknown): boolean {

package/src/hub/recovery-continuity.ts

@@ -1,3 +1,4 @@
+import { ADAPTERS } from "../adapters/registry.ts";
 import { Database } from "bun:sqlite";
 import { createHash, randomUUID } from "node:crypto";
 import { chmodSync, closeSync, constants, fstatSync, lstatSync, openSync, readSync, renameSync, unlinkSync } from "node:fs";
@@ -37,12 +38,12 @@ function canonicalRoot(value: unknown): string {
   return root;
 }
 function checked(value: unknown): RecoveryContinuityBookmark {
-  if (!record(value) || !keys(value, ["schema", "operationId", "projectId", "projectRoot", "at", "pi"]) || value.schema !== 1 || typeof value.operationId !== "string" || !operationIdPattern.test(value.operationId) || !id(value.projectId) || !absolute(value.projectRoot) || !Number.isSafeInteger(value.at) || (value.at as number) < 0) return unavailable();
-  const pi = value.pi;
-  if (!record(pi) || !keys(pi, ["sessionId", "sessionFile", "backend", "model"]) || !id(pi.sessionId) || pi.sessionFile !== undefined && !absolute(pi.sessionFile) || pi.backend !== undefined && !["auto", "dgx", "mlx"].includes(String(pi.backend)) || pi.model !== undefined && !text(pi.model, 4096)) return unavailable();
+  const codecs = ADAPTERS.flatMap(adapter => adapter.session.continuity ? [adapter.session.continuity] : []);
+  if (!record(value) || !keys(value, ["schema", "operationId", "projectId", "projectRoot", "at", ...codecs.map(codec => codec.key)]) || value.schema !== 1 || typeof value.operationId !== "string" || !operationIdPattern.test(value.operationId) || !id(value.projectId) || !absolute(value.projectRoot) || !Number.isSafeInteger(value.at) || (value.at as number) < 0) return unavailable();
+  const native: Record<string, unknown> = {};
+  for (const codec of codecs) { const parsed = codec.parse(value[codec.key]); if (parsed === undefined) return unavailable(); native[codec.key] = parsed; }
   const projectRoot = canonicalRoot(value.projectRoot);
-  return { schema: 1, operationId: value.operationId, projectId: value.projectId, projectRoot, at: value.at as number,
-    pi: { sessionId: pi.sessionId, ...(pi.sessionFile === undefined ? {} : { sessionFile: pi.sessionFile as string }), ...(pi.backend === undefined ? {} : { backend: pi.backend as "auto" | "dgx" | "mlx" }), ...(pi.model === undefined ? {} : { model: pi.model as string }) } };
+  return { schema: 1, operationId: value.operationId, projectId: value.projectId, projectRoot, at: value.at as number, ...native } as RecoveryContinuityBookmark;
 }
 function stateDirectory(stateDir: string): void {
   if (!absolute(stateDir)) return unavailable();

package/src/hub/report.ts

@@ -1,3 +1,4 @@
+import { definitionOf } from "../adapters/registry.ts";
 import type { StampedEvent } from "./events.ts";
 
 export interface Report {
@@ -103,7 +104,7 @@ export function summarize(events: StampedEvent[]): Report {
   const r: Report = { peers: {}, conduct: {}, supervision: {}, routes: {}, usage: { peers: {}, totals: { inputTokens: 0, inputRecords: 0, outputTokens: 0, outputRecords: 0, cacheReadTokens: 0, cacheReadRecords: 0, cacheWriteTokens: 0, cacheWriteRecords: 0, totalTokens: 0, totalRecords: 0 }, unknownPeers: [], completeCoverage: true }, messages: { total: 0, dropped: {}, overflow: 0, undeliverable: 0, perTask: 0 }, overlaps: { warnings: 0, pairs: 0 }, conflicts: 0, tasks: {}, quota: { readings: 0, hard: 0 } };
   const supervisor = (id: string) => (r.supervision[id] ??= { turns: null, tokens: null, measuredTokens: null, knownTokenTurns: 0, unknownTokenTurns: 0 });
   const peer = (id: string) => (r.peers[id] ??= { turns: 0, busyMinutes: 0, tokens: 0 });
-  const claudeNativeStops = events.some(event => event.type === "native_turn_end" && event.peer === "claude" && !!event.id);
+  const nativeStops = events.some(event => event.type === "native_turn_end" && definitionOf(event.peer)?.turnEnd === "native-hook" && !!event.id);
   const seenNativeStops = new Set<string>();
   const usagePeer = (id: string) => (r.usage.peers[id] ??= emptyUsage());
   const pairs = new Set<string>();
@@ -147,11 +148,11 @@ export function summarize(events: StampedEvent[]): Report {
         r.messages.dropped.stale = (r.messages.dropped.stale ?? 0) + 1;
         break;
       case "turn_end":
-        if (e.peer !== "claude" || !claudeNativeStops) peer(e.peer).turns = (peer(e.peer).turns ?? 0) + 1;
+        if (definitionOf(e.peer)?.turnEnd !== "native-hook" || !nativeStops) peer(e.peer).turns = (peer(e.peer).turns ?? 0) + 1;
         peer(e.peer).busyMinutes += e.ms / 60_000;
         break;
       case "native_turn_end":
-        if (e.peer === "claude" && e.id) {
+        if (definitionOf(e.peer)?.turnEnd === "native-hook" && e.id) {
           if (seenNativeStops.has(e.id)) break;
           seenNativeStops.add(e.id);
           peer(e.peer).turns = (peer(e.peer).turns ?? 0) + 1;
@@ -211,10 +212,10 @@ export function summarize(events: StampedEvent[]): Report {
   // Pricing is intentionally absent: a token count is neither an estimated price nor provider-reported spend.
   r.messages.perTask = taskMessages.size ? Number(([...taskMessages.values()].reduce((a, b) => a + b, 0) / taskMessages.size).toFixed(1)) : 0;
   for (const p of Object.values(r.peers)) p.busyMinutes = Number(p.busyMinutes.toFixed(1));
-  if (r.peers.claude) {
-    const logical = events.some(event => event.type === "turn_end" && event.peer === "claude");
-    r.peers.claude.turnSource = claudeNativeStops ? "native-stop" : logical ? "logical-state" : "unknown";
-    if (!claudeNativeStops && !logical) r.peers.claude.turns = null;
+  for (const [id, summary] of Object.entries(r.peers)) if (definitionOf(id)?.turnEnd === "native-hook") {
+    const logical = events.some(event => event.type === "turn_end" && event.peer === id);
+    summary.turnSource = nativeStops ? "native-stop" : logical ? "logical-state" : "unknown";
+    if (!nativeStops && !logical) summary.turns = null;
   }
   return r;
 }
@@ -223,7 +224,7 @@ export function formatReport(r: Report): string[] {
   const lines = [`period: ${r.from ?? "-"} .. ${r.to ?? "-"}`];
   for (const [id, p] of Object.entries(r.peers).sort(([a], [b]) => a.localeCompare(b))) {
     const turns = p.turns === null ? "turns unknown" : `${p.turns} turn${p.turns === 1 ? "" : "s"}${p.turnSource === "native-stop" ? " (native Stop)" : p.turnSource === "logical-state" ? " (logical state, native completion unobserved)" : ""}`;
-    lines.push(`peer ${id}: ${turns}, ${p.busyMinutes} busy minutes, ${p.tokens ? `${p.tokens} tokens` : id === "pi" ? "tokens not reported" : "- tokens"}`);
+    lines.push(`peer ${id}: ${turns}, ${p.busyMinutes} busy minutes, ${p.tokens ? `${p.tokens} tokens` : definitionOf(id)?.reporting?.tokensNotReported ? "tokens not reported" : "- tokens"}`);
   }
   if (Object.keys(r.usage.peers).length) lines.push(...formatUsage(r.usage));
   for (const [id, s] of Object.entries(r.supervision).sort(([a], [b]) => a.localeCompare(b))) {

package/src/hub/roster.ts

@@ -1,15 +1,14 @@
-import { isSupportedPeer, type KnownPeer } from "./peer-catalog.ts";
+import { definitionOf, type KindMap } from "../adapters/registry.ts";
+import { defaultRosterEnabled } from "../adapters/registry.ts";
 
-export type PeerRoster = Partial<Record<KnownPeer, boolean>>;
-// Default participation policy, not another catalog. New catalog members default off.
-const DEFAULT_ON: Partial<Record<KnownPeer, boolean>> = { claude: true, codex: true, kimi: true, local: true };
+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 (!isSupportedPeer(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;
   }
@@ -17,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 (!isSupportedPeer(peer)) return true;
-  return roster[peer] ?? (peer === "pi" ? piEnabled : DEFAULT_ON[peer] ?? false);
+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);
 }