@staix/agent-hub 0.12.38 → 0.12.40

package/src/adapters/acp.ts

@@ -79,6 +79,8 @@ export interface AcpOptions {
   /** Optional launch environment; recovery authority is always removed before spawn. */
   env?: NodeJS.ProcessEnv;
   watchdogMs?: number;
+  /** #542 D4: how long an open tool call keeps a silent turn alive; defaults to 30 minutes, never below the watchdog. */
+  toolCeilingMs?: number;
   /** Bound for a journal-less watchdog cancellation to report its prompt; defaults to the 30 s ACP handshake cap. */
   cancelWaitMs?: number;
   /** ACP stdio MCP servers for the session (the hub's task tools). */
@@ -108,6 +110,7 @@ export interface AcpOptions {
 const HANDSHAKE_MS = 30_000;
 /** Tool calls whose arguments are remembered until their permission request arrives. */
 const TOOL_INPUT_CAP = 64;
+const TOOL_CEILING_MS = 30 * 60_000;
 
 /**
  * The canonical tool binding (#138): an announced `<tool> (<server> MCP Server)` title resolves to
@@ -148,12 +151,17 @@ export class AcpPeer extends BasePeer {
   private readonly toolInputs = new Map<string, unknown>();
   private readonly toolText = new Map<string, string>(); // streamed argument text, per call, until it finishes
   private readonly toolTitles = new Map<string, string>(); // the title a call was announced with, per call id (#138)
+  private readonly openTools = new Map<string, string>(); // this turn's started, unfinished tool calls (#542 D4)
+  private lastSignAt = 0;
   private primed = false;
   private turn = 0; // generation: a prompt cancelled by the watchdog must not touch the turn that followed it
   private stopping = false;
   private activeDeliveryId: string | undefined;
   private activeLegacy: { turn: number; envs: Envelope[] } | undefined;
   private deliveryAccepted = false;
+  /** What the running turn answers: its delivery plus whatever the transport took into it mid-turn (#572). */
+  private turnEnvs: Envelope[] = [];
+  private steerIds: string[] = [];
   private cancelWait: { turn: number; successor: number; timer: ReturnType<typeof setTimeout>; reported: boolean; released: Promise<void>; release: () => void } | undefined;
   private promptActivity = false;
   private activityOpen = false;
@@ -319,6 +327,7 @@ export class AcpPeer extends BasePeer {
     if (legacy?.turn === this.turn) this.onFailed?.(legacy.envs);
     if (reason !== undefined) this.turn++; // a requested stop cannot escalate or complete the cancelled turn
     if (this.activeDeliveryId) this.delivery({ id: this.activeDeliveryId, state: "needs_review", reason: reason ?? "ACP session stopped before settlement" });
+    this.settleSteers("needs_review", reason ?? "ACP session stopped before settlement");
     this.activeDeliveryId = undefined;
     const proc = this.proc;
     if (!proc) { this.setState("offline"); return; }
@@ -336,9 +345,11 @@ export class AcpPeer extends BasePeer {
     const turn = ++this.turn;
     this.activeDeliveryId = deliveryId;
     this.activeLegacy = deliveryId ? undefined : { turn, envs };
+    this.turnEnvs = envs; this.steerIds = [];
     this.deliveryAccepted = false;
     this.promptActivity = false;
     this.chunks = [];
+    this.openTools.clear();
     this.activityOpen = true;
     this.activityPrivate = envs.some(env => env.private === true);
     try { this.activityPrivate ||= this.opts.isPrivateTurn?.() === true; } catch { this.activityPrivate = true; }
@@ -360,13 +371,16 @@ export class AcpPeer extends BasePeer {
         this.observeUsage(result, "prompt_result");
         this.primed = true;
         const body = this.chunks.join("").trim();
-        if (body) this.onMessage?.(body, { inReplyTo: replyParent(envs), to: replyAudience(envs) });
+        // What was steered into the turn is answered by it too: its senders hear back, and the hop cap still holds.
+        const answering = this.turnEnvs.length ? this.turnEnvs : envs;
+        if (body) this.onMessage?.(body, { inReplyTo: replyParent(answering), to: replyAudience(answering) });
         // Partial output cannot certify normal completion (#160).
         if (result?.stopReason !== "end_turn") this.reportTurnFailure(envs, `ACP prompt ended without normal completion (${String(result?.stopReason ?? "unknown")})`);
         if (deliveryId && this.activeDeliveryId === deliveryId) {
           this.acceptDelivery();
           this.delivery({ id: deliveryId, state: result?.stopReason === "end_turn" ? "completed" : "needs_review", ...(result?.stopReason === "end_turn" ? {} : { reason: "ACP prompt ended without normal completion" }) });
         }
+        this.settleSteers(result?.stopReason === "end_turn" ? "completed" : "needs_review", "ACP prompt ended without normal completion");
       })
       .catch((e: Error) => {
         if (turn !== this.turn) {
@@ -375,6 +389,7 @@ export class AcpPeer extends BasePeer {
         }
         this.endActivity("failed", true);
         const reason = sanitize(e.message);
+        this.settleSteers("needs_review", reason);
         this.opts.log?.(`[${this.id}] prompt failed: ${reason}`);
         const quota = !this.stopping && this.kimiAgent ? acpQuotaRefusal(e.message) : undefined;
         if (quota) {
@@ -415,12 +430,23 @@ export class AcpPeer extends BasePeer {
   protected override onWatchdog(): void {
     if (this.state !== "busy") return;
     if (this.cancelWait) { this.clearWatchdog(); return; }
+    // #542 D4: a tool call that started and has not finished is running, not silent, up to its own ceiling.
+    if (this.openTools.size) {
+      const ceiling = Math.max(this.watchdogMs, this.opts.toolCeilingMs ?? TOOL_CEILING_MS);
+      const remaining = ceiling - (Date.now() - this.lastSignAt);
+      if (remaining > 0) { this.touch(Math.min(this.watchdogMs, remaining)); return; }
+      // Privacy latches for the turn and fails closed, as in emitActivity; the title is agent-written, so one quoted line.
+      try { this.activityPrivate ||= this.opts.isPrivateTurn?.() === true; } catch { this.activityPrivate = true; }
+      const tools = this.activityPrivate ? "a tool call" : [...new Set(this.openTools.values())].map(title => JSON.stringify(activityText(title).replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, " ").slice(0, 80))).join(", ");
+      this.opts.log?.(`[${this.id}] open tool call (${tools}) silent past the ${Math.round(ceiling / 60_000)} min tool ceiling; cancelling the turn`);
+    }
     this.endActivity("watchdog cancelled", true);
     const cancelledTurn = this.turn;
     this.cancelPermissions();
     this.activeLegacy = undefined; // the cancelled prompt is discarded, never returned by a later stop
     const durable = !!this.activeDeliveryId;
     if (this.activeDeliveryId) this.delivery({ id: this.activeDeliveryId, state: "needs_review", reason: "ACP turn watchdog timeout" });
+    this.settleSteers("needs_review", "ACP turn watchdog timeout");
     this.activeDeliveryId = undefined;
     this.notify("session/cancel", { sessionId: this.sessionId });
     this.turn++; // whatever the cancelled prompt still reports is stale
@@ -458,6 +484,28 @@ export class AcpPeer extends BasePeer {
     if (observation.availability === "known") this.opts.onTokens?.(observation.total!, this.sessionId);
   }
 
+  /** The running turn's generation, for a transport that must adopt into exactly this turn after an async step (#572). */
+  protected currentTurn(): number { return this.turn; }
+
+  /**
+   * A transport that took envelopes into the running turn (#572) reports them here, once it has acknowledged them. The
+   * turn now answers their senders too, and their receipts settle with the turn: completed on a normal end, held for
+   * review on anything else. Only the busy turn the caller named (`currentTurn()` before sending) can adopt.
+   */
+  protected adoptIntoTurn(turn: number, envs: Envelope[], deliveryId?: string): void {
+    // Fenced to the exact turn the caller saw before it sent anything: a later turn on the same session is never adopted into.
+    if (turn !== this.turn || this.state !== "busy" || this.cancelWait || this.stopping) throw new Error(`${this.id} is ${this.state}, or its turn changed`);
+    this.turnEnvs = [...this.turnEnvs, ...envs];
+    this.activityPrivate ||= envs.some(env => env.private === true);
+    this.primed = true;
+    if (deliveryId) { this.steerIds.push(deliveryId); this.delivery({ id: deliveryId, state: "accepted" }); }
+  }
+
+  private settleSteers(state: "completed" | "needs_review", reason?: string): void {
+    const ids = this.steerIds; this.steerIds = [];
+    for (const id of ids) this.delivery({ id, state, ...(state === "needs_review" ? { reason: reason ?? "steered turn did not complete normally" } : {}) });
+  }
+
   private acceptDelivery(): void {
     if (!this.activeDeliveryId || this.deliveryAccepted) return;
     this.deliveryAccepted = true;
@@ -470,6 +518,7 @@ export class AcpPeer extends BasePeer {
     for (const p of this.pending.values()) p.reject(new Error(reason));
     this.pending.clear();
     if (this.activeDeliveryId) this.delivery({ id: this.activeDeliveryId, state: "needs_review", reason });
+    this.settleSteers("needs_review", reason);
     this.activeDeliveryId = undefined;
     this.setState("offline");
   }
@@ -482,7 +531,7 @@ export class AcpPeer extends BasePeer {
     } catch {
       return; // not protocol output
     }
-    if (this.state === "busy" && !this.cancelWait) this.touch();
+    if (this.state === "busy" && !this.cancelWait) { this.lastSignAt = Date.now(); this.touch(); }
 
     if (msg.method === "session/update") {
       if (msg.params?.sessionId && msg.params.sessionId !== this.sessionId) return;
@@ -517,7 +566,9 @@ export class AcpPeer extends BasePeer {
         if (u.sessionUpdate === "tool_call" && typeof u.title === "string") this.toolTitles.set(u.toolCallId, u.title);
         const text = Array.isArray(u.content) ? u.content.map((c: any) => (c?.type === "content" && c.content?.type === "text" ? String(c.content.text) : "")).join("") : "";
         if (text) this.toolText.set(u.toolCallId, text);
-        if (u.status === "completed" || u.status === "failed") (this.toolInputs.delete(u.toolCallId), this.toolText.delete(u.toolCallId), this.toolTitles.delete(u.toolCallId));
+        if (u.status === "completed" || u.status === "failed") (this.toolInputs.delete(u.toolCallId), this.toolText.delete(u.toolCallId), this.toolTitles.delete(u.toolCallId), this.openTools.delete(u.toolCallId));
+        else if (u.sessionUpdate === "tool_call" || this.openTools.has(u.toolCallId)) this.openTools.set(u.toolCallId, this.toolTitles.get(u.toolCallId) ?? "tool");
+        while (this.openTools.size > TOOL_INPUT_CAP) this.openTools.delete(this.openTools.keys().next().value as string);
         for (const map of [this.toolInputs, this.toolText, this.toolTitles]) while (map.size > TOOL_INPUT_CAP) map.delete(map.keys().next().value as string);
       }
       else if (u?.sessionUpdate === "usage_update") this.observeUsage(u, "usage_update");

package/src/adapters/claude-channel.ts

@@ -86,6 +86,7 @@ const TERMINAL_CLOSES: Record<number, string> = {
   4404: "the hub belongs to a different project or instance; restart this session from the intended project",
   4403: `the hub refused the peer id "${peerId}" (reserved or malformed)`,
   4409: `the peer id "${peerId}" is taken by a hub-managed adapter`,
+  4430: "this Claude launch ended; start a new session with ahub claude, or use a plain session with hub_inbox",
   4426: "wire version mismatch with the running hub: update the agent-hub plugin (ahub setup) and restart this session",
 };
 /** Another session attached under this peer id. Unlike the other closes this one ends on its own, so the
@@ -97,7 +98,7 @@ const INBOX_CAP = 200;
 /**
  * Whether a live session holds this peer id, per the daemon's own status file. The hub gives the id to
  * whoever said hello last, so reconnecting blind would evict the session that just took it and the two
- * would trade the peer forever. No readable status means no live hub holds it, and a connect can only fail.
+ * would trade the peer forever. This file is advisory: a standby hello also checks live ownership at the daemon.
  */
 function peerHeld(): boolean {
   try {
@@ -144,7 +145,7 @@ const text = (s: string) => ({ content: [{ type: "text" as const, text: s }] });
 
 const server = new Server(
   { name: "agent-hub", version: VERSION },
-  toolsMode ? { capabilities: { tools: {} }, instructions: TOOLS_INSTRUCTIONS } : { capabilities: channel ? { experimental: { "claude/channel": {} }, tools: {} } : { tools: {} }, instructions: INSTRUCTIONS },
+  toolsMode ? { capabilities: { tools: { listChanged: true } }, instructions: TOOLS_INSTRUCTIONS } : { capabilities: channel ? { experimental: { "claude/channel": {} }, tools: { listChanged: true } } : { tools: { listChanged: true } }, instructions: INSTRUCTIONS },
 );
 
 const inbox: string[] = []; // pushes that failed; drained by hub_inbox
@@ -243,6 +244,8 @@ async function connectLoop(): Promise<void> {
     let closeReason: string | undefined;
     try {
       const client = await ControlClient.connect(stateDir, { role: toolsMode ? "tools" : "peer", peer: peerId, ...(toolsMode ? {} : { channel }),
+        ...(!toolsMode && process.env.AGENTHUB_LAUNCH_ID ? { launchId: process.env.AGENTHUB_LAUNCH_ID } : {}),
+        ...(!toolsMode && standingBy ? { standby: true } : {}),
         ...(process.env.AGENTHUB_PROJECT_DIR ? { projectRoot } : {}) });
       client.onPush = (msg) => {
         if (msg.t === "queued") {
@@ -267,6 +270,9 @@ async function connectLoop(): Promise<void> {
       standingBy = false;
       detached = undefined;
       log(`connected to hub as "${peerId}"`);
+      // The tool list depends on the connected hub (its lifecycle): when it differs from what the host last listed,
+      // ask the host to list it again (#490).
+      if (listedTools !== undefined) void reannounce(client).catch(() => {});
       code = await new Promise<number>((r) => { client.onClose = (value, reason) => { closeReason = reason; r(value); }; });
       hub = undefined;
       log("hub connection lost");
@@ -290,8 +296,27 @@ async function connectLoop(): Promise<void> {
   }
 }
 
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-  const lifecycle = await activeLifecycle(stateDir, peerId, projectRoot, hub);
+/** The tool definitions the host was last given; a reconnect that changes any of them asks the host to list again (#490).
+ * Whole definitions, not names: a lifecycle change alters schemas (stage enums, required fields) under the same names. */
+let listedTools: string | undefined;
+const toolKey = (list: { tools: unknown[] }) => JSON.stringify(list.tools);
+
+/** After a reconnect, re-announce the tools when they differ from what the host listed. The status probe can time out
+ * right after a restart; retry it, and when it stays unavailable announce anyway: a needless re-list costs less than a
+ * session that keeps a short list until the next disconnect (#490). */
+async function reannounce(client: ControlClient) {
+  for (let tries = 0; ; tries++) {
+    if (hub !== client) return;
+    const lifecycle = await activeLifecycle(stateDir, peerId, projectRoot, client);
+    if (lifecycle === undefined && tries < 2) { await new Promise(r => setTimeout(r, 1000)); continue; }
+    if (lifecycle === undefined || toolKey(toolListFor(lifecycle)) !== listedTools) await server.sendToolListChanged();
+    return;
+  }
+}
+
+async function buildToolList() { return toolListFor(await activeLifecycle(stateDir, peerId, projectRoot, hub)); }
+
+function toolListFor(lifecycle: Awaited<ReturnType<typeof activeLifecycle>>) {
   return {
   tools: [
     {
@@ -333,6 +358,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     ...CONDUCTOR_TOOLS,
   ],
   };
+}
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  const list = await buildToolList();
+  listedTools = toolKey(list);
+  return list;
 });
 
 async function callTool(req: { params: { name: string; arguments?: Record<string, unknown> } }) {

package/src/adapters/codex-appserver.ts

@@ -49,6 +49,7 @@ export interface CodexOptions {
 }
 
 interface Link {
+  launchId?: string;
   tui: ServerWebSocket<Link>;
   up: WebSocket;
   backlog: string[]; // TUI frames that arrived before the upstream socket opened
@@ -128,6 +129,13 @@ export class CodexPeer extends BasePeer {
     return `ws://127.0.0.1:${this.server?.port ?? this.opts.proxyPort}`;
   }
 
+  terminalOwner(launchId: string): { generation: string } | undefined {
+    const link = this.link;
+    return this.threadId && link && link === this.claimedTui && link.launchId === launchId &&
+      link.tui.readyState === WebSocket.OPEN && link.up.readyState === WebSocket.OPEN
+      ? { generation: String(this.sessionGeneration) } : undefined;
+  }
+
   async start(): Promise<void> {
     const upstream = this.opts.upstreamUrl ?? (await this.spawnAppServer());
     try {
@@ -137,7 +145,8 @@ export class CodexPeer extends BasePeer {
       fetch: (req, server) => {
         // Browsers always send Origin on WebSocket upgrades; the TUI never does.
         if (req.headers.has("origin")) return new Response("forbidden", { status: 403 });
-        if (server.upgrade(req, { data: {} as Link })) return undefined;
+        const launchId = new URL(req.url).searchParams.get("launchId");
+        if (server.upgrade(req, { data: { ...(launchId && launchId.length <= 128 ? { launchId } : {}) } as Link })) return undefined;
         return new Response("agent-hub codex proxy");
       },
       websocket: {
@@ -418,7 +427,7 @@ export class CodexPeer extends BasePeer {
 
   private attach(tui: ServerWebSocket<Link>, upstream: string): void {
     const up = new WebSocket(upstream);
-    const link: Link = { tui, up, backlog: [], tracked: new Map() };
+    const link: Link = { tui, up, backlog: [], tracked: new Map(), ...(tui.data.launchId ? { launchId: tui.data.launchId } : {}) };
     this.claimedTui = link;
     tui.data = link;
     up.onopen = () => {
@@ -556,7 +565,7 @@ export class CodexPeer extends BasePeer {
   }
 
   private adopt(link: Link, threadId: unknown, fresh = false): void {
-    if (typeof threadId !== "string" || !threadId) return;
+    if (typeof threadId !== "string" || !threadId || link !== this.claimedTui || link.tui.readyState !== WebSocket.OPEN || link.up.readyState !== WebSocket.OPEN) 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");

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

@@ -22,8 +22,8 @@ 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.
  * 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] : [];
+function compatibilityLaunch(kind: CompatibilityKind, ctx: LaunchContext, explicitMode = false): LaunchPlan {
+  const mode = explicitMode || kind === "kimi" || kind === "pi" ? ["--mode", ctx.form] : [];
   const unattended = ctx.unattended && (kind === "claude" || kind === "codex") ? ["--unattended"] : [];
   const args = [ctx.entrypoint, "--project", ctx.projectRoot, kind, ...mode, ...unattended,
     ...(ctx.model && !ctx.userArgs.includes("--model") ? ["--model", ctx.model] : []), ...ctx.userArgs];
@@ -145,19 +145,21 @@ 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: headlessForms, defaultForm: "headless", ownsTerminal: headless, launch: ctx => compatibilityLaunch("jcode", ctx), conductorStartable: true, hubSwitches: [], ownedFlags: [] },
+    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: [] },
     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", launchConfigKeys: ["jcode_cmd", "jcode_home", "jcode_provider_profile"], startWords: () => ["jcode"] }, display: JCODE_DISPLAY, hooks: { recallPlatform: "jcode" },
+    cli: { command: "jcode", authority: "person", launchConfigKeys: ["jcode_cmd", "jcode_home", "jcode_provider_profile"], startWords: mode => ["jcode", "--mode", mode] }, 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.
+ * The frozen jcode entry stays byte-identical: its headless `launch` emits `jcode` without `--mode`, which the CLI now
+ * 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([

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

@@ -13,11 +13,11 @@ export const DOCTOR_PLUGIN_PROBE = Object.freeze({ command: "claude", argv: Obje
 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 === "config" || name === "retired setting" || name === "routing" ? "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";
+    : ["omniroute", "omniroute key", "routing model", "routing models", "pi mlx"].includes(name) ? "Models" : "Hub";
+  const optional = nativeTool || ["ahub daemon", "pi mlx"].includes(name) || section === "Memory";
+  const level: DoctorCheck["level"] = ok === undefined ? (name === "omniroute" ? "warn" : "unknown") : ok ? "ok" : optional ? "warn" : "fail";
   return { section, level, name, detail };
 }
 
@@ -32,13 +32,16 @@ export function nativeDoctorRecoveryIdentity(peer: { id: string; state: string;
 
 export type NativeDoctorOptionalProbe =
   | { kind: "source-identity"; name: string; command: string[]; detail: string }
+  | { kind: "jcode-mcp"; name: string; home: 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[] {
+export function nativeDoctorOptionalProbes(config: { roster: Readonly<Record<string, boolean | undefined>>; jcode_cmd: string[]; qwen_cmd: string[]; jcode_home?: 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" });
+  // #572 AC4: jcode cannot be told which MCP servers to load, so the host lists the ones its config files name.
+  if (config.roster.jcode === true && config.jcode_home) probes.push({ kind: "jcode-mcp", name: "jcode MCP servers", home: config.jcode_home });
   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" });

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

@@ -22,7 +22,7 @@ export async function runClaudeEntry(ctx: NativeCliEntryContext): Promise<void>
     } finally { hub.close(); }
     return console.log(`${peer} started: a headless reviewer the hub runs per review (stop it with ahub stop ${peer})`);
   }
-  const { launcherPreview, readControl, recordTerminalLaunch, claudeObservationHooks, buildLaunch, runClaudeLaunch, processSignature, recordClaudeLaunch, cleanupStaleClaudeSettings, nativeLaunchEnv, childEnv, cleanupClaudeSettings } = ctx.helpers;
+  const { launcherPreview, readControl, prepareTerminalLaunch, registerTerminalLaunch, claudeObservationHooks, buildLaunch, runClaudeLaunch, processSignature, recordClaudeLaunch, cleanupStaleClaudeSettings, nativeLaunchEnv, childEnv, cleanupClaudeSettings } = ctx.helpers;
   if (args.includes("--print-command") || args.includes("--dry-run")) {
     try { return console.log(JSON.stringify(launcherPreview("claude", args, cwd, stateDir, unattendedEnv), null, 2)); }
     catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }
@@ -30,8 +30,13 @@ export async function runClaudeEntry(ctx: NativeCliEntryContext): Promise<void>
   const control = readControl(stateDir);
   if (control?.instanceId) {
     process.env.AGENTHUB_INSTANCE_ID = control.instanceId;
-    const terminal = await recordTerminalLaunch(peer, cwd, stateDir, control.instanceId, ctx.instance ? { executionCwd: cwd } : undefined);
+    const terminal = await prepareTerminalLaunch(peer, cwd, stateDir, control.instanceId, ctx.instance ? { executionCwd: cwd } : undefined);
     if (!terminal) process.env.AGENTHUB_LAUNCH_ID = randomUUID();
+    else {
+      const hub = await ctx.connect();
+      try { await registerTerminalLaunch(hub, terminal, process.env.AGENTHUB_RECOVERY_OPERATION); }
+      finally { hub.close(); }
+    }
   }
   // `--settings` outranks project and user settings, so the tee has to wrap whichever status line would have won:
   // project local, then project, then user.

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

@@ -4,35 +4,34 @@ import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
 export async function runCodexEntry(ctx: NativeCliEntryContext): Promise<void> {
   const peer = ctx.instance ?? "codex";
   const { args, cwd, stateDir, unattendedEnv, projectConfig, connect, fail, exec } = ctx;
-  const { launcherPreview, buildLaunch, recoveryLock, readControl, recordTerminalLaunch } = ctx.helpers;
+  const { launcherPreview, buildLaunch, readControl, prepareTerminalLaunch, registerTerminalLaunch } = ctx.helpers;
   if (args.includes("--print-command") || args.includes("--dry-run")) {
     try { return console.log(JSON.stringify(launcherPreview("codex", args, cwd, stateDir, unattendedEnv), null, 2)); }
     catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }
   }
   const launch0 = buildLaunch("codex", args, { unattended: unattendedEnv, instance: peer, proxyUrl: "pending" }); // refuse bad flags before starting anything
-  // #215: a launch by a recovery operation records itself before the hub round trip, so the coordinator never takes
-  // a launcher still starting for one that never ran. An ordinary launch records only once the hub accepted it: a
-  // refused start must not replace the record of a Codex already running here (one row per peer and instance).
-  const recovering = !!process.env.AGENTHUB_RECOVERY_OPERATION && process.env.AGENTHUB_RECOVERY_OPERATION === recoveryLock(); // not an id a restored session inherited
-  const before = readControl(stateDir);
-  // ponytail: recovering extras have no authenticated execution-root binding before start replies, so their row
-  // is recorded afterward. The coordinator retains its pending creation/wait evidence; add pre-start recording
-  // only when a future recovery receipt supplies independently verified exact-instance execution-root evidence.
-  if (recovering && !ctx.instance && before?.instanceId) await recordTerminalLaunch(peer, cwd, stateDir, before.instanceId);
   const hub = await connect();
   const snapshot = (await hub.request({ t: "status" })).status;
   const warning = retainedLaunchWarning(snapshot, peer, ctx.definition); if (warning) console.error(warning);
   const res = await hub.request({ t: "start", peer, args: { unattended: launch0.unattended === true }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
-  hub.close();
-  if (!res.ok) fail(res.error);
+  if (!res.ok) { hub.close(); fail(res.error); }
   if (ctx.instance) {
     if (typeof res.executionCwd !== "string" || !res.executionCwd.startsWith("/")) fail("instance execution directory was not verified");
     ctx.executionCwd = res.executionCwd;
   }
   const control = readControl(stateDir);
-  if ((!recovering || ctx.instance) && control?.instanceId) await recordTerminalLaunch(peer, cwd, stateDir, control.instanceId, ctx.instance ? { executionCwd: ctx.executionCwd } : undefined);
+  let proxyUrl = res.proxyUrl;
+  try {
+    if (control?.instanceId) {
+      const terminal = await prepareTerminalLaunch(peer, cwd, stateDir, control.instanceId, ctx.instance ? { executionCwd: ctx.executionCwd } : undefined);
+      if (terminal) {
+        await registerTerminalLaunch(hub, terminal, process.env.AGENTHUB_RECOVERY_OPERATION);
+        const url = new URL(proxyUrl); url.searchParams.set("launchId", terminal.launchId); proxyUrl = url.toString();
+      }
+    }
+  } finally { hub.close(); }
   const runningCodexBin = res.retainedLaunchConfig?.codex_bin;
-  const launch = buildLaunch("codex", args, { unattended: unattendedEnv, instance: peer, proxyUrl: res.proxyUrl, codexBin: typeof runningCodexBin === "string" ? runningCodexBin : projectConfig().codex_bin });
+  const launch = buildLaunch("codex", args, { unattended: unattendedEnv, instance: peer, proxyUrl, codexBin: typeof runningCodexBin === "string" ? runningCodexBin : projectConfig().codex_bin });
   if (launch0.warning) console.error(launch0.warning);
   exec(launch.cmd, launch.args, "codex");
 }

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

@@ -1,30 +1,109 @@
 import { retainedLaunchWarning } from "./native-cli-retained.ts";
 import { resolve } from "node:path";
 import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
+import type { ControlClient } from "../../hub/control-client.ts";
+import type { JcodeTuiBinding, JcodeTuiState } from "../jcode.ts";
 import { bundleInStatus, rosterInStatus } from "../../hub/status-roster.ts";
 
+const WAITING = "jcode's TUI opens after its first hub turn; send it work, or Ctrl-C";
+
+/** The daemon names the one session option that differs from the attached saved session (#559 N2, #574). */
+function refuseNamedOption(reply: { ok?: unknown; option?: unknown }, fail: NativeCliEntryContext["fail"]): void {
+  if (!reply.ok && typeof reply.option === "string" && ["--session-id", "--model", "--provider-profile"].includes(reply.option)) fail(`Jcode is already running with a different ${reply.option}; run ahub jcode without it, or stop jcode first`);
+}
+
+export async function waitForJcodeTui(hub: ControlClient, fail: NativeCliEntryContext["fail"], signal: AbortSignal,
+  options: Record<string, string | undefined>, first?: JcodeTuiState): Promise<Extract<JcodeTuiState, { state: "ready" }> | undefined> {
+  let binding: JcodeTuiBinding | undefined = first?.binding, announced = false, current = first;
+  while (!signal.aborted) {
+    if (!current) {
+      const reply = await hub.request({ t: "native_tui_launch", peer: "jcode", binding, args: options });
+      if (signal.aborted) return;
+      refuseNamedOption(reply, fail);
+      if (!reply.ok || !reply.binding || !["waiting", "ready"].includes(reply.state)) fail("Jcode launch changed or its native saved session is unavailable; retry from a terminal");
+      current = reply as JcodeTuiState;
+    }
+    if (binding && (binding.launchId !== current.binding.launchId || binding.sessionId !== current.binding.sessionId)) fail("Jcode launch changed while waiting");
+    binding = current.binding;
+    if (current.state === "ready") return current;
+    if (!announced) { console.log(WAITING); announced = true; }
+    await new Promise<void>(resolve => {
+      const finish = () => { clearTimeout(timer); signal.removeEventListener("abort", finish); resolve(); };
+      const timer = setTimeout(finish, 200); signal.addEventListener("abort", finish, { once: true });
+      if (signal.aborted) finish();
+    });
+    current = undefined;
+  }
+}
+
 export async function runJcodeEntry(ctx: NativeCliEntryContext): Promise<void> {
   const { args, cwd, stateDir, cliDir, unattendedEnv, connect, fail, takeFlags } = ctx;
-  const { launcherPreview, qwenSessionId, configureJcodeMcp } = ctx.helpers;
-  if (args.includes("--print-command") || args.includes("--dry-run")) {
-    try { return console.log(JSON.stringify(launcherPreview("jcode", args, cwd, stateDir, unattendedEnv), null, 2)); }
-    catch { fail("cannot preview Jcode launch: invalid arguments or configuration (details withheld)"); }
+  const { launcherPreview, qwenSessionId, configureJcodeMcp, readControl, startModeOf } = ctx.helpers;
+  const print = args.includes("--print-command");
+  if (args.includes("--dry-run") || print) {
+    // Pure previews never create a native store or start a session. Only a person may resolve an existing private tuple.
+    if (!print || args.includes("--dry-run") || !ctx.person) {
+      try { return console.log(JSON.stringify(launcherPreview("jcode", args, cwd, stateDir, unattendedEnv), null, 2)); }
+      catch { fail("cannot preview Jcode launch: invalid arguments or configuration (details withheld)"); }
+    }
   }
-  const { one, rest } = takeFlags(args, ["--mode", "--model", "--provider-profile", "--session-id"], []);
-  if (rest.length || (one["--mode"] !== undefined && one["--mode"] !== "headless")) fail("usage: ahub jcode [--mode headless] [--model <alias>] [--provider-profile <name>] [--session-id <id>]");
+  const { one, rest } = takeFlags(args.filter(arg => arg !== "--print-command"), ["--mode", "--model", "--provider-profile", "--session-id"], []);
+  if (rest.length || (one["--mode"] !== undefined && !["headless", "tui"].includes(one["--mode"]))) fail("usage: ahub jcode [--mode tui|headless] [--model <alias>] [--provider-profile <name>] [--session-id <id>]");
   if (one["--session-id"] !== undefined && !qwenSessionId(one["--session-id"])) fail("invalid Jcode session identity");
-  const hub = await connect();
+  const control = readControl(stateDir);
+  const mode = one["--mode"] ?? (ctx.instance ? "headless" : control?.startModes?.jcode ?? startModeOf(ctx.projectConfig().peers, "jcode"));
+  if (print && (mode === "headless" || !control?.features?.includes("native_tui_launch"))) {
+    try { return console.log(JSON.stringify(launcherPreview("jcode", args, cwd, stateDir, unattendedEnv), null, 2)); }
+    catch { return fail("cannot preview Jcode launch: invalid arguments or configuration (details withheld)"); }
+  }
+  if (mode === "tui" && !ctx.person) fail("Jcode's private TUI is person-only; run ahub jcode in your terminal");
+  const hub = await connect(), abort = new AbortController();
+  let interrupted = false;
+  const interruptedWait = () => { if (abort.signal.aborted && !interrupted) fail("hub connection closed while waiting for Jcode; retry from a terminal"); return abort.signal.aborted; };
+  const interrupt = () => { interrupted = true; abort.abort(); hub.close(); process.exitCode = 130; };
+  process.once("SIGINT", interrupt);
+  const oldClose = hub.onClose;
+  hub.onClose = (code, reason) => { if (!abort.signal.aborted) abort.abort(); oldClose?.(code, reason); };
   try {
     const snapshot = (await hub.request({ t: "status" })).status;
     const rostered = rosterInStatus(snapshot, "jcode");
     if (rostered === undefined) fail("cannot read jcode's roster membership from the running hub; upgrade or restart it, then retry (nothing was started)");
     if (!rostered) fail("jcode is off roster; add it with ahub roster add jcode");
     const warning = retainedLaunchWarning(snapshot, "jcode", ctx.definition); if (warning) console.error(warning);
-    // The daemon verifies the entry against its own bundle; fall back to this CLI's copy only for a hub that reports none.
+    const options = { model: one["--model"], providerProfile: one["--provider-profile"], sessionId: one["--session-id"] };
+    if (print) {
+      if (!hub.features.includes("native_tui_launch") || mode !== "tui") return console.log(JSON.stringify(launcherPreview("jcode", args, cwd, stateDir, unattendedEnv), null, 2));
+      const reply = await hub.request({ t: "native_tui_launch", peer: "jcode", args: options });
+      refuseNamedOption(reply, fail);
+      if (!reply.ok || reply.state !== "ready") fail("Jcode's selected native session is not saved and ready; run ahub jcode to wait for its first hub turn");
+      return console.log(JSON.stringify(reply.launch, null, 2));
+    }
+    if (mode === "tui") {
+      if (!hub.features.includes("native_tui_launch")) fail("the running hub does not support Jcode TUI launch; upgrade it before retrying");
+      if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        if (one["--mode"] || Object.values(options).some(value => value !== undefined)) fail("run ahub jcode with these options in a terminal");
+        const reply = await hub.request({ t: "peer_start", peer: "jcode" });
+        if (!reply.ok) fail(reply.error);
+        console.log(reply.command ?? "Jcode terminal requested"); return;
+      }
+    }
     const written = configureJcodeMcp(cwd, stateDir, bundleInStatus(snapshot) ?? resolve(cliDir, "../../plugins/agent-hub/server.js"));
     if (written.tracked) console.error(".jcode/mcp.json is tracked; review this local machine-path change before committing it");
-    const reply = await hub.request({ t: "start", peer: "jcode", args: { mode: "headless", model: one["--model"], providerProfile: one["--provider-profile"], sessionId: one["--session-id"] }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION }, 65_000);
+    const reply = await hub.request({ t: "start", peer: "jcode", args: { mode, ...options }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION }, 65_000);
+    if (interruptedWait()) return;
     if (!reply.ok) fail(reply.error);
-    console.log(reply.already ? "jcode is already attached" : "jcode attached (headless); native policy unmanaged, NO hub sandbox");
-  } finally { hub.close(); }
+    if (mode === "headless") { console.log(reply.already ? "jcode is already attached" : "jcode attached (headless); native policy unmanaged, NO hub sandbox"); return; }
+    const ready = await waitForJcodeTui(hub, fail, abort.signal, options);
+    if (interruptedWait() || !ready) return;
+    // No managed terminal record: Jcode's controlled recovery is refused at plan time, so, like Kimi's TUI, it has
+    // no terminal recovery adapter (#564).
+    const confirmed = await hub.request({ t: "native_tui_launch", peer: "jcode", binding: ready.binding, args: options });
+    if (interruptedWait()) return;
+    if (!confirmed.ok || confirmed.state !== "ready") fail("Jcode launch changed before its terminal opened");
+    // ponytail: jcode 0.98.1's top-level TUI spawns a shared server (no --temporary-server or --owner-pid) when nothing
+    // answers on the dialed socket at startup, and on its reload-handoff reconnect. A hub stop or an owned-server crash
+    // between the confirm reply above and that check can leave an unowned jcode server on the private socket under the
+    // person's JCODE_HOME. No native flag prevents it; revisit if upstream adds an owner flag (#559 N2).
+    ctx.execWithEnv(confirmed.launch.cmd, confirmed.launch.args, { ...ctx.helpers.childEnv(), ...confirmed.launch.env });
+  } finally { process.removeListener("SIGINT", interrupt); hub.onClose = oldClose; hub.close(); }
 }

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

@@ -5,7 +5,7 @@ import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
 export async function runPiEntry(ctx: NativeCliEntryContext): Promise<void> {
   const peer = ctx.instance ?? "pi";
   const { args, cwd, stateDir, unattendedEnv, projectConfig, connect, fail, execWithEnv } = ctx;
-  const { launcherPreview, startModeOf, recoveryLock, readControl, recordTerminalLaunch } = ctx.helpers;
+  const { launcherPreview, startModeOf, readControl, prepareTerminalLaunch, registerTerminalLaunch } = ctx.helpers;
   // --headless is --mode headless everywhere this command goes: the preview, the hub and the conductor path.
   if (args.includes("--headless") && !args.includes("--mode")) args.splice(args.indexOf("--headless"), 1, "--mode", "headless");
   if (args.includes("--print-command") || args.includes("--dry-run")) {
@@ -34,11 +34,6 @@ export async function runPiEntry(ctx: NativeCliEntryContext): Promise<void> {
       return console.log(reply.already ? "pi is already attached" : reply.opened ? `pi: opened a terminal running ${reply.command}; it attaches when its TUI is ready` : 'pi attached (headless). Talk to it with: ahub say @pi "..."');
     } finally { hub.close(); }
   }
-  // #215: as for Codex, a TUI launch by the recovery operation holding the lock records itself before the hub round
-  // trip, so a resume in that window never reads it as gone; an ordinary launch records only after the hub accepted it.
-  const recovering = options.mode === "tui" && !!process.env.AGENTHUB_RECOVERY_OPERATION && process.env.AGENTHUB_RECOVERY_OPERATION === recoveryLock();
-  const before = readControl(stateDir);
-  if (recovering && before?.instanceId) await recordTerminalLaunch(peer, cwd, stateDir, before.instanceId);
   const hub = await connect();
   const snapshot = (await hub.request({ t: "status" })).status;
   const warning = retainedLaunchWarning(snapshot, peer, ctx.definition); if (warning) console.error(warning);
@@ -52,7 +47,14 @@ export async function runPiEntry(ctx: NativeCliEntryContext): Promise<void> {
     delete launchEnv.AGENTHUB_RECOVERY_OPERATION;
     delete launchEnv.AGENTHUB_UNATTENDED;
     const control = readControl(stateDir);
-    if (!recovering && control?.instanceId) await recordTerminalLaunch(peer, cwd, stateDir, control.instanceId);
+    if (control?.instanceId) {
+      const terminal = await prepareTerminalLaunch(peer, cwd, stateDir, control.instanceId);
+      if (terminal) {
+        const registration = await connect();
+        try { await registerTerminalLaunch(registration, terminal, process.env.AGENTHUB_RECOVERY_OPERATION); }
+        finally { registration.close(); }
+      }
+    }
     return execWithEnv(launch.cmd, launch.args, launchEnv);
   }
   console.log(res.already ? `${peer} is already attached` : `${peer} attached (headless). Talk to it with: ahub say @${peer} "..."`);

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

@@ -7,6 +7,7 @@ export interface NativeCliEntryContext {
   instance?: string; executionCwd?: string;
   /** #223: the selected instance is started by the hub (a headless reviewer), never as a terminal launch. */
   hubStarted?: true;
+  person?: boolean;
   args: string[]; cwd: string; stateDir: string; cliDir: string; unattendedEnv: boolean; definition: AdapterDefinition;
   projectConfig(): HubConfig;
   connect(): Promise<ControlClient>;
@@ -18,6 +19,8 @@ export interface NativeCliEntryContext {
     launcherPreview: typeof import("../../cli/preview.ts").launcherPreview;
     readControl: typeof import("../../hub/control-client.ts").readControl;
     recordTerminalLaunch: typeof import("../../cli/terminal-recovery.ts").recordTerminalLaunch;
+    prepareTerminalLaunch: typeof import("../../cli/terminal-recovery.ts").prepareTerminalLaunch;
+    registerTerminalLaunch: typeof import("../../cli/terminal-recovery.ts").registerTerminalLaunch;
     recoveryLock: typeof import("../../hub/recovery-store.ts").recoveryLock;
     processSignature: typeof import("../../pi/process-signature.ts").processSignature;
     buildLaunch: typeof import("../../cli/launch.ts").buildLaunch;