@staix/agent-hub 0.12.43 → 0.12.44

package/src/adapters/codex-appserver.ts

@@ -5,6 +5,9 @@ import type { PermissionMode } from "../hub/permission-mode.ts";
 import { BasePeer } from "../hub/peers.ts";
 import { codexContext, type ContextReading } from "../hub/context-window.ts";
 import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
+import type { ContextReader } from "./registry-types.ts";
+
+const UNIDENTIFIED_CANCELLATION_NOTICE = "Codex cancelled turn has no verified native id; reattach the native session before further hub delivery";
 
 export interface CodexOptions {
   /** Port the TUI attaches to: `codex --enable tui_app_server --remote ws://127.0.0.1:<proxyPort>`. */
@@ -26,6 +29,8 @@ export interface CodexOptions {
   /** Tokens the thread used since the previous update (see `tokenTotal` for how they are counted). */
   onTokens?: (added: number) => void;
   onContext?: (reading: ContextReading) => void;
+  /** The definition's native occupancy reader; standalone proxies retain the native default. */
+  contextReader?: ContextReader;
   /** The native id of each turn as it starts, after the peer turned busy (issue #33: `ahub undo --context`). */
   onTurn?: (turnId: string) => void;
   /** Each thread the TUI starts (`fresh`) or resumes, as it is adopted (#215: which turns belong to which thread). */
@@ -90,6 +95,10 @@ export class CodexPeer extends BasePeer {
   /** Cancellation tombstones last until that exact native completion or session replacement. */
   private readonly retiredTurns = new Set<string>();
   private unidentifiedCancellation = false;
+  /** Fixed operator guidance only; native identifiers and agent text never enter status. */
+  get statusNotice(): { code: "unidentified-cancellation"; message: string } | undefined {
+    return this.unidentifiedCancellation ? { code: "unidentified-cancellation", message: UNIDENTIFIED_CANCELLATION_NOTICE } : undefined;
+  }
   private unboundAccepted = false;
   private nextId = -1;
   private readonly pending = new Map<number, { resolve: (result?: any) => void; reject: (e: Error) => void; deliveryId?: string; kind?: "deliver" | "steer"; expectedTurnId?: string; afterTurn?: () => void; invalidate?: (reason: string) => void }>();
@@ -342,7 +351,7 @@ export class CodexPeer extends BasePeer {
       // ponytail: after one unidentifiable cancellation, lifecycle attribution requires a session reattach.
       // Never guess that an unnamed late report or a later named start belongs to a new turn.
       this.unidentifiedCancellation = true;
-      this.opts.log?.("Codex cancelled turn has no verified native id; reattach the native session before further hub delivery");
+      this.opts.log?.(UNIDENTIFIED_CANCELLATION_NOTICE);
     }
     for (const turnId of known) this.retireTurn(turnId);
     for (const pending of pendingStarts) pending.invalidate?.("Codex turn watchdog timeout before native acceptance was confirmed");
@@ -634,7 +643,8 @@ export class CodexPeer extends BasePeer {
     if (this.unidentifiedCancellation) return; // native traffic is still forwarded to its TUI; hub attribution is fenced
     const unknownTurn = () => [...this.activeTurns].some(id => id.startsWith("unknown:"));
     if (method === "thread/tokenUsage/updated") {
-      this.opts.onContext?.(codexContext(params.tokenUsage, this.threadId, Date.now()));
+      const reader = this.opts.contextReader;
+      this.opts.onContext?.(reader ? reader.read(params.tokenUsage, this.threadId, Date.now()) : codexContext(params.tokenUsage, this.threadId, Date.now()));
       const total = Number(params.tokenUsage?.total?.totalTokens);
       if (!Number.isFinite(total)) return;
       const added = this.tokenTotal === undefined ? (this.freshThread ? total : 0) : Math.max(0, total - this.tokenTotal);
@@ -707,3 +717,7 @@ function parse(raw: string): any {
     return undefined;
   }
 }
+
+export function isCodexPeer(value: unknown): value is CodexPeer {
+  return value instanceof CodexPeer;
+}

package/src/adapters/configured-acp.ts

@@ -0,0 +1,124 @@
+import { basename } from "node:path";
+import { types } from "node:util";
+import { AcpPeer } from "./acp.ts";
+import type { AdapterDefinition } from "./registry-types.ts";
+import type { PermissionMode } from "../hub/permission-mode.ts";
+import { shellQuote } from "../cli/shell-quote.ts";
+
+export interface ConfiguredAcpAdapterConfig {
+  transport: "acp";
+  command: string;
+  args?: readonly string[];
+  displayName: string;
+  roles: readonly string[];
+  identity?: { name: string; version: string };
+  permission?: Partial<Record<PermissionMode, string>>;
+  readOnly?: string;
+}
+const fail = (field: string, reason: string): never => { throw new Error(`${field}: ${reason}`); };
+/** Core command namespace is reserved; configured kinds cannot shadow operational CLI actions. */
+export const CONFIGURED_ACP_RESERVED_COMMANDS = Object.freeze(["help", "version", "completion", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "recovery-run", "upgrade", "restart", "recovery", "models", "say", "queue", "watch", "tail", "budget", "backlog", "release", "board", "sdlc", "task", "review", "remember", "ask", "route", "pause", "resume", "stop", "permission", "roster", "settings", "permit", "pet", "status", "logs", "export", "bench", "memory", "goal", "research", "report", "facts", "check-path", "turns", "undo", "kill", "reset", "role", "doctor"]);
+const MODES = ["ask", "ask-when-needed", "never-ask"];
+const ROLES = ["planner", "implementer", "verifier", "reviewer"];
+function fields(raw: unknown, at: string): Record<string, PropertyDescriptor> {
+  if (!raw || typeof raw !== "object" || types.isProxy(raw) || Array.isArray(raw) || ![Object.prototype, null].includes(Object.getPrototypeOf(raw)) || Object.getOwnPropertySymbols(raw).length) return fail(at, "must be a plain own-data object");
+  const result: Record<string, PropertyDescriptor> = Object.assign(Object.create(null), Object.getOwnPropertyDescriptors(raw));
+  if (Object.values(result).some(d => !Object.hasOwn(d, "value") || !d.enumerable)) return fail(at, "enumerable data fields required");
+  return result;
+}
+function text(raw: unknown, at: string, max = 4096): string {
+  if (typeof raw !== "string" || !raw.trim() || Buffer.byteLength(raw) > max || /[\p{Cc}\p{Cf}]/u.test(raw)) return fail(at, `must be nonempty control-free text of at most ${max} bytes`);
+  return raw;
+}
+function list(raw: unknown, at: string, max: number): string[] {
+  if (!Array.isArray(raw) || types.isProxy(raw) || Object.getPrototypeOf(raw) !== Array.prototype || Object.getOwnPropertySymbols(raw).length) return fail(at, "must be a string array");
+  const descriptors: Record<string, PropertyDescriptor> = Object.assign(Object.create(null), Object.getOwnPropertyDescriptors(raw));
+  const length = descriptors.length?.value;
+  if (!Number.isSafeInteger(length) || length > max || Object.keys(descriptors).length !== length + 1) return fail(at, "array is sparse or too large");
+  return Array.from({ length }, (_, index) => {
+    const d = descriptors[String(index)];
+    if (!d || !Object.hasOwn(d, "value") || !d.enumerable) return fail(at, "array data fields required");
+    return text(d.value, `${at}.${index}`);
+  });
+}
+function freeze<T>(value: T): T {
+  if (value && typeof value === "object") { for (const item of Object.values(value)) freeze(item); Object.freeze(value); }
+  return value;
+}
+
+/** Pure local declaration compiler; file provenance and runtime process ownership remain host checks. */
+export function configuredAcpDefinitions(raw: unknown, builtinKinds: readonly string[]): readonly AdapterDefinition[] {
+  if (raw === undefined) return Object.freeze([]);
+  const declarations = fields(raw, "adapters");
+  if (Object.keys(declarations).length > 64) return fail("adapters", "at most 64 configured kinds supported");
+  const reserved = new Set([...builtinKinds, ...CONFIGURED_ACP_RESERVED_COMMANDS, "user", "hub", "digest", "constructor", "prototype", "__proto__"]);
+  return Object.freeze(Object.entries(declarations).map(([kind, descriptor]) => {
+    const at = `adapters.${kind}`;
+    if (!/^[a-z][a-z0-9-]{0,31}$/.test(kind) || reserved.has(kind)) return fail(at, "kind is invalid, reserved or collides with a builtin");
+    const input = fields(descriptor.value, at);
+    if (Object.keys(input).some(key => !["transport", "command", "args", "displayName", "roles", "identity", "permission", "readOnly"].includes(key))) return fail(at, "unknown or privileged field");
+    if (input.transport?.value !== "acp") return fail(`${at}.transport`, "must be acp");
+    const command = text(input.command?.value, `${at}.command`), args = input.args ? list(input.args.value, `${at}.args`, 128) : [];
+    // The supported contract is a foreground owned stdio process, never an attachment/proxy selector.
+    if ([command, ...args].some(arg => /^--(?:leader|attach|connect|remote)(?:-|=|$)/.test(arg))) return fail(`${at}.args`, "attach/leader selectors are unsupported; command must run foreground owned ACP stdio");
+    const displayName = text(input.displayName?.value, `${at}.displayName`, 256), roles = list(input.roles?.value, `${at}.roles`, ROLES.length);
+    if (roles.includes("conductor")) return fail(`${at}.roles`, "conductor requires explicit project role policy, not adapter defaults");
+    if (!roles.length || new Set(roles).size !== roles.length || roles.some(role => !ROLES.includes(role))) return fail(`${at}.roles`, "roles must be nonempty, known and unique");
+    let identity: ConfiguredAcpAdapterConfig["identity"];
+    if (input.identity) {
+      const value = fields(input.identity.value, `${at}.identity`);
+      if (Object.keys(value).some(key => !["name", "version"].includes(key))) return fail(`${at}.identity`, "unknown identity field");
+      identity = { name: text(value.name?.value, `${at}.identity.name`, 256), version: text(value.version?.value, `${at}.identity.version`, 256) };
+    }
+    const grokContract = kind === "grok" || /^grok(?:\.exe)?$/i.test(basename(command)) || identity?.name.toLowerCase() === "grok";
+    const noLeader = args.indexOf("--no-leader"), endOptions = args.indexOf("--");
+    if (grokContract && (noLeader < 0 || (endOptions >= 0 && noLeader > endOptions) || args.some(arg => arg.startsWith("--no-leader=")))) {
+      return fail(`${at}.args`, "Grok requires explicit --no-leader before argv termination; valued opt-outs are unsupported");
+    }
+    let modes: ConfiguredAcpAdapterConfig["permission"];
+    if (input.permission) {
+      const value = fields(input.permission.value, `${at}.permission`);
+      modes = {};
+      for (const [mode, d] of Object.entries(value)) {
+        if (!MODES.includes(mode)) return fail(`${at}.permission.${mode}`, "unknown hub mode");
+        modes[mode as PermissionMode] = text(d.value, `${at}.permission.${mode}`, 256);
+      }
+      if (!Object.keys(modes).length) modes = undefined; // `permission: {}` maps nothing: unmanaged, exactly like an omitted map
+    }
+    const readOnly = input.readOnly ? text(input.readOnly.value, `${at}.readOnly`, 256) : undefined;
+    const nativePolicy = freeze({ ...(modes ? { modes } : {}), ...(readOnly ? { readOnly } : {}) });
+    const argv = freeze([command, ...args]);
+    identity = identity && freeze(identity);
+    const definition: AdapterDefinition = {
+      api: 1, kind, family: kind, displayName, transport: "acp", roles, optional: true, defaultOnRoster: false,
+      trust: { onPrem: false, hubSandboxed: false }, identity: { mcp: "acp-session" }, instances: { mode: "headless" },
+      start: {
+        daemonPort: "acp", forms: ["headless"], defaultForm: "headless", conductorStartable: true, hubSwitches: [], ownedFlags: [],
+        exclusiveStartRefusal: "configured ACP start already in progress; retry after it settles",
+        preflight: request => request.form !== undefined && request.form !== "headless" ? `${kind}: configured ACP supports headless only`
+          : !identity ? `${kind}: native identity is unverified; configure the observed name/version pin before starting` : undefined,
+        launch: context => {
+          if (context.form !== "headless") throw new Error(`${kind}: configured ACP supports headless only`);
+          return { cmd: command, args: [...args], metadata: { packageEntrypoint: context.entrypoint, argv: [...argv], command: argv.map(shellQuote).join(" "), env: {} } };
+        },
+        create: context => {
+          if (!("acp" in context.daemon)) throw new Error(`${kind}: ACP transport options required`);
+          if (context.permission === "read-only" && !readOnly) throw new Error(`${kind}: read-only native mode is not configured`);
+          if (!identity) throw new Error(`${kind}: native identity is unverified; configure the observed name/version pin before starting`);
+          return new AcpPeer(context.instance, { ...context.daemon.acp, kind, cmd: [...argv], qwen025: false,
+            expectedAgent: identity, requireLoadSessionEcho: true, requireOwnedGroup: true,
+            permissionMode: context.permission === "read-only" ? "ask" : context.permission,
+            nativePolicy: { ...nativePolicy, lockedReadOnly: context.permission === "read-only" }, mcpServers: context.mcpServers });
+        },
+        conductorStartArgs: args => args.length ? new Error("configured ACP starts accept no launch overrides") : {},
+      },
+      permission: { genericAcp: nativePolicy, grants: Object.fromEntries(MODES.map(mode => [mode, modes?.[mode as PermissionMode] ? `${kind}: asks native ACP to select configured ${mode} mode; native tool policy applies; NO hub sandbox` : `${kind}: no configured native mapping for ${mode}; NO hub sandbox`])), ...(!modes || !Object.keys(modes).length ? { unmanaged: `${kind}: native policy unmanaged; no configured permission map; NO hub sandbox` } : {}) },
+      // ponytail: configured ACP has no verified controlled-recovery driver. Add catalog-bound restoration
+      // with native session/group receipts before enabling controlled recovery; explicit/crash load stays fenced.
+      session: { idField: "sessionId", currentId: peer => { const id = peer.recoveryMetadata?.().sessionId; return typeof id === "string" ? id : undefined; }, launchKind: "acp", resumeById: true, recoveryRefusal: () => "configured ACP has no verified controlled-recovery driver; stop it explicitly and restart with its recorded native session id" },
+      turnEnd: "adapter", cli: { command: kind, launchConfigKeys: [`adapters.${kind}.command`, `adapters.${kind}.args`], startWords: () => [kind] },
+      display: { palette: { fg: "white", bg: "black" } },
+    };
+    return freeze(definition);
+  }));
+}

package/src/adapters/definitions/builtin-metadata.ts

@@ -1,3 +1,4 @@
+import type { PermissionMode } from "../../hub/permission-mode.ts";
 import { claudeReviewerBackend, CODEX_REVIEWER_VARIANT, KIMI_REVIEWER_VARIANT } from "./reviewer-variants.ts";
 import { kimiAcpCommand } from "./native-daemon-kimi.ts";
 import { claudeRecoveryLaunch, kimiRecoveryLaunch, claudeRetainedTerminalNotice, piRetainedTerminalNotice, codexRetainedTerminalNotice, codexRosterReturnNotice, jcodeStartPreflight, claudeObservedVersion, codexObservedVersion } from "./native-daemon-policy.ts";
@@ -12,14 +13,14 @@ import { CLAUDE_DISPLAY, CODEX_DISPLAY, KIMI_DISPLAY, PI_DISPLAY, LOCAL_DISPLAY,
 import { CLAUDE_RECOVERY_SESSION, CODEX_RECOVERY_SESSION, KIMI_RECOVERY_SESSION, PI_RECOVERY_SESSION, LOCAL_RECOVERY_SESSION, JCODE_RECOVERY_SESSION } from "./native-recovery.ts";
 import { claudeWindows, codexWindows } from "./native-quota.ts";
 import { claudeContext, codexContext, acpContextValue } from "./native-context.ts";
-import type { AdapterDefinition, LaunchContext, LaunchPlan, StartForm } from "../registry-types.ts";
+import type { AdapterDefinition, LaunchContext, LaunchPlan, StartForm, NativeModeSpec } from "../registry-types.ts";
 import type { PeerAdapter } from "../../hub/peers.ts";
 import { shellQuote } from "../../cli/shell-quote.ts";
 
 type CompatibilityKind = "claude" | "codex" | "kimi" | "pi" | "local" | "jcode";
 
 /**
- * Preserve CLI-wrapper argv plans for definitions that still declare them and the frozen A1 compatibility export.
+ * Preserve CLI-wrapper argv plans only for the frozen A1 compatibility export.
  * Native startup and daemon factories are supplied separately by the runtime definitions.
  */
 function compatibilityLaunch(kind: CompatibilityKind, ctx: LaunchContext, explicitMode = false): LaunchPlan {
@@ -43,8 +44,6 @@ function sessionId(field: "sessionId" | "threadId"): (peer: PeerAdapter) => stri
     return typeof value === "string" && value ? value : undefined;
   };
 }
-const terminal = (form: StartForm) => form === "tui";
-const headless = () => false;
 const switches = Object.freeze(["--unattended", "--safe", "--new"]);
 const implementerRoles = Object.freeze(["implementer", "verifier"]);
 const dualForms = Object.freeze(["tui", "headless"] as const);
@@ -62,9 +61,9 @@ const hubGrants = {
 const CLAUDE_REVIEWER_VARIANT: AdapterDefinition = {
   api: 1, kind: "claude", displayName: "Claude Code reviewer", family: "claude", transport: "hub-native",
   roles: Object.freeze(["reviewer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
-  start: { create: createClaudeReviewer, daemonPort: "claude-print", forms: headlessForms, defaultForm: "headless", ownsTerminal: headless, launch: ctx => compatibilityLaunch("claude", ctx), conductorStartable: true, hubSwitches: [], ownedFlags: [] },
-  identity: { mcp: "env" },
-  permission: { modes: {}, unmanaged: "each review runs read-only (Read, Grep, Glob) and may call only hub_review and hub_task_show" },
+  start: { create: createClaudeReviewer, daemonPort: "claude-print", forms: headlessForms, defaultForm: "headless", conductorStartable: true, hubSwitches: [], ownedFlags: [] },
+  identity: { mcp: "env" }, instances: { mode: "headless" },
+  permission: { unmanaged: "each review runs read-only (Read, Grep, Glob) and may call only hub_review and hub_task_show" },
   session: { idField: "sessionId", currentId: () => undefined, freshOnRestore: true, launchKind: "claude-print", crashPlan: () => ({ resume: {}, how: "claude reviewer: starts again; every review runs in a new session" }) },
   turnEnd: "adapter", budget: { account: "claude" }, routing: { reviewOnly: true }, reviewer: { backend: claudeReviewerBackend, defaultPool: true, declaration: "automatic" },
   cli: { command: "claude", startWords: () => ["claude"] }, display: CLAUDE_DISPLAY,
@@ -76,11 +75,11 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
   {
     api: 1, kind: "claude", displayName: "Claude Code", family: "claude", transport: "claude-channel",
     roles: Object.freeze(["planner", "reviewer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
-    start: { forms: Object.freeze(["tui"] as const), defaultForm: "tui", ownsTerminal: terminal, launch: claudeNativeLaunch, version: claudeObservedVersion, ...CLAUDE_LAUNCH_POLICY, conductorStartable: true,
+    start: { forms: Object.freeze(["tui"] as const), defaultForm: "tui", launch: claudeNativeLaunch, version: claudeObservedVersion, ...CLAUDE_LAUNCH_POLICY, conductorStartable: true,
       unattended: true, hubSwitches: switches, ownedFlags: Object.freeze(["--dangerously-load-development-channels", "--dangerously-skip-permissions"]) },
-    identity: { mcp: "channel-plugin" }, attach: { recoveryLaunch: claudeRecoveryLaunch },
-    // Existing daemon permission hooks enforce these grants; an empty native mode map is neither unmanaged nor a refusal.
-    permission: { modes: {}, grants: { ask: "Claude's own permission rules decide",
+    identity: { mcp: "channel-plugin" }, instances: { mode: "external", roles: ["reviewer", "planner"] }, attach: { externalHello: true, recoveryLaunch: claudeRecoveryLaunch },
+    // Approval enforcement belongs to the verified native transport and host permission gate.
+    permission: { grants: { ask: "Claude's own permission rules decide",
       "ask-when-needed": "file tools on project files run without asking, outside .agenthub, .git and agent configuration; other tools keep Claude's own rules",
       "never-ask": "every tool runs without asking" } },
     session: { idField: "sessionId", currentId: sessionId("sessionId"), configDirEnv: "CLAUDE_CONFIG_DIR", zeroTurnFresh: true, launchKind: "claude-channel", launchRecord: true, ...CLAUDE_RECOVERY_SESSION, crashPlan: claudeCrashPlan, unrecordedTerminal: "always" },
@@ -92,12 +91,10 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     reviewerVariant: CODEX_REVIEWER_VARIANT,
     api: 1, kind: "codex", displayName: "Codex", family: "codex", transport: "codex-appserver",
     roles: Object.freeze(["implementer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
-    start: { create: createCodex, daemonPort: "codex-appserver", forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, launch: codexNativeLaunch, version: codexObservedVersion, ...CODEX_LAUNCH_POLICY, conductorStartable: true,
+    start: { create: createCodex, daemonPort: "codex-appserver", forms: dualForms, defaultForm: "tui", launch: codexNativeLaunch, version: codexObservedVersion, ...CODEX_LAUNCH_POLICY, conductorStartable: true,
       unattended: true, hubSwitches: switches, ownedFlags: Object.freeze(["--remote", "--remote-auth-token-env", "--yolo", "--dangerously-bypass-approvals-and-sandbox"]) },
-    identity: { mcp: "env" },
-    permission: { trackUnattended: true, modes: { ask: { kind: "native-only", note: "restore the session's captured native approval policy" },
-      "ask-when-needed": { kind: "codex-approval", policy: "on-request" }, "never-ask": { kind: "codex-approval", policy: "never" } },
-      grants: { ask: "the session's own approval policy applies again", "ask-when-needed": "approval policy on-request on every turn", "never-ask": "approval policy never on every turn: nothing asks" } },
+    identity: { mcp: "env" }, instances: { mode: "headless" },
+    permission: { trackUnattended: true, grants: { ask: "the session's own approval policy applies again", "ask-when-needed": "approval policy on-request on every turn", "never-ask": "approval policy never on every turn: nothing asks" } },
     session: { nativeRevert: true, idField: "threadId", currentId: sessionId("threadId"), configDirEnv: "CODEX_HOME", zeroTurnFresh: true, launchKind: "codex", launchRecord: true, ...CODEX_RECOVERY_SESSION, crashPlan: codexCrashPlan, unrecordedTerminal: "always" },
     turnEnd: "adapter", budget: { account: "codex", checkpoint: true, reader: { source: "codex rateLimits", read: codexWindows }, context: { source: "codex_token_usage", read: codexContext } },
     cli: { command: "codex", launchConfigKeys: ["codex_bin"], retainedTerminalNotice: codexRetainedTerminalNotice, rosterReturnNotice: codexRosterReturnNotice, stopNotice: () => "this peer belongs to a native terminal; end it in its terminal", startWords: () => ["codex"] }, display: CODEX_DISPLAY, hooks: { recallPlatform: "codex", recallSource: "codex", recallInjected: true, pluginInventory: codexPluginInventory, classifyTool: codexToolSemantic },
@@ -106,25 +103,24 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     reviewerVariant: KIMI_REVIEWER_VARIANT,
     api: 1, kind: "kimi", displayName: "Kimi Code", family: "kimi", transport: "acp",
     roles: implementerRoles, defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
-    start: { create: createKimi, acpCommand: kimiAcpCommand, explicitHeadlessMode: true, planCommand: () => "ahub kimi", daemonPort: "acp", forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, launch: ctx => compatibilityLaunch("kimi", ctx), conductorStartable: true, hubSwitches: [], ownedFlags: [] },
+    start: { create: createKimi, acpCommand: kimiAcpCommand, explicitHeadlessMode: true, planCommand: () => "ahub kimi", daemonPort: "acp", forms: dualForms, defaultForm: "tui", conductorStartable: true, hubSwitches: [], ownedFlags: [] },
     // ACP sessions carry headless identity; the existing CLI alone owns the TUI's project MCP entry.
-    identity: { mcp: "acp-session" }, attach: { pullOnlyForms: Object.freeze(["tui"] as const), recoveryLaunch: kimiRecoveryLaunch,
+    identity: { mcp: "acp-session" }, instances: { mode: "headless" }, attach: { pullOnlyForms: Object.freeze(["tui"] as const), recoveryLaunch: kimiRecoveryLaunch,
       pullOnlyNotice: "pull-only: messages wait for hub_inbox; no push, steer, watchdog or automatic quota handoff",
       admission: { reservedRefusal: "Kimi attaches pull-only in TUI mode; run ahub kimi", watchRefusal: "Kimi is in pull-only TUI mode; use its native terminal or start headless" } },
-    permission: { modes: { ask: { kind: "acp-mode", modeId: "default" }, "ask-when-needed": { kind: "acp-mode", modeId: "yolo" }, "never-ask": { kind: "acp-mode", modeId: "auto" } },
-      grants: { ask: "Kimi asks as it does on its own", "ask-when-needed": "Kimi's yolo mode: it asks only where it judges it must", "never-ask": "Kimi's auto mode: nothing asks" },
+    permission: { grants: { ask: "Kimi asks as it does on its own", "ask-when-needed": "Kimi's yolo mode: it asks only where it judges it must", "never-ask": "Kimi's auto mode: nothing asks" },
       unmanagedForms: Object.freeze(["tui"] as const), unmanagedStatusNote: "Kimi approves tools in its own TUI; no hub permission mode", unmanagedNote: "Kimi approves tools and selects its permission mode in its own TUI; no hub permission mode" },
     session: { idField: "sessionId", currentId: sessionId("sessionId"), freshOnRestore: true, launchKind: "acp", ...KIMI_RECOVERY_SESSION, crashPlan: kimiCrashPlan },
-    turnEnd: "adapter", budget: { account: "kimi", resetSoftTokensOnResume: true, context: { source: "acp_usage_update", read: acpContextValue } }, capabilities: { watch: true }, init: { mcpFile: ".kimi-code/mcp.json" }, hooks: { recallPlatform: "kimi", recallSource: "kimi" },
+    turnEnd: "adapter", budget: { account: "kimi", resetSoftTokensOnResume: true, context: { source: "acp_usage_update", read: acpContextValue } }, capabilities: { watch: true }, hooks: { recallPlatform: "kimi", recallSource: "kimi" },
     cli: { command: "kimi", launchConfigKeys: ["kimi_cmd", "peers.kimi.start_mode"], stopNotice: form => form === "tui" ? "Kimi belongs to its own TUI terminal; end it in that terminal" : "", startWords: form => ["kimi", "--mode", form] }, display: KIMI_DISPLAY,
   },
   {
     api: 1, kind: "pi", enabledSwitchStartOnly: true, displayName: "Pi", family: "pi", transport: "hub-native",
     roles: implementerRoles, defaultOnRoster: false, trust: { onPrem: false, hubSandboxed: true },
-    start: { create: createPi, exclusiveStartRefusal: "Pi start is in progress; inspect status before retrying", refreshTools: true, explicitHeadlessMode: true, daemonPort: "pi-rpc", forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, launch: ctx => compatibilityLaunch("pi", ctx), conductorStartable: true, autoStart: "pi.auto_start", conductorStartArgs: piConductorStartArgs, hubSwitches: [], ownedFlags: [] },
-    identity: { mcp: "env" },
-    // Existing daemon permission hooks enforce these grants; an empty native mode map is neither unmanaged nor a refusal.
-    permission: { modes: {}, grants: { ...hubGrants } },
+    start: { create: createPi, exclusiveStartRefusal: "Pi start is in progress; inspect status before retrying", refreshTools: true, explicitHeadlessMode: true, daemonPort: "pi-rpc", forms: dualForms, defaultForm: "tui", conductorStartable: true, autoStart: "pi.auto_start", conductorStartArgs: piConductorStartArgs, hubSwitches: [], ownedFlags: [] },
+    identity: { mcp: "env" }, instances: { mode: "headless" },
+    // Approval enforcement belongs to the verified native transport and host permission gate.
+    permission: { grants: { ...hubGrants } },
     session: { idField: "sessionId", currentId: sessionId("sessionId"), restoreOnStart: true, launchKind: "pi", launchRecord: true, ...PI_RECOVERY_SESSION, crashPlan: piCrashPlan, unrecordedTerminal: "tui", continuityBookmark: piRecoveryContinuity, continuity: { key: "pi", parse: parsePiContinuity } },
     turnEnd: "adapter", budget: { account: "pi", instrumented: true }, reporting: { tokensNotReported: true }, configuration: { schema: piConfigSchema, routingSchema: piRoutingSchema, settings: PI_SETTINGS, restartReasons: PI_RESTART_REASONS, validateEffective: piEffectiveConfig },
     routing: { localAllowedRefusal: "local_allowed = false also excludes pi for this class", longContext: "backend-limit", preferredTier: true, handoffPriority: 0, trace: "backend", backendLabel: "pi" },
@@ -133,10 +129,10 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
   {
     api: 1, kind: "local", displayName: "Local worker", family: "local", transport: "hub-native",
     roles: implementerRoles, defaultOnRoster: true, trust: { onPrem: true, hubSandboxed: true },
-    start: { create: createLocal, reconfigureWhileAttached: true, refreshTools: true, daemonPort: "local-worker", forms: headlessForms, defaultForm: "headless", ownsTerminal: headless, launch: ctx => compatibilityLaunch("local", ctx), conductorStartable: true, hubSwitches: [], ownedFlags: [] },
-    identity: { mcp: "env" },
-    // Existing daemon permission hooks enforce these grants; an empty native mode map is neither unmanaged nor a refusal.
-    permission: { modes: {}, grants: { ...hubGrants } },
+    start: { create: createLocal, reconfigureWhileAttached: true, refreshTools: true, daemonPort: "local-worker", forms: headlessForms, defaultForm: "headless", conductorStartable: true, hubSwitches: [], ownedFlags: [] },
+    identity: { mcp: "env" }, instances: { mode: "headless" },
+    // Approval enforcement belongs to the verified native transport and host permission gate.
+    permission: { grants: { ...hubGrants } },
     session: { idField: "sessionId", currentId: sessionId("sessionId"), freshOnRestore: true, launchKind: "local", ...LOCAL_RECOVERY_SESSION, crashPlan: localCrashPlan },
     turnEnd: "adapter", budget: { account: "local", quotaExempt: true, instrumented: true }, configuration: { schema: localConfigSchema, routingSchema: localRoutingSchema, restartReasons: LOCAL_RESTART_REASONS },
     routing: { localAllowedRefusal: "local_allowed = false for this class", longContext: "skip-owner", preferredTier: true, handoffPriority: 1, trace: "route" },
@@ -145,9 +141,9 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
   {
     api: 1, kind: "jcode", displayName: "Jcode", family: "jcode", transport: "acp",
     roles: implementerRoles, optional: true, defaultOnRoster: false, trust: { onPrem: false, hubSandboxed: false },
-    start: { create: createJcode, preflight: jcodeStartPreflight, daemonPort: "owned-acp", forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, explicitHeadlessMode: true, launch: ctx => compatibilityLaunch("jcode", ctx, true), conductorStartable: true, hubSwitches: [], ownedFlags: [] },
+    start: { create: createJcode, preflight: jcodeStartPreflight, daemonPort: "owned-acp", forms: dualForms, defaultForm: "tui", explicitHeadlessMode: true, conductorStartable: true, hubSwitches: [], ownedFlags: [] },
     identity: { mcp: "project-file" },
-    permission: { modes: {}, unmanaged: "Jcode native policy is unmanaged; no hub mode mapping", grants: {
+    permission: { unmanaged: "Jcode native policy is unmanaged; no hub mode mapping", grants: {
       ask: "no verified hub mode mapping; native policy only", "ask-when-needed": "no verified hub mode mapping; native policy only", "never-ask": "no verified hub mode mapping; native policy only" } },
     session: { idField: "sessionId", currentId: sessionId("sessionId"), launchKind: "jcode", ...JCODE_RECOVERY_SESSION, crashPlan: jcodeCrashPlan }, turnEnd: "adapter", budget: { account: "jcode" },
     // Jcode has no dedicated CSS swatch today: retain peer-palette.ts's existing 'other' fallback.
@@ -155,6 +151,14 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
   },
 ] satisfies AdapterDefinition[]);
 
+// Frozen A1 metadata is a compatibility snapshot, not the runtime definition contract.
+export type LegacyAdapterDefinition = AdapterDefinition & {
+  init?: { templateFragment?: string; mcpFile?: string };
+  start: AdapterDefinition["start"] & { ownsTerminal(form: StartForm): boolean; launch(ctx: LaunchContext): LaunchPlan };
+  permission: AdapterDefinition["permission"] & { modes: Partial<Record<PermissionMode, NativeModeSpec>>; readOnly?: NativeModeSpec };
+};
+const terminal = (form: StartForm) => form === "tui";
+const headless = () => false;
 /**
  * ponytail: retain the released A1 metadata export for source/library compatibility until A4 retires it.
  * Core runtime consumers use NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN through the registry exclusively.
@@ -162,7 +166,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
  * resolves to the TUI (#464, #559). Callers of this export must pass `--mode headless` themselves.
  */
 const palette = (fg: string) => ({ palette: { fg, bg: "transparent" } });
-export const BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition[] = Object.freeze([
+export const BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly LegacyAdapterDefinition[] = Object.freeze([
   {
     api: 1, kind: "claude", displayName: "Claude Code", family: "claude", transport: "claude-channel",
     roles: Object.freeze(["planner", "reviewer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
@@ -233,4 +237,4 @@ export const BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition[] = Ob
     // Jcode has no dedicated CSS swatch today: retain peer-palette.ts's existing 'other' fallback.
     cli: { command: "jcode", startWords: () => ["jcode"] }, display: palette("#8a8f99"),
   },
-] satisfies AdapterDefinition[]);
+] satisfies LegacyAdapterDefinition[]);

package/src/adapters/definitions/native-channel-state.ts

@@ -0,0 +1,41 @@
+// No imports: the statusline tee and the CLI load this without the daemon (#450 I3).
+const PEER = /^[a-z][a-z0-9-]{0,31}$/;
+
+/** The peer a Claude process writes for: its AGENTHUB_PEER_ID when well formed, otherwise the builtin claude peer. */
+export function claudePeer(value: string | undefined): string {
+  return value !== undefined && PEER.test(value) ? value : "claude";
+}
+
+// Instance ids are always <kind>-<name>, so a Claude peer is the builtin id or a claude-<name> instance.
+const CLAUDE_PEER = /^claude(?:-[a-z0-9-]+)?$/;
+
+/** Per-peer Claude state file names. The builtin claude peer keeps its original names, so nothing migrates. */
+export function claudeStateFile(base: "claude-launch" | "claude-session" | "claude-context", peer: string): string {
+  // #624: another kind (agy is a hyphen-free builtin too) must never resolve to Claude's own files.
+  if (!CLAUDE_PEER.test(peer) || !PEER.test(peer)) throw new Error(`${peer} is not a Claude peer; Claude state files belong to Claude peers only`);
+  return peer.includes("-") ? `${base}.${peer}.json` : `${base}.json`;
+}
+
+/** A Claude peer's own row in terminal-recovery.json for this daemon, never a sibling instance's (row order is arbitrary). */
+export function ownTerminalRow(records: unknown, peer: string, projectRoot: string, instanceId: string): { launchId?: unknown } | undefined {
+  if (!Array.isArray(records)) return undefined;
+  return records.find((row) => row?.peer === peer && row?.projectRoot === projectRoot && row?.instanceId === instanceId);
+}
+
+/**
+ * Whether a Claude session's transcript exists: the path the peer's own status line reported for that session, else
+ * the builtin's default location. An instance may run under its own CLAUDE_CONFIG_DIR, which the hub cannot see:
+ * without its reported path the answer is unknown, and unknown counts as persisted (it never waives session identity).
+ */
+export function transcriptPersisted(reported: { sessionId?: string; transcriptPath?: string }, sessionId: string, instance: boolean, fallbackPath: string, exists: (path: string) => boolean | "unknown"): boolean {
+  // Only a positive "missing" (ENOENT) is not persisted; an unreadable path is unknown and keeps the identity strict.
+  const found = (path: string) => exists(path) !== false;
+  if (reported.sessionId === sessionId && reported.transcriptPath) return found(reported.transcriptPath);
+  return instance || found(fallbackPath);
+}
+
+/** lstat evidence: true when present, false only on ENOENT/ENOTDIR, "unknown" for any other failure (EACCES included). */
+export function pathEvidence(path: string, lstat: (path: string) => unknown): boolean | "unknown" {
+  try { lstat(path); return true; }
+  catch (error) { const code = (error as { code?: string }).code; return code === "ENOENT" || code === "ENOTDIR" ? false : "unknown"; }
+}

package/src/adapters/definitions/native-cli-entry-kimi.ts

@@ -41,9 +41,11 @@ export async function runKimiEntry(ctx: NativeCliEntryContext): Promise<void> {
       const admission = await hub.request({ t: "start", peer, args: { mode: "tui" }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
       if (!admission.ok) fail(admission.error);
       const runningCommand = admission.retainedLaunchConfig?.kimi_cmd;
-      const launch = buildKimiTuiLaunch(Array.isArray(runningCommand) && runningCommand.every((arg: unknown) => typeof arg === "string") ? runningCommand : projectConfig().kimi_cmd, model);
+      let launch: ReturnType<typeof buildKimiTuiLaunch>;
       let result: ReturnType<typeof spawnSync>;
       try {
+        // Inside the try: a kimi_cmd with no TUI form throws here, and the admission must still be released (#549).
+        launch = buildKimiTuiLaunch(Array.isArray(runningCommand) && runningCommand.every((arg: unknown) => typeof arg === "string") ? runningCommand : projectConfig().kimi_cmd, model);
         // The daemon's own bundle, so the MCP server matches the hub it talks to (#502); this CLI's copy only for an older hub.
         const written = configureKimiMcp(cwd, stateDir, bundleInStatus(snapshot) ?? resolve(cliDir, "../../plugins/agent-hub/server.js"), "tui");
         if (written.tracked) console.error(".kimi-code/mcp.json is tracked; the agent-hub entry contains machine paths. Review this local change before committing it.");

package/src/adapters/definitions/native-cli-preview-qwen.ts

@@ -14,7 +14,7 @@ export function previewQwen(ctx: NativePreviewContext) {
   const sessionId = value("--session-id");
   if (sessionId !== undefined && !adapter.session.crashIdentity?.({ sessionId }).sessionId) throw new Error("invalid Qwen session identity");
   if (sessionId) unresolved.push({ field: "sessionId", reason: "requested through ACP session/load at start; preview does not load or expose it" });
-  launch = adapter.start.launch({ instance: tool, form: "headless", projectRoot: cwd, stateDir, entrypoint: join(cliDir, "main.js"),
+  launch = adapter.start.launch!({ instance: tool, form: "headless", projectRoot: cwd, stateDir, entrypoint: join(cliDir, "main.js"),
     userArgs: [], unattended: false, env: {}, preview: true, nativeCommand: nativeCommand(config.qwen_cmd, ["qwen", "--acp"]), model: model ? REDACTED : undefined });
   unresolved.push({ field: "nativeIdentity", reason: "Qwen Code 0.25.0 identity and permission modes are checked at ACP initialization; preview starts nothing" });
 

package/src/adapters/definitions/native-identity-defaults.ts

@@ -0,0 +1,14 @@
+import type { AdapterDefinition } from "../registry-types.ts";
+
+/** Legacy native shell marker defaults; the host validates markers and conflicts before selection. */
+export function nativeCliMarkerPeer(channel: boolean, appserver: boolean): string | undefined {
+  return channel ? "claude" : appserver ? "codex" : undefined;
+}
+
+/** Historical identity for captures whose host did not supply an agent id. */
+export function defaultCapturePeer(): string { return "local"; }
+
+/** Released recovery receipts retain their native/channel group vocabulary. */
+export function nativeRestoreGroup(transport: AdapterDefinition["transport"] | undefined): "claude" | "native" {
+  return transport === "claude-channel" ? "claude" : "native";
+}

package/src/adapters/definitions/qwen.ts

@@ -2,7 +2,7 @@ import { QWEN_DISPLAY } from "./native-display.ts";
 import { QWEN_RECOVERY_SESSION } from "./native-recovery.ts";
 import { AcpPeer } from "../acp.ts";
 import type { AdapterDefinition } from "../registry-types.ts";
-import { buildQwenLaunch, qwenNativeIdentity, qwenSessionId, QWEN_MODE_IDS } from "./qwen-native.ts";
+import { buildQwenLaunch, qwenSessionId } from "./qwen-native.ts";
 import { shellQuote } from "../../cli/shell-quote.ts";
 
 /** Production Qwen policy. Legacy AcpPeer callers opt in separately through qwen025. */
@@ -20,7 +20,6 @@ export const QWEN_DEFINITION: AdapterDefinition = {
     daemonPort: "acp",
     forms: ["headless"],
     defaultForm: "headless",
-    ownsTerminal: () => false,
     conductorStartable: true,
     hubSwitches: [],
     ownedFlags: [],
@@ -40,12 +39,8 @@ export const QWEN_DEFINITION: AdapterDefinition = {
     conductorStartArgs: args => args.length ? new Error("conductor starts accept no launch overrides; use ahub qwen") : {},
   },
   identity: { mcp: "acp-session" },
+  instances: { mode: "headless" },
   permission: {
-    modes: {
-      ask: { kind: "acp-mode", modeId: QWEN_MODE_IDS.ask },
-      "ask-when-needed": { kind: "acp-mode", modeId: QWEN_MODE_IDS["ask-when-needed"] },
-      "never-ask": { kind: "acp-mode", modeId: QWEN_MODE_IDS["never-ask"] },
-    },
     grants: {
       ask: "every write, edit and shell command asks",
       "ask-when-needed": "Qwen auto-edit approves file edits; shell commands ask; NO hub sandbox",
@@ -71,5 +66,5 @@ export const QWEN_DEFINITION: AdapterDefinition = {
   capabilities: { watch: true },
   cli: { command: "qwen", launchConfigKeys: ["qwen_cmd"], startWords: () => ["qwen"] },
   display: QWEN_DISPLAY,
-  hooks: { agentIdentity: init => { qwenNativeIdentity("qwen", true, init); }, recallPlatform: "qwen" },
+  hooks: { recallPlatform: "qwen" },
 };

package/src/adapters/definitions/reviewer-variants.ts

@@ -6,18 +6,14 @@ import { createReviewer, createCodexReviewer } from "./native-factories.ts";
 import { CODEX_DISPLAY, KIMI_DISPLAY } from "./native-display.ts";
 
 export { claudeReviewerBackend };
-/** No launch path is exposed by metadata-only placeholders. */
-function unavailableLaunch(): never { throw new Error("Reviewer unavailable: verified runtime support is deferred to #533"); }
-
 function reviewerVariant(kind: string, displayName: string, reviewer: NonNullable<AdapterDefinition["reviewer"]>, display: AdapterDefinition["display"]): AdapterDefinition {
   return {
     api: 1, kind, family: kind, displayName, transport: "hub-native", roles: ["reviewer"],
     defaultOnRoster: false, trust: { onPrem: false, hubSandboxed: false },
-    start: { ...(reviewer.backend ? { create: createReviewer, daemonPort: "reviewer-print" as const } : {}), forms: ["headless"], defaultForm: "headless", ownsTerminal: () => false,
-      launch: unavailableLaunch,
+    start: { ...(reviewer.backend ? { create: createReviewer, daemonPort: "reviewer-print" as const } : {}), forms: ["headless"], defaultForm: "headless",
       conductorStartable: true, hubSwitches: [], ownedFlags: [] },
-    identity: { mcp: "env" },
-    permission: { modes: {}, readOnly: { kind: "hub-gate", allow: ["read", "search", "think"] }, unmanaged: "fresh read-only reviewer; an isolation receipt is required before startup" },
+    identity: { mcp: "env" }, instances: { mode: "headless" },
+    permission: { unmanaged: "fresh read-only reviewer; an isolation receipt is required before startup" },
     session: { idField: "sessionId", currentId: () => undefined, freshOnRestore: true, launchKind: "reviewer-print", crashPlan: () => ({ resume: {}, how: "starts a fresh isolated review session" }) },
     turnEnd: "adapter", budget: { account: kind }, routing: { reviewOnly: true },
     reviewer, cli: { command: kind, startWords: () => [] }, display,

package/src/adapters/jcode.ts

@@ -286,3 +286,7 @@ export class JcodePeer extends AcpPeer {
     return { ...super.recoveryMetadata(), launch: { kind: "jcode", peer: "jcode", mode: "headless", ...(this.jcode.launchModel ? { model: this.jcode.launchModel } : {}), ...(this.jcode.providerProfile ? { providerProfile: this.jcode.providerProfile } : {}) } };
   }
 }
+
+export function isJcodePeer(value: unknown): value is JcodePeer {
+  return value instanceof JcodePeer;
+}

package/src/adapters/local-worker.ts

@@ -490,3 +490,7 @@ function safeParse(json: string): Record<string, unknown> {
     return {};
   }
 }
+
+export function isLocalPeer(value: unknown): value is LocalPeer {
+  return value instanceof LocalPeer;
+}

package/src/adapters/pi.ts

@@ -945,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;
+}