mstro-app 0.5.1 → 0.5.6

package/server/services/plan/composer.ts

@@ -10,6 +10,7 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { getEtaProfileCached } from '../../cli/eta-estimator.js';
 import type { ToolUseEvent } from '../../cli/headless/index.js';
 import { ResilientRunner } from '../../cli/headless/resilient-runner.js';
 import { cleanupAttachments, preparePromptAndAttachments } from '../../cli/improvisation-attachments.js';
@@ -28,6 +29,21 @@ const PROMPT_TOOL_MESSAGES: Record<string, string> = {
   Bash: 'Running commands...',
 };
 
+/**
+ * Resolve the ETA quantile profile used by the planning indicator. Reads
+ * .mstro/history (chat improv movements) since planning-prompt durations
+ * cluster in the same range. Failures degrade silently to undefined — the
+ * indicator falls back to elapsed-only display.
+ */
+async function resolvePromptEtaProfile(workingDir: string): Promise<NonNullable<Awaited<ReturnType<typeof getEtaProfileCached>>> | undefined> {
+  try {
+    const profile = await getEtaProfileCached(join(workingDir, '.mstro', 'history'));
+    return profile ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function getPromptToolCompleteMessage(event: ToolUseEvent): string | null {
   const input = event.completeInput;
   if (!input) return null;
@@ -229,6 +245,7 @@ blocks: []                 # Use backlog-relative paths: backlog/IS-NNN.md
 review_gate: auto
 output_type: auto          # code = modify source files, document = produce written artifact, auto = infer
 output_file: null
+agents: []                 # Agent hints — see "agents field rules" below
 ---
 
 # IS-NNN: Title
@@ -268,6 +285,21 @@ Implementation guidance.
 - When output_type is \`document\`, "Files to Modify" entries are treated as references, not files to edit. The AI produces a document artifact and is reviewed on document quality.
 - When output_type is \`code\`, "Files to Modify" lists actual source files the AI must edit. The review gate verifies source files were changed.
 
+## agents field rules
+
+The \`agents\` field is a list of agent hints for the executing Claude Code session. The executor uses Claude Code's Task tool to delegate work to matching subagents in the user's \`.claude/agents/\` directory (project / global / bundled), with a fallback to the general-purpose agent when no match is found.
+
+- ALWAYS populate \`agents\` with the most relevant 1–4 agents for the work the issue describes. Empty arrays mean "no hints" — only use \`[]\` when no agent type plausibly applies (rare).
+- Entries can be specific agent file names (e.g. \`backend-architect\`, \`frontend-developer\`, \`code-reviewer\`, \`security-auditor\`) OR general role pointers the user's system can match (e.g. \`backend engineer\`, \`product designer\`, \`marketing\`). Prefer specific names — they resolve more reliably.
+- Match agents to the actual work, not the issue's surface topic. A "fix login button" issue is frontend work (\`frontend-developer\`); a "design login flow" issue is product/design (\`product-designer\`, \`ux-writer\`).
+- Common pairings:
+  - Code implementation: pick from \`frontend-developer\`, \`backend-architect\`, \`typescript-pro\`, \`python-pro\`, \`golang-pro\`, etc., based on stack
+  - UI/design work: \`ui-designer\`, \`product-designer\`, \`design-system-architect\`, \`ux-writer\`
+  - Data/DB: \`database-architect\`, \`database-optimizer\`, \`data-engineer\`, \`sql-pro\`
+  - Quality: pair an implementation agent with \`code-reviewer\`, \`test-automator\`, or \`security-auditor\` for sensitive issues
+  - Product/strategy: \`product-manager\`, \`product-marketing\`, \`business-analyst\`
+- YAML format: inline \`agents: [backend-architect, code-reviewer]\` or block list with \`-\` items both work.
+
 ## Epic creation rules
 
 - Create an EP-*.md file in ${cc.backlogPath} with type: epic and a children: [] field in front matter
@@ -287,11 +319,27 @@ User request: ${userPrompt}`;
     prepareAttachmentPrompt(ctx, enrichedPrompt, attachments, workingDir, cc.effectiveBoardId);
 
   const streamBoardId = cc.effectiveBoardId ?? null;
+  const etaProfile = await resolvePromptEtaProfile(workingDir);
+
+  // Tracks whether `planPromptResponse` has been broadcast. The web side
+  // treats this event as the authoritative completion signal — without it,
+  // the composer todo list stays stuck on a spinner. The finally block
+  // guarantees a completion broadcast even if the runner throws or exits
+  // through an unexpected path.
+  let responseSent = false;
+  const sendResponse = (response: string, success: boolean, error: string | null) => {
+    if (responseSent) return;
+    responseSent = true;
+    ctx.broadcastToAll({
+      type: 'planPromptResponse',
+      data: { response, success, error, boardId: streamBoardId },
+    });
+  };
 
   try {
     ctx.broadcastToAll({
       type: 'planPromptProgress',
-      data: { message: 'Starting project planning...', boardId: streamBoardId },
+      data: { message: 'Starting project planning...', boardId: streamBoardId, etaProfile },
     });
 
     const runner = new ResilientRunner({
@@ -339,15 +387,11 @@ User request: ${userPrompt}`;
       data: { message: 'Finalizing project plan...', boardId: streamBoardId },
     });
 
-    ctx.broadcastToAll({
-      type: 'planPromptResponse',
-      data: {
-        response: result.completed ? 'Prompt executed successfully.' : (result.error || 'Unknown error'),
-        success: result.completed,
-        error: result.error || null,
-        boardId: streamBoardId,
-      },
-    });
+    sendResponse(
+      result.completed ? 'Prompt executed successfully.' : (result.error || 'Unknown error'),
+      result.completed,
+      result.error || null,
+    );
 
     // Re-parse and broadcast updated state
     const updatedState = parsePlanDirectory(workingDir);
@@ -355,11 +399,19 @@ User request: ${userPrompt}`;
       ctx.broadcastToAll({ type: 'planStateUpdated', data: updatedState });
     }
   } catch (error) {
+    const errorMsg = error instanceof Error ? error.message : String(error);
     ctx.broadcastToAll({
       type: 'planError',
-      data: { error: error instanceof Error ? error.message : String(error), boardId: streamBoardId },
+      data: { error: errorMsg, boardId: streamBoardId },
     });
+    // Send a completion signal too — `planError` clears streaming on the web
+    // but doesn't set the response banner. Without this, the user sees a
+    // half-finished UI (no spinner, no message).
+    sendResponse(errorMsg, false, errorMsg);
   } finally {
     cleanupAttachments(workingDir, attachmentSessionId);
+    // Defense in depth: guarantee a completion broadcast for any control
+    // flow not covered above (process abort, unexpected throw types, etc.).
+    sendResponse('Prompt execution ended unexpectedly.', false, 'No completion signal');
   }
 }

package/server/services/plan/executor.ts

@@ -265,7 +265,6 @@ export class PlanExecutor extends EventEmitter {
   /** Run waves until done, paused, stopped, or stalled. */
   private async runWaveLoop(): Promise<'done' | 'stalled' | 'dead'> {
     let consecutiveZeroCompletions = 0;
-    const maxParallel = await getBoardMaxParallelAgents(this.context.pmDir, this.effectiveBoardId(), this.emitWarn);
 
     while (!this.shouldStop && !this.shouldPause) {
       const readyIssues = await this.pickReadyIssues();
@@ -274,6 +273,9 @@ export class PlanExecutor extends EventEmitter {
         return await this.hasDeadIssues() ? 'dead' : 'done';
       }
 
+      // Re-read on each wave so users can scale agents up/down mid-execution
+      // without restarting — the new value takes effect at the next wave boundary.
+      const maxParallel = await getBoardMaxParallelAgents(this.context.pmDir, this.effectiveBoardId(), this.emitWarn);
       const completedCount = await this.executeWave(readyIssues.slice(0, maxParallel));
 
       if (completedCount > 0) {

package/server/services/plan/issue-prompt-builder.ts

@@ -8,6 +8,7 @@
  */
 
 import { join } from 'node:path';
+import { type ResolvedAgent, resolveAgentHints } from './agent-resolver.js';
 import { resolveIsCodeTask } from './issue-classification.js';
 import type { Issue } from './types.js';
 
@@ -21,6 +22,41 @@ export interface IssuePromptOptions {
   outputPath: string;
 }
 
+/**
+ * Render the Agents section of an issue prompt. Splits resolved hints from
+ * unresolved ones so Claude knows which names are real subagents to delegate to
+ * via the Task tool, vs. role hints for which the user has no installed match.
+ */
+function renderAgentsSection(resolved: ResolvedAgent[]): string {
+  if (resolved.length === 0) return '';
+
+  const matched = resolved.filter(r => r.resolvedName);
+  const unmatched = resolved.filter(r => !r.resolvedName);
+
+  const lines: string[] = ['', '## Suggested Agents'];
+
+  if (matched.length > 0) {
+    lines.push('Delegate the relevant portions of this work to these subagents using the Task tool (subagent_type = the agent name). Use them as primary executors when the work matches their expertise:');
+    for (const r of matched) {
+      const desc = r.info?.description ? ` — ${r.info.description}` : '';
+      const labelHint = r.hint.toLowerCase() !== (r.resolvedName ?? '').toLowerCase()
+        ? ` (matched from "${r.hint}")`
+        : '';
+      lines.push(`- \`${r.resolvedName}\`${labelHint}${desc}`);
+    }
+  }
+
+  if (unmatched.length > 0) {
+    lines.push('');
+    lines.push('Role hints with no installed subagent match — use the general-purpose agent (or your best judgment) for work in these areas:');
+    for (const r of unmatched) {
+      lines.push(`- ${r.hint}`);
+    }
+  }
+
+  return `\n${lines.join('\n')}`;
+}
+
 /**
  * Build a self-contained prompt for one issue.
  * The resulting Claude Code session will work independently —
@@ -45,6 +81,8 @@ export function buildIssuePrompt(options: IssuePromptOptions): string {
     ? `\n## Predecessor Outputs\nRead these before starting — they contain context from upstream issues:\n${predecessorDocs.map(d => `- ${d}`).join('\n')}`
     : '';
 
+  const agentSection = renderAgentsSection(resolveAgentHints(issue.agents, workingDir));
+
   const outDir = boardDir ? join(boardDir, 'out') : pmDir ? join(pmDir, 'out') : join(workingDir, '.mstro', 'pm', 'out');
 
   return `You are executing issue ${issue.id}: ${issue.title}.
@@ -67,7 +105,7 @@ ${criteria || 'No specific criteria defined.'}
 
 ### Technical Notes
 ${issue.technicalNotes || 'None'}
-${files}${predecessorSection}
+${files}${predecessorSection}${agentSection}
 
 ## Your Task
 

package/server/services/plan/parser-core.ts

@@ -287,6 +287,7 @@ export function parseIssue(content: string, filePath: string): Issue {
     reviewGate: (['none', 'auto', 'required'].includes(String(fm.review_gate)) ? String(fm.review_gate) : 'auto') as Issue['reviewGate'],
     outputType: (['code', 'document', 'auto'].includes(String(fm.output_type)) ? String(fm.output_type) : 'auto') as Issue['outputType'],
     outputFile: optionalString(fm.output_file),
+    agents: toStringArray(fm.agents),
     body,
     path: filePath,
   };

package/server/services/plan/types.ts

@@ -98,6 +98,10 @@ export interface Issue {
   outputType: 'code' | 'document' | 'auto';
   // Planned output file path (from front matter output_file, relative to working dir)
   outputFile: string | null;
+  // Agent hints for the executing Claude Code session — names or general roles
+  // (e.g. ["backend-architect", "database-architect"], ["product, design"]).
+  // Empty = no agent hints; the executor uses default behavior.
+  agents: string[];
   // Full markdown body
   body: string;
   // File path relative to .mstro/pm/

package/server/services/runtime-info.ts

@@ -0,0 +1,24 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+
+/**
+ * Runtime Info
+ *
+ * Holds process-wide singletons that are known after server startup but
+ * needed by code paths (e.g. the headless runner / MCP config generator)
+ * that don't have a natural reference to the Hono app or instance registry.
+ *
+ * Specifically: the port the CLI server is bound to. We need it so the MCP
+ * bouncer subprocess can call back into us via HTTP for AskUserQuestion.
+ *
+ * Set once at server startup (see `server/index.ts`).
+ */
+
+let currentPort: number | undefined;
+
+export function setCurrentMstroPort(port: number): void {
+  currentPort = port;
+}
+
+export function getCurrentMstroPort(): number | undefined {
+  return currentPort;
+}

package/server/services/settings.ts

@@ -15,10 +15,75 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
+import type { EngineId } from '../engines/types.js'
 
 const MSTRO_DIR = join(homedir(), '.mstro')
 const SETTINGS_FILE = join(MSTRO_DIR, 'settings.json')
 
+/**
+ * Configuration for the Layer-2 Bouncer classifier (the AI model that runs
+ * for every ambiguous tool call). The model MUST be flagged
+ * `bouncerEligible` in the engine's model catalogue — frontier models
+ * (Opus, GPT-4o, …) are deliberately disallowed because they slow the
+ * classifier path and degrade the whole security layer.
+ */
+export interface BouncerClassifierConfig {
+  engine: EngineId
+  /** Engine-specific model id, e.g. 'haiku', 'sonnet', 'openai/gpt-5-mini'. */
+  model: string
+}
+
+/**
+ * Canonical list of bouncer-eligible models per engine. Mirrors
+ * `web/src/components/views/SettingsView/constants.ts` — keep the two in
+ * sync. Only cheap/fast models appear here; if you need to add a model,
+ * check p50 latency < ~1s and JSON-mode capability first.
+ */
+export const BOUNCER_ELIGIBLE_MODELS: Record<EngineId, readonly string[]> = {
+  'claude-code': ['haiku', 'sonnet'],
+  opencode: [
+    'openai/gpt-5-mini',
+    'openai/gpt-5-nano',
+    'google/gemini-2.5-flash',
+    'ollama/llama3.1:8b',
+  ],
+}
+
+/** Default classifier — Claude Haiku. Matches the pre-feature-flag behavior. */
+export const DEFAULT_BOUNCER_CLASSIFIER: BouncerClassifierConfig = {
+  engine: 'claude-code',
+  model: 'haiku',
+}
+
+/**
+ * Validate a `BouncerClassifierConfig`. Rejects with a thrown `Error` when
+ * the model is not flagged `bouncerEligible` under the requested engine —
+ * e.g. attempting to use Opus as a classifier, or a frontier OpenCode
+ * model. The WebSocket settings handler uses this to reject crafted
+ * payloads from the web client.
+ */
+export function validateBouncerClassifier(config: unknown): BouncerClassifierConfig {
+  if (config === null || typeof config !== 'object') {
+    throw new Error('bouncerClassifier must be an object with { engine, model }')
+  }
+  const { engine, model } = config as { engine?: unknown; model?: unknown }
+  if (engine !== 'claude-code' && engine !== 'opencode') {
+    throw new Error(`bouncerClassifier.engine must be 'claude-code' or 'opencode' (got ${String(engine)})`)
+  }
+  if (typeof model !== 'string' || model.length === 0) {
+    throw new Error('bouncerClassifier.model must be a non-empty string')
+  }
+  const eligible = BOUNCER_ELIGIBLE_MODELS[engine]
+  if (!eligible.includes(model)) {
+    throw new Error(
+      `Model '${model}' is not bouncer-eligible for engine '${engine}'. ` +
+        `Eligible models: ${eligible.join(', ')}. ` +
+        `Frontier models (Opus, GPT-4o, etc.) are deliberately excluded to keep the classifier fast.`,
+    )
+  }
+  return { engine, model }
+}
+
 export interface MstroSettings {
   /**
    * Claude model to use for main execution.
@@ -37,11 +102,26 @@ export interface MstroSettings {
   effortLevel: string
   /** Per-repo preferred PR base branch, keyed by normalized remote URL */
   prBaseBranches?: Record<string, string>
+  /**
+   * Feature flag gating all OpenCode code paths (engine factory, classifier
+   * factory, and UI). When `false`, the system behaves byte-identically to
+   * pre-OpenCode main: no `opencode serve` subprocess, no classifier picker,
+   * no EngineSection/EnginePicker in the web UI. Resolution order in
+   * `isEngineSwapEnabled()`: env var → stored setting → NODE_ENV default.
+   */
+  engineSwap?: boolean
+  /**
+   * Which engine + model backs the Layer-2 Bouncer classifier. Defaults to
+   * `{ engine: 'claude-code', model: 'haiku' }`. Only models flagged
+   * `bouncerEligible` are accepted — see {@link validateBouncerClassifier}.
+   */
+  bouncerClassifier?: BouncerClassifierConfig
 }
 
 const DEFAULT_SETTINGS: MstroSettings = {
   model: 'opus',
-  effortLevel: 'auto'
+  effortLevel: 'auto',
+  bouncerClassifier: { ...DEFAULT_BOUNCER_CLASSIFIER },
 }
 
 /**
@@ -54,7 +134,11 @@ function ensureMstroDir(): void {
 }
 
 /**
- * Get current settings, merged with defaults for any missing fields
+ * Get current settings, merged with defaults for any missing fields. A
+ * persisted `bouncerClassifier` that is no longer bouncer-eligible (e.g. a
+ * catalogue change removed the model) is dropped in favor of the default
+ * and a warning is logged — the Bouncer must never silently run a
+ * non-eligible model just because someone edited settings.json by hand.
  */
 export function getSettings(): MstroSettings {
   if (!existsSync(SETTINGS_FILE)) {
@@ -64,10 +148,22 @@ export function getSettings(): MstroSettings {
   try {
     const content = readFileSync(SETTINGS_FILE, 'utf-8')
     const stored = JSON.parse(content)
-    return {
+    const merged: MstroSettings = {
       ...DEFAULT_SETTINGS,
       ...stored,
     }
+    if (stored && typeof stored === 'object' && 'bouncerClassifier' in stored) {
+      try {
+        merged.bouncerClassifier = validateBouncerClassifier(stored.bouncerClassifier)
+      } catch (err) {
+        console.warn(
+          '[settings] Stored bouncerClassifier is not bouncer-eligible, falling back to default:',
+          err instanceof Error ? err.message : String(err),
+        )
+        merged.bouncerClassifier = { ...DEFAULT_BOUNCER_CLASSIFIER }
+      }
+    }
+    return merged
   } catch (err) {
     console.warn('Failed to read settings file, using defaults:', err)
     return { ...DEFAULT_SETTINGS }
@@ -75,9 +171,18 @@ export function getSettings(): MstroSettings {
 }
 
 /**
- * Save full settings to disk
+ * Save full settings to disk. Rejects if `bouncerClassifier` is present but
+ * its model is not flagged `bouncerEligible` — this is the save-time half
+ * of the guard; `getSettings` enforces the read-time half. Together they
+ * ensure the Bouncer is never configured with a frontier model (Opus,
+ * GPT-4o, …) regardless of whether the mutation came from the web UI or a
+ * direct edit of settings.json.
  */
 export function saveSettings(settings: MstroSettings): void {
+  if (settings.bouncerClassifier !== undefined) {
+    // Throws on non-eligible model — callers must surface the error.
+    validateBouncerClassifier(settings.bouncerClassifier)
+  }
   ensureMstroDir()
   writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2), {
     mode: 0o600
@@ -116,6 +221,58 @@ export function setEffortLevel(effortLevel: string): void {
   saveSettings(settings)
 }
 
+/**
+ * Get the current Bouncer classifier configuration. Returns the default
+ * `{ engine: 'claude-code', model: 'haiku' }` when nothing is persisted.
+ */
+export function getBouncerClassifier(): BouncerClassifierConfig {
+  const settings = getSettings()
+  if (settings.bouncerClassifier) {
+    try {
+      return validateBouncerClassifier(settings.bouncerClassifier)
+    } catch {
+      // Stored config is no longer eligible (e.g. model removed from the
+      // catalogue). Fall back to the safe default rather than crashing.
+      return { ...DEFAULT_BOUNCER_CLASSIFIER }
+    }
+  }
+  return { ...DEFAULT_BOUNCER_CLASSIFIER }
+}
+
+/**
+ * Persist a new Bouncer classifier config. Throws if the model is not
+ * flagged `bouncerEligible` under the requested engine — callers should
+ * surface the error to the UI so the user sees a clear rejection reason.
+ */
+export function setBouncerClassifier(config: unknown): BouncerClassifierConfig {
+  const validated = validateBouncerClassifier(config)
+  const settings = getSettings()
+  settings.bouncerClassifier = validated
+  saveSettings(settings)
+  return validated
+}
+
+/**
+ * Resolve the engineSwap feature flag. Precedence:
+ *   1. `MSTRO_ENABLE_ENGINE_SWAP` env var ('true'|'1' → on, 'false'|'0' → off).
+ *   2. `engineSwap` field in `~/.mstro/settings.json`.
+ *   3. NODE_ENV default — off in production, on otherwise (dev/staging/test).
+ *
+ * Callers who need a single boolean should use this helper rather than
+ * reading the field directly, so the precedence stays in one place.
+ */
+export function isEngineSwapEnabled(): boolean {
+  const envFlag = process.env.MSTRO_ENABLE_ENGINE_SWAP
+  if (envFlag !== undefined) {
+    const normalized = envFlag.trim().toLowerCase()
+    if (normalized === 'true' || normalized === '1') return true
+    if (normalized === 'false' || normalized === '0') return false
+  }
+  const stored = getSettings().engineSwap
+  if (typeof stored === 'boolean') return stored
+  return process.env.NODE_ENV !== 'production'
+}
+
 /** Normalize a remote URL into a stable key (e.g. "github.com/owner/repo") */
 function normalizeRemoteUrl(remoteUrl: string): string {
   return remoteUrl

package/server/services/websocket/ask-user-question-bridge.ts

@@ -0,0 +1,148 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+
+/**
+ * AskUserQuestion Bridge
+ *
+ * Bridges the MCP bouncer subprocess (which receives Claude's AskUserQuestion
+ * tool calls) and the web client (which collects the user's answers).
+ *
+ * Flow:
+ *   Claude → MCP bouncer (subprocess)
+ *          → POST /internal/ask-user-question (this CLI server)
+ *          → registerPendingQuestion() stores a resolver
+ *          → broadcastTabEvent('askUserQuestion', …) pushes the question to web
+ *          → web user answers → WS `askUserQuestionResponse`
+ *          → resolvePendingQuestion() resolves the awaited promise
+ *          → HTTP response to bouncer with answers
+ *          → bouncer returns { behavior: "allow", updatedInput: { questions, answers } }
+ *
+ * Ownership of state: pending questions live only here, in-process. The
+ * registry is keyed by `toolUseId` (Claude's per-call id) which guarantees
+ * uniqueness across tabs and sessions.
+ *
+ * Timeouts: questions auto-reject after `DEFAULT_TIMEOUT_MS`. The bouncer's
+ * HTTP call gets a 504 and returns a deny to Claude rather than blocking the
+ * Claude turn forever.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+/** Default per-question timeout (15 minutes). */
+const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
+
+interface PendingQuestion {
+  toolUseId: string;
+  tabId: string;
+  resolve: (answers: Record<string, string>) => void;
+  reject: (reason: 'timeout' | 'cancelled' | 'session-ended') => void;
+  timer: ReturnType<typeof setTimeout>;
+  createdAt: number;
+}
+
+const pending = new Map<string, PendingQuestion>();
+
+/** Per-process secret the MCP bouncer must echo to authenticate.
+ *  Generated once at server start, passed to bouncers via env var. */
+const bouncerSharedSecret = randomUUID();
+
+/** Get the per-process bouncer secret (passed via env var to bouncer subprocesses). */
+export function getBouncerSecret(): string {
+  return bouncerSharedSecret;
+}
+
+/** Validate a secret claimed by an inbound /internal request. */
+export function isValidBouncerSecret(secret: string | undefined | null): boolean {
+  if (!secret) return false;
+  return secret === bouncerSharedSecret;
+}
+
+export interface RegisterPendingQuestionOptions {
+  toolUseId: string;
+  tabId: string;
+  timeoutMs?: number;
+}
+
+/**
+ * Register a pending question. The returned promise resolves when
+ * `resolvePendingQuestion` is called for the same toolUseId, or rejects on
+ * timeout / cancellation.
+ */
+export function registerPendingQuestion(
+  opts: RegisterPendingQuestionOptions,
+): Promise<Record<string, string>> {
+  const { toolUseId, tabId, timeoutMs = DEFAULT_TIMEOUT_MS } = opts;
+
+  // Defensive: reject any prior pending entry for this id (shouldn't happen
+  // but a process restart or duplicate POST shouldn't leak handlers).
+  const existing = pending.get(toolUseId);
+  if (existing) {
+    clearTimeout(existing.timer);
+    existing.reject('cancelled');
+    pending.delete(toolUseId);
+  }
+
+  return new Promise<Record<string, string>>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      const entry = pending.get(toolUseId);
+      if (!entry) return;
+      pending.delete(toolUseId);
+      entry.reject('timeout');
+    }, timeoutMs);
+
+    pending.set(toolUseId, {
+      toolUseId,
+      tabId,
+      resolve,
+      reject: (reason) => reject(new Error(reason)),
+      timer,
+      createdAt: Date.now(),
+    });
+  });
+}
+
+/**
+ * Resolve a pending question with the user's answers. Returns true if a
+ * pending entry was found and resolved; false if there was no matching
+ * pending question (already answered, timed out, or unknown id).
+ */
+export function resolvePendingQuestion(
+  toolUseId: string,
+  answers: Record<string, string>,
+): boolean {
+  const entry = pending.get(toolUseId);
+  if (!entry) return false;
+  pending.delete(toolUseId);
+  clearTimeout(entry.timer);
+  entry.resolve(answers);
+  return true;
+}
+
+/**
+ * Cancel all pending questions for a given tab. Used when a tab is removed,
+ * a session is reset, or an orchestra disconnects. Returns the toolUseIds
+ * that were cancelled so callers can broadcast `askUserQuestionDismissed`.
+ */
+export function cancelPendingQuestionsForTab(
+  tabId: string,
+  reason: 'cancelled' | 'session-ended' = 'cancelled',
+): string[] {
+  const cancelled: string[] = [];
+  for (const [id, entry] of pending) {
+    if (entry.tabId !== tabId) continue;
+    pending.delete(id);
+    clearTimeout(entry.timer);
+    entry.reject(reason);
+    cancelled.push(id);
+  }
+  return cancelled;
+}
+
+/** Look up the tab that owns a pending question, or undefined. */
+export function getPendingQuestionTab(toolUseId: string): string | undefined {
+  return pending.get(toolUseId)?.tabId;
+}
+
+/** Diagnostic: how many questions are currently waiting on user input. */
+export function pendingQuestionCount(): number {
+  return pending.size;
+}