@staix/agent-hub 0.16.0 → 0.17.0

package/src/adapters/codex-review-isolation.ts

@@ -172,7 +172,8 @@ function ownServer(text: string): Record<string, unknown> {
   if (Object.keys(hub).some(key => !["command", "args", "env"].includes(key)) || typeof hub.command !== "string" || !hub.command || hub.args !== undefined && (!Array.isArray(hub.args) || hub.args.some(arg => typeof arg !== "string"))) throw new Error("invalid hub transport");
   const env = hub.env === undefined ? {} : object(hub.env);
   if (Object.values(env).some(value => typeof value !== "string")) throw new Error("invalid hub environment");
-  return { command: hub.command, args: hub.args ?? [], env, enabled: true, required: true, enabled_tools: TOOLS };
+  return { command: hub.command, args: hub.args ?? [], env, enabled: true, required: true, enabled_tools: TOOLS,
+    tools: Object.fromEntries(TOOLS.map(name => [name, { approval_mode: "approve" }])) };
 }
 
 /** All reads are model-free and bounded; stdout/config/env values never become diagnostic text. */
@@ -301,6 +302,14 @@ async function prepare(ctx: ReviewerPrepareContext): Promise<ReviewerLaunch | {
 
 export const codexReviewerBackend: ReviewerBackend = {
   id: "codex", prepare,
+  toolTrace(event) {
+    const row = event as { type?: string; item?: { type?: string; server?: string; tool?: string; error?: { message?: unknown } | string; result?: { isError?: boolean; content?: { type?: string; text?: unknown }[] } } };
+    const item = row?.item;
+    if (row?.type !== "item.completed" || item?.type !== "mcp_tool_call" || item.server !== "agent-hub" || (item.tool !== "hub_review" && item.tool !== "hub_task_show")) return undefined;
+    const failure = typeof item.error === "string" ? item.error : item.error?.message;
+    const refused = item.result?.isError === true && Array.isArray(item.result.content) ? item.result.content.filter(value => value?.type === "text" && typeof value.text === "string").map(value => value.text).join("\n") : undefined;
+    return { tool: item.tool, ...(typeof failure === "string" ? { refusal: failure } : typeof refused === "string" ? { refusal: refused } : {}) };
+  },
   usage(event) {
     const row = event as { type?: string; usage?: { input_tokens?: number; output_tokens?: number; cached_input_tokens?: number } };
     return row?.type === "turn.completed" && row.usage ? { input_tokens: row.usage.input_tokens, output_tokens: row.usage.output_tokens, cache_read_input_tokens: row.usage.cached_input_tokens } : undefined;

package/src/adapters/compat.ts

@@ -35,8 +35,8 @@ export const COMPAT = {
   "codex-review": { label: "Codex reviewer (codex-cli)", verified: ["0.146.0", "0.163.0", "0.164.0"], gate: "isolation", probe: ["codex", "--version"], config: "codex_bin",
     parse: out => plain(out.trim().replace(/^codex-cli /, "")),
     trustNote: "Every launch still proves the MCP inventory, Apps/plugins/hooks disabled, sandbox read/write denial and the binary fence; a failed leg still refuses. Trust covers only the source-level claims those probes cannot see (docs/verification/2026-10-19-reviewer-isolation.md)." },
-  // Kimi 2.3.0 / Qwen 0.26.0 receipt: docs/verification/2026-10-22-kimi-qwen-compat.md
-  "kimi-review": { label: "Kimi reviewer (kimi-code)", verified: ["2.2.0", "2.3.0"], gate: "isolation", probe: ["kimi", "--version"],
+  // Kimi 2.3.0 / Qwen 0.26.0 receipt: docs/verification/2026-10-22-kimi-qwen-compat.md; Kimi 2.3.1: docs/verification/2026-10-25-kimi-231-reviewer-compat.md
+  "kimi-review": { label: "Kimi reviewer (kimi-code)", verified: ["2.2.0", "2.3.0", "2.3.1"], gate: "isolation", probe: ["kimi", "--version"],
     parse: out => plain(out.trim()),
     trustNote: "Every launch still builds the private config, exact two-tool agent file and task-bound MCP; the native tool allowlist behaviour of an untested version is not re-proven." },
   jcode: { label: "Jcode", verified: ["0.98.1", "0.99.0"], line: { min: "0.98.0", below: "1.0.0" }, gate: "contract", probe: ["jcode", "--quiet", "version", "--json"], config: "jcode_cmd",
@@ -48,6 +48,11 @@ export const COMPAT = {
   qwen: { label: "Qwen Code", verified: ["0.25.0", "0.26.0"], gate: "contract", probe: ["qwen", "--version"], config: "qwen_cmd",
     parse: out => plain(out.trim()),
     trustNote: "Native ACP identity and mode ids have dated receipts; 0.26.0 permission callbacks were checked without inference. Another version may change those contracts." },
+  // Receipt: docs/verification/2026-10-25-qwen-dual-output-t0.md. The dual-output contract (input file, event file, can_use_tool control requests) is its own entry:
+  // the ACP receipts of the headless `qwen` entry say nothing about it, so that entry is not widened and this one carries no `line`.
+  "qwen-dual": { label: "Qwen Code dual-output TUI", verified: ["0.26.1"], gate: "contract", probe: ["qwen", "--version"], config: "qwen_cmd",
+    parse: out => plain(out.trim()),
+    trustNote: "The dual-output file contract (submit and confirmation_response input, user/assistant/stream_event/control events, session_start identity) was verified on 0.26.1 only. A hub deny ends the turn without any Qwen event, and no external stop of a running turn exists; another version may change either." },
 } as const satisfies Record<string, CompatPolicy>;
 export type CompatId = keyof typeof COMPAT;
 type CommandConfig = { codex_bin: string; jcode_cmd: string[]; qwen_cmd: string[] };

package/src/adapters/conformance/enrollment.ts

@@ -1,15 +1,25 @@
 import type { AdapterDefinition } from "../registry-types.ts";
+import { isFixedBuiltinDefinition } from "../registry.ts";
 
 /** Stable generic ACP legs; both actual test registration and enrollment validation consume this catalog. */
 export const ACP_LEGS = Object.freeze(["native-approval-rpc", "native-mode-ack", "native-quota", "watchdog-generation"] as const);
 export type AcpLeg = typeof ACP_LEGS[number];
+/** Reserved until 2b supplies the restrictive ACP product members; not an executable ACP leg yet. */
+export const ACP_PORTS_LEG = "restrictive-ports";
+export const NATIVE_PROOF_PORTS_LEG = "native-proof-ports";
 /** No unsupported key or non-generic ACP engine can silently escape an executable catalog leg. */
 export function assertAcpLegEnrollment(definitions: readonly AdapterDefinition[], unsupportedLegs: Readonly<Record<string, string>> = {}): void {
   const acp = new Map(definitions.filter(definition => definition.transport === "acp").map(definition => [definition.kind, definition]));
   for (const [key, reason] of Object.entries(unsupportedLegs)) {
     const separator = key.lastIndexOf(":"), kind = key.slice(0, separator), leg = key.slice(separator + 1);
-    if (separator < 1 || !acp.has(kind) || !(ACP_LEGS as readonly string[]).includes(leg)) throw new Error(`${key}: stale or unknown unsupported ACP leg`);
     if (typeof reason !== "string" || !reason.trim()) throw new Error(`${key}: unsupported ACP leg requires a concrete reason`);
+    if (leg === NATIVE_PROOF_PORTS_LEG) {
+      const row = definitionIdentities(definitions).find(row => row.id === kind);
+      if (!row || !isFixedBuiltinDefinition(row.definition)) throw new Error(`${key}: only fixed builtin proof legs may be nonapplicable`);
+      continue;
+    }
+    if (separator < 1 || !acp.has(kind) || !(ACP_LEGS as readonly string[]).includes(leg) && leg !== ACP_PORTS_LEG) throw new Error(`${key}: stale or unknown unsupported ACP leg`);
+    if (leg === ACP_PORTS_LEG && reason !== "ports added in 2b") throw new Error(`${key}: reserved ACP ports leg requires reason ports added in 2b`);
   }
   for (const definition of acp.values()) if (definition.start.daemonPort !== "acp") {
     for (const leg of ACP_LEGS) {
@@ -24,8 +34,12 @@ export function definitionIdentities(definitions: readonly AdapterDefinition[]):
     ...(definition.headlessVariant ? [{ id: `${definition.kind}:implementer`, definition: definition.headlessVariant }] : [])]);
 }
 export function assertEnrollment(definitions: readonly AdapterDefinition[], enrolled: readonly string[], unsupported: Readonly<Record<string, string>>, unsupportedLegs: Readonly<Record<string, string>> = {}, coherence?: (definition: AdapterDefinition) => void): void {
-  assertAcpLegEnrollment(definitions, unsupportedLegs);
   const rows = definitionIdentities(definitions), identities = new Set(rows.map(row => row.id));
+  for (const { id, definition } of rows) {
+    try { coherence?.(definition); }
+    catch (error) { throw new Error(`${id}: ${(error as Error).message}`); }
+  }
+  assertAcpLegEnrollment(definitions, unsupportedLegs);
   if (identities.size !== rows.length) throw new Error("duplicate conformance definition identity");
   if (new Set(enrolled).size !== enrolled.length) throw new Error("duplicate conformance enrollment");
   for (const id of enrolled) if (!identities.has(id)) throw new Error(`${id}: enrolled fixture has no registry definition`);
@@ -35,8 +49,8 @@ export function assertEnrollment(definitions: readonly AdapterDefinition[], enro
     if (enrolled.includes(id)) throw new Error(`${id}: cannot be both enrolled and unsupported`);
   }
   for (const { id, definition } of rows) {
-    try { coherence?.(definition); }
-    catch (error) { throw new Error(`${id}: ${(error as Error).message}`); }
+    if (isFixedBuiltinDefinition(definition) && !Object.hasOwn(unsupportedLegs, `${id}:${NATIVE_PROOF_PORTS_LEG}`)) throw new Error(`${id}: native proof ports need an explicit nonapplicable reason`);
+    if (definition.transport === "acp" && !Object.hasOwn(unsupportedLegs, `${id}:${ACP_PORTS_LEG}`)) throw new Error(`${id}: ACP restrictive ports require the reserved 2b reason`);
     if (!enrolled.includes(id) && !Object.hasOwn(unsupported, id)) throw new Error(`${id}: no conformance fixture or unsupported reason`);
     if (definition.transport === "acp" && !enrolled.includes(id)) throw new Error(`${id}: every ACP definition must run the ACP legs`);
     if (id.endsWith(":reviewer") && !definition.reviewer) throw new Error(`${id}: reviewer variant lacks reviewer policy`);

package/src/adapters/conformance/factories.ts

@@ -1,13 +1,16 @@
 import type { AdapterDefinition, CreateContext, DaemonPorts } from "../registry-types.ts";
 import type { PeerAdapter } from "../../hub/peers.ts";
 import { join } from "node:path";
+import { assertNativeProofPorts } from "./kit.ts";
 
 /** The supplied definition creates its actual adapter, with only this fixture's transport options. */
 export function createFromDefinition<T extends PeerAdapter>(definition: AdapterDefinition, daemon: DaemonPorts): T {
   if (!definition.start.create) throw new Error(`${definition.kind}: no driven native factory; use its external-hello fixture`);
   const options = Object.values(daemon)[0] as { cwd: string; stateDir?: string; mcpServers?: CreateContext["mcpServers"] };
-  return definition.start.create({ instance: definition.kind, projectRoot: options.cwd, stateDir: options.stateDir ?? join(options.cwd, "state"),
+  const product = definition.start.create({ instance: definition.kind, projectRoot: options.cwd, stateDir: options.stateDir ?? join(options.cwd, "state"),
     kindConfig: {}, permission: "ask", mcpServers: options.mcpServers ?? [], daemon }) as T;
+  assertNativeProofPorts(definition, product);
+  return product;
 }
 /** Explicit watchdog seam on the factory-created implementation, replacing direct test subclasses. */
 export function expire(peer: PeerAdapter): void {

package/src/adapters/conformance/kit.ts

@@ -2,6 +2,7 @@ import { expect, test } from "bun:test";
 import type { Envelope } from "../../hub/envelope.ts";
 import { newEnvelope } from "../../hub/envelope.ts";
 import type { PeerAdapter } from "../../hub/peers.ts";
+import { isFixedBuiltinDefinition, type AdapterDefinition } from "../registry.ts";
 
 export async function until(condition: () => boolean, label: string): Promise<void> {
   const deadline = Date.now() + 5000;
@@ -19,14 +20,24 @@ export interface ConformanceFixture {
 }
 export interface AdapterConformance {
   kind: string;
+  definition?: AdapterDefinition;
   create(): Promise<ConformanceFixture>;
 }
 
+/** Presence itself is forbidden on a foreign product: even an undefined native proof port must fail the kit. */
+export function assertNativeProofPorts(definition: AdapterDefinition | undefined, product: PeerAdapter): void {
+  if (isFixedBuiltinDefinition(definition)) return;
+  for (const port of ["frontendProxy", "statusNotice", "revertTurn"] as const) {
+    if (port in product) throw new Error(`${definition?.kind ?? product.id}: ${port} is restricted to fixed builtin adapter products`);
+  }
+}
+
 /** Shared observable contract; every invocation uses the real adapter and its fake native transport. */
 export function registerConformance(adapter: AdapterConformance): void {
   test(`P4 ${adapter.kind}: transport delivery, synchronous occupancy and owned teardown`, async () => {
     const f = await adapter.create();
     try {
+      assertNativeProofPorts(adapter.definition, f.peer);
       expect(f.peer.id).toBe(adapter.kind);
       expect(f.peer.state).toBe("idle");
       const envelope: Envelope = newEnvelope("user", "conformance ping", { to: [adapter.kind] });

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

@@ -1,9 +1,16 @@
+import { peerChildEnv } from "../../hub/child-process.ts";
 import { retainedLaunchWarning } from "./native-cli-retained.ts";
 import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
 
+function verifiedLaunch(value: unknown): { cmd: string; args: string[]; env: NodeJS.ProcessEnv } | undefined {
+  const launch = value as { cmd?: unknown; args?: unknown; env?: unknown } | undefined;
+  if (!launch || typeof launch.cmd !== "string" || !launch.cmd || !Array.isArray(launch.args) || !launch.args.every((word: unknown) => typeof word === "string") || !launch.env || typeof launch.env !== "object" || Array.isArray(launch.env)) return undefined;
+  return { cmd: launch.cmd, args: launch.args as string[], env: launch.env as NodeJS.ProcessEnv };
+}
+
 export async function runQwenEntry(ctx: NativeCliEntryContext): Promise<void> {
   const peer = ctx.instance ?? "qwen";
-  const { args, cwd, stateDir, unattendedEnv, connect, fail, takeFlags } = ctx;
+  const { args, cwd, stateDir, unattendedEnv, connect, fail, takeFlags, execWithEnv } = ctx;
   const { launcherPreview } = ctx.helpers;
   if (args.includes("--print-command") || args.includes("--dry-run")) {
     try { return console.log(JSON.stringify(launcherPreview("qwen", args, cwd, stateDir, unattendedEnv), null, 2)); }
@@ -11,14 +18,35 @@ export async function runQwenEntry(ctx: NativeCliEntryContext): Promise<void> {
   }
   const { one, rest } = takeFlags(args, ["--mode", "--model", "--session-id"], []);
   const adapter = ctx.definition;
+  const usage = "usage: ahub qwen [--mode headless|tui] [--model <alias>] [--session-id <id>]";
   if (one["--session-id"] !== undefined && !adapter.session.crashIdentity?.({ sessionId: one["--session-id"] }).sessionId) fail("invalid Qwen session identity");
-  if (rest.length || (one["--mode"] !== undefined && !(adapter.start.forms as readonly string[]).includes(one["--mode"]))) fail("Qwen TUI is not offered before verification; usage: ahub qwen [--mode headless] [--model <alias>] [--session-id <id>]");
+  if (rest.length || (one["--mode"] !== undefined && !["headless", "tui"].includes(one["--mode"]))) fail(usage);
+  const mode = one["--mode"] === "tui" ? "tui" : "headless";
+  if (mode === "tui" && ctx.instance) fail("extra Qwen instances require headless mode");
+  if (mode === "tui" && !(process.stdin.isTTY && process.stdout.isTTY)) fail("Qwen's TUI needs a terminal: run ahub qwen --mode tui in one, or use --mode headless");
   const hub = await connect();
+  let launch: unknown;
   try {
     const snapshot = (await hub.request({ t: "status" })).status;
     const warning = retainedLaunchWarning(snapshot, peer, ctx.definition); if (warning) console.error(warning);
-    const reply = await hub.request({ t: "start", peer, args: { mode: "headless", ...(one["--model"] ? { model: one["--model"] } : {}), ...(one["--session-id"] ? { sessionId: one["--session-id"] } : {}) }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION }, 35_000);
+    const reply = await hub.request({ t: "start", peer, args: { mode, ...(one["--model"] ? { model: one["--model"] } : {}), ...(one["--session-id"] ? { sessionId: one["--session-id"] } : {}) }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION }, 35_000);
     if (!reply.ok) fail(reply.error);
-    console.log(reply.already ? `${peer} is already attached` : `${peer} attached (headless); use ahub say @${peer} and the console for approvals`);
+    if (mode === "tui") {
+      if (reply.already) return console.log("qwen is already attached (its TUI is running); use that terminal");
+      if (reply.adopted) return console.log("qwen: the hub read on from its saved position; the Qwen terminal it was driving is still running");
+      launch = reply.launch;
+    } else console.log(reply.already ? `${peer} is already attached` : `${peer} attached (headless); use ahub say @${peer} and the console for approvals`);
   } finally { hub.close(); }
+  if (mode !== "tui") return;
+  const verified = verifiedLaunch(launch);
+  if (!verified) return fail("Qwen TUI launch metadata was not verified");
+  // The daemon's launch env carries only the peer marker: Qwen runs in the person's own terminal and needs their PATH, HOME (its settings and sessions) and the key its provider
+  // names, none of which the daemon may copy. So the person's environment is the base and the daemon's marker goes over it. (Measured: without this the exec found no `qwen`.)
+  // That terminal may itself be inside another agent (a Claude or Codex shell): its vendor markers and every hub marker but AGENTHUB_HOME are dropped, so Qwen and its hub MCP
+  // server never carry another peer's identity, launch id or mode.
+  const person = Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith("AGENTHUB_") || name === "AGENTHUB_HOME"));
+  const env = { ...peerChildEnv(peer, person), ...verified.env };
+  delete env.AGENTHUB_RECOVERY_OPERATION; delete env.AGENTHUB_UNATTENDED;
+  console.error("Qwen runs in this terminal, driven by the hub through its dual-output files. Limits: a hub deny ends the turn without an answer, and a stalled turn is stopped only by pressing Esc here.");
+  return execWithEnv(verified.cmd, verified.args, env);
 }

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

@@ -10,11 +10,19 @@ export function previewQwen(ctx: NativePreviewContext) {
   let launch: Launch;
   const mode = value("--mode") ?? "headless", model = value("--model");
   const adapter = ctx.definition;
-  if (!(adapter.start.forms as readonly string[]).includes(mode)) throw new Error("Qwen TUI is not offered before verification");
+  if (!["headless", "tui"].includes(mode)) throw new Error("unknown Qwen mode");
   for (let i = 0; i < args.length; i += 2) if (!["--model", "--mode", "--session-id"].includes(args[i]!) || !args[i + 1]) throw new Error("unknown Qwen option");
   const sessionId = value("--session-id");
   if (sessionId !== undefined && !adapter.session.crashIdentity?.({ sessionId }).sessionId) throw new Error("invalid Qwen session identity");
   if (sessionId) unresolved.push({ field: "sessionId", reason: "requested through ACP session/load at start; preview does not load or expose it" });
+  if (mode === "tui") {
+    // The TUI's argv is built by the daemon from the files it prepares; the preview names the shape and the compat entry, never a path or the MCP config contents.
+    const [bin = "qwen", ...prefix] = nativeCommand(config.qwen_cmd, ["qwen"]).filter(word => word !== "--acp");
+    launch = { cmd: bin, args: [...prefix, "--input-file", "<state dir>/qwen/qwen-dual/input.jsonl", "--json-file", "<state dir>/qwen/qwen-dual/events.jsonl", "--mcp-config", "<state dir>/qwen/qwen-dual/mcp.json", "--approval-mode", "default", ...(model ? ["--model", REDACTED] : []), ...(sessionId ? ["-r", REDACTED] : [])] };
+    unresolved.push({ field: "files", reason: "the daemon prepares the input and event files (0600) when the start is admitted; preview creates nothing" });
+    unresolved.push({ field: "nativeIdentity", reason: `Qwen Code (${describe("qwen-dual")}) is checked before the start and again from its session_start event; preview starts nothing` });
+    return finishPreview(ctx, launch, envNames, unresolved, undefined);
+  }
   launch = adapter.start.launch!({ instance: tool, form: "headless", projectRoot: cwd, stateDir, entrypoint: join(cliDir, "main.js"),
     userArgs: [], unattended: false, env: {}, preview: true, nativeCommand: nativeCommand(config.qwen_cmd, ["qwen", "--acp"]), model: model ? REDACTED : undefined });
   unresolved.push({ field: "nativeIdentity", reason: `Qwen Code (${describe("qwen")}) identity and permission modes are checked at ACP initialization; preview starts nothing` });

package/src/adapters/definitions/native-factories.ts

@@ -24,6 +24,13 @@ export function createJcode(ctx: CreateContext): PeerAdapter {
   return new JcodePeer(ctx.daemon.jcode);
 }
 
+export function createQwenDual(ctx: CreateContext): PeerAdapter {
+  if (!("qwenDual" in ctx.daemon)) throw new Error("Qwen TUI requires its dual-output transport options");
+  if (ctx.permission === "read-only") throw new Error("Qwen has no verified read-only permission mapping");
+  const { QwenDualPeer } = require("../qwen-dual.ts") as typeof import("../qwen-dual.ts");
+  return new QwenDualPeer(ctx.instance, ctx.daemon.qwenDual);
+}
+
 export function createPi(ctx: CreateContext): PeerAdapter {
   if (!("pi" in ctx.daemon)) throw new Error("Pi requires its Pi transport options");
   if (ctx.permission === "read-only") throw new Error("Pi has no verified read-only permission mapping");
@@ -71,6 +78,7 @@ export function createClaudeImplementer(ctx: CreateContext): PeerAdapter {
 export const DAEMON_PORTS = {
   "codex-appserver": (options: Extract<DaemonPorts, { codex: unknown }>["codex"]) => ({ codex: options }),
   acp: (options: Extract<DaemonPorts, { acp: unknown }>["acp"]) => ({ acp: options }),
+  "qwen-dual": (options: Extract<DaemonPorts, { qwenDual: unknown }>["qwenDual"]) => ({ qwenDual: options }),
   "owned-acp": (options: Extract<DaemonPorts, { jcode: unknown }>["jcode"]) => ({ jcode: options }),
   "pi-rpc": (options: Extract<DaemonPorts, { pi: unknown }>["pi"]) => ({ pi: options }),
   "local-worker": (options: Extract<DaemonPorts, { local: unknown }>["local"]) => ({ local: options }),

package/src/adapters/definitions/native-recovery.ts

@@ -82,6 +82,14 @@ export const JCODE_RECOVERY_SESSION: SessionPolicy = {
 export const QWEN_RECOVERY_SESSION: SessionPolicy = {
   legacyTargetSupport: { file: "src/hub/peer-catalog.ts", exportName: "OPTIONAL_PEERS", refusal: "target does not support Qwen; end Qwen and make a new plan, or choose a supporting target; runtimes unchanged" },
   restoreArgs: peer => ({ ...startupArgs(peer), ...(peer.sessionId ? { "session-id": peer.sessionId } : {}) }),
+  // #286 Part 3: the Qwen TUI belongs to the person's terminal. It is never restored as a headless worker; `ahub qwen --mode tui` resumes it (qwen -r <session>) from its saved offset.
+  // Worded and shaped unlike Kimi's refusal on purpose: the `kimi-recovery-tui-fence` seed anchors on that exact first line and must still match once.
+  recoveryRefusal: (peer, phase = "plan") => {
+    if (peer.args?.mode !== "tui") return undefined;
+    return phase === "restore"
+      ? "Qwen's own terminal cannot be restored as a headless worker; end it in that terminal and make a new recovery plan"
+      : "qwen: its own terminal has no automatic restore; end it in that terminal, then make a new recovery plan (restart it with ahub qwen --mode tui, which resumes its session)";
+  },
 };
 
 /** Fixed legacy native probes: callers retain their existing source-text capability checks. */

package/src/adapters/definitions/qwen.ts

@@ -7,6 +7,7 @@ import { AcpPeer } from "../acp.ts";
 import type { AdapterDefinition } from "../registry-types.ts";
 import { buildQwenLaunch, qwenSessionId } from "./qwen-native.ts";
 import { shellQuote } from "../../cli/shell-quote.ts";
+import { createQwenDual } from "./native-factories.ts";
 
 /** Production Qwen policy. Legacy AcpPeer callers opt in separately through qwen025. */
 export const QWEN_DEFINITION: AdapterDefinition = {
@@ -27,10 +28,12 @@ export const QWEN_DEFINITION: AdapterDefinition = {
     conductorStartable: true,
     hubSwitches: [],
     ownedFlags: [],
-    preflight: request => request.form !== undefined && request.form !== "headless"
-      ? "Qwen TUI is not offered before its native verification; use ahub qwen --mode headless" : undefined,
+    // The TUI (#286 Part 3) is explicit only: forms stays headless, so Qwen never becomes a start-mode peer and the hub never opens it by itself.
+    preflight: request => request.form !== undefined && request.form !== "headless" && request.form !== "tui"
+      ? "unknown Qwen mode; usage: ahub qwen [--mode headless|tui]" : undefined,
+    createTui: createQwenDual,
     launch: context => {
-      if (context.form !== "headless") throw new Error("Qwen TUI is not offered before its native verification; use ahub qwen --mode headless");
+      if (context.form !== "headless") throw new Error("the Qwen TUI is launched from the files the daemon prepares; use ahub qwen --mode tui");
       const launch = buildQwenLaunch(context.nativeCommand ?? ["qwen", "--acp"], context.model);
       const argv = [launch.cmd, ...launch.args];
       return { ...launch, metadata: { packageEntrypoint: context.entrypoint, argv, command: argv.map(shellQuote).join(" "), env: {} } };
@@ -68,7 +71,7 @@ export const QWEN_DEFINITION: AdapterDefinition = {
   turnEnd: "adapter",
   budget: { account: "qwen" },
   capabilities: { watch: true },
-  cli: { command: "qwen", entry: { lifecycleAdmission: true, execute: runQwenEntry }, preview: previewQwen, usage: [["ahub qwen [--mode headless] [--model <alias>] [--session-id <id>] [--print-command]", `start optional Qwen Code ACP (${describe("qwen")}; roster.qwen, default off)`]], launchConfigKeys: ["qwen_cmd"], startWords: () => ["qwen"] },
+  cli: { command: "qwen", entry: { lifecycleAdmission: true, execute: runQwenEntry }, preview: previewQwen, usage: [["ahub qwen [--mode headless|tui] [--model <alias>] [--session-id <id>] [--print-command]", `start optional Qwen Code ACP (${describe("qwen")}; roster.qwen, default off); --mode tui runs Qwen's own TUI in this terminal, driven through its dual-output files (${describe("qwen-dual")}); a hub deny ends the turn without an answer and a stalled turn is stopped with Esc in the Qwen terminal`]], launchConfigKeys: ["qwen_cmd"], startWords: () => ["qwen"] },
   display: QWEN_DISPLAY,
   hooks: { recallPlatform: "qwen" },
 };