@staix/agent-hub 0.12.38 → 0.12.39

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,6 +151,8 @@ 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;
@@ -339,6 +344,7 @@ export class AcpPeer extends BasePeer {
     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; }
@@ -415,6 +421,16 @@ 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();
@@ -482,7 +498,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 +533,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/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,13 +145,13 @@ 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[]);
 

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

@@ -1,30 +1,99 @@
 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";
+
+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;
+      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 });
+      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;
+    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);
+    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");
+    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-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>;

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

@@ -14,6 +14,7 @@ export interface NativePreviewHelpers {
   childEnv: typeof import("../../hub/child-process.ts").childEnv;
   startModeOf: typeof import("../../hub/start-mode.ts").startModeOf;
   kimiMcpPlan: typeof import("../../cli/kimi-mcp.ts").kimiMcpPlan;
+  jcodeTuiCommand: typeof import("../jcode.ts").jcodeTuiCommand;
   jcodeCommand: typeof import("../jcode.ts").jcodeCommand;
   qwenSessionId: typeof import("../../hub/crash.ts").qwenSessionId;
   relayModelIds: typeof import("../../models/relay.ts").relayModelIds;

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

@@ -1,20 +1,20 @@
 import type { Launch } from "../../cli/launch.ts";
-import { REDACTED, UNRESOLVED, nativeCommand, previewState, finishPreview, type NativePreviewContext } from "./native-cli-preview-common.ts";
+import { REDACTED, UNRESOLVED, nativeCommand, previewState, finishPreview, type NativePreviewContext, type NativePreview } from "./native-cli-preview-common.ts";
 
-export function previewJcode(ctx: NativePreviewContext) {
+export function previewJcode(ctx: NativePreviewContext): NativePreview {
   const { args, config } = ctx;
-  const { jcodeCommand, qwenSessionId } = ctx.helpers;
+  const { jcodeCommand, jcodeTuiCommand, qwenSessionId, startModeOf } = ctx.helpers;
   const state = previewState(args, ctx.baseEnvNames), { unresolved, value } = state;
   let envNames = state.envNames;
   let launch: Launch;
-  const mode = value("--mode") ?? "headless", model = value("--model"), profile = value("--provider-profile"), session = value("--session-id");
-  if (mode !== "headless") throw new Error("Jcode TUI driving is unverified");
+  const mode = value("--mode") ?? startModeOf(config.peers, "jcode"), model = value("--model"), profile = value("--provider-profile"), session = value("--session-id");
+  if (mode !== "headless" && mode !== "tui") throw new Error("invalid Jcode start mode");
   for (let i = 0; i < args.length; i += 2) if (!["--model", "--mode", "--provider-profile", "--session-id"].includes(args[i]!) || !args[i + 1]) throw new Error("unknown Jcode option");
   if (session !== undefined && !qwenSessionId(session)) throw new Error("invalid Jcode session identity");
-  const cmd = jcodeCommand(nativeCommand(config.jcode_cmd, ["jcode"]), "acp", UNRESOLVED, UNRESOLVED, model ? REDACTED : undefined, profile || config.jcode_provider_profile ? REDACTED : undefined);
+  const cmd = mode === "tui" ? jcodeTuiCommand(nativeCommand(config.jcode_cmd, ["jcode"]), UNRESOLVED, UNRESOLVED, model ? REDACTED : undefined, profile || config.jcode_provider_profile ? REDACTED : undefined) : jcodeCommand(nativeCommand(config.jcode_cmd, ["jcode"]), "acp", UNRESOLVED, UNRESOLVED, model ? REDACTED : undefined, profile || config.jcode_provider_profile ? REDACTED : undefined);
   launch = { cmd: cmd[0]!, args: cmd.slice(1) };
   unresolved.push({ field: "ownedDaemon", reason: "private daemon/socket and source-pinned native identity verified at start; preview starts nothing" });
   unresolved.push({ field: "hubTools", reason: "project MCP bridge required; native tool-call receipt remains unverified" });
 
-  return finishPreview(ctx, launch, envNames, unresolved, undefined);
+  return { ...finishPreview(ctx, launch, envNames, unresolved), mode };
 }

package/src/adapters/definitions/native-daemon-policy.ts

@@ -12,7 +12,7 @@ export const codexRetainedTerminalNotice = (_instance: string, _form: StartForm
 export const codexRosterReturnNotice = (resumeCommand: string): string =>
   `Codex 0.146.0 needs a manual return: resume the previous native session with ${resumeCommand}.`;
 export const jcodeStartPreflight = (request: StartRequest): string | undefined =>
-  request.form !== undefined && request.form !== "headless" ? "Jcode native TUI driving is unverified; use headless" : undefined;
+  request.form !== undefined && request.form !== "headless" && request.form !== "tui" ? "invalid Jcode start mode" : undefined;
 export const claudeObservedVersion = (context: VersionContext): string | undefined => context.observedVersion;
 export const codexObservedVersion = (context: VersionContext): string | undefined =>
   (context.peer as { version?: string } | undefined)?.version ?? context.observedVersion;

package/src/adapters/jcode.ts

@@ -1,5 +1,5 @@
 import { spawn, spawnSync, type ChildProcess } from "node:child_process";
-import { existsSync, lstatSync, mkdtempSync, rmSync } from "node:fs";
+import { closeSync, constants, existsSync, fstatSync, lstatSync, mkdtempSync, openSync, readSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import type { Readable } from "node:stream";
@@ -17,6 +17,45 @@ export function jcodeCommand(command: string[], kind: "serve" | "acp", socket: s
   return [...command, kind, "--socket", socket, "--cwd", cwd, "--no-update", "--no-selfdev", ...(model ? ["--model", model] : []), ...(profile ? ["--provider-profile", profile] : []),
     ...(kind === "serve" ? ["--temporary-server", "--owner-pid", String(process.pid), "--server-name", "agent-hub-jcode"] : ["--mcp-tools", "eager"])];
 }
+export interface JcodeTuiBinding { launchId: string; sessionId: string }
+export type JcodeTuiState = { state: "waiting"; binding: JcodeTuiBinding } |
+  { state: "ready"; binding: JcodeTuiBinding; launch: { cmd: string; args: string[]; env: NodeJS.ProcessEnv } };
+
+export function jcodeTuiCommand(command: string[], socket: string, sessionId: string, model?: string, profile?: string): string[] {
+  if (!command.length || command.some(word => typeof word !== "string" || !word)) throw new Error("jcode_cmd must name an executable argv");
+  return [...command, "--socket", socket, "--resume", sessionId, "--no-update", "--no-selfdev",
+    ...(model ? ["--model", model] : []), ...(profile ? ["--provider-profile", profile] : [])];
+}
+
+/** Read native persistence only. Never synthesize a native session or send a save-inducing prompt. */
+function savedSession(home: string, id: string): boolean {
+  if (!/^[A-Za-z0-9_-]{1,128}$/.test(id)) throw new Error("invalid native session identity");
+  const directory = join(home, "sessions"), info = lstatSync(directory, { throwIfNoEntry: false });
+  if (!info) return false;
+  if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("unsafe native session directory");
+  const file = join(directory, `${id}.json`), entry = lstatSync(file, { throwIfNoEntry: false });
+  if (!entry) return false;
+  if (!entry.isFile() || entry.isSymbolicLink()) throw new Error("unsafe native session proof");
+  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 false; throw error; }
+  try {
+    const before = fstatSync(fd);
+    // ponytail: bound native persistence proof to 32 MiB; larger conversations need a native saved-session API.
+    if (!before.isFile() || before.nlink !== 1 || before.size > 32 * 1024 * 1024) throw new Error("unsafe native session proof");
+    if (!before.size) return false;
+    const bytes = Buffer.alloc(before.size);
+    let offset = 0;
+    while (offset < bytes.length) { const n = readSync(fd, bytes, offset, bytes.length - offset, offset); if (!n) return false; offset += n; }
+    const after = fstatSync(fd);
+    if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) return false;
+    let data: unknown;
+    try { data = JSON.parse(bytes.toString("utf8")); } catch { return false; }
+    if (!data || typeof data !== "object" || (data as { id?: unknown }).id !== id || !Array.isArray((data as { messages?: unknown }).messages)) throw new Error("native saved session identity is unproven");
+    return true;
+  } finally { closeSync(fd); }
+}
+
 /** Set on every owned jcode process: no Claude MCP import, and no native telemetry (jcode-telemetry-core is_enabled, #529). */
 const JCODE_OWNED_ENV = { JCODE_DISABLE_CLAUDE_MCP: "1", JCODE_NO_TELEMETRY: "1" } as const;
 /** The oldest native release accepted; its ACP, serve and MCP contract was verified live on 0.98.1 (docs/verification). */
@@ -45,6 +84,8 @@ export function verifiedJcodeCommand(command: string[], cwd: string): boolean {
 
 /** Both processes are ours. The user's global daemon and its sockets are never stopped. */
 export class JcodePeer extends AcpPeer {
+  private readonly launchId = crypto.randomUUID();
+  private socketIdentity: { dev: number; ino: number } | undefined;
   private readonly root: string;
   private readonly socket: string;
   private server: ChildProcess | undefined;
@@ -79,6 +120,8 @@ export class JcodePeer extends AcpPeer {
         ready.once("data", () => { clearTimeout(timer); server.off("exit", fail); if (lstatSync(this.socket, { throwIfNoEntry: false })?.isSocket()) resolve(); else reject(new Error("Jcode readiness has no private socket")); });
       });
       server.once("exit", () => { if (!this.ending && this.server === server) void this.stop("Jcode owned daemon disconnected").catch(() => {}); });
+      const identity = lstatSync(this.socket);
+      this.socketIdentity = { dev: identity.dev, ino: identity.ino };
       await super.start();
     } catch (error) { await this.stop().catch(() => {}); throw error; }
   }
@@ -119,6 +162,20 @@ export class JcodePeer extends AcpPeer {
     }
     if (failure) throw failure;
   }
+  tuiLaunch(expected?: JcodeTuiBinding, options: { model?: string; providerProfile?: string; sessionId?: string } = {}): JcodeTuiState {
+    const sessionId = super.recoveryMetadata().sessionId;
+    const socket = lstatSync(this.socket, { throwIfNoEntry: false });
+    if (this.ending || !this.server || this.server.exitCode !== null || this.server.signalCode !== null || this.state === "offline" ||
+      !socket?.isSocket() || socket.dev !== this.socketIdentity?.dev || socket.ino !== this.socketIdentity.ino || typeof sessionId !== "string") throw new Error("owned Jcode launch is unavailable");
+    const binding = { launchId: this.launchId, sessionId };
+    if (expected && (expected.launchId !== binding.launchId || expected.sessionId !== binding.sessionId)) throw new Error("Jcode launch changed");
+    if ((options.sessionId !== undefined && options.sessionId !== sessionId) ||
+      (options.model !== undefined && options.model !== this.jcode.launchModel) ||
+      (options.providerProfile !== undefined && options.providerProfile !== this.jcode.providerProfile)) throw new Error("Jcode launch options differ from its running session");
+    if (!savedSession(this.jcode.home, sessionId)) return { state: "waiting", binding };
+    const [cmd, ...args] = jcodeTuiCommand(this.jcode.command, this.socket, sessionId, this.jcode.launchModel, this.jcode.providerProfile);
+    return { state: "ready", binding, launch: { cmd: cmd!, args, env: { JCODE_HOME: this.jcode.home, JCODE_SOCKET: this.socket, ...JCODE_OWNED_ENV } } };
+  }
   override recoveryMetadata(): Record<string, unknown> {
     return { ...super.recoveryMetadata(), launch: { kind: "jcode", peer: "jcode", mode: "headless", ...(this.jcode.launchModel ? { model: this.jcode.launchModel } : {}), ...(this.jcode.providerProfile ? { providerProfile: this.jcode.providerProfile } : {}) } };
   }

package/src/adapters/registry.ts

@@ -16,7 +16,7 @@ export const ADAPTER_API = 1;
 export const KNOWN_PEERS = ["claude", "codex", "kimi", "pi", "local"] as const;
 export const OPTIONAL_PEERS = ["qwen", "jcode", "agy"] as const;
 export const SUPPORTED_PEERS = [...KNOWN_PEERS, ...OPTIONAL_PEERS] as const;
-export const START_MODE_PEERS = ["pi", "codex", "kimi"] as const;
+export const START_MODE_PEERS = ["pi", "codex", "kimi", "jcode"] as const;
 export const OFFICE_PEER_ORDER: readonly string[] = KNOWN_PEERS;
 
 

package/src/cli/main.ts

@@ -255,8 +255,8 @@ function exec(bin: string, argv: string[], tool?: "claude" | "codex" | "kimi", e
   process.exit(res.status ?? 1);
 }
 
-function execWithEnv(bin: string, argv: string[], extra: NodeJS.ProcessEnv, executionCwd = cwd): never {
-  const env: NodeJS.ProcessEnv = { ...nativeLaunchEnv(selectedInstance ?? "pi", extra, declaredInstances), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd };
+function execWithEnv(bin: string, argv: string[], extra: NodeJS.ProcessEnv, peer: string, executionCwd = cwd): never {
+  const env: NodeJS.ProcessEnv = { ...nativeLaunchEnv(peer, extra, declaredInstances), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd };
   delete env.AGENTHUB_RECOVERY_OPERATION;
   delete env.AGENTHUB_UNATTENDED;
   const res = spawnSync(bin, argv, { cwd: executionCwd, stdio: "inherit", env });
@@ -854,11 +854,11 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (selectedInstance && !args.includes("--print-command") && !args.includes("--dry-run")) {
       const hub = await nativeConnect(); hub.close();
     }
-    const context: NativeCliEntryContext = { args, cwd, stateDir, cliDir: import.meta.dir, unattendedEnv, definition: entry.definition,
+    const context: NativeCliEntryContext = { args, cwd, stateDir, cliDir: import.meta.dir, unattendedEnv, person: caller.role === "console", definition: entry.definition,
       ...(selectedInstance ? { instance: selectedInstance } : {}), ...(nativeSelection.hubStarted ? { hubStarted: true as const } : {}),
       projectConfig, connect: nativeConnect, fail,
       exec: (bin, argv, tool) => exec(bin, argv, tool, context.executionCwd),
-      execWithEnv: (bin, argv, env) => execWithEnv(bin, argv, env, context.executionCwd), takeFlags,
+      execWithEnv: (bin, argv, env) => execWithEnv(bin, argv, env, selectedInstance ?? entry.command, context.executionCwd), takeFlags,
       helpers: { launcherPreview: (tool, raw, projectRoot, state, unattended) => launcherPreview(tool, raw, projectRoot, state, unattended, selectedInstance), readControl, recordTerminalLaunch, recoveryLock, processSignature,
         buildLaunch, claudeObservationHooks, recordClaudeLaunch, cleanupStaleClaudeSettings, cleanupClaudeSettings,
         nativeLaunchEnv, runClaudeLaunch, childEnv, qwenSessionId, configureJcodeMcp, configureKimiMcp,

package/src/cli/preview.ts

@@ -4,7 +4,7 @@ import { childEnv } from "../hub/child-process.ts";
 import { startModeOf } from "../hub/start-mode.ts";
 import { instanceLaunchArguments, buildLaunch, buildKimiLaunch, buildKimiTuiLaunch, nativeLaunchEnv, claudeObservationHooks } from "./launch.ts";
 import { kimiMcpPlan } from "./kimi-mcp.ts";
-import { jcodeCommand } from "../adapters/jcode.ts";
+import { jcodeCommand, jcodeTuiCommand } from "../adapters/jcode.ts";
 import { qwenSessionId } from "../hub/crash.ts";
 import { relayModelIds } from "../models/relay.ts";
 import { buildPiLaunch } from "../pi/launch.ts";
@@ -24,7 +24,7 @@ export function launcherPreview(tool: "claude" | "codex" | "kimi" | "pi" | "qwen
   const result = preview({ tool, args, cwd, stateDir, cliDir: import.meta.dir, unattended, config, definition,
     baseEnvNames: Object.keys(childEnv()).concat(["AGENTHUB_STATE_DIR", "AGENTHUB_PROJECT_DIR"]),
     helpers: { buildLaunch: (native, argv, ctx) => buildLaunch(native, argv, { ...ctx, ...(selected.instance ? { instance: selected.instance } : {}) }), claudeObservationHooks, buildKimiLaunch, buildKimiTuiLaunch, nativeLaunchEnv, childEnv,
-      startModeOf, kimiMcpPlan, jcodeCommand, qwenSessionId, relayModelIds, buildPiLaunch },
+      startModeOf, kimiMcpPlan, jcodeCommand, jcodeTuiCommand, qwenSessionId, relayModelIds, buildPiLaunch },
   });
   if (!selected.instance) return result;
   return { ...result, instance: selected.instance,

package/src/hub/control-client.ts

@@ -8,7 +8,7 @@ export function stateDirFor(cwd: string): string {
 
 /** Control WS wire version. 2 = `deliver` carries `envs` (digests); 3 = `tools` role and task messages; 4 = budget messages and `hub_checkpoint`; 5 = `ask`; 6 = console-only `ui` session bootstrap; 8 = controlled recovery; 9 = Pi bridge metadata; 10 = durable delivery receipts; 11 = queue hold diagnostics; 12 = generation-bound channel settlement and execution budgets; 13 = turn-free facts (`facts` with tool, session and transcript binding, `silenced`) and per-recipient send results (issue #108). 14 = native context-window status and session-bound context checkpoint request ids (issue #185). 15 = conductor tools and permission deadlines/closed events (issues #190, #194). 16 = a Claude session without channel evidence: hello `channel: false` and `inbox` (issue #205). The plugin is installed apart from the daemon, so they can drift. */
 export const PROTOCOL = 16;
-export const DAEMON_FEATURES = ["native_hook_launch", "task_cancel", "recovery_deferred_hub", "peer_instances", "release_trains", "reviewer_pool"] as const;
+export const DAEMON_FEATURES = ["native_hook_launch", "task_cancel", "recovery_deferred_hub", "peer_instances", "release_trains", "reviewer_pool", "native_tui_launch"] as const;
 /** Protocols a current coordinator may authenticate while upgrading a running source. */
 export const RECOVERY_SOURCE_PROTOCOLS = [9, 10, 11, 12, 13, 14, 15, PROTOCOL] as const;
 

package/src/hub/daemon.ts

@@ -3322,7 +3322,7 @@ export async function startDaemon(opts: DaemonOptions) {
       if (owner instanceof PiPeer && owner.state !== "offline" && owner.mode === "tui") return { ok: false, error: "Pi runs in a terminal; end it there before starting a headless one", command: "ahub pi --headless" };
       return startPeer(peer, definitionOf(peer)?.start.explicitHeadlessMode ? { mode: "headless", ...(resume ?? {}) } : {});
     }
-    if (owner && owner.state !== "offline") return { ok: true, already: true, mode };
+    if (owner && owner.state !== "offline" && definitionOf(peer)?.start.daemonPort !== "owned-acp") return { ok: true, already: true, mode };
     const words = [...startWords(peer, mode)];
     if (resume) words.push(...(resume.sessionFile ? ["--session-file", resume.sessionFile] : ["--session-id", resume.sessionId]), ...(resume.backend ? ["--backend", resume.backend] : []), ...(resume.model ? ["--model", resume.model] : []));
     const command = `ahub ${resume ? words.map(shellQuote).join(" ") : words.join(" ")}`;
@@ -5579,6 +5579,18 @@ export async function startDaemon(opts: DaemonOptions) {
         if (typeof msg.admissionId === "string" && msg.admissionId === kimiAdmissionId) clearKimiAdmission();
         return void reply({ ok: true });
       }
+      case "native_tui_launch": {
+        if (c.role !== "console") return void reply({ ok: false, error: "native TUI launch is console only" });
+        const peer = String(msg.peer), owner = bus.peers.get(peer);
+        if (stopping || recoveryActive() || !membershipAllowed(peer) || rosterChanging === peer || requestedPeerStops.has(peer) ||
+          peer !== definitionOf(peer)?.kind || !(owner instanceof JcodePeer) || !jcodeMcpReady(opts.cwd, opts.stateDir, SERVER_JS)) return void reply({ ok: false, error: "owned native TUI launch is unavailable" });
+        try {
+          if (msg.binding !== undefined && (!msg.binding || typeof msg.binding.launchId !== "string" || typeof msg.binding.sessionId !== "string")) throw new Error("invalid binding");
+          const options = msg.args ?? {};
+          for (const key of ["model", "providerProfile", "sessionId"]) if (options[key] !== undefined && typeof options[key] !== "string") throw new Error("invalid option");
+          return void reply({ ok: true, ...owner.tuiLaunch(msg.binding, options) });
+        } catch { return void reply({ ok: false, error: "owned Jcode launch or saved session could not be verified; details withheld" }); }
+      }
       case "peer_start":
         // #269: a start the hub makes in the peer's start mode, for a console child with no terminal of its own.
         if (c.role !== "console") return void reply({ ok: false, error: "peer_start is a console command; use hub_peer_start with the conductor role" });

package/src/hub/peers.ts

@@ -73,11 +73,11 @@ export abstract class BasePeer implements PeerAdapter {
   }
 
   /** Any sign of life from a busy peer re-arms the watchdog (it measures inactivity, not duration). */
-  protected touch(): void {
+  protected touch(ms = this.watchdogMs): void {
     this.clearWatchdog();
     this.timer = setTimeout(() => {
       if (this._state === "busy") this.onWatchdog();
-    }, this.watchdogMs);
+    }, ms);
     this.timer.unref?.();
   }
 

package/src/hub/start-mode.ts

@@ -11,7 +11,7 @@ export type StartMode = typeof START_MODES[number];
 // ponytail: released coordinators source-probe this exact literal before restoring headless Kimi.
 // Keep it until those readers negotiate the registry capability.
 /** The peers with both forms. Kimi's TUI is pull-only; Claude has only a TUI and local only headless. */
-export const START_MODE_PEERS = ["pi", "codex", "kimi"] as const;
+export const START_MODE_PEERS = ["pi", "codex", "kimi", "jcode"] as const;
 /** Every peer the hub can start itself. */
 export const STARTABLE_PEERS = SUPPORTED_PEERS;
 export type StartablePeer = typeof STARTABLE_PEERS[number];