@staix/agent-hub 0.12.42 → 0.12.44

package/src/adapters/pi.ts

@@ -52,10 +52,14 @@ export interface PiOptions {
   onApprovalStop?: (reason: string) => void;
   /** How long stop() waits for a graceful TUI owner exit before verified teardown. Tests shrink this. */
   stopGraceMs?: number;
+  /** Host process-identity reader; never supplied by bridge events or peer config. */
+  signature?: typeof processSignature;
 }
 export interface PiTuiLaunch { cmd: string; args: string[]; env: NodeJS.ProcessEnv; }
 type RpcMessage = { type?: string; id?: string | number; command?: string; success?: boolean; data?: any; [key: string]: any };
 type VerifiedEmptyResume = { sessionId: string };
+type TerminalOwnerObservation = { pid: number; signature: string; sessionId: string; sessionFile: string; ownerToken: string; checkedAt: number };
+const TERMINAL_OWNER_MAX_AGE_MS = 1_000;
 function ownerStillAlive(pid: number, signature: string | undefined): boolean { const current = processSignature(pid); if (current !== undefined) return current === signature; try { process.kill(pid, 0); return true; } catch { return false; } }
 
 
@@ -121,6 +125,7 @@ export class PiPeer extends BasePeer {
   private ownerPid?: number;
   private ownerSignature?: string;
   private ownerMonitor?: ReturnType<typeof setInterval>;
+  private terminalOwnerObservation?: TerminalOwnerObservation;
   private tuiExit?: Promise<void>;
   private resolveTuiExit?: () => void;
   private tuiCommands = new Map<string, { command: Record<string, unknown>; resolve: (value: any) => void; reject: (error: Error) => void }>();
@@ -139,7 +144,7 @@ export class PiPeer extends BasePeer {
     if (this.state === "busy" || this.starting || this.activeTools) return false;
     if (this.sessionFile && !existsSync(this.sessionFile) && (this.activityObserved || this.persistedOnce)) return false;
     if (this.opts.mode === "headless") return this.state === "idle" || !this.proc || this.proc.exitCode !== null || this.proc.signalCode !== null;
-    if (this.state === "idle") return this.ownerClaimed && !!this.ownerPid && processSignature(this.ownerPid) === this.ownerSignature;
+    if (this.state === "idle") return this.ownerClaimed && !!this.ownerPid && this.readOwnerSignature(this.ownerPid) === this.ownerSignature;
     return this.stopping && !this.ownerClaimed && (!this.ownerPid || !ownerStillAlive(this.ownerPid, this.ownerSignature));
   }
   /** Explicit replacement may retain an unpersisted identity, but never a live/unknown owner or active effects. */
@@ -337,6 +342,7 @@ export class PiPeer extends BasePeer {
   }
 
   private async startImpl(): Promise<void> {
+    this.terminalOwnerObservation = undefined;
     this.stopping = false;
     this.rosterDetached = false; this.rosterUnownedRun = false;
     this.requestedStopReason = undefined;
@@ -366,7 +372,7 @@ export class PiPeer extends BasePeer {
       }
       if (request.method !== "POST") return new Response("method not allowed", { status: 405 });
       const body = await request.json() as any;
-      if (url.pathname === "/event") { if (body.type === "session_start" && this.stopping) return Response.json({ ok: false, error: "Pi launch has ended" }, { status: 409 }); if (body.type === "session_start" && (typeof body.sessionId !== "string" || !body.sessionId || typeof body.sessionFile !== "string" || !body.sessionFile)) return Response.json({ ok: false, error: "Pi session identity is missing" }, { status: 400 }); if (body.type === "session_start" && this.ownerClaimed && (body.ownerToken !== this.ownerToken || body.pid !== this.ownerPid || body.signature !== this.ownerSignature || (this.sessionId && body.sessionId !== this.sessionId) || (this.sessionFile && body.sessionFile !== this.sessionFile))) return Response.json({ ok: false, error: "Pi session owner or identity already claimed" }, { status: 409 }); if (body.type === "session_start" && (!Number.isInteger(body.pid) || !body.signature || processSignature(body.pid) !== body.signature)) return Response.json({ ok: false, error: "Pi process identity is not verified" }, { status: 409 }); this.handleBridgeEvent(body); return Response.json({ ok: true }); }
+      if (url.pathname === "/event") { if (body.type === "session_start" && this.stopping) return Response.json({ ok: false, error: "Pi launch has ended" }, { status: 409 }); if (body.type === "session_start" && (typeof body.sessionId !== "string" || !body.sessionId || typeof body.sessionFile !== "string" || !body.sessionFile)) return Response.json({ ok: false, error: "Pi session identity is missing" }, { status: 400 }); if (body.type === "session_start" && this.ownerClaimed && (body.ownerToken !== this.ownerToken || body.pid !== this.ownerPid || body.signature !== this.ownerSignature || (this.sessionId && body.sessionId !== this.sessionId) || (this.sessionFile && body.sessionFile !== this.sessionFile))) return Response.json({ ok: false, error: "Pi session owner or identity already claimed" }, { status: 409 }); if (body.type === "session_start" && (!Number.isInteger(body.pid) || !body.signature || this.readOwnerSignature(body.pid) !== body.signature)) return Response.json({ ok: false, error: "Pi process identity is not verified" }, { status: 409 }); this.handleBridgeEvent(body); return Response.json({ ok: true }); }
       if (url.pathname === "/ack") {
         const pending = this.tuiCommands.get(String(body.id));
         if (!pending) return Response.json({ ok: false }, { status: 404 });
@@ -415,7 +421,7 @@ export class PiPeer extends BasePeer {
     // The hub spawned this headless owner and get_state proved its session. Pin the same
     // identity a native extension claim uses, including fakes that do not load the extension.
     if (!this.ownerClaimed) {
-      const pid = this.proc?.pid, signature = pid ? processSignature(pid) : undefined;
+      const pid = this.proc?.pid, signature = pid ? this.readOwnerSignature(pid) : undefined;
       if (!pid || !signature) throw new Error("Pi headless owner process identity is not verified");
       this.ownerPid = pid; this.ownerSignature = signature;
       this.ownerToken = String(this._tuiLaunch?.env.AGENTHUB_PI_OWNER_TOKEN ?? ""); this.ownerClaimed = true;
@@ -426,12 +432,26 @@ export class PiPeer extends BasePeer {
     this.setState("idle");
   }
 
+  private readOwnerSignature(pid: number): string | undefined { return (this.opts.signature ?? processSignature)(pid); }
+
   private verifiedOwner(): boolean {
-    return this.ownerClaimed && !!this.ownerPid && !!this.ownerSignature && processSignature(this.ownerPid) === this.ownerSignature;
+    return this.ownerClaimed && !!this.ownerPid && !!this.ownerSignature && this.readOwnerSignature(this.ownerPid) === this.ownerSignature;
+  }
+
+  private rememberTerminalOwner(): void {
+    if (!this.ownerClaimed || !this.ownerPid || !this.ownerSignature) return;
+    this.terminalOwnerObservation = { pid: this.ownerPid, signature: this.ownerSignature, sessionId: this.sessionId,
+      sessionFile: this.sessionFile, ownerToken: this.ownerToken, checkedAt: performance.now() };
   }
 
   terminalOwner(_launchId: string): { generation: string; nativePid: number } | undefined {
-    if (this.opts.mode !== "tui" || !this.started || this.stopping || this.rosterDetached || !this.verifiedOwner() || !this.sessionId || !this.sessionFile ||
+    const observed = this.terminalOwnerObservation;
+    // Reconciliation reads the monitor's bounded observation, never spawning ps on its 1 s tick.
+    // Effect admission and teardown keep their fresh process-identity checks.
+    if (this.opts.mode !== "tui" || !this.started || this.stopping || this.rosterDetached || this.state === "offline" ||
+        !this.ownerClaimed || !observed || performance.now() - observed.checkedAt > TERMINAL_OWNER_MAX_AGE_MS ||
+        observed.pid !== this.ownerPid || observed.signature !== this.ownerSignature || observed.sessionId !== this.sessionId ||
+        observed.sessionFile !== this.sessionFile || observed.ownerToken !== this.ownerToken || !this.sessionId || !this.sessionFile ||
         this.opts.sessionId && this.opts.sessionId !== this.sessionId || this.opts.sessionFile && this.opts.sessionFile !== this.sessionFile) return undefined;
     const generation = this.sessionGeneration;
     return generation && this.ownerPid ? { generation, nativePid: this.ownerPid } : undefined;
@@ -448,6 +468,7 @@ export class PiPeer extends BasePeer {
   /** Withdraw hub admission without shutting down a person's Pi TUI or its bridge. */
   async detachForRoster(): Promise<void> {
     if (this.opts.mode !== "tui") throw new Error("Pi roster detach requires a personal TUI");
+    this.terminalOwnerObservation = undefined;
     this.rosterDetached = true; this.rosterEpoch++;
     this.setState("offline");
     clearTimeout(this.executionBudgetTimer); this.executionBudgetTimer = undefined;
@@ -489,6 +510,7 @@ export class PiPeer extends BasePeer {
   async stop(reason?: string): Promise<void> {
     if (reason !== undefined) this.requestedStopReason = reason;
     this.rosterEpoch++;
+    this.terminalOwnerObservation = undefined;
     this.stopping = true; // fence new calls before withdrawing both turn and idle-shell execution
     for (const id of this.activeDeliveryIds) this.delivery({ id, state: "needs_review", reason: reason ?? "Pi session stopped before settlement" });
     this.activeDeliveryIds.clear();
@@ -713,6 +735,7 @@ export class PiPeer extends BasePeer {
       this.sessionId = String(event.sessionId ?? ""); this.sessionFile = String(event.sessionFile ?? "");
       this.ownerPid = Number.isInteger(event.pid) ? event.pid : undefined; this.ownerSignature = typeof event.signature === "string" ? event.signature : undefined;
       if ((this.opts.sessionId && this.sessionId !== this.opts.sessionId) || (this.opts.sessionFile && this.sessionFile !== this.opts.sessionFile)) { this.opts.log?.(`[${this.id}] Pi session identity mismatch`); return; }
+      this.rememberTerminalOwner();
       this.startOwnerMonitor(); if (this.opts.mode === "tui") { this.started = true; this.setState("idle"); }
     }
     if (event.type === "session_shutdown") {
@@ -723,7 +746,7 @@ export class PiPeer extends BasePeer {
       if (this.opts.mode === "tui") this.reportExit(exit);
     }
     if (event.type === "tool_abort" && this.agentRunning && this.ownerClaimed && this.ownerPid && this.ownerSignature
-      && processSignature(this.ownerPid) === this.ownerSignature && event.sessionId === this.sessionId && event.generation === this.budgetGeneration
+      && this.readOwnerSignature(this.ownerPid) === this.ownerSignature && event.sessionId === this.sessionId && event.generation === this.budgetGeneration
       && typeof event.toolCallId === "string" && event.toolCallId.length > 0 && event.toolCallId.length <= 512) {
       const pending = this.pendingToolGenerations.get(event.toolCallId);
       if (pending && pending.generation === event.generation) pending.abort.abort();
@@ -846,6 +869,7 @@ export class PiPeer extends BasePeer {
   }
 
   private fail(error: Error): void {
+    this.terminalOwnerObservation = undefined;
     const approvalStopReason = this.approvalStopReason;
     this.abortTools();
     this.agentRunning = false;
@@ -866,18 +890,24 @@ export class PiPeer extends BasePeer {
   private startOwnerMonitor(): void {
     this.clearOwnerMonitor();
     if (this.opts.mode !== "tui" || !this.ownerPid || !this.ownerSignature) return;
-    this.ownerMonitor = setInterval(() => {
-      if (!this.ownerPid || ownerStillAlive(this.ownerPid, this.ownerSignature)) return;
-      const exit = this.exitMetadata("owner_lost");
-      this.stopping = true; this.ownerClaimed = false; this.clearOwnerMonitor();
-      this.resolveTuiExit?.(); this.resolveTuiExit = undefined;
-      for (const pending of this.tuiCommands.values()) pending.reject(new Error("Pi owner exited"));
-      this.tuiCommands.clear(); this.tuiQueue = [];
-      this.fail(new Error("Pi owner process exited without session_shutdown"));
-      this.reportExit(exit);
-    }, 500);
+    this.ownerMonitor = setInterval(() => this.checkOwner(), 500);
     this.ownerMonitor.unref?.();
   }
+  private checkOwner(): void {
+    if (!this.ownerPid) { this.terminalOwnerObservation = undefined; return; }
+    const current = this.readOwnerSignature(this.ownerPid);
+    if (current !== undefined && current === this.ownerSignature) { this.rememberTerminalOwner(); return; }
+    this.terminalOwnerObservation = undefined;
+    // Unknown process identity retains the existing live-owner fence, but is never terminal proof.
+    if (current === undefined) { try { process.kill(this.ownerPid, 0); return; } catch { /* positively gone */ } }
+    const exit = this.exitMetadata("owner_lost");
+    this.stopping = true; this.ownerClaimed = false; this.clearOwnerMonitor();
+    this.resolveTuiExit?.(); this.resolveTuiExit = undefined;
+    for (const pending of this.tuiCommands.values()) pending.reject(new Error("Pi owner exited"));
+    this.tuiCommands.clear(); this.tuiQueue = [];
+    this.fail(new Error("Pi owner process exited without session_shutdown"));
+    this.reportExit(exit);
+  }
   private clearOwnerMonitor(): void { if (this.ownerMonitor) clearInterval(this.ownerMonitor); this.ownerMonitor = undefined; }
   private async endApprovalTurn(generation: number, reason: string): Promise<void> {
     if (!this.agentRunning || generation !== this.budgetGeneration || this.approvalStopReason !== reason || !this.acceptingTools || this.state === "offline") return;
@@ -915,3 +945,7 @@ export class PiPeer extends BasePeer {
     void this.terminateFailedTurn(new Error("Pi run became inactive before agent_settled"));
   }
 }
+
+export function isPiPeer(value: unknown): value is PiPeer {
+  return value instanceof PiPeer;
+}

package/src/adapters/registry-types.ts

@@ -90,6 +90,7 @@ export interface VersionContext {
   env: Readonly<Record<string, string>>;
 }
 
+/** Compatibility type for frozen A1 permission metadata, not a runtime permission port. */
 export type NativeModeSpec =
   | { kind: "acp-mode"; modeId: string }
   | { kind: "codex-approval"; policy: string }
@@ -100,7 +101,6 @@ export type NativeModeSpec =
 export interface QuotaReader {
   source: string;
   read(value: unknown): UsageWindow[];
-  resetOnWindow?: boolean;
 }
 
 export interface ContextReader {
@@ -145,12 +145,7 @@ export interface NativeFactsPort {
 
 /** Only the frozen native seams are extensible; a definition cannot add an arbitrary daemon callback. */
 export interface NativeHooks {
-  agentIdentity(init: unknown): void;
-  onAttach(instance: string): void;
-  onDetach(instance: string): void;
   factsHook: NativeFactsPort;
-  conversationRevert(turnId: string): Promise<void>;
-  replaceSession(req: StartRequest): Promise<unknown>;
   pluginInventory(ctx: { home: string; cwd?: string; env: Readonly<Record<string, string | undefined>> }): Addon[];
   recallSource: string;
   recallInjected: boolean;
@@ -182,8 +177,8 @@ export interface AdapterDefinition {
   start: {
     forms: readonly StartForm[];
     defaultForm: StartForm;
-    ownsTerminal(form: StartForm): boolean;
-    launch(ctx: LaunchContext): LaunchPlan;
+    /** A real native argv planner; absent when startup belongs to a separate verified host port. */
+    launch?(ctx: LaunchContext): LaunchPlan;
     create?(ctx: CreateContext): PeerAdapter;
     daemonPort?: DaemonEngine;
     preflight?(ctx: StartRequest): string | undefined;
@@ -203,16 +198,20 @@ export interface AdapterDefinition {
     conductorStartArgs?(args: string[]): { mode?: StartForm } | Error;
   };
   identity: { mcp: "acp-session" | "project-file" | "env" | "channel-plugin" };
+  /** Declaration admission only; execution-root and runtime owner proof remain host responsibilities. */
+  instances?: { mode: "external" | "headless"; roles?: readonly string[] };
   attach?: {
+    /** The authenticated external hello may claim this id; independent of MCP configuration shape. */
+    externalHello?: boolean;
     pullOnlyForms?: readonly StartForm[];
     recoveryLaunch?(instance: string): Record<string, unknown>;
     pullOnlyNotice?: string;
     admission?: { reservedRefusal: string; watchRefusal: string };
   };
   permission: {
-    modes: Partial<Record<PermissionMode, NativeModeSpec>>;
+    /** Consumed configured-ACP mode capability; native runtime and instance ceiling use the same validated mapping. */
+    genericAcp?: { modes?: Partial<Record<PermissionMode, string>>; readOnly?: string };
     grants?: Partial<Record<PermissionMode, string>>;
-    readOnly?: NativeModeSpec;
     unmanaged?: string;
     unmanagedForms?: readonly StartForm[];
     unmanagedNote?: string;
@@ -273,12 +272,6 @@ export interface AdapterDefinition {
     validateEffective?(raw: Record<string, unknown>, fail: (key: string, reason: string) => never): void;
   };
   capabilities?: { manifest?(peer: PeerAdapter): Promise<CapabilityManifest>; watch?: boolean };
-  init?: {
-    templateFragment?: string;
-    mcpFile?: string;
-    /** Pure planner; the CLI host owns every write and cleanup. */
-    mcpPlan?(ctx: { projectRoot: string; stateDir: string; entrypoint: string; form: StartForm }): { file: string; tracked: boolean; changed: boolean; action: string };
-  };
   cli: {
     command: string;
     /** Configuration leaves that select this peer's next native launch command or provider profile. */
@@ -302,3 +295,12 @@ export interface AdapterDefinition {
 
 /** Explicit project declarations, passed by the bound host. No process-global instance registration. */
 export type KindMap = Readonly<Record<string, { readonly kind: string; readonly roles?: readonly string[]; readonly start_mode?: "tui" | "headless"; readonly review_mode?: "fresh" }>>;
+
+/** Immutable per-project resolver; exported globals remain builtin-only. */
+export interface ProjectAdapterCatalog {
+  readonly definitions: readonly AdapterDefinition[];
+  definitionOf(id: string, instances?: KindMap): AdapterDefinition | undefined;
+  kindOf(id: string, instances?: KindMap): string | undefined;
+  familyOf(id: string, instances?: KindMap): string | undefined;
+  isSupportedPeer(id: unknown, instances?: KindMap): id is string;
+}

package/src/adapters/registry.ts

@@ -6,7 +6,8 @@ import { DAEMON_PORTS } from "./definitions/native-factories.ts";
 export { DAEMON_PORTS };
 import { NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN } from "./definitions/builtin-metadata.ts";
 import { QWEN_DEFINITION } from "./definitions/qwen.ts";
-import type { AdapterDefinition, KindMap } from "./registry-types.ts";
+import { configuredAcpDefinitions } from "./configured-acp.ts";
+import type { AdapterDefinition, KindMap, ProjectAdapterCatalog } from "./registry-types.ts";
 import { types } from "node:util";
 
 export type * from "./registry-types.ts";
@@ -41,9 +42,9 @@ export const ADAPTERS: readonly AdapterDefinition[] = immutable([
 const declarationOnlyDefinitions: readonly AdapterDefinition[] = immutable([]);
 const definitions = new Map<string, AdapterDefinition>();
 for (const definition of [...ADAPTERS, ...declarationOnlyDefinitions]) {
-  assertDaemonEngine(definition);
+  assertDefinitionCoherence(definition);
   assertNativeCapabilityScope(definition);
-  if (definition.reviewerVariant) { assertDaemonEngine(definition.reviewerVariant); assertNativeCapabilityScope(definition.reviewerVariant); }
+  if (definition.reviewerVariant) { assertDefinitionCoherence(definition.reviewerVariant); assertNativeCapabilityScope(definition.reviewerVariant); }
   if (definition.api !== ADAPTER_API || definitions.has(definition.kind)) throw new Error("invalid builtin adapter registry");
   definitions.set(definition.kind, definition);
 }
@@ -65,7 +66,7 @@ function ownField(value: unknown, key: string): unknown {
   return field && Object.hasOwn(field, "value") && field.enumerable ? field.value : undefined;
 }
 /** Declaration reads never execute caller accessors or inherit another project's mapping. */
-function declaredKind(id: string, instances: KindMap | undefined): string | undefined {
+function declaredKind(id: string, instances: KindMap | undefined, catalog: ReadonlyMap<string, AdapterDefinition> = definitions): string | undefined {
   if (!instances || typeof instances !== "object" || types.isProxy(instances) || Array.isArray(instances)
     || ![Object.prototype, null].includes(Object.getPrototypeOf(instances))) return undefined;
   const field = Object.getOwnPropertyDescriptor(instances, id);
@@ -74,7 +75,7 @@ function declaredKind(id: string, instances: KindMap | undefined): string | unde
   if (!entry || typeof entry !== "object" || types.isProxy(entry) || Array.isArray(entry)
     || ![Object.prototype, null].includes(Object.getPrototypeOf(entry))) return undefined;
   const kind = Object.getOwnPropertyDescriptor(entry, "kind");
-  if (!kind || !Object.hasOwn(kind, "value") || !kind.enumerable || typeof kind.value !== "string" || !definitions.has(kind.value)) return undefined;
+  if (!kind || !Object.hasOwn(kind, "value") || !kind.enumerable || typeof kind.value !== "string" || !catalog.has(kind.value)) return undefined;
   const prefix = `${kind.value}-`;
   return /^[a-z][a-z0-9-]{0,31}$/.test(id) && id.startsWith(prefix) && /^[a-z0-9][a-z0-9-]*$/.test(id.slice(prefix.length)) ? kind.value : undefined;
 }
@@ -84,7 +85,10 @@ export function kindOf(id: string, instances?: KindMap): string | undefined {
 }
 export function definitionOf(id: string, instances?: KindMap): AdapterDefinition | undefined {
   const kind = kindOf(id, instances);
-  const definition = kind === undefined ? undefined : definitions.get(kind);
+  return resolvedDefinition(id, kind, instances, definitions);
+}
+function resolvedDefinition(id: string, kind: string | undefined, instances: KindMap | undefined, catalog: ReadonlyMap<string, AdapterDefinition>): AdapterDefinition | undefined {
+  const definition = kind === undefined ? undefined : catalog.get(kind);
   // #223: only a declared extra (never the builtin id) with start_mode "headless" runs as the kind's reviewer variant.
   const declaration = ownField(instances, id), roles = ownField(declaration, "roles");
   const reviewerOnly = Array.isArray(roles) && !types.isProxy(roles) && roles.length === 1 && Object.getOwnPropertyDescriptor(roles, "0")?.value === "reviewer";
@@ -96,6 +100,24 @@ export function familyOf(id: string, instances?: KindMap): string | undefined {
   return definitionOf(id, instances)?.family;
 }
 
+/** Compile one captured, host-trusted declaration set; never register native policy globally. */
+export function createProjectAdapterCatalog(rawAdapters?: unknown): ProjectAdapterCatalog {
+  const configured = configuredAcpDefinitions(rawAdapters, [...definitions.keys()]);
+  for (const definition of configured) { assertDefinitionCoherence(definition); assertNativeCapabilityScope(definition); }
+  const entries = Object.freeze([...ADAPTERS, ...configured]);
+  const catalog = new Map([...definitions, ...configured.map(definition => [definition.kind, definition] as const)]);
+  const kindOf = (id: string, instances?: KindMap): string | undefined => catalog.has(id) ? id : typeof id === "string" ? declaredKind(id, instances, catalog) : undefined;
+  const definitionOf = (id: string, instances?: KindMap): AdapterDefinition | undefined => resolvedDefinition(id, kindOf(id, instances), instances, catalog);
+  return Object.freeze({ definitions: entries, kindOf, definitionOf,
+    familyOf: (id: string, instances?: KindMap) => definitionOf(id, instances)?.family,
+    isSupportedPeer: (id: unknown, instances?: KindMap): id is string => {
+      if (typeof id !== "string") return false;
+      const kind = kindOf(id, instances), runtime = kind === undefined ? undefined : catalog.get(kind), resolved = definitionOf(id, instances);
+      return runtime !== undefined && resolved !== undefined && (kind === id || resolved === runtime || resolved.reviewer?.unavailable === undefined);
+    },
+  });
+}
+
 /** Compatibility projection order is observable in default role maps and planner selection. */
 const ROLE_ORDER = ["claude", "codex", "kimi", "local", "pi", "qwen", "jcode", "agy"] as const;
 export const PLANNER_PEERS = ["claude", "codex", "kimi", "qwen", "jcode"] as const;
@@ -126,6 +148,46 @@ export function assertDaemonEngine(definition: Pick<AdapterDefinition, "start">)
   if (definition.start.create && engine === undefined || engine !== undefined && !Object.hasOwn(DAEMON_PORTS, engine)) throw new Error("invalid adapter daemon engine");
 }
 
+/** Structural registry contract only: native telemetry readers are never executed during loading. */
+export function assertDefinitionCoherence(definition: AdapterDefinition): void {
+  const fail = (field: string, reason: string): never => { throw new Error(`${definition.kind}.${field}: ${reason}`); };
+  const nonempty = (value: unknown): value is string => typeof value === "string" && value.trim().length > 0;
+  assertDaemonEngine(definition);
+  if (definition.identity.mcp === "channel-plugin" && definition.transport !== "claude-channel" && definition.transport !== "ws-pull") {
+    fail("identity.mcp", "channel-plugin requires claude-channel or ws-pull transport");
+  }
+  if (definition.turnEnd === "native-hook" && definition.transport !== "claude-channel" && !definition.hooks?.factsHook) {
+    fail("turnEnd", "native-hook requires the Claude transport or a native factsHook");
+  }
+  const attach = definition.attach, pullOnly = attach?.pullOnlyForms;
+  if (pullOnly !== undefined) {
+    if (!Array.isArray(pullOnly) || pullOnly.some(form => !definition.start.forms.includes(form))) fail("attach.pullOnlyForms", "each pull-only form must be a supported start form");
+  }
+  if (definition.transport === "ws-pull" || definition.transport === "claude-channel" || definition.instances?.mode === "external") {
+    if (attach?.externalHello !== true) fail("attach.externalHello", "external transport or instance admission requires an explicit hello policy");
+  }
+  if (definition.transport === "ws-pull" && !pullOnly?.length) fail("attach.pullOnlyForms", "ws-pull requires a nonempty pull-only contract");
+  if (attach?.admission !== undefined) {
+    if (!attach.admission || typeof attach.admission !== "object") fail("attach.admission", "admission must declare its refusal policy");
+    if (!definition.start.forms.includes("tui") || !pullOnly?.includes("tui")) fail("attach.admission", "native admission requires a supported pull-only TUI form");
+    for (const field of ["reservedRefusal", "watchRefusal"] as const) {
+      if (!nonempty(attach.admission[field])) fail(`attach.admission.${field}`, "admission refusal text must be nonempty");
+    }
+  }
+  if (definition.budget !== undefined) {
+    if (!nonempty(definition.budget?.account)) fail("budget.account", "declared budget account must be a nonempty string");
+    for (const field of ["reader", "context"] as const) {
+      const reader = definition.budget[field];
+      if (reader === undefined) continue;
+      if (!reader || typeof reader !== "object") fail(`budget.${field}`, "telemetry reader must be an object");
+      if (!nonempty(reader.source)) fail(`budget.${field}.source`, "telemetry source must be a nonempty string");
+      if (typeof reader.read !== "function") fail(`budget.${field}.read`, "telemetry read must be callable");
+    }
+  }
+  if (definition.reviewerVariant && !definition.reviewerVariant.reviewer) fail("reviewerVariant.reviewer", "reviewer variant lacks reviewer policy");
+  if (definition.reviewer?.unavailable && (definition.start.create || definition.reviewer.backend)) fail("reviewer", "unavailable reviewer must remain metadata-only");
+}
+
 /** Host-global native quirks are not capabilities a config-only or external definition may opt into. */
 export function assertNativeCapabilityScope(definition: AdapterDefinition): void {
   if (fixedBuiltinDefinitions.has(definition)) return;

package/src/adapters/reviewer-print.ts

@@ -380,3 +380,7 @@ export class ReviewerPrintPeer extends BasePeer {
     if (this.child === child) { await this.childCleanup?.(); this.child = undefined; this.childStop = undefined; this.childCleanup = undefined; this.childCurrent = undefined; }
   }
 }
+
+export function isReviewerPrintPeer(value: unknown): value is ReviewerPrintPeer {
+  return value instanceof ReviewerPrintPeer;
+}

package/src/cli/agy-mcp.ts

@@ -1,3 +1,4 @@
+import { AGY_DEFINITION } from "../adapters/agy/definition.ts";
 import type { Stats } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { closeSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
@@ -53,7 +54,7 @@ function shellUnquote(value: string): string | undefined {
 }
 
 function validateOptions(options: AgyMcpOptions) {
-  const peer = options.peer ?? "agy";
+  const peer = options.peer ?? AGY_DEFINITION.kind;
   if (!/^[a-z][a-z0-9-]{0,31}$/.test(peer)) throw new Error("agy peer id is invalid");
   for (const [name, value] of Object.entries({ projectRoot: options.projectRoot, stateDir: options.stateDir, serverJs: options.serverJs, hookScript: options.hookScript })) {
     if (typeof value !== "string" || !isAbsolute(value) || value.length > 4096 || /[\u0000-\u001f\u007f]/.test(value)) throw new Error(`${name} must be an absolute control-free path`);
@@ -326,7 +327,7 @@ export function cleanupAgyMcp(options: AgyMcpOptions): void {
   if (!present.length) return;
   if (present.length !== FILES.length) throw new Error("managed agy plugin is incomplete; inspect it before cleanup");
   const currentHooks = parseJson(readFileSync(join(plan.root, HOOKS_FILE)), HOOKS_FILE);
-  const launch = managedHookLaunch(currentHooks, options, options.peer ?? "agy");
+  const launch = managedHookLaunch(currentHooks, options, options.peer ?? AGY_DEFINITION.kind);
   if (!launch || launch.instanceId !== options.instanceId || launch.launchId !== options.launchId) return;
   // A stale cleanup never removes files a newer config update has replaced.
   if (plan.changed) return;

package/src/cli/completion.ts

@@ -0,0 +1,173 @@
+import { HELP } from "./help.ts";
+
+/** An option's value: a fixed list, a path, free text, or none (a flag). */
+type Value = readonly string[] | "path" | "text" | null;
+interface Node { children: Set<string>; options: Map<string, Value>; equals: Set<string> }
+
+/** Printed instead of candidates when the shell should complete file names. */
+export const FILES = "__files__";
+const WORD = /^[a-z][a-z0-9-]*$/;
+const ALTERNATION = /^[a-z][a-z0-9-]*(\|[a-z][a-z0-9-]*)*$/;
+
+/** Split at spaces outside brackets; a bracket group stays one token. */
+function tokens(text: string): string[] {
+  const out: string[] = [];
+  let depth = 0, current = "";
+  for (const ch of text) {
+    if (ch === "[") depth++;
+    if (ch === "]") depth--;
+    if (ch === " " && depth === 0) { if (current) out.push(current); current = ""; } else current += ch;
+  }
+  if (current) out.push(current);
+  return out;
+}
+
+/** Split at ` | ` outside brackets: `ahub sdlc status [task] | explain <task>` has two alternatives. */
+function alternatives(text: string): string[] {
+  const out: string[] = [];
+  let depth = 0, start = 0;
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === "[") depth++;
+    if (text[i] === "]") depth--;
+    if (depth === 0 && text.startsWith(" | ", i)) { out.push(text.slice(start, i)); start = i + 3; i += 2; }
+  }
+  return [...out, text.slice(start)];
+}
+
+/**
+ * A value spec: `a|b|<iso>` offers the literals a and b; an upper-case word (`N`) is a placeholder. Inside angle
+ * brackets the words are placeholders (`<path|id>` is a path, `<id|node>` free text), except a list of three or more
+ * (`<blue|teal|violet|ochre>`) and the keywords none and inherit.
+ */
+// ponytail: the keyword list is what help uses today; a new keyword inside <> needs adding here.
+function value(spec: string): Value {
+  if (spec.startsWith("<")) {
+    const parts = spec.slice(1, -1).split("|");
+    if (parts.length >= 3) return parts;
+    if (/path|dir|file/.test(spec)) return "path";
+    const keywords = parts.filter(part => part === "none" || part === "inherit");
+    return keywords.length ? keywords : "text";
+  }
+  const literal = spec.split("|").filter(part => /^[a-z0-9][\w.-]*$/.test(part));
+  if (literal.length) return literal;
+  return /path|dir|file/.test(spec) ? "path" : "text";
+}
+
+/** Options in a token group: `--flag`, `--name <value>`, `--name a|b`, `--name=a|b`; a group never lends its value to another. */
+function options(group: string[], into: Node): void {
+  for (let i = 0; i < group.length; i++) {
+    const token = group[i]!;
+    if (token.startsWith("[")) { options(tokens(token.slice(1, -1)), into); continue; }
+    const eq = /^(--?[a-zA-Z][\w-]*)=(.+)$/.exec(token);
+    if (eq) { into.options.set(eq[1]!, value(eq[2]!)); into.equals.add(eq[1]!); continue; }
+    if (!/^--?[a-zA-Z][\w-]*$/.test(token)) continue;
+    const next = group[i + 1];
+    if (next !== undefined && !next.startsWith("-") && !next.startsWith("[") && next !== "|") { into.options.set(token, value(next)); i++; }
+    else if (!into.options.has(token)) into.options.set(token, null);
+  }
+}
+
+let table: Map<string, Node> | undefined;
+/** The completion table, read from the `ahub help` entries so it cannot drift from what help documents. */
+export function completionTable(): Map<string, Node> {
+  if (table) return table;
+  const nodes = new Map<string, Node>();
+  const node = (path: readonly string[]) => {
+    const key = path.join(" ");
+    let found = nodes.get(key);
+    if (!found) { found = { children: new Set(), options: new Map(), equals: new Set() }; nodes.set(key, found); }
+    if (path.length) node(path.slice(0, -1)).children.add(path.at(-1)!);
+    return found;
+  };
+  const root = node([]);
+  root.options.set("--project", "path").set("--live-test", null).set("--help", null).set("-h", null);
+  for (const { usage } of HELP) {
+    if (usage.includes("<command>")) continue; // the global --project and --live-test forms, set above
+    let parent: string[] = [];
+    alternatives(usage.replace(/^ahub /, "")).forEach((alt, index) => {
+      const parts = tokens(alt);
+      if (parts[0]?.startsWith("-")) { options(parts, index ? node(parent.slice(0, -1)) : root); return; }
+      let prefixes: string[][] = [index ? parent.slice(0, -1) : []];
+      let i = 0;
+      for (; i < parts.length && ALTERNATION.test(parts[i]!); i++) prefixes = prefixes.flatMap(prefix => parts[i]!.split("|").map(word => [...prefix, word]));
+      const sub = parts[i]?.match(/^\[([a-z][a-z0-9-]*(?:\|[a-z][a-z0-9-]*)+)\]$/);
+      for (const path of prefixes) {
+        const target = node(path);
+        if (sub) for (const word of sub[1]!.split("|")) node([...path, word]);
+        options(parts.slice(i), target);
+      }
+      parent = prefixes[0]!;
+    });
+  }
+  return (table = nodes);
+}
+
+/** Candidates for the last word, given every word after `ahub`. Static: no daemon, project or network. */
+export function completeWords(words: readonly string[]): string[] {
+  const nodes = completionTable(), root = nodes.get("")!;
+  const cur = words.at(-1) ?? "";
+  const path: string[] = [];
+  let pending: Value | undefined;
+  let positional = false; // after a positional argument no subcommand can follow
+  const optionOf = (name: string) => nodes.get(path.join(" "))?.options.get(name) ?? root.options.get(name);
+  for (const word of words.slice(0, -1)) {
+    if (pending !== undefined) { pending = undefined; continue; }
+    if (word.startsWith("-")) { const kind = optionOf(word); if (kind && !word.includes("=")) pending = kind; continue; }
+    if (!positional && nodes.get(path.join(" "))?.children.has(word)) path.push(word);
+    else positional = true;
+  }
+  const values = (kind: Value, prefix = "") => kind === "path" ? [FILES] : Array.isArray(kind) ? kind.map(v => prefix + v) : [];
+  if (pending !== undefined) return values(pending).filter(v => v === FILES || v.startsWith(cur));
+  const eq = /^(--?[\w-]+)=/.exec(cur);
+  if (eq) return values(optionOf(eq[1]!) ?? null, eq[0]).filter(v => v === FILES || v.startsWith(cur));
+  const here = nodes.get(path.join(" "))!;
+  // An option documented as `--name=value` is offered as `--name=`; the shell adds no space after it.
+  const opts = [...new Set([...here.options.keys(), ...(path.length ? [] : root.options.keys())])].map(o => here.equals.has(o) ? `${o}=` : o);
+  const children = positional ? [] : [...here.children];
+  const candidates = cur.startsWith("-") ? opts : [...children, ...(cur && children.length ? [] : opts)];
+  const matched = candidates.filter(c => c.startsWith(cur)).sort();
+  return matched.length || cur.startsWith("-") || children.length ? matched : [FILES];
+}
+
+const SCRIPTS: Record<string, string> = {
+  zsh: `#compdef ahub
+# ahub zsh completion: candidates come from \`ahub __complete\`, read from ahub's own help entries.
+_ahub() {
+  local -a c
+  c=("\${(@f)$(ahub __complete -- "\${(@)words[2,CURRENT]}" 2>/dev/null)}")
+  c=(\${c:#})
+  if [[ "\${c[1]}" == ${FILES} ]]; then _files; return; fi
+  compadd -Q -S '' -- \${(M)c:#*=}
+  compadd -Q -- \${c:#*=}
+}
+compdef _ahub ahub
+`,
+  bash: `# ahub bash completion: candidates come from \`ahub __complete\`, read from ahub's own help entries.
+_ahub() {
+  local IFS=$'\\n' cur=\${COMP_WORDS[COMP_CWORD]}
+  local c=($(ahub __complete -- "\${COMP_WORDS[@]:1:COMP_CWORD}" 2>/dev/null))
+  if [ "\${c[0]}" = ${FILES} ]; then COMPREPLY=($(compgen -f -- "$cur")); else COMPREPLY=("\${c[@]}"); fi
+  case "\${COMPREPLY[*]}" in *=) compopt -o nospace 2>/dev/null ;; esac
+}
+complete -o default -F _ahub ahub
+`,
+  fish: `# ahub fish completion: candidates come from \`ahub __complete\`, read from ahub's own help entries.
+function __ahub_complete
+    set -l cur (commandline -ct)
+    # "$cur" keeps an empty current word as an argument: Tab after a space completes the next word
+    set -l out (ahub __complete -- (commandline -opc)[2..-1] "$cur" 2>/dev/null)
+    if test "$out[1]" = ${FILES}
+        __fish_complete_path (commandline -ct)
+    else
+        printf '%s\\n' $out
+    end
+end
+complete -c ahub -f -a '(__ahub_complete)'
+`,
+};
+
+export const COMPLETION_SHELLS = Object.keys(SCRIPTS);
+/** The script for one shell, or undefined for a shell ahub does not support. */
+export function completionScript(shell: string | undefined): string | undefined {
+  return shell === undefined ? undefined : SCRIPTS[shell];
+}