@staix/agent-hub 0.12.39 → 0.12.40

package/src/adapters/acp.ts

@@ -159,6 +159,9 @@ export class AcpPeer extends BasePeer {
   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;
@@ -324,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; }
@@ -341,6 +345,7 @@ 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 = [];
@@ -366,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) {
@@ -381,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) {
@@ -437,6 +446,7 @@ export class AcpPeer extends BasePeer {
     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
@@ -474,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;
@@ -486,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");
   }

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

@@ -158,6 +158,8 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly 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

@@ -7,6 +7,11 @@ 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;
@@ -14,6 +19,7 @@ export async function waitForJcodeTui(hub: ControlClient, fail: NativeCliEntryCo
     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;
     }
@@ -68,6 +74,7 @@ export async function runJcodeEntry(ctx: NativeCliEntryContext): Promise<void> {
     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));
     }
@@ -88,12 +95,15 @@ export async function runJcodeEntry(ctx: NativeCliEntryContext): Promise<void> {
     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;
-    const instanceId = typeof snapshot?.instanceId === "string" ? snapshot.instanceId : undefined;
-    if (!instanceId) return fail("cannot bind Jcode's terminal to the running hub");
-    await ctx.helpers.recordTerminalLaunch("jcode", cwd, stateDir, instanceId);
+    // 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

@@ -19,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;

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

@@ -1,4 +1,4 @@
-import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { closeSync, constants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { hubGitSync } from "../../hub/git.ts";
@@ -56,3 +56,57 @@ export function configureJcodeMcp(cwd: string, stateDir: string, bundle: string,
   } finally { if (existsSync(temporary)) unlinkSync(temporary); }
   return { changed: true, tracked };
 }
+
+/**
+ * #572 AC4: jcode 0.99.0 has no flag or environment variable that chooses which MCP servers its `serve` and `acp`
+ * load (`--mcp-tools` and `JCODE_MCP_TOOLS` only change how their tools are exposed, and `JCODE_DISABLE_CLAUDE_MCP`
+ * does not stop a project `.mcp.json`). The hub-owned jcode therefore starts every server these files name, besides
+ * the hub's own. This lists their names for `ahub doctor`. It reads only `<JCODE_HOME>/mcp.json` and the project's
+ * `.jcode/mcp.json`, `.mcp.json` and `.claude/mcp.json`: no other path, no home search.
+ * Links are refused below the trusted root (ceiling: per-component `lstat` plus `O_NOFOLLOW` does not pin a directory against a concurrent same-user swap; that would need fd-relative traversal): each controlled directory component (`.jcode`, `.claude`) and the
+ * file itself must be a real directory or a real regular file, and the file is opened without following a link and
+ * checked again after the open (review I3). The project root and the home are the hub's own configured paths, so a
+ * system alias at or above them (macOS `/var`) stays legitimate. Names only: a command, url, header or environment
+ * value never leaves the file.
+ */
+function readBoundedJson(root: string, parts: string[]): unknown | undefined {
+  let dir = root;
+  for (const part of parts.slice(0, -1)) {
+    dir = join(dir, part);
+    const info = lstatSync(dir, { throwIfNoEntry: false });
+    if (!info) return undefined; // absent: nothing to list
+    if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("unsafe directory");
+  }
+  const file = join(dir, parts[parts.length - 1]!), info = lstatSync(file, { throwIfNoEntry: false });
+  if (!info) return undefined;
+  if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1 || info.size > 256 * 1024) throw new Error("unsafe file");
+  let fd: number;
+  try { fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; throw error; }
+  try {
+    const open = fstatSync(fd);
+    if (!open.isFile() || open.nlink !== 1 || open.size > 256 * 1024 || open.dev !== info.dev || open.ino !== info.ino) throw new Error("unsafe file");
+    const bytes = Buffer.alloc(open.size);
+    let offset = 0;
+    while (offset < bytes.length) { const n = readSync(fd, bytes, offset, bytes.length - offset, offset); if (!n) break; offset += n; }
+    return JSON.parse(bytes.subarray(0, offset).toString("utf8"));
+  } finally { closeSync(fd); }
+}
+
+export function jcodeExtraMcpServers(cwd: string, home: string): { servers: string[]; unreadable: string[] } {
+  const sources: [label: string, root: string, parts: string[]][] = [
+    ["mcp.json (JCODE_HOME)", home, ["mcp.json"]], [JCODE_MCP_FILE, cwd, [".jcode", "mcp.json"]],
+    [".mcp.json", cwd, [".mcp.json"]], [".claude/mcp.json", cwd, [".claude", "mcp.json"]],
+  ];
+  const names = new Set<string>(), unreadable: string[] = [];
+  for (const [label, root, parts] of sources) {
+    try {
+      const doc = readBoundedJson(root, parts);
+      if (doc === undefined) continue;
+      const servers = object(doc) ? (doc.mcpServers ?? doc.servers) : undefined;
+      if (!object(doc) || (servers !== undefined && !object(servers))) { unreadable.push(label); continue; }
+      for (const name of Object.keys(servers ?? {})) if (name !== JCODE_MCP_NAME) names.add(name);
+    } catch { unreadable.push(label); }
+  }
+  return { servers: [...names].sort(), unreadable };
+}