@adhdev/daemon-core 0.9.82-rc.287 → 0.9.82-rc.289

package/dist/providers/spec/fsm-types.d.ts

@@ -58,6 +58,20 @@ export interface FsmTransition {
     /** Human label for the debugger. */
     label?: string;
 }
+/**
+ * Declarative "trust this folder before spawn" config. Some agent CLIs gate the
+ * first run in a new folder behind an interactive trust prompt and persist the
+ * answer as a string array in a JSON settings file. Declaring this lets the
+ * engine add the workspace path to that array before spawn so the prompt never
+ * appears — the robust alternative to detecting and auto-clicking the modal.
+ * CLIs without such a gate omit this field and the engine does nothing.
+ */
+export interface PreLaunchTrust {
+    /** Path to the CLI's JSON settings file. A leading `~` expands to $HOME. */
+    settings_path: string;
+    /** Key of the string-array of trusted folder paths within that file. */
+    key: string;
+}
 export interface CliSpecV4 {
     $schema: 'adhdev:cli/spec@4';
     id: string;
@@ -81,6 +95,14 @@ export interface CliSpecV4 {
     send_on_spawn?: string[];
     /** Delay (ms) after spawn before writing `send_on_spawn`. Default 250. */
     send_on_spawn_delay_ms?: number;
+    /**
+     * Optional pre-spawn folder-trust step. When present, the engine adds the
+     * launch workspace path to the declared trusted-folders array before
+     * spawning, so a CLI that gates first run on a "trust this folder?" prompt
+     * (e.g. antigravity's `agy`) starts trusted and never blocks. Omitted for
+     * CLIs without such a gate. See pre-launch-trust.ts.
+     */
+    pre_launch_trust?: PreLaunchTrust;
     send_message: {
         submit_key: string;
         delay_ms_before_submit?: number;

package/dist/providers/spec/pre-launch-trust.d.ts

@@ -0,0 +1,16 @@
+import type { PreLaunchTrust } from './fsm-types.js';
+/**
+ * Idempotently add `workingDir` (realpath) to the trusted-folders array named
+ * by `trust.key` inside the JSON settings file at `trust.settings_path`.
+ *
+ * - Creates the file (and parent dir) if missing.
+ * - Preserves all other settings; only the trust array is touched.
+ * - No-ops if the path is already present.
+ * - Best-effort: any failure is logged and swallowed. A failed pre-trust must
+ *   not block the launch — the worst case is the old behavior (the FSM still
+ *   detects the trust modal as an approval state), not a crash.
+ *
+ * Returns the path that was added (realpath), or null if nothing changed /
+ * an error occurred — purely so callers/tests can assert the effect.
+ */
+export declare function applyPreLaunchTrust(trust: PreLaunchTrust, workingDir: string): string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.287",
+  "version": "0.9.82-rc.289",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -46,7 +46,7 @@
   "author": "vilmire",
   "license": "AGPL-3.0-or-later",
   "dependencies": {
-    "@adhdev/mesh-shared": "0.9.82-rc.287",
+    "@adhdev/mesh-shared": "0.9.82-rc.289",
     "@adhdev/session-host-core": "*",
     "@agentclientprotocol/sdk": "^0.16.1",
     "ajv": "^8.20.0",

package/src/commands/router.ts

@@ -6965,6 +6965,32 @@ export class DaemonCommandRouter {
                     const mesh = meshRecord?.mesh;
                     const node = mesh?.nodes?.find((n: any) => n.id === nodeId || n.nodeId === nodeId);
 
+                    // Guard: refuse to remove the coordinator's OWN local base node
+                    // (same machine, NOT a worktree). Removing it breaks live mesh
+                    // membership — the coordinator can no longer be reached and has
+                    // to be restarted. Worktree clones are always safe to remove;
+                    // only the non-worktree node bound to this daemon is protected.
+                    // An explicit force:true overrides for intentional mesh teardown.
+                    if (node && !args?._meshDirectDispatch && node.isLocalWorktree !== true && args?.force !== true) {
+                        const nodeDaemonId = typeof node.daemonId === 'string' ? node.daemonId.trim() : '';
+                        const nodeMachineId = readMeshNodeMachineId(node as Record<string, unknown>) || '';
+                        const selfDaemonId = this.deps.statusInstanceId || '';
+                        const selfMachineId = (() => { try { return loadConfig().machineId || ''; } catch { return ''; } })();
+                        const isCoordinatorBaseNode =
+                            (!!selfDaemonId && (nodeDaemonId === selfDaemonId || nodeMachineId === selfDaemonId))
+                            || (!!selfMachineId && (nodeDaemonId === selfMachineId || nodeMachineId === selfMachineId));
+                        if (isCoordinatorBaseNode) {
+                            return {
+                                success: false,
+                                removed: false,
+                                code: 'mesh_remove_coordinator_base_node_protected',
+                                error: `Refusing to remove the coordinator's own base node '${typeof node.workspace === 'string' ? node.workspace : nodeId}'. `
+                                    + `It is the local non-worktree node bound to this coordinator daemon; removing it breaks live mesh membership and forces a restart.`,
+                                recoveryHint: 'Remove worktree clone nodes instead, or pass force:true only if you are intentionally tearing down this mesh and accept that the coordinator must be re-registered/restarted.',
+                            };
+                        }
+                    }
+
                     const sessionCleanupMode = this.normalizeMeshSessionCleanupMode(
                         args?.sessionCleanupMode ?? args?.session_cleanup_mode ?? mesh?.policy?.sessionCleanupOnNodeRemove,
                     );

package/src/mesh/mesh-events-coordinator.ts

@@ -12,7 +12,7 @@ import { createSessionDelivery, markSessionDeliveriesTerminal, updateSessionDeli
 import { MeshRuntimeStore } from './mesh-runtime-store.js';
 import { queuePendingMeshCoordinatorEvent, drainPendingMeshCoordinatorEvents } from './mesh-events-pending.js';
 import type { PendingMeshCoordinatorEvent } from './mesh-events-pending.js';
-import { resolveWorkerDelegateRouting, recordUnroutableDelegateEvent } from './mesh-routing.js';
+import { resolveWorkerDelegateRouting, recordUnroutableDelegateEvent, isUnroutableDelegateRejection } from './mesh-routing.js';
 import { resolveDelegatedWorkerAutoApprove } from '../repo-mesh-types.js';
 import {
     findRecentTerminalLedgerEvidence,
@@ -1446,11 +1446,16 @@ export function handleMeshForwardEvent(components: DaemonComponents, payload: Re
     if (!isMeshCoordinatorEvent(eventName)) {
         return { success: false, error: 'unsupported mesh event' };
     }
-    const meshId = readNonEmptyString(payload.meshId);
-    if (!meshId) return { success: false, error: 'meshId required' };
-
     const nodeId = readNonEmptyString(payload.nodeId);
     const workspace = readNonEmptyString(payload.workspace);
+
+    // The fallback worker-forward path (forwardUnresolvedDelegateEvent) cannot resolve a
+    // mesh id locally on the remote worker, so it forwards the event with workspace only.
+    // The coordinator hosting the mesh CAN resolve it: recover the mesh id by workspace
+    // when the payload doesn't carry one.
+    const meshId = readNonEmptyString(payload.meshId)
+        || (workspace ? readNonEmptyString(getCachedMeshByWorkspace(workspace)?.id) : '');
+    if (!meshId) return { success: false, error: 'meshId required' };
     const nodeLabel = nodeId ? `Node '${nodeId}'` : workspace ? `Agent at ${workspace}` : 'Remote agent';
     const relayModalMessage = readNonEmptyString(payload.modalMessage);
     const relayModalButtons = Array.isArray(payload.modalButtons)
@@ -1493,6 +1498,67 @@ export function handleMeshForwardEvent(components: DaemonComponents, payload: Re
     });
 }
 
+// ---------------------------------------------------------------------------
+// Worker-side fallback forward for unresolved-mesh delegates.
+//
+// A REMOTE worker daemon that is being P2P-remote-controlled by a coordinator is
+// NOT a member of the coordinator's mesh — it has no local mesh record. So when its
+// completion event reaches the forwarder, resolveWorkerDelegateRouting() resolves the
+// coordinator anchor (meshCoordinatorDaemonId) from the worker envelope but cannot
+// resolve the mesh id (neither meshNodeFor nor a workspace→mesh lookup yields one) and
+// returns isDelegate=false / mesh_unresolved. Before this fallback the event was dropped
+// (delivery_unroutable) and only recovered later when the coordinator happened to pull
+// the worker's queue — which it can't, because the worker never queued an unroutable
+// event. Live symptom: `WARN [MeshEvents] delivery_unroutable: ... mesh unresolved`.
+//
+// The fix: the routing object still carries coordinatorDaemonId. Forward the raw event
+// straight to that coordinator daemon over P2P (mesh_forward_event). The coordinator
+// hosts the mesh, so it recovers the mesh id by workspace in handleMeshForwardEvent and
+// injects/queues it normally. meshId is intentionally omitted from the payload (the
+// worker has none); workspace is the routing anchor the coordinator resolves from.
+//
+// No loop / no double-delivery:
+//  - This only fires on the WORKER (the coordinator-own session is rejected by the
+//    resolver before reaching here), and the coordinator merely injects — it does not
+//    re-enter this forwarder for the relayed event.
+//  - It fires only when the normal queue path did NOT run (isDelegate=false), so the
+//    event is never both queued locally and forwarded.
+//
+// Returns true when the event was handed off to the coordinator daemon (so the caller
+// skips the delivery_unroutable diagnostic); false when no fallback was possible.
+function forwardUnresolvedDelegateEvent(
+    components: DaemonComponents,
+    routing: ReturnType<typeof resolveWorkerDelegateRouting>,
+    event: Record<string, unknown>,
+): boolean {
+    const coordinatorDaemonId = readNonEmptyString(routing.coordinatorDaemonId);
+    if (!coordinatorDaemonId) return false;
+    if (!components.dispatchMeshCommand) return false;
+
+    const eventName = readNonEmptyString(event.event);
+    if (!eventName) return false;
+
+    // Flat payload mirroring buildForwardPayloadFromPending / what handleMeshForwardEvent
+    // reads. meshId is omitted on purpose — the worker can't resolve it; the coordinator
+    // recovers it from workspace. nodeId/workspace come from the worker envelope so the
+    // coordinator can name and locate the node.
+    const payload: Record<string, unknown> = {
+        ...event,
+        event: eventName,
+        nodeId: readNonEmptyString(routing.nodeId) || readNonEmptyString(event.meshNodeId) || undefined,
+        workspace: readNonEmptyString(routing.workspace) || readNonEmptyString(event.workspace) || undefined,
+    };
+
+    Promise.resolve(components.dispatchMeshCommand(coordinatorDaemonId, 'mesh_forward_event', payload))
+        .catch((e: any) => {
+            // The coordinator may be momentarily unreachable; the diagnostic was already
+            // skipped, so leave a trace here so an operator can see the relay attempt failed.
+            LOG.warn('MeshEvents', `Fallback forward of ${eventName} to coordinator ${coordinatorDaemonId} failed: ${e?.message || e}`);
+        });
+    LOG.info('MeshEvents', `Fallback-forwarded ${eventName} for unresolved-mesh worker at ${routing.workspace || '(no workspace)'} to coordinator daemon ${coordinatorDaemonId}`);
+    return true;
+}
+
 export function setupMeshEventForwarding(components: DaemonComponents) {
     components.instanceManager.onEvent((event) => {
         // --- Coordinator idle auto-flush (fast path) ---
@@ -1572,10 +1638,19 @@ export function setupMeshEventForwarding(components: DaemonComponents) {
             getMeshByWorkspace: (workspace) => getCachedMeshByWorkspace(workspace),
         });
         if (!routing.isDelegate) {
-            // R4: a worker that presented a valid envelope but resolved to no mesh used to be
-            // dropped silently. Leave a fail-loud diagnostic so the missing completion is
-            // traceable. Benign non-delegate rejections (not_cli / no_workspace / etc.) are
-            // no-ops inside recordUnroutableDelegateEvent.
+            // Fallback: a REMOTE worker that isn't a member of the coordinator's mesh can't
+            // resolve a mesh id locally (mesh_unresolved), but it still carries the coordinator
+            // daemon anchor. Forward the event straight to that coordinator over P2P instead of
+            // dropping it — the coordinator hosts the mesh and recovers the id by workspace.
+            if (isUnroutableDelegateRejection(routing)
+                && forwardUnresolvedDelegateEvent(components, routing, event)) {
+                return;
+            }
+            // R4: a worker that presented a valid envelope but resolved to no mesh (and could
+            // not be fallback-forwarded — e.g. no coordinator anchor) used to be dropped
+            // silently. Leave a fail-loud diagnostic so the missing completion is traceable.
+            // Benign non-delegate rejections (not_cli / no_workspace / etc.) are no-ops inside
+            // recordUnroutableDelegateEvent.
             recordUnroutableDelegateEvent(routing, event.event);
             return;
         }

package/src/mesh/mesh-routing.ts

@@ -82,10 +82,13 @@ export function resolveWorkerDelegateRouting(
     const sessionId = readNonEmptyString(instanceId);
     let workspace = '';
     let coordinatorDaemonId = '';
+    // Runtime node-id stamp, surfaced even on rejection so the unresolved-mesh fallback
+    // forward can name the worker node for the coordinator.
+    let runtimeNodeId = '';
     const reject = (rejectionReason: WorkerDelegateRejectionReason): WorkerDelegateRouting => ({
         isDelegate: false,
         meshId: '',
-        nodeId: '',
+        nodeId: runtimeNodeId,
         nodeLabel: '',
         coordinatorDaemonId,
         workspace,
@@ -102,6 +105,7 @@ export function resolveWorkerDelegateRouting(
 
     const settings = readSettings(state);
     coordinatorDaemonId = readNonEmptyString(settings.meshCoordinatorDaemonId);
+    runtimeNodeId = readNonEmptyString(settings.meshNodeId);
 
     // A coordinator session (meshCoordinatorFor set) is only treated as a worker delegate
     // when it is itself the target of an active direct dispatch — otherwise its own events
@@ -138,7 +142,6 @@ export function resolveWorkerDelegateRouting(
     if (!meshId) return reject('mesh_unresolved');
 
     const targetNode = mesh?.nodes?.find((n: any) => n.workspace === workspace);
-    const runtimeNodeId = readNonEmptyString(settings.meshNodeId);
     const nodeId = readNonEmptyString(targetNode?.id) || runtimeNodeId;
     const nodeLabel = targetNode
         ? `Node '${targetNode.id}'`

package/src/providers/spec/fsm-driver.ts

@@ -34,6 +34,7 @@ import {
     initialState, stateById, statusForState, outgoingTransitions,
 } from './fsm-types.js';
 import { loadFsmSpec } from './fsm-loader.js';
+import { applyPreLaunchTrust } from './pre-launch-trust.js';
 import type { Control, DelegateTrigger } from './types.js';
 import { LOG } from '../../logging/logger.js';
 
@@ -245,6 +246,12 @@ export class FsmDriver implements ISpecDriver {
         this.currentStateId = init.id;
         this.stateEnteredAt = now;
         this.prevStateAt = now;
+        // Pre-trust the workspace before spawning so a first-run folder-trust
+        // prompt never appears (best-effort; failures fall back to the FSM's
+        // trust-modal detection). Only runs for specs that declare it.
+        if (this.spec.pre_launch_trust) {
+            applyPreLaunchTrust(this.spec.pre_launch_trust, this.opts.workingDir);
+        }
         this.adapter.start();
         // Prime focus-gated TUIs (see CliSpecV4.send_on_spawn). Written once,
         // shortly after spawn, so the input stream is awake before the first

package/src/providers/spec/fsm-loader.ts

@@ -36,6 +36,16 @@ export function validateFsmSpec(raw: unknown): string[] {
     if (!spec.binary) errs.push('binary is required');
     if (!spec.send_message?.submit_key) errs.push('send_message.submit_key is required');
 
+    if (spec.pre_launch_trust !== undefined) {
+        const t = spec.pre_launch_trust as { settings_path?: unknown; key?: unknown };
+        if (!t || typeof t !== 'object' || Array.isArray(t)) {
+            errs.push('pre_launch_trust must be an object');
+        } else {
+            if (typeof t.settings_path !== 'string' || !t.settings_path) errs.push('pre_launch_trust.settings_path is required');
+            if (typeof t.key !== 'string' || !t.key) errs.push('pre_launch_trust.key is required');
+        }
+    }
+
     if (!Array.isArray(spec.states) || spec.states.length === 0) {
         errs.push('states[] must be a non-empty array');
         return errs;

package/src/providers/spec/fsm-types.ts

@@ -118,6 +118,21 @@ export interface FsmTransition {
     label?: string;
 }
 
+/**
+ * Declarative "trust this folder before spawn" config. Some agent CLIs gate the
+ * first run in a new folder behind an interactive trust prompt and persist the
+ * answer as a string array in a JSON settings file. Declaring this lets the
+ * engine add the workspace path to that array before spawn so the prompt never
+ * appears — the robust alternative to detecting and auto-clicking the modal.
+ * CLIs without such a gate omit this field and the engine does nothing.
+ */
+export interface PreLaunchTrust {
+    /** Path to the CLI's JSON settings file. A leading `~` expands to $HOME. */
+    settings_path: string;
+    /** Key of the string-array of trusted folder paths within that file. */
+    key: string;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // CliSpecV4 — the v4 runtime spec
 // ─────────────────────────────────────────────────────────────────────────────
@@ -145,6 +160,14 @@ export interface CliSpecV4 {
     send_on_spawn?: string[];
     /** Delay (ms) after spawn before writing `send_on_spawn`. Default 250. */
     send_on_spawn_delay_ms?: number;
+    /**
+     * Optional pre-spawn folder-trust step. When present, the engine adds the
+     * launch workspace path to the declared trusted-folders array before
+     * spawning, so a CLI that gates first run on a "trust this folder?" prompt
+     * (e.g. antigravity's `agy`) starts trusted and never blocks. Omitted for
+     * CLIs without such a gate. See pre-launch-trust.ts.
+     */
+    pre_launch_trust?: PreLaunchTrust;
     send_message: {
         submit_key: string;
         delay_ms_before_submit?: number;

package/src/providers/spec/pre-launch-trust.ts

@@ -0,0 +1,104 @@
+/**
+ * pre_launch_trust — generic, declarative "trust this folder before spawn"
+ * step for spec-backed CLI providers.
+ *
+ * Some agent CLIs (the canonical case is antigravity's `agy`) gate the first
+ * run in any new folder behind an interactive "Do you trust the files in this
+ * folder?" prompt. Under the v4 FSM spec path the daemon spawns the binary
+ * directly in the worktree (`cwd = workingDir`), so every fresh worktree —
+ * every delegated mesh task running in its own clone — hits that prompt and
+ * stalls until something clicks through it. (The legacy bash-wrapper symlink
+ * trick in provider.v1.json's `spawn` block is not used by SpecCliAdapter.)
+ *
+ * These CLIs persist their trusted folders in a JSON settings file as a string
+ * array. If we add the workspace path to that array *before* spawning, the
+ * prompt never appears. That is the most robust fix: the agent runs trusted
+ * from the first frame instead of relying on the FSM to detect and auto-click
+ * a modal whose wording or position could drift.
+ *
+ * The mechanism is intentionally data-driven and CLI-agnostic. A spec declares
+ * the settings file and the array key; the engine does the rest. CLIs that do
+ * not have a folder-trust gate simply omit `pre_launch_trust` and this code
+ * never runs for them — so other providers (claude/codex/hermes) are untouched.
+ */
+'use strict';
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import type { PreLaunchTrust } from './fsm-types.js';
+import { LOG } from '../../logging/logger.js';
+
+/** Expand a leading `~` to the user's home directory. */
+function expandHome(p: string): string {
+    if (p === '~') return os.homedir();
+    if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
+    return p;
+}
+
+/**
+ * Resolve the canonical, real (symlink-followed) absolute form of the
+ * workspace path. Trust files store realpaths, and matching has to be exact, so
+ * we normalise the same way the CLI does. Falls back to the raw path if the
+ * directory can't be stat'd (e.g. it does not exist yet).
+ */
+function realWorkspacePath(workingDir: string): string {
+    try {
+        return fs.realpathSync(workingDir);
+    } catch {
+        return path.resolve(workingDir);
+    }
+}
+
+/**
+ * Idempotently add `workingDir` (realpath) to the trusted-folders array named
+ * by `trust.key` inside the JSON settings file at `trust.settings_path`.
+ *
+ * - Creates the file (and parent dir) if missing.
+ * - Preserves all other settings; only the trust array is touched.
+ * - No-ops if the path is already present.
+ * - Best-effort: any failure is logged and swallowed. A failed pre-trust must
+ *   not block the launch — the worst case is the old behavior (the FSM still
+ *   detects the trust modal as an approval state), not a crash.
+ *
+ * Returns the path that was added (realpath), or null if nothing changed /
+ * an error occurred — purely so callers/tests can assert the effect.
+ */
+export function applyPreLaunchTrust(trust: PreLaunchTrust, workingDir: string): string | null {
+    const settingsPath = expandHome(trust.settings_path);
+    const key = trust.key;
+    const real = realWorkspacePath(workingDir);
+    try {
+        let parsed: Record<string, unknown> = {};
+        if (fs.existsSync(settingsPath)) {
+            const text = fs.readFileSync(settingsPath, 'utf8');
+            if (text.trim().length > 0) {
+                const json = JSON.parse(text);
+                if (json && typeof json === 'object' && !Array.isArray(json)) {
+                    parsed = json as Record<string, unknown>;
+                }
+            }
+        }
+
+        const existing = parsed[key];
+        const list: string[] = Array.isArray(existing)
+            ? existing.filter((v): v is string => typeof v === 'string')
+            : [];
+
+        if (list.includes(real)) {
+            LOG.debug('pre-launch-trust', `[${trust.settings_path}] ${real} already trusted — no change`);
+            return null;
+        }
+
+        list.push(real);
+        parsed[key] = list;
+
+        fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+        fs.writeFileSync(settingsPath, `${JSON.stringify(parsed, null, 2)}\n`, 'utf8');
+        LOG.info('pre-launch-trust', `pre-trusted workspace in ${trust.settings_path} (key="${key}")`);
+        return real;
+    } catch (err) {
+        LOG.warn('pre-launch-trust', `failed to pre-trust workspace in ${trust.settings_path}: ${(err as Error).message}`);
+        return null;
+    }
+}

package/src/providers/types/interactive-prompt.ts

@@ -137,7 +137,14 @@ export interface ClaudeInteractiveTuiPage {
   header?: string;
 }
 
-const CLAUDE_TUI_OPTION_PATTERN = /^\s*(?:[❯›>]\s*)?(\d+)\.\s+(.+?)\s*$/;
+// Option rows look like "❯ 1. Label". The multi-select picker additionally
+// draws a checkbox marker that can sit before or after the number
+// ("❯ [ ] 1. Label" / "❯ 1. [x] Label" / "☐ 1. Label"); the optional,
+// non-capturing checkbox groups absorb it so the captured label stays clean.
+const CLAUDE_TUI_OPTION_CHECKBOX = '(?:\\[[ xX]\\]|[☐☒◻◼])';
+const CLAUDE_TUI_OPTION_PATTERN = new RegExp(
+  `^\\s*(?:[❯›>]\\s*)?(?:${CLAUDE_TUI_OPTION_CHECKBOX}\\s*)?(\\d+)\\.\\s+(?:${CLAUDE_TUI_OPTION_CHECKBOX}\\s*)?(.+?)\\s*$`,
+);
 
 function claudeTuiQuestionHeaders(screenText: string): string[] {
   const navLine = screenText.split(/\r?\n/).find(line => line.includes('✔ Submit') && /[☐☒]/.test(line));
@@ -155,6 +162,41 @@ function isClaudeTuiSelectFooter(text: string): boolean {
   return /Enter to select/i.test(text) && /Esc to cancel/i.test(text);
 }
 
+/**
+ * Decide whether a captured claude-cli AskUserQuestion TUI page is multi-select.
+ *
+ * The original heuristic only matched the footer hint `/Space to select|toggle
+ * selections/i`. That string drifts between claude-cli versions, so when it
+ * changed the dashboard silently fell back to multiSelect:false and rendered
+ * single-select (radio) controls even though the on-screen picker showed
+ * checkboxes — the user could not check more than one box. (The CLI's own
+ * terminal still rendered `[ ]` correctly because it never depends on this
+ * parse.)
+ *
+ * Make detection robust by ALSO recognising the actual checkbox markers the
+ * multi-select picker draws on its option rows (`[ ]` / `[x]` / `☐` / `☒` /
+ * `◻` / `◼`). Single-select rows are drawn with a `❯`/number cursor only and
+ * carry none of these box glyphs, so their presence is a reliable signal. The
+ * broadened footer patterns ("Space to", "toggle", "select multiple") are kept
+ * as a secondary signal for layouts that render markers differently.
+ */
+function detectClaudeTuiMultiSelect(screenText: string): boolean {
+  if (/Space to (?:select|toggle)|toggle selection|select multiple|select all that apply/i.test(screenText)) {
+    return true;
+  }
+  // A checkbox glyph sitting in front of a NUMBERED option row only appears in
+  // the multi-select picker (e.g. "❯ [ ] 1. TypeScript" / "☐ 2. Python"). We
+  // require the numbered "N." option marker so we don't false-positive on the
+  // `✔ Submit` nav line (per-question answered-state ☐/☒) or on the headerless
+  // variant where the QUESTION line itself begins with `☐ ` (single-select).
+  const optionCheckbox = /^\s*(?:[❯›>]\s*)?(?:\[[ xX]\]|[☐☒◻◼])\s*\d+\.\s+\S/;
+  for (const line of screenText.split(/\r?\n/)) {
+    if (line.includes('✔ Submit')) continue; // header/nav line
+    if (optionCheckbox.test(line)) return true;
+  }
+  return false;
+}
+
 function readClaudeHeaderLine(lines: string[], beforeIndex: number): string | undefined {
   for (let i = beforeIndex; i >= 0; i -= 1) {
     const candidate = lines[i].trim();
@@ -254,7 +296,7 @@ function parseClaudeHeaderlessInteractiveTuiQuestion(page: ClaudeInteractiveTuiP
     questionId: `q${index + 1}`,
     question,
     ...(header ? { header } : {}),
-    multiSelect: /Space to select|toggle selections/i.test(page.screenText),
+    multiSelect: detectClaudeTuiMultiSelect(page.screenText),
     options,
     ...(allowFreeform ? { allowFreeform: true } : {}),
   };
@@ -313,7 +355,7 @@ function parseClaudeInteractiveTuiQuestion(page: ClaudeInteractiveTuiPage, index
     questionId: `q${index + 1}`,
     question,
     ...(header ? { header } : {}),
-    multiSelect: /Space to select|toggle selections/i.test(page.screenText),
+    multiSelect: detectClaudeTuiMultiSelect(page.screenText),
     options,
     ...(allowFreeform ? { allowFreeform: true } : {}),
   };