@staix/agent-hub 0.12.34 → 0.12.35

package/src/hub/execution-budget.ts

@@ -1,4 +1,4 @@
-import { definitionOf } from "../adapters/registry.ts";
+import { definitionOf, type KindMap } from "../adapters/registry.ts";
 import { Database } from "bun:sqlite";
 import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 
@@ -42,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");
@@ -57,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) => !definitionOf(peer)?.budget?.instrumented);
+    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

@@ -5,6 +5,9 @@ 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. 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_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"]),
@@ -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/permission-mode.ts

@@ -1,4 +1,4 @@
-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";
 
@@ -8,12 +8,12 @@ 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)) {
-    const definition = typeof peer === "string" ? definitionOf(peer) : undefined;
+    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`);
@@ -22,16 +22,16 @@ export function permissionDefaults(value: unknown): Record<string, PermissionMod
   return result;
 }
 /** Approval frequency does not create a common sandbox across native peers. */
-export function permissionBoundary(peer: string): string {
-  const definition = definitionOf(peer);
+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 (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";

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);
 }