@staix/agent-hub 0.12.32 → 0.12.34

package/src/adapters/codex-appserver.ts

@@ -85,8 +85,13 @@ export class CodexPeer extends BasePeer {
   private tokenTotal: number | undefined;
   private freshThread = false;
   private readonly activeTurns = new Set<string>();
+  private deliveryEpoch = 0;
+  /** Cancellation tombstones last until that exact native completion or session replacement. */
+  private readonly retiredTurns = new Set<string>();
+  private unidentifiedCancellation = false;
+  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 }>();
+  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 }>();
   private usageTimer: ReturnType<typeof setInterval> | undefined;
   private injected: Envelope | undefined; // the hub envelope that started the current turn, if any
   private answering: Envelope[] = []; // everything delivered or steered into the current turn: who its answer is for
@@ -189,16 +194,35 @@ export class CodexPeer extends BasePeer {
       return Promise.reject(new Error(`${this.id} is not injectable`));
     }
     const text = this.render(envs);
-    const id = this.nextId--;
+    const id = this.nextId--, epoch = this.deliveryEpoch, session = this.contextEpoch;
     this.setState("busy"); // claim the turn now so the bus stops draining
     return new Promise<void>((resolve, reject) => {
+      let invalidated = false;
+      const retiredAtCancel = new Set<string>();
+      const invalidate = (reason: string) => {
+        if (invalidated) return;
+        invalidated = true;
+        for (const turn of [...this.activeTurns, ...this.turnDeliveries.keys()]) if (!turn.startsWith("unknown:")) retiredAtCancel.add(turn);
+        envs = []; // only the late native-id callback survives, never the cancelled audience/prompt
+        if (deliveryId) this.delivery({ id: deliveryId, state: "needs_review", reason });
+        reject(new Error(reason));
+      };
       this.pending.set(id, {
-        deliveryId, kind: "deliver",
+        deliveryId, kind: "deliver", invalidate,
         resolve: (result) => {
+          const nativeTurn = typeof result?.turn?.id === "string" ? result.turn.id : undefined;
+          if (invalidated || epoch !== this.deliveryEpoch || session !== this.contextEpoch || link !== this.link) {
+            invalidate("Codex turn acceptance arrived after its delivery was invalidated");
+            if (nativeTurn && session === this.contextEpoch && link === this.link &&
+              (!retiredAtCancel.has(nativeTurn) || this.retiredTurns.has(nativeTurn))) this.retireTurn(nativeTurn);
+            return;
+          }
           this.primed = true;
           this.injected = replyParent(envs);
           this.answering = [...envs];
-          const nativeTurn = typeof result?.turn?.id === "string" ? result.turn.id : undefined;
+          // Native acceptance can precede turn/started, also for legacy journal-less callers.
+          if (nativeTurn && !this.turnDeliveries.has(nativeTurn)) this.turnDeliveries.set(nativeTurn, new Set());
+          if (!nativeTurn && !this.activeTurns.size) this.unboundAccepted = true;
           if (deliveryId) {
             if (nativeTurn) this.addTurnDelivery(nativeTurn, deliveryId);
             else this.unboundDeliveries.add(deliveryId);
@@ -208,6 +232,10 @@ export class CodexPeer extends BasePeer {
         },
         reject: (e) => {
           this.restoringApprovals.delete(id);
+          if (invalidated) return; // uncertainty already settled; a late refusal cannot relabel it failed_safe
+          if (epoch !== this.deliveryEpoch || session !== this.contextEpoch || link !== this.link) {
+            invalidate("Codex turn refusal arrived after its delivery was invalidated"); return;
+          }
           if (!this.activeTurns.size) this.setState("idle");
           if (deliveryId) this.delivery({ id: deliveryId, state: this.knownRejection(e) ? "failed_safe" : "needs_review", reason: e.message });
           reject(e);
@@ -298,19 +326,34 @@ export class CodexPeer extends BasePeer {
 
   /** A silent turn is interrupted before the peer is declared idle, or the next turn/start would land inside it. */
   protected override onWatchdog(): void {
-    for (const turnId of this.activeTurns) {
-      if (turnId.startsWith("unknown:")) continue;
-      this.link?.up.send(JSON.stringify({ method: "turn/interrupt", id: this.nextId--, params: { threadId: this.threadId, turnId } }));
+    this.deliveryEpoch++;
+    const known = new Set([...this.activeTurns, ...this.turnDeliveries.keys()].filter(id => !id.startsWith("unknown:")));
+    const pendingStarts = [...this.pending.values()].filter(pending => pending.kind === "deliver");
+    if ([...this.activeTurns].some(id => id.startsWith("unknown:")) || (this.unboundDeliveries.size || this.unboundAccepted || pendingStarts.length) && !known.size) {
+      // 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");
     }
+    for (const turnId of known) this.retireTurn(turnId);
+    for (const pending of pendingStarts) pending.invalidate?.("Codex turn watchdog timeout before native acceptance was confirmed");
     this.activeTurns.clear();
+    this.unboundAccepted = false;
     for (const ids of this.turnDeliveries.values()) for (const id of ids) this.delivery({ id, state: "needs_review", reason: "Codex turn watchdog timeout" });
     for (const id of this.unboundDeliveries) this.delivery({ id, state: "needs_review", reason: "Codex turn watchdog timeout" });
     this.turnDeliveries.clear(); this.unboundDeliveries.clear();
     this.injected = undefined;
     this.answering = [];
     this.lastAnswer = "";
+    this.deltas.clear();
     this.abandonSteers("turn went silent");
-    super.onWatchdog();
+    if (this.unidentifiedCancellation) this.setState("offline");
+    else super.onWatchdog();
+  }
+
+  private retireTurn(turnId: string): void {
+    this.retiredTurns.add(turnId);
+    if (this.link?.up.readyState === WebSocket.OPEN) this.link.up.send(JSON.stringify({ method: "turn/interrupt", id: this.nextId--, params: { threadId: this.threadId, turnId } }));
   }
 
   /** A steer nobody answered must not vanish: rejecting it sends the envelope back to the queue. */
@@ -394,10 +437,13 @@ export class CodexPeer extends BasePeer {
     this.restoringApprovals.clear();
     this.threadId = "";
     this.contextEpoch++;
+    this.deliveryEpoch++;
+    this.retiredTurns.clear(); this.unidentifiedCancellation = false;
     this.activeTurns.clear();
+    this.unboundAccepted = false;
     for (const p of this.pending.values()) {
-      if (p.deliveryId && p.kind !== "steer") this.delivery({ id: p.deliveryId, state: "needs_review", reason: "Codex TUI detached" });
-      p.reject(new Error(p.kind === "steer" ? "Codex TUI detached" : "codex TUI detached"));
+      if (p.kind === "deliver") p.invalidate?.("Codex TUI detached");
+      else p.reject(new Error(p.kind === "steer" ? "Codex TUI detached" : "codex TUI detached"));
     }
     this.pending.clear();
     for (const ids of this.turnDeliveries.values()) for (const id of ids) this.delivery({ id, state: "needs_review", reason: "Codex TUI detached" });
@@ -483,7 +529,8 @@ export class CodexPeer extends BasePeer {
 
   private fromAppServer(link: Link, raw: string): void {
     const msg = parse(raw);
-    if (this.state === "busy") this.touch();
+    const nativeId = msg?.params?.turnId ?? msg?.params?.turn?.id ?? msg?.result?.turn?.id;
+    if (this.state === "busy" && !(typeof nativeId === "string" && this.retiredTurns.has(nativeId))) this.touch();
     if (!msg) return void link.tui.send(raw);
 
     if (msg.id !== undefined && !msg.method) this.settlePermissionRestore(msg.id, !!msg.error);
@@ -511,12 +558,22 @@ export class CodexPeer extends BasePeer {
   private adopt(link: Link, threadId: unknown, fresh = false): void {
     if (typeof threadId !== "string" || !threadId) return;
     this.abandonSteers("thread changed");
+    for (const [id, pending] of this.pending) if (pending.kind === "deliver") {
+      pending.invalidate?.("Codex native thread changed before acceptance was confirmed");
+      this.pending.delete(id); // a replaced session needs no late native-id callback
+    }
+    for (const ids of this.turnDeliveries.values()) for (const id of ids) this.delivery({ id, state: "needs_review", reason: "Codex native thread changed" });
+    for (const id of this.unboundDeliveries) this.delivery({ id, state: "needs_review", reason: "Codex native thread changed" });
+    this.turnDeliveries.clear(); this.unboundDeliveries.clear();
     this.tokenTotal = undefined;
     this.freshThread = fresh;
     this.link = link;
     this.threadId = threadId;
     this.contextEpoch++;
+    this.deliveryEpoch++;
+    this.retiredTurns.clear(); this.unidentifiedCancellation = false;
     this.activeTurns.clear();
+    this.unboundAccepted = false;
     this.forgetTurn();
     this.opts.log?.(`[${this.id}] thread ${threadId}`);
     this.opts.onThread?.(threadId, fresh);
@@ -560,6 +617,13 @@ export class CodexPeer extends BasePeer {
       this.opts.onUsage?.({ rateLimitReachedType: "usageLimitExceeded" }, true);
     }
     if (link !== this.link || params.threadId !== this.threadId) return;
+    const nativeId = method === "turn/started" || method === "turn/completed" ? params.turn?.id : params.turnId;
+    if (typeof nativeId === "string" && this.retiredTurns.has(nativeId)) {
+      if (method === "turn/completed") this.retiredTurns.delete(nativeId);
+      return;
+    }
+    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 total = Number(params.tokenUsage?.total?.totalTokens);
@@ -571,22 +635,26 @@ export class CodexPeer extends BasePeer {
     }
     if (method === "turn/started") {
       const nativeTurn = params.turn?.id ?? `unknown:${Date.now()}`;
+      this.unboundAccepted = false;
       this.activeTurns.add(nativeTurn);
       for (const id of [...this.unboundDeliveries]) this.addTurnDelivery(nativeTurn, id);
       this.lastAnswer = "";
       this.setState("busy");
       if (params.turn?.id) this.opts.onTurn?.(params.turn.id);
     } else if (method === "item/agentMessage/delta") {
+      if (!this.activeTurns.size || typeof params.turnId === "string" && !this.activeTurns.has(params.turnId) && !unknownTurn()) return;
       const buf = this.deltas.get(params.itemId) ?? [];
       buf.push(params.delta);
       this.deltas.set(params.itemId, buf);
     } else if (method === "item/completed" && ["fileChange", "commandExecution", "mcpToolCall", "userMessage"].includes(params.item?.type)) {
+      if (typeof params.turnId === "string" && !this.activeTurns.has(params.turnId) && !unknownTurn()) return;
       try {
         this.opts.onItem?.(params.item, typeof params.turnId === "string" && this.activeTurns.has(params.turnId) ? params.turnId : undefined);
       } catch (error) {
         this.opts.log?.(`[${this.id}] item handler failed: ${(error as Error).message}`); // the proxy keeps going
       }
     } else if (method === "item/completed" && params.item?.type === "agentMessage") {
+      if (!this.activeTurns.size || typeof params.turnId === "string" && !this.activeTurns.has(params.turnId) && !unknownTurn()) return;
       const item = params.item;
       const text: string =
         item.text ?? item.content?.map((c: any) => c.text ?? "").join("") ?? this.deltas.get(item.id)?.join("") ?? "";
@@ -595,6 +663,8 @@ export class CodexPeer extends BasePeer {
       if (item.phase !== "commentary" && text.trim()) this.lastAnswer = text.trim();
     } else if (method === "turn/completed") {
       const nativeTurn = params.turn?.id;
+      // A watchdog or a newer turn has invalidated this completion. Unknown-id legacy starts retain their fallback.
+      if (!this.activeTurns.size || typeof nativeTurn === "string" && !this.activeTurns.has(nativeTurn) && ![...this.activeTurns].some(id => id.startsWith("unknown:"))) return;
       this.activeTurns.delete(nativeTurn);
       for (const id of this.activeTurns) if (id.startsWith("unknown:")) this.activeTurns.delete(id);
       if (params.turn?.status === "failed") {

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

@@ -1,12 +1,25 @@
+import { kimiAcpCommand } from "./native-daemon-kimi.ts";
+import { claudeRecoveryLaunch, kimiRecoveryLaunch, claudeRetainedTerminalNotice, piRetainedTerminalNotice, codexRetainedTerminalNotice, codexRosterReturnNotice, jcodeStartPreflight, claudeObservedVersion, codexObservedVersion } from "./native-daemon-policy.ts";
+import { piConfigSchema, localConfigSchema, piRoutingSchema, localRoutingSchema, PI_SETTINGS, PI_RESTART_REASONS, LOCAL_RESTART_REASONS, piEffectiveConfig } from "./native-config-policy.ts";
+import { claudeCrashPlan, codexCrashPlan, kimiCrashPlan, piCrashPlan, localCrashPlan, jcodeCrashPlan, claudePluginInventory, codexPluginInventory, parsePiContinuity, codexToolSemantic } from "./native-policy-aux.ts";
+import { piRecoveryContinuity } from "./native-recovery-continuity.ts";
+import { piConductorStartArgs } from "./native-cli-pi.ts";
+import { claudeNativeLaunch, CLAUDE_LAUNCH_POLICY } from "./native-cli-claude-launch.ts";
+import { codexNativeLaunch, CODEX_LAUNCH_POLICY } from "./native-cli-codex-launch.ts";
+import { createCodex, createKimi, createJcode, createPi, createLocal } from "./native-factories.ts";
+import { CLAUDE_DISPLAY, CODEX_DISPLAY, KIMI_DISPLAY, PI_DISPLAY, LOCAL_DISPLAY, JCODE_DISPLAY } from "./native-display.ts";
+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 { PeerAdapter } from "../../hub/peers.ts";
-import { shellQuote } from "../../cli/terminal-recovery.ts";
+import { shellQuote } from "../../cli/shell-quote.ts";
 
 type CompatibilityKind = "claude" | "codex" | "kimi" | "pi" | "local" | "jcode";
 
 /**
- * ponytail: A1 compatibility definitions delegate to the existing CLI; the existing daemon remains their runtime
- * authority until A2 migrates each native path. These launch methods are not a second native launcher or factory.
+ * Preserve CLI-wrapper argv plans for definitions that still declare them and the frozen A1 compatibility export.
+ * Native startup and daemon factories are supplied separately by the runtime definitions.
  */
 function compatibilityLaunch(kind: CompatibilityKind, ctx: LaunchContext): LaunchPlan {
   const mode = kind === "kimi" || kind === "pi" ? ["--mode", ctx.form] : [];
@@ -35,7 +48,6 @@ const switches = Object.freeze(["--unattended", "--safe", "--new"]);
 const implementerRoles = Object.freeze(["implementer", "verifier"]);
 const dualForms = Object.freeze(["tui", "headless"] as const);
 const headlessForms = Object.freeze(["headless"] as const);
-const palette = (fg: string) => ({ palette: { fg, bg: "transparent" } });
 const hubGrants = {
   ask: "every write, edit and shell command asks",
   "ask-when-needed": "write and edit inside the project run without asking; shell and git writes still ask",
@@ -44,6 +56,91 @@ const hubGrants = {
 
 // Sources: peer-catalog.ts roles, roster.ts defaults, start-mode.ts forms, permission-mode.ts grants,
 // daemon.ts runtime mappings/stop policy, budget.ts exemptions, and ui/peer-palette.ts CSS foregrounds.
+export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition[] = 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 },
+    start: { forms: Object.freeze(["tui"] as const), defaultForm: "tui", ownsTerminal: terminal, 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",
+      "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" },
+    turnEnd: "native-hook", budget: { account: "claude", checkpoint: true, reader: { source: "claude status line", read: claudeWindows }, context: { source: "claude_statusline", read: claudeContext } },
+    cli: { command: "claude", retainedTerminalNotice: claudeRetainedTerminalNotice, stopNotice: () => "this peer belongs to a native terminal; end it in its terminal", startWords: () => ["claude"] }, display: CLAUDE_DISPLAY, hooks: { recallPlatform: "claude", recallSource: "claude", recallInjected: true, pluginInventory: claudePluginInventory },
+  },
+  {
+    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,
+      unattended: true, hubSwitches: switches, ownedFlags: Object.freeze(["--remote", "--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" } },
+    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", 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 },
+  },
+  {
+    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: [] },
+    // 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,
+      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" },
+      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" },
+    cli: { command: "kimi", 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 } },
+    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" },
+    cli: { command: "pi", previewArgs: ["--mode", "tui"], retainedTerminalNotice: piRetainedTerminalNotice, personOnlyFlags: ["--replace-session"], startWords: form => ["pi", "--mode", form] }, display: PI_DISPLAY,
+  },
+  {
+    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 } },
+    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" },
+    cli: { command: "local", startWords: () => ["local"] }, display: LOCAL_DISPLAY,
+  },
+  {
+    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: headlessForms, defaultForm: "headless", ownsTerminal: headless, launch: ctx => compatibilityLaunch("jcode", ctx), conductorStartable: true, hubSwitches: [], ownedFlags: [] },
+    identity: { mcp: "project-file" },
+    permission: { modes: {}, 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.
+    cli: { command: "jcode", authority: "person", startWords: () => ["jcode"] }, display: JCODE_DISPLAY, hooks: { recallPlatform: "jcode" },
+  },
+] satisfies AdapterDefinition[]);
+
+/**
+ * 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.
+ */
+const palette = (fg: string) => ({ palette: { fg, bg: "transparent" } });
 export const BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition[] = Object.freeze([
   {
     api: 1, kind: "claude", displayName: "Claude Code", family: "claude", transport: "claude-channel",
@@ -51,7 +148,6 @@ export const BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition[] = Ob
     start: { forms: Object.freeze(["tui"] as const), defaultForm: "tui", ownsTerminal: terminal, launch: ctx => compatibilityLaunch("claude", ctx), conductorStartable: true,
       unattended: true, hubSwitches: switches, ownedFlags: Object.freeze(["--dangerously-load-development-channels", "--dangerously-skip-permissions"]) },
     identity: { mcp: "channel-plugin" },
-    // ponytail: A1 compatibility, existing daemon permission hooks remain authority until A2; absence is not unmanaged or a refusal.
     permission: { modes: {}, 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" } },
@@ -90,7 +186,6 @@ export const BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition[] = Ob
     roles: implementerRoles, defaultOnRoster: false, trust: { onPrem: false, hubSandboxed: true },
     start: { forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, launch: ctx => compatibilityLaunch("pi", ctx), conductorStartable: true, autoStart: "pi.auto_start", hubSwitches: [], ownedFlags: [] },
     identity: { mcp: "env" },
-    // ponytail: A1 compatibility, existing daemon permission hooks remain authority until A2; absence is not unmanaged or a refusal.
     permission: { modes: {}, grants: { ...hubGrants } },
     session: { idField: "sessionId", currentId: sessionId("sessionId"), launchKind: "pi", launchRecord: true },
     turnEnd: "adapter", budget: { account: "pi" },
@@ -101,7 +196,6 @@ export const BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition[] = Ob
     roles: implementerRoles, defaultOnRoster: true, trust: { onPrem: true, hubSandboxed: true },
     start: { forms: headlessForms, defaultForm: "headless", ownsTerminal: headless, launch: ctx => compatibilityLaunch("local", ctx), conductorStartable: true, hubSwitches: [], ownedFlags: [] },
     identity: { mcp: "env" },
-    // ponytail: A1 compatibility, existing daemon permission hooks remain authority until A2; absence is not unmanaged or a refusal.
     permission: { modes: {}, grants: { ...hubGrants } },
     session: { idField: "sessionId", currentId: sessionId("sessionId"), freshOnRestore: true, launchKind: "local" },
     turnEnd: "adapter",

package/src/adapters/definitions/native-cli-claude-launch.ts

@@ -0,0 +1,90 @@
+import { mkdirSync, writeFileSync, renameSync, unlinkSync, readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { resolve, join } from "node:path";
+import { CLAUDE_CHANNEL, sessionSettings, UNATTENDED_WARNING, type Launch } from "../../cli/launch.ts";
+import type { LaunchContext, LaunchPlan } from "../registry-types.ts";
+import { nativeLaunchArguments, nativeLaunchPlan } from "./native-cli-launch-common.ts";
+
+export const CLAUDE_LAUNCH_POLICY = Object.freeze({ hubSwitches: Object.freeze(["--unattended", "--safe", "--new"]), ownedFlags: Object.freeze(["--dangerously-load-development-channels", "--dangerously-skip-permissions"]), unattended: true, passthrough: true });
+
+function claudeChannel(userArgs: string[]): string {
+  const bundle = resolve(import.meta.dir, "../../../plugins/agent-hub/server.js");
+  for (let i = 0; i < userArgs.length; i++) {
+    const arg = userArgs[i]!;
+    const path = arg === "--mcp-config" ? userArgs[i + 1] : arg.startsWith("--mcp-config=") ? arg.slice("--mcp-config=".length) : undefined;
+    if (!path) continue;
+    try {
+      const server = JSON.parse(readFileSync(resolve(path), "utf8")).mcpServers?.["agent-hub"];
+      if (server?.command === "bun" && Array.isArray(server.args) && server.args.some((value: unknown) => typeof value === "string" && resolve(value) === bundle)) return "server:agent-hub";
+    } catch { /* The native CLI reports invalid user-supplied MCP configuration. */ }
+  }
+  return CLAUDE_CHANNEL;
+}
+
+export function claudeNativeLaunch(ctx: LaunchContext): LaunchPlan {
+  const { passthrough, unattended } = nativeLaunchArguments("claude", ctx, CLAUDE_LAUNCH_POLICY);
+  const build = (): Launch => {
+    // `--settings` takes one value, so a user-supplied one wins and Claude has no quota source for that session.
+    const own = passthrough.some((a) => a === "--settings" || a.startsWith("--settings="));
+    let settingsArgs = ctx.statusLine && !own ? ["--settings", sessionSettings(ctx.statusLine, ctx.facts)] : [];
+    let nativeArgs = passthrough;
+    let settingsFile: string | undefined;
+    if (own) {
+      if (passthrough.filter(a => a === "--settings" || a.startsWith("--settings=")).length > 1) throw new Error("pass --settings only once so the hub permission hook stays installed");
+      const index = passthrough.findIndex(a => a === "--settings" || a.startsWith("--settings="));
+      const arg = passthrough[index]!;
+      const value = arg === "--settings" ? passthrough[index + 1] : arg.slice("--settings=".length);
+      if (!value) throw new Error("--settings requires a JSON object or readable file so the hub permission hook can be installed");
+      let caller: Record<string, unknown>;
+      try {
+        caller = JSON.parse(value.trim().startsWith("{") ? value : readFileSync(resolve(value), "utf8"));
+        if (!caller || typeof caller !== "object" || Array.isArray(caller)) throw new Error("not an object");
+      } catch { throw new Error("cannot read --settings as a JSON object; the hub permission hook must be installed"); }
+      if (ctx.facts && caller.disableAllHooks === true) throw new Error("--settings disableAllHooks prevents the required hub permission hook; enable hooks to launch");
+      const injected = JSON.parse(sessionSettings(undefined, ctx.facts));
+      const callerHooks = caller.hooks;
+      if (callerHooks !== undefined && (!callerHooks || typeof callerHooks !== "object" || Array.isArray(callerHooks))) throw new Error("--settings hooks must be an object");
+      const hooks = { ...(callerHooks as Record<string, unknown> | undefined) };
+      for (const [event, entries] of Object.entries(injected.hooks ?? {})) {
+        const existing = hooks[event];
+        if (existing !== undefined && !Array.isArray(existing)) throw new Error(`--settings ${event} hooks must be an array`);
+        hooks[event] = [...(existing as unknown[] | undefined ?? []), ...(entries as unknown[])];
+      }
+      settingsArgs = ["--settings", JSON.stringify({ ...caller, ...(ctx.facts ? { hooks } : {}) })];
+      nativeArgs = passthrough.filter((_, i) => i !== index && (arg !== "--settings" || i !== index + 1));
+    } else if (ctx.facts && !ctx.statusLine) {
+      const injected = JSON.parse(sessionSettings(undefined, ctx.facts));
+      settingsArgs = ["--settings", JSON.stringify({ hooks: injected.hooks })];
+    }
+    if (settingsArgs.length && !ctx.preview) {
+      const stateDir = ctx.facts?.stateDir ?? ctx.statusLine?.stateDir;
+      if (!stateDir) throw new Error("Claude session settings require the hub state directory");
+      const file = join(stateDir, `claude-settings-${randomUUID()}.json`);
+      try {
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        writeFileSync(`${file}.tmp`, settingsArgs[1]!, { mode: 0o600, flag: "wx" });
+        renameSync(`${file}.tmp`, file);
+      } catch {
+        try { unlinkSync(`${file}.tmp`); } catch { /* no temp file was written */ }
+        throw new Error("cannot write private Claude session settings in the hub state directory");
+      }
+      settingsArgs[1] = file;
+      settingsFile = file;
+    }
+    const notes = [
+      unattended ? UNATTENDED_WARNING : "",
+      ctx.statusLine && own ? "note: you passed --settings, so the hub's status line tee is off and the budget coordinator cannot see Claude's quota (ahub budget set claude <0..1> still works)." : "",
+    ].filter(Boolean);
+    return {
+      cmd: "claude",
+      args: ["--dangerously-load-development-channels", claudeChannel(passthrough), ...(unattended ? ["--dangerously-skip-permissions"] : []), ...settingsArgs, ...nativeArgs],
+      ...(settingsFile ? { settingsFile } : {}),
+      permissionHook: !!ctx.facts,
+      ...(ctx.facts ? { hookPurpose: ctx.facts.purpose ?? "facts" } : {}),
+      unattended,
+      ...(notes.length ? { warning: notes.join("\n") } : {}),
+    };
+
+  };
+  return nativeLaunchPlan(build(), ctx);
+}

package/src/adapters/definitions/native-cli-claude-setup.ts

@@ -0,0 +1,80 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { realPath } from "../../hub/project.ts";
+import { VERSION } from "../../version.ts";
+
+export const PLUGIN = "agent-hub@agent-hub";
+const MARKETPLACE = "agent-hub";
+
+export interface InstalledPlugin {
+  id: string;
+  version?: string;
+  installPath?: string;
+}
+export interface Marketplace {
+  name: string;
+  path?: string;
+}
+
+/** `claude plugin list --json` / `claude plugin marketplace list --json`. Anything that does not parse is an empty list. */
+export function parseList<T>(json: string): T[] {
+  try {
+    const d = JSON.parse(json);
+    return Array.isArray(d) ? d : [];
+  } catch {
+    return [];
+  }
+}
+
+const real = (p: string) => {
+  try {
+    return realPath(p);
+  } catch {
+    return p;
+  }
+};
+const read = (p: string) => {
+  try {
+    return readFileSync(p, "utf8");
+  } catch {
+    return undefined;
+  }
+};
+
+export type PluginState = { state: "missing" } | { state: "current"; version: string } | { state: "stale"; version: string; why: string };
+
+/**
+ * Is the installed Claude plugin the one this hub ships? The version is compared, and so is the bundle itself: Claude
+ * Code runs a cached copy, and a copy taken from an earlier build of the same version speaks an older wire protocol.
+ */
+export function pluginState(plugins: InstalledPlugin[], packageRoot: string): PluginState {
+  const mine = plugins.find((p) => p.id === PLUGIN);
+  if (!mine) return { state: "missing" };
+  const version = mine.version ?? "unknown";
+  if (version !== VERSION) return { state: "stale", version, why: `version ${version}, this hub is ${VERSION}` };
+  const shipped = read(join(packageRoot, "plugins", "agent-hub", "server.js"));
+  const cached = mine.installPath ? read(join(mine.installPath, "server.js")) : undefined;
+  if (shipped !== undefined && cached !== undefined && shipped !== cached) return { state: "stale", version, why: "same version, but the cached bundle differs from the one this hub ships" };
+  return { state: "current", version };
+}
+
+export interface SetupStep {
+  why: string;
+  argv: string[];
+}
+
+/**
+ * The next thing `ahub setup` has to do, or nothing. One step at a time: the state is read again after every step,
+ * because what a step leaves behind is Claude Code's business (removing a marketplace may uninstall its plugins).
+ */
+export function nextStep(plugins: InstalledPlugin[], marketplaces: Marketplace[], packageRoot: string): SetupStep | undefined {
+  const root = real(packageRoot);
+  const market = marketplaces.find((m) => m.name === MARKETPLACE);
+  if (market && real(market.path ?? "") !== root) return { why: `the ${MARKETPLACE} marketplace points at ${market.path ?? "another source"}, not at this package`, argv: ["claude", "plugin", "marketplace", "remove", MARKETPLACE] };
+  if (!market) return { why: "register this package as a Claude Code plugin marketplace", argv: ["claude", "plugin", "marketplace", "add", root] };
+  const state = pluginState(plugins, root);
+  if (state.state === "missing") return { why: "install the channel plugin", argv: ["claude", "plugin", "install", PLUGIN] };
+  // Uninstall rather than update: with an unchanged version number an update has nothing to do.
+  if (state.state === "stale") return { why: `replace the installed plugin (${state.why})`, argv: ["claude", "plugin", "uninstall", PLUGIN] };
+  return undefined;
+}

package/src/adapters/definitions/native-cli-codex-launch.ts

@@ -0,0 +1,14 @@
+import type { LaunchContext, LaunchPlan } from "../registry-types.ts";
+import { nativeLaunchArguments, nativeLaunchPlan } from "./native-cli-launch-common.ts";
+
+export const CODEX_LAUNCH_POLICY = Object.freeze({ hubSwitches: Object.freeze(["--unattended", "--safe", "--new"]), ownedFlags: Object.freeze(["--remote", "--yolo", "--dangerously-bypass-approvals-and-sandbox"]), unattended: true, passthrough: true });
+export function codexNativeLaunch(ctx: LaunchContext): LaunchPlan {
+  const { passthrough, unattended, warning } = nativeLaunchArguments("codex", ctx, CODEX_LAUNCH_POLICY);
+  if (!ctx.proxyUrl) throw new Error("codex proxy url is missing");
+  return nativeLaunchPlan({
+    cmd: ctx.codexBin ?? "codex",
+    args: ["--enable", "tui_app_server", "--remote", ctx.proxyUrl, ...(unattended ? ["--dangerously-bypass-approvals-and-sandbox"] : []), ...passthrough],
+    unattended,
+    ...warning,
+  }, ctx);
+}

package/src/adapters/definitions/native-cli-doctor.ts

@@ -0,0 +1,46 @@
+import type { DoctorCheck } from "../../cli/output.ts";
+
+// Fixed builtin doctor policy only. These projections neither execute probes nor extend AdapterDefinition.
+const nativeTools = [
+  { id: "claude", initial: true }, { id: "codex", initial: true }, { id: "kimi", initial: true },
+  { id: "qwen", initial: false }, { id: "jcode", initial: false },
+] as const;
+export const DOCTOR_TOOL_PROBES: readonly string[] = Object.freeze(["bun", ...nativeTools.filter(tool => tool.initial).map(tool => tool.id)]);
+export const DOCTOR_MEMORY_CAPTURE_PEERS = Object.freeze(["codex", "kimi"] as const);
+export const DOCTOR_PLUGIN_PROBE = Object.freeze({ command: "claude", argv: Object.freeze(["plugin", "list", "--json"] as const), name: "claude plugin" });
+
+/** Exact legacy section and severity classification, including non-native and unknown diagnostic names. */
+export function nativeDoctorCheck(ok: boolean | undefined, name: string, detail: string): DoctorCheck {
+  const nativeTool = nativeTools.some(tool => tool.id === name);
+  const section: DoctorCheck["section"] = name === "bun" || nativeTool ? "Tools"
+    : name === "config" || name === "retired setting" ? "Config"
+    : name.startsWith("memory") ? "Memory"
+    : ["omniroute", "omniroute key", "local fixed_model", "switchyard", "pi mlx"].includes(name) ? "Models" : "Hub";
+  const optional = nativeTool || ["ahub daemon", "switchyard", "pi mlx"].includes(name) || section === "Memory";
+  const level: DoctorCheck["level"] = ok === undefined ? (["switchyard", "omniroute"].includes(name) ? "warn" : "unknown") : ok ? "ok" : optional ? "warn" : "fail";
+  return { section, level, name, detail };
+}
+
+/** Recovery IDs are checked only for the two legacy native conversation surfaces. */
+export function nativeDoctorRecoveryIdentity(peer: { id: string; state: string; sessionId?: string; threadId?: string }): { ok: boolean; name: string; detail: string } | undefined {
+  const fields = { claude: "sessionId", codex: "threadId" } as const;
+  const field = Object.hasOwn(fields, peer.id) ? fields[peer.id as keyof typeof fields] : undefined;
+  if (!field || peer.state === "offline") return undefined;
+  const identity = peer[field];
+  return { ok: !!identity, name: `${peer.id} recovery ID`, detail: identity ? "recorded" : `missing; verify the current conversation and reconnect with ahub ${peer.id} before upgrading` };
+}
+
+export type NativeDoctorOptionalProbe =
+  | { kind: "source-identity"; name: string; command: string[]; detail: string }
+  | { kind: "pinned-version"; name: string; command: string[]; expected: string; confirmed: string; unconfirmed: string };
+
+/** The host runs these existing checks in order; no process, filesystem or caller callback enters this planner. */
+export function nativeDoctorOptionalProbes(config: { roster: Readonly<Record<string, boolean | undefined>>; jcode_cmd: string[]; qwen_cmd: string[] }): NativeDoctorOptionalProbe[] {
+  const probes: NativeDoctorOptionalProbe[] = [];
+  if (config.roster.jcode === true) probes.push({ kind: "source-identity", name: "jcode", command: config.jcode_cmd,
+    detail: "CLI/source identity only; provider, project MCP and native teardown require separate receipts; native policy unmanaged" });
+  if (config.roster.qwen === true) probes.push({ kind: "pinned-version", name: "qwen", command: config.qwen_cmd, expected: "0.25.0",
+    confirmed: "CLI reports 0.25.0; native ACP identity/modes and provider access require a separate live check",
+    unconfirmed: "Qwen Code 0.25.0 executable not confirmed; provider and ACP readiness unknown" });
+  return probes;
+}