@staix/agent-hub 0.12.43 → 0.12.44

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/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

@@ -48,6 +48,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 <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 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"],
@@ -178,3 +179,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.`;
+}

package/src/cli/identity.ts

@@ -1,5 +1,6 @@
+import { nativeCliMarkerPeer } from "../adapters/definitions/native-identity-defaults.ts";
 import { recoveryPresentationFlag } from "./recovery-presentation-options.ts";
-import { definitionOf, kindOf, type KindMap } from "../adapters/registry.ts";
+import { definitionOf, kindOf, type KindMap, type ProjectAdapterCatalog } from "../adapters/registry.ts";
 
 /** Recovery reads this declaration before delegating to another package's CLI. */
 export const LIVE_TEST_SUPPORTED = true;
@@ -42,7 +43,7 @@ export function detectCliIdentity(env: Readonly<Record<string, string | undefine
   if (codex !== undefined && (!codex || /\s/.test(codex))) return invalid("invalid CODEX_THREAD_ID marker");
   if (session !== undefined && claude === undefined) return invalid("CLAUDE_CODE_SESSION_ID without CLAUDECODE marker");
   if (claude !== undefined && codex !== undefined) return invalid("conflicting native agent markers");
-  const native = claude !== undefined ? "claude" : codex !== undefined ? "codex" : undefined;
+  const native = nativeCliMarkerPeer(claude !== undefined, codex !== undefined);
   if (hub !== undefined && native !== undefined && (kindOf(hub, instances) ?? hub) !== native) return invalid("AGENTHUB_PEER_ID conflicts with native agent marker");
   const peer = hub ?? native;
   return peer === undefined ? { role: "console" } : { role: "tools", peer };
@@ -51,9 +52,9 @@ export function detectCliIdentity(env: Readonly<Record<string, string | undefine
 export type PeerCommandAccess = "allowed" | "conductor" | "console";
 
 /** A closed list: unknown commands cannot acquire console authority through an agent shell. */
-export function classifyPeerCommand(command: string, args: readonly string[]): PeerCommandAccess {
+export function classifyPeerCommand(command: string, args: readonly string[], catalog?: ProjectAdapterCatalog): PeerCommandAccess {
   if (command === "recovery" && recoveryAction(args) === "reattach") return "console";
-  const native = definitionOf(command);
+  const native = catalog?.definitionOf(command) ?? definitionOf(command);
   if (native?.cli.personOnlyFlags?.some(flag => args.includes(flag))) return "console";
   if (command === "pet" && args.includes("--window")) return "console";
   if (command === "permission" || command === "stop" || command === "watch") return "console";
@@ -82,11 +83,11 @@ export function classifyPeerCommand(command: string, args: readonly string[]): P
 }
 
 /** No argument text is included: notices and refusal logs must not copy task text or credentials. */
-export function cliCommandLabel(command: string, args: readonly string[]): string {
+export function cliCommandLabel(command: string, args: readonly string[], catalog?: ProjectAdapterCatalog): string {
   if (command === "backlog") return ["list", "add", "pull", "pull-ready", "split", "return", "plan", "pin", "undo"].includes(args[0] ?? "") ? `backlog ${args[0]}` : "backlog";
   if (command === "board" && args[0] === "import") return "board import";
   if (command === "release") return ["new", "list", "show", "plan", "activate", "freeze", "ship", "drop"].includes(args[0] ?? "") ? `release ${args[0]}` : "release";
-  if (!definitionOf(command) && !["upgrade", "restart", "recovery", "recovery-run", "help", "--help", "--version", "version", "completion", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "stop", "models", "say", "queue", "tail", "watch", "budget", "board", "task", "review", "remember", "ask", "route", "pause", "resume", "permit", "permission", "settings", "roster", "status", "pet", "logs", "export", "report", "research", "memory", "goal", "bench", "sdlc", "role", "facts", "check-path", "turns", "undo", "kill", "reset", "doctor"].includes(command)) return "unknown";
+  if (!(catalog?.definitionOf(command) ?? definitionOf(command)) && !["upgrade", "restart", "recovery", "recovery-run", "help", "--help", "--version", "version", "completion", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "stop", "models", "say", "queue", "tail", "watch", "budget", "board", "task", "review", "remember", "ask", "route", "pause", "resume", "permit", "permission", "settings", "roster", "status", "pet", "logs", "export", "report", "research", "memory", "goal", "bench", "sdlc", "role", "facts", "check-path", "turns", "undo", "kill", "reset", "doctor"].includes(command)) return "unknown";
   if (["task", "queue", "budget", "route", "recovery", "models", "projects", "research", "memory", "goal", "bench"].includes(command)) {
     const sub = command === "bench" || command === "memory" || command === "goal" ? args.find((arg) => arg !== "--json") : args[0];
     if (sub && ["propose", "show", "assign", "unassign", "escalate", "label", "list", "resolve", "resume", "set", "execution", "explain", "status", "abort", "dispose", "reattach", "setup", "start", "stop", "remove", "export", "backfill", "addons", "run", "report", "compare", "search", "graph", "promote", "demote", "forget", "supersede", "dedupe", "decay", "rebuild", "sync", "machine", "import", "suggestions", "confirm", "reject", "new", "link", "state", "done", "take"].includes(sub)) return `${command} ${sub}`;

package/src/cli/launch.ts

@@ -1,3 +1,4 @@
+import { claudePeer as defaultChannelPeer } from "../hub/claude-state.ts";
 // Launchers inject only the flags the hub owns and refuse user-supplied duplicates.
 import { claudeStateFile } from "../hub/claude-state.ts";
 import { mkdirSync, writeFileSync, renameSync, unlinkSync, lstatSync, readFileSync, openSync, closeSync, readSync, accessSync, constants, linkSync } from "node:fs";
@@ -159,7 +160,7 @@ async function withClaudeLaunchRecord(stateDir: string, action: () => void): Pro
 }
 
 function writeClaudeLaunchRecord(stateDir: string, record: Record<string, unknown>): void {
-  const file = join(stateDir, claudeStateFile("claude-launch", typeof record.peer === "string" ? record.peer : "claude")), temp = `${file}.${randomUUID()}.tmp`;
+  const file = join(stateDir, claudeStateFile("claude-launch", typeof record.peer === "string" ? record.peer : defaultChannelPeer(undefined))), temp = `${file}.${randomUUID()}.tmp`;
   try { writeFileSync(temp, JSON.stringify(record), { mode: 0o600 }); renameSync(temp, file); }
   finally { try { unlinkSync(temp); } catch { /* the rename normally consumed it */ } }
 }
@@ -202,7 +203,7 @@ export async function recordClaudeNative(stateDir: string, launch: ClaudeLaunchR
   const publication = await withClaudeLaunchRecord(stateDir, () => {
     let current: ClaudeLaunchRecord;
     try {
-      const file = join(stateDir, claudeStateFile("claude-launch", launch.peer ?? "claude")), stat = lstatSync(file);
+      const file = join(stateDir, claudeStateFile("claude-launch", launch.peer ?? defaultChannelPeer(undefined))), stat = lstatSync(file);
       if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || (stat.mode & 0o777) !== 0o600 || !process.getuid || stat.uid !== process.getuid()) return;
       current = JSON.parse(readFileSync(file, "utf8"));
     } catch { return; }
@@ -219,7 +220,7 @@ export async function recordClaudeNative(stateDir: string, launch: ClaudeLaunchR
       writeFileSync(temp, JSON.stringify({ ...launch, nativePid: pid, nativeSignature: signature, nativeIdentity: "direct-child" }), { mode: 0o600, flag: "wx" });
       renameSync(temp, file);
     } finally { try { unlinkSync(temp); } catch { /* atomic rename consumed our private temporary file */ } }
-    try { recorded = sameClaudeLaunch(JSON.parse(readFileSync(join(stateDir, claudeStateFile("claude-launch", launch.peer ?? "claude")), "utf8")), launch); } catch { /* replaced or unreadable managed record */ }
+    try { recorded = sameClaudeLaunch(JSON.parse(readFileSync(join(stateDir, claudeStateFile("claude-launch", launch.peer ?? defaultChannelPeer(undefined))), "utf8")), launch); } catch { /* replaced or unreadable managed record */ }
   });
   if (publication.warning) report?.(publication.warning);
   return publication.recorded && recorded;
@@ -333,7 +334,7 @@ export function buildLaunch(
 ): Launch {
   const adapter = definitionOf(tool);
   if (!adapter) throw new Error("native launch definition unavailable");
-  const { metadata: _metadata, ...launch } = adapter.start.launch({
+  const { metadata: _metadata, ...launch } = adapter.start.launch!({
     instance: ctx.instance ?? tool, form: "tui", projectRoot: process.cwd(), stateDir: ctx.facts?.stateDir ?? ctx.statusLine?.stateDir ?? "",
     entrypoint: resolve(import.meta.dir, "main.js"), userArgs, env: {}, ...ctx,
   });