@staix/agent-hub 0.12.43 → 0.12.45

package/src/adapters/registry-types.ts

@@ -16,6 +16,9 @@ import type { LocalOptions } from "./local-worker.ts";
 import type { PiOptions } from "./pi.ts";
 import type { ClaudePrintOptions } from "./claude-print.ts";
 
+import type { BuiltinCliEntry } from "./definitions/native-cli-entry-types.ts";
+import type { NativePreviewBuilder } from "./definitions/native-cli-preview-common.ts";
+
 export type StartForm = "tui" | "headless";
 export type DaemonEngine = "codex-appserver" | "acp" | "owned-acp" | "pi-rpc" | "local-worker" | "claude-print" | "reviewer-print";
 
@@ -90,6 +93,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 +104,6 @@ export type NativeModeSpec =
 export interface QuotaReader {
   source: string;
   read(value: unknown): UsageWindow[];
-  resetOnWindow?: boolean;
 }
 
 export interface ContextReader {
@@ -145,12 +148,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 +180,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 +201,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,14 +275,14 @@ 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 };
-  };
+  /** Stable host projection order and planner eligibility, independent of default task roles. */
+  projection?: { roleRank?: number; startRank?: number; helpRank?: number; plannerEligible?: boolean };
   cli: {
     command: string;
+    /** Fixed builtin CLI ports; project definitions cannot supply these callbacks. */
+    entry?: Readonly<Omit<BuiltinCliEntry, "command">>;
+    preview?: NativePreviewBuilder;
+    usage?: readonly (readonly [usage: string, description: string])[];
     /** Configuration leaves that select this peer's next native launch command or provider profile. */
     launchConfigKeys?: readonly string[];
     /** Restrictions only; core identity remains authoritative. */
@@ -302,3 +304,13 @@ 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[];
+  readonly externalDefinitions: 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,18 +6,14 @@ 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";
-export const ADAPTER_API = 1;
+import { ADAPTER_API } from "./adapter-api.ts";
+export { ADAPTER_API };
 
-/** Ordered compatibility projections stay typed independently of definition implementation inference. */
-export const KNOWN_PEERS = ["claude", "codex", "kimi", "pi", "local"] as const;
-export const OPTIONAL_PEERS = ["qwen", "jcode", "agy"] as const;
-export const SUPPORTED_PEERS = [...KNOWN_PEERS, ...OPTIONAL_PEERS] as const;
-export const START_MODE_PEERS = ["pi", "codex", "kimi", "jcode"] as const;
-export const OFFICE_PEER_ORDER: readonly string[] = KNOWN_PEERS;
 
 
 function immutable<T>(value: T, seen = new WeakSet<object>()): T {
@@ -37,13 +33,38 @@ export const ADAPTERS: readonly AdapterDefinition[] = immutable([
   ...NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN.filter(definition => definition.kind === "jcode"),
   AGY_DEFINITION,
 ]);
+export interface AdapterLists {
+  readonly KNOWN_PEERS: readonly string[]; readonly OPTIONAL_PEERS: readonly string[]; readonly SUPPORTED_PEERS: readonly string[];
+  readonly START_MODE_PEERS: readonly string[]; readonly ROLE_ORDER: readonly string[]; readonly HELP_ORDER: readonly string[]; readonly PLANNER_PEERS: readonly string[];
+}
+/** Pure builtin projections. Unranked definitions retain their source order after ranked definitions. */
+export function deriveAdapterLists(definitions: readonly AdapterDefinition[]): AdapterLists {
+  const ordered = (field: "roleRank" | "startRank" | "helpRank", eligible = (_definition: AdapterDefinition) => true) => definitions
+    .map((definition, index) => ({ definition, index })).filter(({ definition }) => eligible(definition))
+    .sort((left, right) => {
+      const a = left.definition.projection?.[field], b = right.definition.projection?.[field];
+      if (a === undefined) return b === undefined ? left.index - right.index : 1;
+      if (b === undefined) return -1;
+      return a - b || left.index - right.index;
+    }).map(({ definition }) => definition.kind);
+  const KNOWN_PEERS = definitions.filter(definition => !definition.optional).map(definition => definition.kind);
+  const OPTIONAL_PEERS = definitions.filter(definition => definition.optional).map(definition => definition.kind);
+  return immutable({ KNOWN_PEERS, OPTIONAL_PEERS, SUPPORTED_PEERS: [...KNOWN_PEERS, ...OPTIONAL_PEERS],
+    START_MODE_PEERS: ordered("startRank", definition => definition.start.forms.includes("tui") && definition.start.forms.includes("headless")),
+    ROLE_ORDER: ordered("roleRank"), HELP_ORDER: ordered("helpRank"),
+    PLANNER_PEERS: definitions.filter(definition => definition.projection?.plannerEligible === true).map(definition => definition.kind),
+  });
+}
+export const { KNOWN_PEERS, OPTIONAL_PEERS, SUPPORTED_PEERS, START_MODE_PEERS, ROLE_ORDER, PLANNER_PEERS } = deriveAdapterLists(ADAPTERS);
+export const OFFICE_PEER_ORDER: readonly string[] = KNOWN_PEERS;
+
 // Unavailable declarations are metadata, not supported native peers or launchers.
 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 +86,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 +95,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 +105,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,9 +120,33 @@ 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, externalDefinitions: readonly AdapterDefinition[] = []): ProjectAdapterCatalog {
+  const configured = configuredAcpDefinitions(rawAdapters, [...definitions.keys()]);
+  for (const definition of configured) { assertDefinitionCoherence(definition); assertNativeCapabilityScope(definition); }
+  const seen = new Set([...definitions.keys(), ...configured.map(item => item.kind)]);
+  for (const definition of externalDefinitions) {
+    if (definition.api !== ADAPTER_API || seen.has(definition.kind)) throw new Error("external adapter kind or API collision");
+    assertDefinitionCoherence(definition); assertNativeCapabilityScope(definition);
+    seen.add(definition.kind);
+  }
+  const external = immutable([...externalDefinitions]);
+  const entries = Object.freeze([...ADAPTERS, ...configured, ...external]);
+  const catalog = new Map([...definitions, ...[...configured, ...external].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, externalDefinitions: external, 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;
+
 
 /** Callers own their role arrays, independent of immutable native policy. */
 export function defaultPeerRoles(includeOptional = false): Record<string, string[]> {
@@ -126,6 +174,52 @@ 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 projection = definition.projection;
+  if (projection !== undefined) {
+    if (!projection || typeof projection !== "object" || Array.isArray(projection) || Object.keys(projection).some(key => !["roleRank", "startRank", "helpRank", "plannerEligible"].includes(key))) fail("projection", "invalid projection metadata");
+    for (const field of ["roleRank", "startRank", "helpRank"] as const) if (projection[field] !== undefined && (typeof projection[field] !== "number" || !Number.isFinite(projection[field]))) fail(`projection.${field}`, "rank must be finite");
+    if (projection.plannerEligible !== undefined && typeof projection.plannerEligible !== "boolean") fail("projection.plannerEligible", "boolean required");
+  }
+  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;
@@ -137,9 +231,13 @@ export function assertNativeCapabilityScope(definition: AdapterDefinition): void
     ["session.crashIdentity", declared(definition.session, "crashIdentity")],
     ["start.daemonPort pi-rpc", definition.start.daemonPort === "pi-rpc"],
     ["routing", definition.routing !== undefined],
+    ["projection", definition.projection !== undefined],
     ["reviewerVariant", definition.reviewerVariant !== undefined],
     ["reviewer", definition.reviewer !== undefined],
     ["hooks.factsHook", declared(definition.hooks, "factsHook")],
+    ["cli.entry", declared(definition.cli, "entry")],
+    ["cli.preview", declared(definition.cli, "preview")],
+    ["cli.usage", declared(definition.cli, "usage")],
   ];
   const field = restricted.find(([, present]) => present)?.[0];
   if (field) throw new Error(`${field} is restricted to fixed builtin adapter definitions`);
@@ -174,8 +272,8 @@ export function builtinPreviewOf(id: string) {
 /** Fixed builtin doctor metadata and pure observed-value projections; the CLI retains all probe effects. */
 export { DOCTOR_TOOL_PROBES, DOCTOR_MEMORY_CAPTURE_PEERS, DOCTOR_PLUGIN_PROBE, nativeDoctorCheck, nativeDoctorRecoveryIdentity, nativeDoctorOptionalProbes } from "./definitions/native-cli-doctor.ts";
 
-/** Internal fixed builtin CLI entries; public AdapterDefinition and NativeHooks expose no execution extension. */
-export const BUILTIN_CLI_ENTRIES = Object.freeze(builtinCliEntries.map(entry => {
+/** Definition-owned CLI entries are restricted to fixed builtins, never config or external execution extensions. */
+export const BUILTIN_CLI_ENTRIES = Object.freeze(builtinCliEntries(ADAPTERS).map(entry => {
   const definition = definitionOf(entry.command);
   if (!definition) throw new Error("builtin CLI entry has no adapter definition");
   return Object.freeze({ ...entry, definition });

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/configured-acp-entry.ts

@@ -0,0 +1,58 @@
+import type { ProjectAdapterCatalog } from "../adapters/registry.ts";
+import type { InstancesConfig } from "../hub/instances.ts";
+import { requireActiveInstance, requirePeerInstances } from "./launch.ts";
+import { configuredAcpPreview } from "./preview.ts";
+
+export interface ConfiguredAcpSelection { peer: string; mode: "headless"; sessionId?: string; preview: boolean }
+export function parseConfiguredAcpArguments(kind: string, raw: readonly string[], catalog: ProjectAdapterCatalog, instances?: InstancesConfig): ConfiguredAcpSelection {
+  const definition = catalog.definitionOf(kind);
+  if (!definition?.permission.genericAcp) throw new Error("unknown configured ACP kind");
+  const values = new Map<string, string>();
+  let preview = false;
+  for (let index = 0; index < raw.length; index++) {
+    const arg = raw[index]!;
+    if (arg === "--print-command" || arg === "--dry-run") { if (preview) throw new Error("preview option may appear only once"); preview = true; continue; }
+    const equal = arg.indexOf("="), flag = equal < 0 ? arg : arg.slice(0, equal);
+    if (!["--as", "--mode", "--session-id"].includes(flag) || values.has(flag)) throw new Error("configured ACP accepts only --mode headless, --as, --session-id and one preview option");
+    const value = equal < 0 ? raw[++index] : arg.slice(equal + 1);
+    if (!value || value.startsWith("--") || Buffer.byteLength(value) > 4096 || /[\p{Cc}\p{Cf}]/u.test(value)) throw new Error(`${flag} needs a bounded control-free value`);
+    values.set(flag, value);
+  }
+  if (values.has("--mode") && values.get("--mode") !== "headless") throw new Error("configured ACP supports headless only");
+  const peer = values.get("--as") ?? kind;
+  if (values.has("--as") && (!instances || !Object.hasOwn(instances, peer) || instances[peer]?.kind !== kind || !catalog.definitionOf(peer, instances))) throw new Error("--as must name a declared instance of this configured kind");
+  return { peer, mode: "headless", ...(values.has("--session-id") ? { sessionId: values.get("--session-id")! } : {}), preview };
+}
+export interface ConfiguredAcpControl {
+  features: readonly string[];
+  request(message: Record<string, unknown>, timeout?: number): Promise<any>;
+  close(): void;
+}
+export async function requireActiveConfiguredAcp(hub: ConfiguredAcpControl, kind: string, peer: string, warn?: (text: string) => void): Promise<void> {
+  if (!hub.features.includes("configured_acp")) throw new Error("running hub lacks configured_acp; upgrade and restart it first");
+  if (peer !== kind) requirePeerInstances(hub.features);
+  const reply = await hub.request({ t: "status" });
+  const active = reply.status?.configuredAdapters;
+  if (!Array.isArray(active) || !active.includes(kind)) throw new Error(`running hub has not loaded ${kind}; restart it after declaring the adapter`);
+  if (peer !== kind) requireActiveInstance(reply.status, peer);
+  const namespace = `adapters.${kind}`;
+  const retained = [reply.status?.retainedConfig, reply.status?.pendingRestart].some(rows => Array.isArray(rows) && rows.some(row => {
+    const key = row && typeof row === "object" ? row.key : undefined;
+    return typeof key === "string" && (key === "adapters" || key === namespace || key.startsWith(`${namespace}.`));
+  }));
+  if (retained) warn?.(`${kind}: configured adapter changes are retained; this start uses the running definition. Restart the hub to apply the file's definition.`);
+}
+export async function runConfiguredAcpEntry(context: {
+  kind: string; raw: readonly string[]; catalog: ProjectAdapterCatalog; instances?: InstancesConfig;
+  connect(): Promise<ConfiguredAcpControl>; print(text: string): void; operationId?: string;
+}): Promise<void> {
+  const selected = parseConfiguredAcpArguments(context.kind, context.raw, context.catalog, context.instances);
+  if (selected.preview) { context.print(JSON.stringify(configuredAcpPreview(context.kind, selected.peer, selected.sessionId !== undefined), null, 2)); return; }
+  const hub = await context.connect();
+  try {
+    await requireActiveConfiguredAcp(hub, context.kind, selected.peer, context.print);
+    const reply = await hub.request({ t: "start", peer: selected.peer, args: { mode: "headless", ...(selected.sessionId ? { sessionId: selected.sessionId } : {}) }, ...(context.operationId ? { operationId: context.operationId } : {}) }, 70_000);
+    if (!reply.ok) throw new Error(typeof reply.error === "string" ? reply.error : "configured ACP start refused");
+    context.print(reply.already ? `${selected.peer} is already attached` : `${selected.peer} attached (headless); use ahub say @${selected.peer} and the console for approvals`);
+  } finally { hub.close(); }
+}

package/src/cli/console-state.ts

@@ -2,7 +2,7 @@ import { consoleNeeds, characterAttentionLine, attentionCommand } from "./attent
 import { CHARACTERS, petFrame, petSize, petFooterRows, type CharacterId, type PetSize, type PetPose } from "../pet/frame.ts";
 import { PEER_PALETTE } from "../ui/peer-palette.ts";
 import { PERMISSION_MODES, permissionBoundary } from "../hub/permission-mode.ts";
-import { PLANNER_PEERS, definitionOf, nativeStreamTone } from "../adapters/registry.ts";
+import { PLANNER_PEERS, definitionOf, nativeStreamTone, createProjectAdapterCatalog } from "../adapters/registry.ts";
 import { taskProgress } from "../ui/task-progress.ts";
 import type { ProgressStage } from "../ui/task-progress.ts";
 import { sanitize } from "../hub/envelope.ts";
@@ -91,7 +91,7 @@ export function syncPermissionDefaults(s: ConsoleState, rows: unknown): boolean
   return true;
 }
 export function permissionDefaultText(row: Pick<PermissionDefault, "peer" | "source">): string {
-  return `never-ask default for ${row.peer} from ${quoted(row.source)}\n${permissionBoundary(row.peer)}\nUntil you answer y, this default stays ask. y enables; n cancels for this hub; Esc defers.`;
+  return `never-ask default for ${row.peer} from ${quoted(row.source)}\n${permissionBoundary(row.peer, undefined, createProjectAdapterCatalog())}\nUntil you answer y, this default stays ask. y enables; n cancels for this hub; Esc defers.`;
 }
 /** Strip terminal controls before any daemon or child output reaches a terminal. Preserve printable Unicode. */
 export function terminalText(value: unknown): string {
@@ -471,6 +471,8 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
   if (s.settingsEdit) {
     const edit = { ...s.settingsEdit }; s.settingsEdit = edit;
     if (key === "\x1b") { s.settingsEdit = undefined; return done(); }
+    const locked = s.settingsRows?.find(row => row.key === edit.key)?.locked;
+    if (locked) { s.settingsEdit = undefined; notify(s, locked, now); return done(); }
     if (edit.phase === "preview") return done();
     if (edit.phase === "confirm") {
       s.settingsEdit = undefined;
@@ -632,6 +634,8 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
     const row = selectedPanelRow(s);
     if (key === "u" && !s.settingsUndo) { notify(s, "nothing to undo", now); return done(); }
     if (key === "e" && !row) return done();
+    const locked = (key === "e" ? row : s.settingsRows?.find(row => row.key === s.settingsUndo))?.locked;
+    if (locked) { notify(s, locked, now); return done(); }
     const token = (s.settingsSequence ?? 0) + 1; s.settingsSequence = token;
     s.settingsEdit = { token, undo: key === "u", ...(key === "e" ? { key: row.key } : {}), phase: key === "u" ? "preview" : "value", text: key === "e" ? settingValueText(row.fileValue) : "" };
     if (key === "u") effects.push({ type: "settings_preview", token, undo: true });
@@ -975,6 +979,7 @@ export function renderConsoleLines(s: ConsoleState, columns: number, rows = 24,
     if (p.paused) summary.push(span(" paused", "attention"));
     if (typeof p.importantWaitingSince === "number") summary.push(span(` important waiting ${duration(now - p.importantWaitingSince)}`, "attention")); // #572 AC1: a busy ACP peer that cannot be steered
     if (p.toolsOnly) summary.push(span(definitionOf(id)?.attach?.pullOnlyForms?.includes("tui") ? ` pull-only, read ${typeof p.lastInboxAt === "number" ? relative(p.lastInboxAt, now) : "never"}` : " tools-only: ahub claude", "attention"));
+    if (typeof p.statusNotice?.message === "string" && p.statusNotice.message) summary.push(span(` ${flat(p.statusNotice.message)}`, "attention"));
   }
   if (s.pendingRestart?.length) summary.push(span(`${summary.length ? " | " : ""}restart pending: ${s.pendingRestart.map(row => row.key).join(", ")}`, "attention"));
   if (s.retainedConfig?.length) summary.push(span(`${summary.length ? " | " : ""}config retained: ${s.retainedConfig.map(row => row.key).join(", ")}; run ahub settings reload`, "attention"));
@@ -988,7 +993,7 @@ export function renderConsoleLines(s: ConsoleState, columns: number, rows = 24,
   const neverPeer = s.confirm?.type === "permission_default" ? s.confirm.peer : s.confirm?.type === "command" && s.confirm.args[0] === "permission" && s.confirm.args[2] === "never-ask" ? s.confirm.args[1] : undefined;
   const defaultSource = s.confirm?.type === "permission_default" ? s.confirm.source : undefined;
   if (s.confirm?.type === "permission_default") prompt = `enable never-ask default for ${s.confirm.peer}? y/n Esc defer`;
-  const footer = [fitLine(neverPeer ? [span(permissionBoundary(neverPeer), "attention")] : summary, columns),
+  const footer = [fitLine(neverPeer ? [span(permissionBoundary(neverPeer, undefined, createProjectAdapterCatalog()), "attention")] : summary, columns),
     fitLine(defaultSource !== undefined ? [span(`source ${quoted(defaultSource.split(/[\\/]/).at(-1))}; stays ask until y`, "attention")] : approvals, columns),
     fitLine([span(prompt, s.confirm || s.optionChoice ? "attention" : undefined)], columns)];
   const rule = [span("-".repeat(Math.max(0, columns)), "muted")];
@@ -1006,7 +1011,7 @@ export function renderConsoleLines(s: ConsoleState, columns: number, rows = 24,
   const noticeLines = noticeShown && s.petEnabled && petSize(s.petSize, columns, rows) !== "line" ? wrap(`Notice: ${s.notice}`, columns).slice(0, Math.max(0, bodyHeight - 6)).map(text => [span(text, s.noticeTone ?? "failure")]) : [];
   const height = bodyHeight - noticeLines.length;
   const lines: Span[][] = [];
-  if (s.confirm?.type === "permission_default") lines.push(...fieldLines([["default", `${s.confirm.peer} never-ask`], ["source", s.confirm.source], ["bounds", permissionBoundary(s.confirm.peer)], ["decision", "y enables; n cancels for this hub; Esc defers; until then ask"]], columns, now).flat());
+  if (s.confirm?.type === "permission_default") lines.push(...fieldLines([["default", `${s.confirm.peer} never-ask`], ["source", s.confirm.source], ["bounds", permissionBoundary(s.confirm.peer, undefined, createProjectAdapterCatalog())], ["decision", "y enables; n cancels for this hub; Esc defers; until then ask"]], columns, now).flat());
   else if (s.settingsEdit) {
     const edit = s.settingsEdit;
     const row = s.settingsRows?.find(row => row.key === edit.key);

package/src/cli/facts-hook.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import { claudePeer as defaultChannelPeer } from "../hub/claude-state.ts";
 import { definitionOf } from "../adapters/registry.ts";
 // Managed Claude hook transport for turn-free facts, native observations and runtime permissions.
 // PreToolUse preserves facts additionalContext and adds permission decisions; other phases observe only.
@@ -101,7 +102,7 @@ export async function factsHook(stdin: string, stateDir: string, peer: string, t
 if (import.meta.main) {
   try {
     const stateDir = process.env.AGENTHUB_STATE_DIR;
-    const out = stateDir ? await factsHook(await Bun.stdin.text(), stateDir, process.env.AGENTHUB_PEER_ID ?? "claude", 2000, process.env.AGENTHUB_HOOK_EVENT) : undefined;
+    const out = stateDir ? await factsHook(await Bun.stdin.text(), stateDir, process.env.AGENTHUB_PEER_ID ?? defaultChannelPeer(undefined), 2000, process.env.AGENTHUB_HOOK_EVENT) : undefined;
     if (out) console.log(out);
   } catch {
     // a hook that fails must not get in the way of the tool call

package/src/cli/help.ts

@@ -1,3 +1,4 @@
+import { ADAPTERS, deriveAdapterLists, type AdapterDefinition } from "../adapters/registry.ts";
 import { VERSION } from "../version.ts";
 import { paint, wrap, type Span } from "./console-state.ts";
 
@@ -26,9 +27,10 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub sdlc status [task] | explain <task> | export <task> | record <task> <receipt-json>", "read head-bound lifecycle gates and the next actor/action (person only)"],
     ["ahub sdlc queue <owner/repo> | release <owner/repo> [live-issue...]", "read-only merge and release evidence (person only)"],
     ["ahub sdlc accept <task> --issue <n> [--repo owner/repo]", "accept the task's spec issue at its current body; build entry needs it in enforce (person only)"],
-    ["ahub sdlc plan-review <task> <revision> <reason...> [--review full|delta|none --reviewers N --ci full|focused|reuse]", "record planner review, scope and host-read issue metadata"],
+    ["ahub sdlc accept-departure <task> <head> <reason...>", "accept current plan departures on that exact PR head (person only)"],
+    ["ahub sdlc plan-review <task> <revision> <reason...> [--review full|delta|none --reviewers N] [--ci full|focused|reuse]", "record planner review, scope and host-read issue metadata"],
     ["ahub sdlc train report|configure|cut <release-id> [revision] [json]", "plan a release and freeze its approved scope after resource/quota admission"],
-    ["ahub sdlc release-assign <task> <revision> <release-id|none> <reason>", "assign approved/in-flight work without changing execution"],
+    ["ahub sdlc release-assign <task> <revision> <release-id|none> <reason...>", "assign approved/in-flight work without changing execution"],
     ["ahub sdlc costs [owner/repo]", "read bounded planner cost metrics for linked merged PRs"],
     ["ahub backlog groom | return <task> <revision> <reason...>", "read grooming findings or return accepted untouched work to backlog (planner/person)"],
     ["ahub status [--json] [--full] [--color=auto|always|never]", "the hub, its peers, model backends and task counts"],
@@ -48,15 +50,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub recovery-run <operation-id>", "internal: the detached runner of an upgrade, restart or recovery resume"],
   ]],
   ["Agents", [
-    ["ahub claude [--print-command] [--unattended] [args...]", "launch Claude Code with the hub channel"],
-    ["ahub codex [--print-command] [--unattended] [args...]", "start the Codex adapter and attach the TUI"],
-    ["ahub kimi [--print-command] [--mode tui|headless] [--model <alias>]", "default: Kimi's own TUI, pull-only via hub_inbox; no push, steer, watchdog, console approvals or automatic quota handoff. Select headless for ACP"],
-    ["ahub jcode [--mode tui|headless] [--model <alias>] [--provider-profile <name>] [--session-id <id>] [--print-command]", "optional Jcode (roster.jcode, default off): its TUI on the hub-owned ACP session, opened once that session is saved; --mode headless for ACP only; native policy unmanaged, no hub sandbox"],
-    ["ahub agy [--print-command | --dry-run] [args...]", "optional Antigravity CLI 1.4.x TUI (1.4.2 verified) in this terminal (roster.agy, default off): pull-only via hub_inbox, implementer/verifier only; native permissions unmanaged, no hub sandbox"],
-    ["ahub qwen [--mode headless] [--model <alias>] [--session-id <id>] [--print-command]", "start optional Qwen Code 0.25.0 ACP (roster.qwen, default off)"],
-    ["ahub pi [--print-command] [--mode headless|tui | --headless] [--backend auto|dgx|mlx] [--model <alias>] [--session-id <id>] [--session-file <path>] [--replace-session]", "start Pi: its TUI in this terminal unless --headless or the start mode setting (peers.pi.start_mode) says headless; without a terminal the hub opens one or says how"],
-    ["ahub local [--route <id> | --model <id>]", "start the hub-native worker on the self-hosted models (routing.toml)"],
-    ["ahub claude|codex|kimi|qwen|pi|local --as <instance> [options...]", "start an extra instance of that kind declared under instances in .agenthub/config.local.json"],
+    ["ahub <configured-kind> [--mode headless] [--as <instance>] [--session-id <id>] [--print-command | --dry-run]", "start a trusted config.local.json ACP kind (default off roster); native argv is withheld in previews"],
     ["ahub role list [--group <group>] | show <id>", "read bounded catalog guidance with layer and content hash"],
     ["ahub role assign <peer> <id> | clear <peer> [<id>]", "person only: add or clear catalog guidance, applied at the next peer start"],
     ["ahub stop <peer>", "human only: stop a hub-owned headless peer; end TUI agents in their terminals"],
@@ -70,7 +64,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub permission [<peer> [ask|ask-when-needed|never-ask]] [--yes]", "human only: inspect or set a running peer mode; never-ask requires --yes; config never-ask waits for console y"],
     ["ahub permit <id> <option>", "answer a permission request shown by tail (\"deny\" cancels)"],
     ["ahub roster [--json] [--color=auto|always|never]", "human only: every known peer, participation, start mode and retained work"],
-    ["ahub roster add <peer> | remove <peer> [--yes] [--now]", "human only: change live participation through settings; removal previews retained messages and task handoff"],
+    ["ahub roster add <peer> | remove <peer> [--yes] [--now]", "human only: change live participation through settings; removal previews retained messages and task handoff; remove also deletes the roster key of an instance no longer declared"],
     ["ahub settings [list] [--json] | get <key> [--json]", "human only: the settings the dashboard can change, each with its value, the file it comes from and when it applies"],
     ["ahub settings set <key> <value|inherit> [--yes] [--preview] [--now] | undo | reload", "human only: change or reload validated settings, written to .agenthub/config.local.json or routing.local.toml (never a tracked file); --preview shows the effect and saves nothing; undo puts back the last write"],
     ["ahub pause|resume <peer>", "hold a peer's deliveries in its queue / release them"],
@@ -93,7 +87,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub task unassign <id> [--role owner|reviewer] [--revision N]", "person only: remove the owner/reservation or reviewer without routing a replacement or stopping native work"],
     ["ahub task cancel <id> --reason <text> [--superseded-by <ref>] [--revision N]", "person only: close obsolete work with a reason; retain its history without stopping native work or releasing dependents"],
     ["ahub task label <id> ok|regressed|reverted|incomplete|wrong|abandoned [--created <time>]", "your later verdict on an approved task, kept in the research records (research must be on)"],
-    ["ahub review <id> approved|changes_requested [note...] [--unmet <item>]... [--head <sha>]", "give a review verdict on a task"],
+    ["ahub review <id> approved|changes_requested [note...] [--unmet <item>]... [--head <sha>] [--findings <json>]", "give a review verdict on a task"],
     ["ahub review brief <id>", "print the review brief of a task's commit: reviewable and excluded files, rules, coverage to account for"],
     ["ahub route explain <id>", "why a task went where it went, its reserved owner included"],
     ["ahub route explain --class <c> <title...>", "what would happen to such a task now"],
@@ -144,7 +138,18 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub manager", "internal: the dashboard manager process that ahub ui --all starts"],
   ]],
 ];
-export const HELP: readonly HelpEntry[] = SECTIONS.flatMap(([section, rows]) => rows.map(([usage, description]) => ({ section, usage, description })));
+export function helpEntries(definitions: readonly AdapterDefinition[] = ADAPTERS): readonly HelpEntry[] {
+  const byKind = new Map(definitions.map(definition => [definition.kind, definition]));
+  const order = deriveAdapterLists(definitions).HELP_ORDER;
+  const native = order.flatMap(kind => byKind.get(kind)?.cli.usage ?? []);
+  const instanceKinds = order.filter(kind => byKind.get(kind)?.instances !== undefined);
+  const instances: readonly [string, string] = [`ahub ${instanceKinds.join("|")} --as <instance> [options...]`, "start an extra instance of that kind declared under instances in .agenthub/config.local.json"];
+  return SECTIONS.flatMap(([section, rows]) => {
+    const entries: readonly (readonly [string, string])[] = section === "Agents" ? [rows[0]!, ...native, ...(instanceKinds.length ? [instances] : []), ...rows.slice(1)] : rows;
+    return entries.map(([usage, description]) => ({ section, usage, description }));
+  });
+}
+export const HELP = helpEntries();
 
 const COMMAND = /^ahub (-{0,2}[a-z][a-z-]*(?: ?\| ?-{0,2}[a-z][a-z-]*)*)/;
 /** The command words a usage documents: `ahub pause|resume <peer>` documents pause and resume. */
@@ -158,9 +163,10 @@ const DESCRIPTION = 34;
  * (80 to 100 columns). A usage too long for that column puts its description on the next line.
  * With a command, only its entries; an unknown command renders nothing.
  */
-export function renderHelp(columns: number, color: boolean, command?: string): string {
+export function renderHelp(columns: number, color: boolean, command?: string, definitions?: readonly AdapterDefinition[]): string {
   const width = Math.min(100, Math.max(80, columns || 80));
-  const entries = command === undefined ? HELP : HELP.filter(entry => helpCommands(entry).includes(command));
+  const model = definitions === undefined ? HELP : helpEntries(definitions);
+  const entries = command === undefined ? model : model.filter(entry => helpCommands(entry).includes(command));
   const lines: Span[][] = command === undefined ? wrap(`agent-hub ${VERSION}: Claude Code, Codex and Kimi as peers in one project directory`, width, 0).map(text => [{ text }]) : [];
   let section = "";
   for (const entry of entries) {
@@ -178,3 +184,8 @@ export function renderHelp(columns: number, color: boolean, command?: string): s
   }
   return lines.map(line => paint(line, color)).join("\n");
 }
+
+/** Body-free configured command guidance; no native argv or environment values enter help. */
+export function configuredAcpHelp(kind: string): string {
+  return `ahub ${kind} [--mode headless] [--as <instance>] [--session-id <id>] [--print-command | --dry-run]\nConfigured ACP runs headless through the hub, with native permissions and NO hub sandbox.\nDeclare it in untracked .agenthub/config.local.json, restart the hub, then enable roster.${kind}.\nPreview withholds native argv and starts nothing. Native/model overrides and --unattended are refused.`;
+}