gsd-pi 2.78.0 → 2.78.1-dev.42ef05fbe

package/packages/mcp-server/src/readers/paths.test.ts

@@ -0,0 +1,67 @@
+// GSD MCP Server — .gsd/ path cache tests
+
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  _resetReaderCaches,
+  findMilestoneIds,
+  findSliceIds,
+  findTaskFiles,
+} from './paths.js';
+
+function makeTempDir(prefix: string): string {
+  return mkdtempSync(join(tmpdir(), `${prefix}-`));
+}
+
+function writeFixture(base: string, relPath: string, content: string): void {
+  const full = join(base, relPath);
+  mkdirSync(join(full, '..'), { recursive: true });
+  writeFileSync(full, content, 'utf8');
+}
+
+describe('reader path caches', () => {
+  beforeEach(() => {
+    _resetReaderCaches();
+  });
+
+  it('returns defensive copies of cached milestone and slice ids', () => {
+    const tmp = makeTempDir('gsd-path-cache');
+    try {
+      const gsdRoot = join(tmp, '.gsd');
+      mkdirSync(join(gsdRoot, 'milestones', 'M001', 'slices', 'S01'), { recursive: true });
+      mkdirSync(join(gsdRoot, 'milestones', 'M002'), { recursive: true });
+
+      const milestoneIds = findMilestoneIds(gsdRoot);
+      milestoneIds.push('M999');
+      assert.deepEqual(findMilestoneIds(gsdRoot), ['M001', 'M002']);
+
+      const sliceIds = findSliceIds(gsdRoot, 'M001');
+      sliceIds.push('S99');
+      assert.deepEqual(findSliceIds(gsdRoot, 'M001'), ['S01']);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it('returns defensive copies of cached task file objects', () => {
+    const tmp = makeTempDir('gsd-path-task-cache');
+    try {
+      const gsdRoot = join(tmp, '.gsd');
+      writeFixture(gsdRoot, 'milestones/M001/slices/S01/tasks/T01-PLAN.md', '# T01');
+
+      const taskFiles = findTaskFiles(gsdRoot, 'M001', 'S01');
+      taskFiles[0].hasSummary = true;
+      taskFiles.push({ id: 'T99', hasPlan: true, hasSummary: true });
+
+      assert.deepEqual(findTaskFiles(gsdRoot, 'M001', 'S01'), [
+        { id: 'T01', hasPlan: true, hasSummary: false },
+      ]);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+});

package/packages/mcp-server/src/readers/paths.ts

@@ -1,10 +1,115 @@
 // GSD MCP Server — .gsd/ directory resolution
-// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
 
 import { existsSync, statSync, readdirSync } from 'node:fs';
 import { join, resolve, dirname, basename } from 'node:path';
 import { execFileSync } from 'node:child_process';
 
+// ---------------------------------------------------------------------------
+// Caching
+// ---------------------------------------------------------------------------
+//
+// Read-only MCP tools (gsd_progress, gsd_roadmap, gsd_doctor, …) hammer the
+// filesystem on every call: gsd_roadmap alone resolves milestone directories
+// 5–6× per milestone, and resolveGsdRoot can spawn `git rev-parse` for
+// non-direct .gsd/ layouts. Without caching, an MCP host pipelining several
+// tool calls blocks the event loop on dozens of redundant readdir/stat
+// syscalls per request.
+//
+// Two layers:
+//   * resolveGsdRoot — short TTL (the result depends on a possibly-expensive
+//     git subprocess; projectDir is stable for the life of an MCP session).
+//   * readdir-backed lookups — keyed on the directory's mtime, so any add/
+//     remove/rename invalidates the cache automatically.
+
+const GSD_ROOT_TTL_MS = 30_000;
+const MAX_CACHE_ENTRIES = 256;
+const gsdRootCache = new Map<string, { value: string; expiresAt: number }>();
+
+function setBoundedCache<K, V>(cache: Map<K, V>, key: K, value: V): void {
+  if (cache.has(key)) cache.delete(key);
+  cache.set(key, value);
+  while (cache.size > MAX_CACHE_ENTRIES) {
+    const oldest = cache.keys().next();
+    if (oldest.done) break;
+    cache.delete(oldest.value);
+  }
+}
+
+function cachedGsdRoot(projectDir: string): string | null {
+  const hit = gsdRootCache.get(projectDir);
+  if (!hit) return null;
+  if (hit.expiresAt < Date.now()) {
+    gsdRootCache.delete(projectDir);
+    return null;
+  }
+  setBoundedCache(gsdRootCache, projectDir, hit);
+  return hit.value;
+}
+
+function rememberGsdRoot(projectDir: string, value: string): void {
+  setBoundedCache(gsdRootCache, projectDir, { value, expiresAt: Date.now() + GSD_ROOT_TTL_MS });
+}
+
+interface MtimeEntry<V> { mtimeMs: number; value: V }
+
+/**
+ * Read-through cache keyed on a directory path's mtime. Returns the cached
+ * value if the directory's mtime is unchanged since the last write; otherwise
+ * runs `compute` and stores the new result. Misses on read errors (ENOENT,
+ * EACCES) are cached via `compute`'s own return value, but the cache entry
+ * is dropped if the directory disappears later.
+ */
+function readWithMtimeCache<V>(
+  cache: Map<string, MtimeEntry<V>>,
+  cacheKey: string,
+  dir: string,
+  compute: () => V,
+  cloneForStore: (value: V) => V = (value) => value,
+  cloneForReturn: (value: V) => V = (value) => value,
+): V {
+  let mtimeMs: number;
+  try {
+    mtimeMs = statSync(dir).mtimeMs;
+  } catch {
+    cache.delete(cacheKey);
+    return compute();
+  }
+  const hit = cache.get(cacheKey);
+  if (hit && hit.mtimeMs === mtimeMs) {
+    setBoundedCache(cache, cacheKey, hit);
+    return cloneForReturn(hit.value);
+  }
+  const value = cloneForStore(compute());
+  setBoundedCache(cache, cacheKey, { mtimeMs, value });
+  return cloneForReturn(value);
+}
+
+const milestoneIdsCache = new Map<string, MtimeEntry<string[]>>();
+const milestoneDirCache = new Map<string, MtimeEntry<string | null>>();
+const sliceIdsCache = new Map<string, MtimeEntry<string[]>>();
+const sliceDirCache = new Map<string, MtimeEntry<string | null>>();
+const taskFilesCache = new Map<string, MtimeEntry<Array<{ id: string; hasPlan: boolean; hasSummary: boolean }>>>();
+
+function cloneStringArray(value: string[]): string[] {
+  return Array.from(value);
+}
+
+function cloneTaskFiles(
+  value: Array<{ id: string; hasPlan: boolean; hasSummary: boolean }>,
+): Array<{ id: string; hasPlan: boolean; hasSummary: boolean }> {
+  return value.map((task) => ({ ...task }));
+}
+
+/** @internal — exported for testing only */
+export function _resetReaderCaches(): void {
+  gsdRootCache.clear();
+  milestoneIdsCache.clear();
+  milestoneDirCache.clear();
+  sliceIdsCache.clear();
+  sliceDirCache.clear();
+  taskFilesCache.clear();
+}
+
 /**
  * Resolve the .gsd/ root directory for a project.
  *
@@ -17,9 +122,13 @@ import { execFileSync } from 'node:child_process';
 export function resolveGsdRoot(projectDir: string): string {
   const resolved = resolve(projectDir);
 
+  const cached = cachedGsdRoot(resolved);
+  if (cached) return cached;
+
   // Fast path: .gsd/ in the given directory
   const direct = join(resolved, '.gsd');
   if (existsSync(direct) && statSync(direct).isDirectory()) {
+    rememberGsdRoot(resolved, direct);
     return direct;
   }
 
@@ -32,6 +141,7 @@ export function resolveGsdRoot(projectDir: string): string {
     }).trim();
     const gitGsd = join(gitRoot, '.gsd');
     if (existsSync(gitGsd) && statSync(gitGsd).isDirectory()) {
+      rememberGsdRoot(resolved, gitGsd);
       return gitGsd;
     }
   } catch {
@@ -43,12 +153,13 @@ export function resolveGsdRoot(projectDir: string): string {
   while (dir !== dirname(dir)) {
     const candidate = join(dir, '.gsd');
     if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+      rememberGsdRoot(resolved, candidate);
       return candidate;
     }
     dir = dirname(dir);
   }
 
-  // Fallback
+  // Fallback — don't cache so that an init() call right after this is seen.
   return direct;
 }
 
@@ -70,16 +181,16 @@ export function findMilestoneIds(gsdRoot: string): string[] {
   const dir = milestonesDir(gsdRoot);
   if (!existsSync(dir)) return [];
 
-  const entries = readdirSync(dir, { withFileTypes: true });
-  const ids: string[] = [];
-
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const match = entry.name.match(/^(M\d+)/);
-    if (match) ids.push(match[1]);
-  }
-
-  return ids.sort();
+  return readWithMtimeCache(milestoneIdsCache, dir, dir, () => {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    const ids: string[] = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const match = entry.name.match(/^(M\d+)/);
+      if (match) ids.push(match[1]);
+    }
+    return ids.sort();
+  }, cloneStringArray, cloneStringArray);
 }
 
 /**
@@ -90,19 +201,21 @@ export function resolveMilestoneDir(gsdRoot: string, milestoneId: string): strin
   const dir = milestonesDir(gsdRoot);
   if (!existsSync(dir)) return null;
 
-  // Fast path: exact match
-  const exact = join(dir, milestoneId);
-  if (existsSync(exact) && statSync(exact).isDirectory()) return exact;
-
-  // Prefix match
-  const entries = readdirSync(dir, { withFileTypes: true });
-  for (const entry of entries) {
-    if (entry.isDirectory() && entry.name.startsWith(milestoneId)) {
-      return join(dir, entry.name);
+  return readWithMtimeCache(milestoneDirCache, `${dir} ${milestoneId}`, dir, () => {
+    // Fast path: exact match
+    const exact = join(dir, milestoneId);
+    if (existsSync(exact) && statSync(exact).isDirectory()) return exact;
+
+    // Prefix match
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory() && entry.name.startsWith(milestoneId)) {
+        return join(dir, entry.name);
+      }
     }
-  }
 
-  return null;
+    return null;
+  });
 }
 
 /**
@@ -136,16 +249,16 @@ export function findSliceIds(gsdRoot: string, milestoneId: string): string[] {
   const slicesDir = join(mDir, 'slices');
   if (!existsSync(slicesDir)) return [];
 
-  const entries = readdirSync(slicesDir, { withFileTypes: true });
-  const ids: string[] = [];
-
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const match = entry.name.match(/^(S\d+)/);
-    if (match) ids.push(match[1]);
-  }
-
-  return ids.sort();
+  return readWithMtimeCache(sliceIdsCache, slicesDir, slicesDir, () => {
+    const entries = readdirSync(slicesDir, { withFileTypes: true });
+    const ids: string[] = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const match = entry.name.match(/^(S\d+)/);
+      if (match) ids.push(match[1]);
+    }
+    return ids.sort();
+  }, cloneStringArray, cloneStringArray);
 }
 
 /** Resolve the actual directory for a slice */
@@ -156,16 +269,18 @@ export function resolveSliceDir(gsdRoot: string, milestoneId: string, sliceId: s
   const slicesDir = join(mDir, 'slices');
   if (!existsSync(slicesDir)) return null;
 
-  const exact = join(slicesDir, sliceId);
-  if (existsSync(exact) && statSync(exact).isDirectory()) return exact;
+  return readWithMtimeCache(sliceDirCache, `${slicesDir} ${sliceId}`, slicesDir, () => {
+    const exact = join(slicesDir, sliceId);
+    if (existsSync(exact) && statSync(exact).isDirectory()) return exact;
 
-  const entries = readdirSync(slicesDir, { withFileTypes: true });
-  for (const entry of entries) {
-    if (entry.isDirectory() && entry.name.startsWith(sliceId)) {
-      return join(slicesDir, entry.name);
+    const entries = readdirSync(slicesDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory() && entry.name.startsWith(sliceId)) {
+        return join(slicesDir, entry.name);
+      }
     }
-  }
-  return null;
+    return null;
+  });
 }
 
 /** Resolve a slice-level file (S01-PLAN.md, etc.) */
@@ -198,20 +313,22 @@ export function findTaskFiles(
   const tasksDir = join(sDir, 'tasks');
   if (!existsSync(tasksDir)) return [];
 
-  const files = readdirSync(tasksDir);
-  const taskMap = new Map<string, { hasPlan: boolean; hasSummary: boolean }>();
-
-  for (const f of files) {
-    const match = f.match(/^(T\d+).*-(PLAN|SUMMARY)\.md$/i);
-    if (!match) continue;
-    const [, id, type] = match;
-    const existing = taskMap.get(id) ?? { hasPlan: false, hasSummary: false };
-    if (type.toUpperCase() === 'PLAN') existing.hasPlan = true;
-    if (type.toUpperCase() === 'SUMMARY') existing.hasSummary = true;
-    taskMap.set(id, existing);
-  }
+  return readWithMtimeCache(taskFilesCache, tasksDir, tasksDir, () => {
+    const files = readdirSync(tasksDir);
+    const taskMap = new Map<string, { hasPlan: boolean; hasSummary: boolean }>();
+
+    for (const f of files) {
+      const match = f.match(/^(T\d+).*-(PLAN|SUMMARY)\.md$/i);
+      if (!match) continue;
+      const [, id, type] = match;
+      const existing = taskMap.get(id) ?? { hasPlan: false, hasSummary: false };
+      if (type.toUpperCase() === 'PLAN') existing.hasPlan = true;
+      if (type.toUpperCase() === 'SUMMARY') existing.hasSummary = true;
+      taskMap.set(id, existing);
+    }
 
-  return Array.from(taskMap.entries())
-    .map(([id, info]) => ({ id, ...info }))
-    .sort((a, b) => a.id.localeCompare(b.id));
+    return Array.from(taskMap.entries())
+      .map(([id, info]) => ({ id, ...info }))
+      .sort((a, b) => a.id.localeCompare(b.id));
+  }, cloneTaskFiles, cloneTaskFiles);
 }

package/packages/mcp-server/src/remote-questions.ts

@@ -781,7 +781,15 @@ async function pollUntilDone(
       }
 
       if (answer) return answer;
-    } catch {
+    } catch (err) {
+      // Auth errors (401/403) mean the configured token is invalid or
+      // revoked — re-throw so the caller can surface a useful error
+      // immediately instead of silently spinning until the timeout.
+      // Network/transient errors keep the retry behaviour.
+      const msg = String((err as Error)?.message ?? err);
+      if (msg.includes('HTTP 401') || msg.includes('HTTP 403')) {
+        throw err;
+      }
       // Non-fatal poll error — wait and retry
     }
 
@@ -868,7 +876,15 @@ export async function tryRemoteQuestions(
     };
   }
 
-  const answer = await pollUntilDone(config, prompt, ref, state, signal);
+  let answer: RemoteAnswer | null;
+  try {
+    answer = await pollUntilDone(config, prompt, ref, state, signal);
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: `Remote questions failed (${config.channel}): ${(err as Error).message}` }],
+      details: { remote: true, channel: config.channel, error: true, status: 'failed' },
+    };
+  }
 
   if (!answer) {
     const timedOut = !signal?.aborted;

package/packages/mcp-server/src/server.ts

@@ -14,9 +14,11 @@
 import { readFile, readdir, stat } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
 import { z } from 'zod';
 import type { SessionManager } from './session-manager.js';
 import { isRemoteConfigured, tryRemoteQuestions } from './remote-questions.js';
+import type { RemoteToolResult } from './remote-questions.js';
 import { readProgress } from './readers/state.js';
 import { readRoadmap } from './readers/roadmap.js';
 import { readHistory } from './readers/metrics.js';
@@ -34,7 +36,21 @@ import { applySecrets, checkExistingEnvKeys, detectDestination, resolveProjectEn
 
 const MCP_PKG = '@modelcontextprotocol/sdk';
 const SERVER_NAME = 'gsd';
-const SERVER_VERSION = '2.53.0';
+
+/**
+ * Read the version from this package's package.json so the MCP handshake
+ * always advertises the deployed artifact's version. Falls back to '0.0.0'
+ * if package.json can't be located (e.g. unusual bundling); the fallback
+ * is loud-ish but won't crash the server.
+ */
+const SERVER_VERSION: string = (() => {
+  try {
+    const require = createRequire(import.meta.url);
+    const pkg = require('../package.json') as { version?: unknown };
+    if (typeof pkg.version === 'string' && pkg.version.length > 0) return pkg.version;
+  } catch { /* fall through */ }
+  return '0.0.0';
+})();
 
 /** User-interaction timeout — generous but bounded so elicitation can't hang indefinitely (#4586). */
 const ELICIT_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
@@ -48,15 +64,28 @@ const ELICIT_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
 function defaultExecFn(
   cmd: string,
   args: string[],
+  opts?: { stdin?: string },
 ): Promise<{ code: number; stderr: string }> {
   return new Promise((res) => {
-    // stdin: ignore — avoids hanging if the child ever prompts interactively.
+    // stdin: pipe only when a caller explicitly supplies input; otherwise
+    // ignore it to avoid hanging if the child ever prompts interactively.
     // stdout: ignore — consumer only cares about stderr + exit code, and an
     //   un-drained pipe deadlocks once the kernel buffer (~64KB) fills.
     // stderr: pipe — captured below for error surfacing.
-    const child = spawn(cmd, args, { stdio: ['ignore', 'ignore', 'pipe'] });
+    const child = spawn(resolveShellCommand(cmd), args, {
+      shell: process.platform === 'win32',
+      stdio: [opts?.stdin === undefined ? 'ignore' : 'pipe', 'ignore', 'pipe'],
+      windowsHide: true,
+    });
     let stderr = '';
-    child.stderr.on('data', (chunk) => {
+    child.stdin?.on('error', () => {
+      // Child exited before consuming stdin; close/error handling below will
+      // surface the real process result.
+    });
+    if (opts?.stdin !== undefined) {
+      child.stdin?.end(opts.stdin, 'utf8');
+    }
+    child.stderr?.on('data', (chunk) => {
       stderr += chunk.toString('utf8');
     });
     child.on('error', (err) => res({ code: 1, stderr: err.message }));
@@ -64,9 +93,19 @@ function defaultExecFn(
   });
 }
 
+function resolveShellCommand(cmd: string): string {
+  if (process.platform !== 'win32') return cmd;
+  if (cmd === 'vercel') return 'vercel.cmd';
+  if (cmd === 'npx') return 'npx.cmd';
+  return cmd;
+}
+
 /**
  * Race a promise against a timeout. Rejects with a typed error on timeout so
  * callers can return a specific MCP error response rather than hanging.
+ * If a parent AbortSignal is provided, an abort also rejects the race so
+ * client-side cancellation propagates instead of being absorbed by the
+ * 10-minute elicitation hold.
  *
  * @param timeoutMs - override for testing; defaults to ELICIT_TIMEOUT_MS
  */
@@ -74,18 +113,36 @@ export async function withElicitTimeout<T>(
   promise: Promise<T>,
   label: string,
   timeoutMs = ELICIT_TIMEOUT_MS,
+  signal?: AbortSignal,
 ): Promise<T> {
   let timer: ReturnType<typeof setTimeout> | undefined;
-  const timeout = new Promise<never>((_, reject) => {
-    timer = setTimeout(
-      () => reject(new Error(`${label} timed out after ${timeoutMs / 60000} minutes — no user response received`)),
-      timeoutMs,
+  const racers: Promise<T>[] = [promise];
+  racers.push(
+    new Promise<never>((_, reject) => {
+      timer = setTimeout(
+        () => reject(new Error(`${label} timed out after ${timeoutMs / 60000} minutes — no user response received`)),
+        timeoutMs,
+      );
+    }),
+  );
+  let abortListener: (() => void) | undefined;
+  if (signal) {
+    if (signal.aborted) {
+      clearTimeout(timer);
+      throw new Error(`${label} cancelled by client`);
+    }
+    racers.push(
+      new Promise<never>((_, reject) => {
+        abortListener = () => reject(new Error(`${label} cancelled by client`));
+        signal.addEventListener('abort', abortListener, { once: true });
+      }),
     );
-  });
+  }
   try {
-    return await Promise.race([promise, timeout]);
+    return await Promise.race(racers);
   } finally {
     clearTimeout(timer);
+    if (signal && abortListener) signal.removeEventListener('abort', abortListener);
   }
 }
 
@@ -387,6 +444,89 @@ export function formatAskUserQuestionsElicitResult(
   return JSON.stringify({ answers });
 }
 
+interface AskUserQuestionsHandlerDeps {
+  elicitInput(params: AskUserQuestionsElicitRequest): Promise<AskUserQuestionsElicitResult>;
+  isRemoteConfigured(): boolean;
+  tryRemoteQuestions(questions: AskUserQuestion[], signal?: AbortSignal): Promise<RemoteToolResult | null>;
+}
+
+function isLocalElicitFallbackError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  const message = err.message.toLowerCase();
+  return (
+    message.includes('timed out after') ||
+    message.includes('elicit') ||
+    message.includes('elicitation') ||
+    message.includes('host') ||
+    message.includes('not supported') ||
+    message.includes('method not found') ||
+    message.includes('-32601')
+  );
+}
+
+function formatErrorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+export async function askUserQuestionsHandler(
+  questions: AskUserQuestion[],
+  extra: McpToolExtra | undefined,
+  deps: AskUserQuestionsHandlerDeps,
+): Promise<ToolContent> {
+  try {
+    const validationError = validateAskUserQuestionsPayload(questions);
+    if (validationError) return errorContent(validationError);
+
+    // Local-first: try the MCP host's elicitation channel (Claude Code,
+    // Cursor, etc.) before any configured remote channel. A misconfigured
+    // remote (e.g. expired Discord token returning 401) must not block the
+    // depth-verification gate when the user is sitting in front of the host.
+    let localElicitError: unknown;
+    try {
+      const elicitation = await withElicitTimeout(
+        deps.elicitInput(buildAskUserQuestionsElicitRequest(questions)),
+        'ask_user_questions',
+      );
+      if (elicitation.action === 'accept' && elicitation.content) {
+        return textContent(formatAskUserQuestionsElicitResult(questions, elicitation));
+      }
+    } catch (err) {
+      if (!isLocalElicitFallbackError(err)) throw err;
+      localElicitError = err;
+      console.warn(`[gsd:mcp] ask_user_questions local elicitation unavailable; trying remote fallback: ${formatErrorMessage(err)}`);
+    }
+
+    // Local cancelled / unavailable — fall back to the configured remote
+    // channel (Discord, Slack, Telegram) if one is set.
+    if (deps.isRemoteConfigured()) {
+      let remoteResult: RemoteToolResult | null;
+      try {
+        remoteResult = await deps.tryRemoteQuestions(questions, extra?.signal);
+      } catch (err) {
+        if (localElicitError) {
+          throw new Error(
+            `Local elicitation failed (${formatErrorMessage(localElicitError)}); remote fallback failed (${formatErrorMessage(err)})`,
+          );
+        }
+        throw err;
+      }
+      if (remoteResult) {
+        const details = remoteResult.details as Record<string, unknown> | undefined;
+        if (details?.['timed_out'] || details?.['error']) {
+          return textContent(remoteResult.content[0]?.text ?? 'Remote questions timed out or failed');
+        }
+        return textContent(remoteResult.content[0]?.text ?? '');
+      }
+    }
+
+    if (localElicitError) throw localElicitError;
+
+    return textContent('ask_user_questions was cancelled before receiving a response');
+  } catch (err) {
+    return errorContent(err instanceof Error ? err.message : String(err));
+  }
+}
+
 // ---------------------------------------------------------------------------
 // secure_env_collect handler (extracted so tests can drive it directly)
 // ---------------------------------------------------------------------------
@@ -750,39 +890,11 @@ export async function createMcpServer(
     },
     async (args: Record<string, unknown>, extra?: McpToolExtra) => {
       const { questions } = args as unknown as AskUserQuestionsParams;
-      try {
-        const validationError = validateAskUserQuestionsPayload(questions);
-        if (validationError) return errorContent(validationError);
-
-        // Delegate to remote-questions manager when a remote channel is configured
-        // (Discord, Slack, Telegram). This path is the only one reachable for
-        // Claude Code-under-gsd sessions, which have no local TUI.
-        if (isRemoteConfigured()) {
-          const remoteResult = await tryRemoteQuestions(questions, extra?.signal);
-          if (remoteResult) {
-            const details = remoteResult.details as Record<string, unknown> | undefined;
-            if (details?.['timed_out'] || details?.['error']) {
-              // Surface timeout/error as plain text so the LLM knows to retry
-              return textContent(remoteResult.content[0]?.text ?? 'Remote questions timed out or failed');
-            }
-            return textContent(remoteResult.content[0]?.text ?? '');
-          }
-          // resolveRemoteConfig() returned null between isRemoteConfigured() and
-          // tryRemoteQuestions() (e.g. env var was cleared) — fall through to local.
-        }
-
-        const elicitation = await withElicitTimeout(
-          server.server.elicitInput(buildAskUserQuestionsElicitRequest(questions)),
-          'ask_user_questions',
-        );
-        if (elicitation.action !== 'accept' || !elicitation.content) {
-          return textContent('ask_user_questions was cancelled before receiving a response');
-        }
-
-        return textContent(formatAskUserQuestionsElicitResult(questions, elicitation));
-      } catch (err) {
-        return errorContent(err instanceof Error ? err.message : String(err));
-      }
+      return askUserQuestionsHandler(questions, extra, {
+        elicitInput: (params) => server.server.elicitInput(params),
+        isRemoteConfigured,
+        tryRemoteQuestions,
+      });
     },
   );