@staix/agent-hub 0.12.32 → 0.12.34

package/src/hub/deferred-hub.ts

@@ -0,0 +1,60 @@
+import { HUB, MAX_HOP, type Envelope } from "./envelope.ts";
+
+/** ponytail: cap recovery at 2048 unpublished hub originals; replace with a paged durable outbox if measured recovery workloads exceed it. */
+export const MAX_DEFERRED_HUB = 2048;
+
+/** Refuses admission without dropping already accepted deferred work. */
+export class RecoveryDeferredHubError extends Error {
+  readonly code = "recovery_deferred_hub";
+  constructor(message = "recovery deferred hub notice limit reached; release or abort recovery before publishing more notices") {
+    super(message);
+    this.name = "RecoveryDeferredHubError";
+  }
+}
+
+/** Journal-less restore uses the same bounded core envelope shape as durable deferred work. */
+export function validateDeferredEnvelope(value: unknown, name: string): Envelope {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new RecoveryDeferredHubError(`${name} must be an envelope`);
+  const env = value as Record<string, unknown>;
+  const text = (value: unknown, max: number) => typeof value === "string" && value.length > 0 && value.length <= max;
+  if (!text(env.id, 256) || !text(env.trace, 256) || env.from !== HUB ||
+      typeof env.body !== "string" || env.body.length > 1_000_000 ||
+      !Number.isSafeInteger(env.hop) || (env.hop as number) < 0 || (env.hop as number) > MAX_HOP ||
+      !Number.isSafeInteger(env.ts) || (env.ts as number) < 0 ||
+      !["chat", "task", "review", "status", "budget", "presence"].includes(env.kind as string) ||
+      !["important", "status", "fyi"].includes(env.priority as string) ||
+      (!Array.isArray(env.to) || env.to.length > 256 || !env.to.every(peer => text(peer, 256))) ||
+      (env.private !== undefined && typeof env.private !== "boolean"))
+    throw new RecoveryDeferredHubError(`${name} is invalid`);
+  if (env.refs !== undefined) {
+    if (!env.refs || typeof env.refs !== "object" || Array.isArray(env.refs)) throw new RecoveryDeferredHubError(`${name}.refs is invalid`);
+    const refs = env.refs as Record<string, unknown>;
+    for (const key of ["repo", "branch", "commit", "task"])
+      if (refs[key] !== undefined && !text(refs[key], 4096)) throw new RecoveryDeferredHubError(`${name}.refs.${key} is invalid`);
+    if (refs.paths !== undefined && (!Array.isArray(refs.paths) || refs.paths.length > 256 || !refs.paths.every(path => text(path, 4096))))
+      throw new RecoveryDeferredHubError(`${name}.refs.paths is invalid`);
+  }
+  return value as Envelope;
+}
+
+/** Callers keep their existing envelope validation; this leaf checks deferred-only invariants. */
+export function validateDeferredHub(
+  value: unknown,
+  envelope: (value: unknown, name: string) => Envelope = validateDeferredEnvelope,
+  occupied: ReadonlySet<string> = new Set(),
+  name = "bus.deferredHub",
+): Envelope[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > MAX_DEFERRED_HUB)
+    throw new RecoveryDeferredHubError(`${name} must be an array of at most ${MAX_DEFERRED_HUB} hub envelopes`);
+  const ids = new Set<string>();
+  return value.map((item, index) => {
+    validateDeferredEnvelope(item, `${name}[${index}]`);
+    const env = envelope(item, `${name}[${index}]`);
+    if (env.from !== HUB) throw new RecoveryDeferredHubError(`${name}[${index}] is not hub-originated`);
+    if (ids.has(env.id) || occupied.has(env.id)) throw new RecoveryDeferredHubError(`${name}[${index}] repeats an accepted envelope id`);
+    ids.add(env.id);
+    return env;
+  });
+}

package/src/hub/delivery-journal.ts

@@ -6,6 +6,7 @@ import { HUB, USER, type Envelope, type Kind } from "./envelope.ts";
 import { heldDeliveryHints } from "./delivery-hints.ts";
 import { processLiveness } from "../pi/process-signature.ts";
 import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
+import { validateDeferredHub } from "./deferred-hub.ts";
 
 export type JournalDeliveryState =
   | "queued"
@@ -167,6 +168,11 @@ function validateBus(value: unknown, name = "bus"): BusSnapshot {
     list(b.manualPaused, `${name}.manualPaused`, 4096).forEach((id) =>
       text(id, `${name}.manualPaused[]`, 256),
     );
+  const occupied = new Set<string>([
+    ...(b.seen as Envelope[]).map(env => env.id),
+    ...Object.values(queues).flatMap(items => (items as Envelope[]).map(env => env.id)),
+  ]);
+  validateDeferredHub(b.deferredHub, validateEnvelope, occupied, `${name}.deferredHub`);
   if (b.journal !== undefined) fail("nested journal snapshot is invalid");
   return b as unknown as BusSnapshot;
 }

package/src/hub/execution-budget.ts

@@ -1,3 +1,4 @@
+import { definitionOf } from "../adapters/registry.ts";
 import { Database } from "bun:sqlite";
 import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 
@@ -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)?.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,7 +1,7 @@
 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";
 
@@ -63,7 +63,7 @@ export const TASK_TOOLS: HubTool[] = [
   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_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. 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 +80,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"]),
 ];

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,4 +1,3 @@
-import { isSupportedPeer } from "./peer-catalog.ts";
 import { definitionOf } from "../adapters/registry.ts";
 import { lstatSync } from "node:fs";
 import { isAbsolute, relative, resolve, sep } from "node:path";
@@ -14,8 +13,9 @@ export function permissionDefaults(value: unknown): Record<string, PermissionMod
   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) : 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;
   }
@@ -23,25 +23,22 @@ export function permissionDefaults(value: unknown): Record<string, PermissionMod
 }
 /** 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`;
+  const definition = definitionOf(peer);
+  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];
   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/restart.ts

@@ -2,10 +2,11 @@ import { chmodSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSy
 import { createHash } from "node:crypto";
 import { join } from "node:path";
 import type { BusSnapshot } from "./bus.ts";
-import type { PeerId, PeerState } from "./envelope.ts";
+import type { Envelope, PeerId, PeerState } from "./envelope.ts";
 import { MAX_HOP } from "./envelope.ts";
 import { validateJournalSnapshot } from "./delivery-journal.ts";
 import { atomicPrivateJSON } from "./recovery-store.ts";
+import { RecoveryDeferredHubError, validateDeferredHub } from "./deferred-hub.ts";
 
 export const RESTART_SCHEMA_VERSION = 1;
 
@@ -75,6 +76,16 @@ export function readRestartSnapshot(stateDir: string, expected: RestartReadExpec
   const bus = s.bus as Partial<BusSnapshot>;
   if (bus.schemaVersion !== 1 || !bus.queues || typeof bus.queues !== "object" || !bus.prefaces || typeof bus.prefaces !== "object" || !Array.isArray(bus.seen) || !bus.attempts || typeof bus.attempts !== "object" || !Array.isArray(bus.withdrawn)) return undefined;
   if (!Object.keys(bus.queues).every(peerId) || !Object.keys(bus.prefaces).every(peerId) || !Object.values(bus.queues).every((queue) => Array.isArray(queue) && queue.every((e) => isEnvelope(e))) || !Object.values(bus.prefaces).every((e) => isEnvelope(e)) || !bus.seen.every((e) => isEnvelope(e, true)) || !bus.withdrawn.every((id) => typeof id === "string" && id.length > 0) || !Object.values(bus.attempts).every((n) => Number.isSafeInteger(n) && n > 0)) return undefined;
+  try {
+    const occupied = new Set<string>([
+      ...bus.seen.map(env => env.id),
+      ...Object.values(bus.queues).flatMap(queue => queue.map(env => env.id)),
+    ]);
+    validateDeferredHub(bus.deferredHub, (value, name) => {
+      if (!isEnvelope(value)) throw new Error(`${name} is invalid`);
+      return value as Envelope;
+    }, occupied);
+  } catch (error) { if (error instanceof RecoveryDeferredHubError) throw error; return undefined; }
   if (!Array.isArray(s.manualPaused) || !s.manualPaused.every((id) => typeof id === "string") || !Array.isArray(s.peers) || !s.peers.every((peer) => peer && typeof peer === "object" && typeof peer.id === "string" && ["idle", "busy", "paused", "offline"].includes(peer.state as string) && Array.isArray(peer.queueIds) && peer.queueIds.every((id) => typeof id === "string"))) return undefined;
   if (s.integrity !== undefined && (!s.integrity || typeof s.integrity !== "object" || typeof s.integrity.boardDigest !== "string" || typeof s.integrity.budgetDigest !== "string" || !Array.isArray(s.integrity.manualPaused) || !s.integrity.manualPaused.every((id) => typeof id === "string") || !s.integrity.queues || typeof s.integrity.queues !== "object" || !Object.values(s.integrity.queues).every((ids) => Array.isArray(ids) && ids.every((id) => typeof id === "string")))) return undefined;
   if (bus.journal !== undefined) { try { validateJournalSnapshot(bus.journal); } catch { return undefined; } }

package/src/hub/roster.ts

@@ -1,15 +1,14 @@
-import { isSupportedPeer, type KnownPeer } from "./peer-catalog.ts";
+import { definitionOf } 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 {
   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)) throw new Error("roster contains an unsupported peer");
     if (typeof on !== "boolean") throw new Error(`roster.${peer} must be a boolean`);
     roster[peer] = on;
   }
@@ -18,6 +17,6 @@ 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);
+  if (!definitionOf(peer)) return true;
+  return roster[peer] ?? defaultRosterEnabled(peer, piEnabled);
 }

package/src/hub/routing.ts

@@ -1,3 +1,4 @@
+import { ADAPTERS, definitionOf } 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";
@@ -17,7 +18,7 @@ export interface ClassPolicy {
   /** Switchyard route the local worker asks for on a task of this class */
   route?: string;
   fixed_model?: string;
-  /** on two consecutive changes_requested */
+  /** on `tasks.escalate_after` consecutive changes_requested (default 3) */
   escalate_to?: PeerId[];
   /** false: `local` is never owner or reviewer for this class */
   local_allowed?: boolean;
@@ -108,6 +109,16 @@ const TEMPLATE = join(import.meta.dir, "..", "..", "templates", "routing.toml");
 export const LOCAL: PeerId = "local";
 export const PI: PeerId = "pi";
 
+/** The quota/roster relay keeps its native preference order, then the class's original tail. */
+export function relayCandidates(classPeers: readonly PeerId[], pii: boolean): PeerId[] {
+  const preferred = ADAPTERS.filter(adapter => adapter.routing?.handoffPriority !== undefined)
+    .sort((a, b) => a.routing!.handoffPriority! - b.routing!.handoffPriority!);
+  return [
+    ...preferred.filter(adapter => !pii || adapter.trust.onPrem).map(adapter => adapter.kind),
+    ...classPeers.filter(peer => definitionOf(peer)?.routing?.handoffPriority === undefined),
+  ].filter((peer): peer is PeerId => !!peer);
+}
+
 /**
  * `.agenthub/routing.toml`, or the shipped default when the project has none, with `.agenthub/routing.local.toml`
  * merged over it key by key (#269). Throws on a file that does not parse or lacks a fixed model.
@@ -323,15 +334,15 @@ export function assign(
     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 && peer !== LOCAL) return deny("pii", "pii: on-prem peers only");
-    if (peer === LOCAL && policy?.local_allowed === false) return deny("policy", "local_allowed = false for this class");
-    if (peer === PI && policy?.local_allowed === false) return deny("policy", "local_allowed = false also excludes pi for this class");
-    if (peer === PI && task.signals.includes("long_context")) {
+    if (pii && definitionOf(peer)?.trust.onPrem !== true) return deny("pii", "pii: on-prem peers only");
+    const nativeRouting = definitionOf(peer)?.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";
       const limit = backend === "mlx" ? routing.pi.mlx_max_context_tokens : routing.pi.dgx_max_context_tokens;
-      if (routing.signals.long_context_tokens > limit) return deny("policy", `pi ${backend} capability limit ${limit} tokens`);
+      if (routing.signals.long_context_tokens > limit) return deny("policy", `${nativeRouting.backendLabel} ${backend} capability limit ${limit} tokens`);
     }
-    if (peer === LOCAL && role === "owner" && task.signals.includes("long_context") && routing.constraints.long_context === "skip_local") return deny("policy", "long_context: skip local");
+    if (nativeRouting?.longContext === "skip-owner" && role === "owner" && task.signals.includes("long_context") && routing.constraints.long_context === "skip_local") return deny("policy", "long_context: skip local");
     return undefined;
   };
   /** Quota that resets soonest gets used first: headroom per hour left in the window, at least 15 min (a task assigned that close to a reset mostly runs after it). */
@@ -381,7 +392,7 @@ export function assign(
     }
     const ranked = 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) => (p === LOCAL || p === PI) && !(role === "owner" && peerEntry(opts.demoted, p)));
+    const localTier = ranked.filter((p) => definitionOf(p)?.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];
   };
@@ -413,8 +424,8 @@ 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 === LOCAL) trace.push(`route: ${route ?? "(none)"}, fixed_model ${fixedModel}`);
-  if (owner === PI) trace.push(`pi 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}` : ""}`);
+  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 };
 }
 

package/src/hub/settings.ts

@@ -1,4 +1,4 @@
-import { PLANNER_PEERS, SUPPORTED_PEERS } from "./peer-catalog.ts";
+import { definitionOf, ADAPTERS, PLANNER_PEERS, SUPPORTED_PEERS, START_MODE_PEERS } from "../adapters/registry.ts";
 import { createHash } from "node:crypto";
 import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -6,7 +6,7 @@ import { basename, dirname, join } from "node:path";
 import { CLASSES, type TaskClass } from "./board.ts";
 import { configTracked, configRepositoryPresent } from "./config-trust.ts";
 import { PERMISSION_MODES, permissionBoundary } from "./permission-mode.ts";
-import { START_MODE_PEERS, START_MODES } from "./start-mode.ts";
+import { START_MODES } from "./start-mode.ts";
 import { OVERLAY_FILE, overlayToml, parseOverlay, parseRouting, routingText, type Routing, type RoutingOverlay } from "./routing.ts";
 
 /**
@@ -49,14 +49,15 @@ export const SETTINGS: readonly SettingDef[] = [
   ...["enabled", "auto_reassign"].map((key): SettingDef => ({ key: `task_sweep.${key}`, group: "Switches", label: `Task sweep: ${key}`, type: "boolean", store: "config", applies: "live", risk: "raises", floor: false, path: ["task_sweep", key] })),
   ...["interval_s", "unaccepted_min", "idle_min", "review_min", "ready_min", "ladder_min"].map((key): SettingDef => ({ key: `task_sweep.${key}`, group: "Switches", label: `Task sweep: ${key}`, type: "number", min: 1, max: 2_147_483_647 / (key === "interval_s" ? 1000 : 60_000), store: "config", applies: "live", risk: "raises", path: ["task_sweep", key] })),
   ...SETTING_PEERS.map((peer): SettingDef => ({ key: `tasks.wip_limits.${peer}`, group: "Routing", label: `${peer}: planner WIP limit`, type: "integer", min: 0, max: 32, store: "config", applies: "live", risk: "raises", floor: 0, path: ["tasks", "wip_limits", peer] })),
+  { key: "tasks.escalate_after", group: "Routing", label: "Escalate after N consecutive changes_requested", type: "integer", min: 1, max: 10, store: "config", applies: "live", risk: "raises", path: ["tasks", "escalate_after"] },
   { key: "planner", group: "Roles", label: "Planner (the one peer that plans)", type: "enum", values: PLANNER_PEERS, store: "config", applies: "live", risk: "raises", path: ["planner"] },
   ...SETTING_PEERS.map((peer): SettingDef => ({ key: `catalog_roles.${peer}`, group: "Roles", label: `${peer}: catalog guidance`, type: "roles", store: "config", applies: "next use", risk: "safe", path: ["catalog_roles", peer] })),
   { key: "scoped_grants.protect_instructions", group: "Permissions", label: "Ask before writing instruction files", type: "boolean", store: "config", applies: "live", risk: "raises", floor: true, path: ["protect_instruction_files"] },
   ...SETTING_PEERS.map((peer): SettingDef => ({ key: `roster.${peer}`, group: "Roster", label: `${peer}: participates`, type: "boolean", store: "config", applies: "live", risk: "raises", floor: false, path: ["roster", peer] })),
-  ...SETTING_PEERS.filter(peer => peer !== "jcode").map((peer): SettingDef => ({ key: `permission.${peer}`, group: "Permissions", label: `${peer}: mode now`, type: "enum", values: PERMISSION_MODES, store: "runtime", applies: "live", risk: "raises", floor: "ask", path: [peer] })),
-  ...SETTING_PEERS.filter(peer => peer !== "jcode").map((peer): SettingDef => ({ key: `permission_modes.${peer}`, group: "Permissions", label: `${peer}: mode at next peer start`, type: "enum", values: PERMISSION_MODES, store: "config", applies: "next use", risk: "raises", floor: "ask", path: ["permission_modes", peer] })),
+  ...SETTING_PEERS.filter(peer => !definitionOf(peer)?.permission.unmanaged).map((peer): SettingDef => ({ key: `permission.${peer}`, group: "Permissions", label: `${peer}: mode now`, type: "enum", values: PERMISSION_MODES, store: "runtime", applies: "live", risk: "raises", floor: "ask", path: [peer] })),
+  ...SETTING_PEERS.filter(peer => !definitionOf(peer)?.permission.unmanaged).map((peer): SettingDef => ({ key: `permission_modes.${peer}`, group: "Permissions", label: `${peer}: mode at next peer start`, type: "enum", values: PERMISSION_MODES, store: "config", applies: "next use", risk: "raises", floor: "ask", path: ["permission_modes", peer] })),
   ...START_MODE_PEERS.map((peer): SettingDef => ({ key: `peers.${peer}.start_mode`, group: "Start", label: `${peer}: start mode (tui unless set)`, type: "enum", values: START_MODES, store: "config", applies: "next use", risk: "raises", floor: "tui", path: ["peers", peer, "start_mode"] })),
-  { key: "pi.auto_start", group: "Start", label: "Start Pi with the hub", type: "boolean", store: "config", applies: "next use", risk: "raises", floor: false, path: ["pi", "auto_start"] },
+  ...ADAPTERS.flatMap(adapter => adapter.configuration?.settings ?? []),
   { key: "routing.stay_switch", group: "Routing", label: "Stay or switch (hub/auto and stage routes)", type: "enum", values: ["off", "shadow", "enforce"], store: "routing", applies: "live", risk: "raises", path: ["stay_switch"] },
   ...CLASSES.flatMap(perClass),
   { key: "research.enabled", group: "Switches", label: "Research records", type: "boolean", store: "config", applies: "live", risk: "safe", path: ["research", "enabled"] },

package/src/hub/settled-roles.ts

@@ -1,5 +1,5 @@
 import { conductorPeer } from "./conductor.ts";
-import { PLANNER_PEERS } from "./peer-catalog.ts";
+import { PLANNER_PEERS } from "../adapters/registry.ts";
 
 export interface SettledRoles {
   roles: Record<string, string[]>;

package/src/hub/start-mode.ts

@@ -1,4 +1,4 @@
-import { SUPPORTED_PEERS, isSupportedPeer } from "./peer-catalog.ts";
+import { definitionOf, SUPPORTED_PEERS, START_MODE_PEERS as REGISTRY_START_MODE_PEERS } from "../adapters/registry.ts";
 
 /**
  * #269: how a peer comes up when the hub starts it: its own TUI in a terminal, or headless. A person who types
@@ -8,12 +8,15 @@ import { SUPPORTED_PEERS, isSupportedPeer } from "./peer-catalog.ts";
 export const PEER_START_RETRY_MS = 30_000;
 export const START_MODES = ["tui", "headless"] as const;
 export type StartMode = typeof START_MODES[number];
+// ponytail: released coordinators source-probe this exact literal before restoring headless Kimi.
+// Keep it until those readers negotiate the registry capability.
 /** The peers with both forms. Kimi's TUI is pull-only; Claude has only a TUI and local only headless. */
 export const START_MODE_PEERS = ["pi", "codex", "kimi"] as const;
 /** Every peer the hub can start itself. */
 export const STARTABLE_PEERS = SUPPORTED_PEERS;
 export type StartablePeer = typeof STARTABLE_PEERS[number];
-export const isStartablePeer = (value: unknown): value is StartablePeer => isSupportedPeer(value);
+export const isStartablePeer = (value: unknown): value is StartablePeer => typeof value === "string" && !!definitionOf(value)?.start.conductorStartable;
+
 
 export type PeerStartConfig = Record<string, { start_mode?: StartMode }>;
 /** The checked per-peer start modes; only peers with both forms may be configured. */
@@ -22,7 +25,7 @@ export function peerStartConfig(value: unknown): PeerStartConfig {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("peers must be an object of per-peer settings");
   const result: PeerStartConfig = {};
   for (const [peer, block] of Object.entries(value)) {
-    if (!(START_MODE_PEERS as readonly string[]).includes(peer)) throw new Error(`peers.${peer}: only ${START_MODE_PEERS.join(" and ")} have a start mode`);
+    if (!(REGISTRY_START_MODE_PEERS as readonly string[]).includes(peer)) throw new Error(`peers.${peer}: only ${REGISTRY_START_MODE_PEERS.join(" and ")} have a start mode`);
     if (!block || typeof block !== "object" || Array.isArray(block)) throw new Error(`peers.${peer} must be an object`);
     const mode = (block as { start_mode?: unknown }).start_mode;
     if (mode !== undefined && !(START_MODES as readonly unknown[]).includes(mode)) throw new Error(`peers.${peer}.start_mode must be tui or headless`);
@@ -33,9 +36,8 @@ export function peerStartConfig(value: unknown): PeerStartConfig {
 
 /** The mode a start of `peer` takes when nothing more specific was asked: `tui` wherever the peer has one. */
 export function startModeOf(peers: PeerStartConfig | undefined, peer: string): StartMode {
-  if (peer === "claude") return "tui";
-  if ((START_MODE_PEERS as readonly string[]).includes(peer)) return peers?.[peer]?.start_mode ?? "tui";
-  return "headless";
+  if ((REGISTRY_START_MODE_PEERS as readonly string[]).includes(peer)) return peers?.[peer]?.start_mode ?? definitionOf(peer)?.start.defaultForm ?? "tui";
+  return definitionOf(peer)?.start.defaultForm ?? "headless";
 }
 
 /**