gsd-pi 2.76.0-dev.fe143342a → 2.77.0-dev.1d17f366c

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

@@ -13,8 +13,10 @@
 
 import { readFile, readdir, stat } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
 import { z } from 'zod';
 import type { SessionManager } from './session-manager.js';
+import { isRemoteConfigured, tryRemoteQuestions } from './remote-questions.js';
 import { readProgress } from './readers/state.js';
 import { readRoadmap } from './readers/roadmap.js';
 import { readHistory } from './readers/metrics.js';
@@ -24,7 +26,7 @@ import { buildGraph, writeGraph, writeSnapshot, graphStatus, graphQuery, graphDi
 import { resolveGsdRoot } from './readers/paths.js';
 import { runDoctorLite } from './readers/doctor-lite.js';
 import { registerWorkflowTools, validateProjectDir } from './workflow-tools.js';
-import { applySecrets, checkExistingEnvKeys, detectDestination } from './env-writer.js';
+import { applySecrets, checkExistingEnvKeys, detectDestination, resolveProjectEnvFilePath } from './env-writer.js';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -34,6 +36,59 @@ const MCP_PKG = '@modelcontextprotocol/sdk';
 const SERVER_NAME = 'gsd';
 const SERVER_VERSION = '2.53.0';
 
+/** User-interaction timeout — generous but bounded so elicitation can't hang indefinitely (#4586). */
+const ELICIT_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
+
+/**
+ * Default child-process runner used by secure_env_collect to push secrets
+ * into `vercel env add` / `npx convex env set`. Previously `applySecrets`
+ * was called without an `execFn`, so vercel/convex destinations silently
+ * dropped every collected key. This restores the write path.
+ */
+function defaultExecFn(
+  cmd: string,
+  args: string[],
+): Promise<{ code: number; stderr: string }> {
+  return new Promise((res) => {
+    // stdin: ignore — avoids 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'] });
+    let stderr = '';
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString('utf8');
+    });
+    child.on('error', (err) => res({ code: 1, stderr: err.message }));
+    child.on('close', (code) => res({ code: code ?? 1, stderr }));
+  });
+}
+
+/**
+ * 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.
+ *
+ * @param timeoutMs - override for testing; defaults to ELICIT_TIMEOUT_MS
+ */
+export async function withElicitTimeout<T>(
+  promise: Promise<T>,
+  label: string,
+  timeoutMs = ELICIT_TIMEOUT_MS,
+): 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,
+    );
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Tool result helpers
 // ---------------------------------------------------------------------------
@@ -458,17 +513,40 @@ export async function createMcpServer(sessionManager: SessionManager): Promise<{
 
   // -----------------------------------------------------------------------
   // gsd_cancel — cancel a running session
+  //
+  // Supports two lookup strategies:
+  //   1. sessionId  — the ID returned from gsd_execute (primary)
+  //   2. projectDir — absolute path to the project directory (fallback)
+  //
+  // The projectDir fallback handles interactive sessions (started via
+  // `/gsd auto` in the terminal) and post-restart MCP sessions that were
+  // never registered with a sessionId in this server instance.
   // -----------------------------------------------------------------------
   server.tool(
     'gsd_cancel',
-    'Cancel a running GSD session. Aborts the current operation and stops the process.',
+    'Cancel a running GSD session. Aborts the current operation and stops the process. Provide sessionId (from gsd_execute) or projectDir as a fallback for interactive/restarted sessions.',
     {
-      sessionId: z.string().describe('Session ID returned from gsd_execute'),
+      sessionId: z.string().optional().describe('Session ID returned from gsd_execute'),
+      projectDir: z.string().optional().describe('Absolute path to the project directory (fallback when sessionId is unavailable)'),
     },
     async (args: Record<string, unknown>) => {
-      const { sessionId } = args as { sessionId: string };
+      const { sessionId, projectDir } = args as { sessionId?: string; projectDir?: string };
       try {
-        await sessionManager.cancelSession(sessionId);
+        if (!sessionId && !projectDir) {
+          return errorContent('Either sessionId or projectDir must be provided');
+        }
+        if (sessionId) {
+          try {
+            await sessionManager.cancelSession(sessionId);
+          } catch (err) {
+            if (!projectDir || !(err instanceof Error) || !err.message.includes('Session not found')) {
+              throw err;
+            }
+            await sessionManager.cancelSessionByDir(projectDir);
+          }
+        } else if (projectDir) {
+          await sessionManager.cancelSessionByDir(projectDir);
+        }
         return jsonContent({ cancelled: true });
       } catch (err) {
         return errorContent(err instanceof Error ? err.message : String(err));
@@ -545,13 +623,33 @@ export async function createMcpServer(sessionManager: SessionManager): Promise<{
         allowMultiple: z.boolean().optional().describe('If true, the user can select multiple options. No "None of the above" option is added.'),
       })).describe('Questions to show the user. Prefer 1 and do not exceed 3.'),
     },
-    async (args: Record<string, unknown>) => {
+    async (args: Record<string, unknown>, extra?: McpToolExtra) => {
       const { questions } = args as unknown as AskUserQuestionsParams;
       try {
         const validationError = validateAskUserQuestionsPayload(questions);
         if (validationError) return errorContent(validationError);
 
-        const elicitation = await server.server.elicitInput(buildAskUserQuestionsElicitRequest(questions));
+        // 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');
         }
@@ -591,7 +689,7 @@ export async function createMcpServer(sessionManager: SessionManager): Promise<{
 
       try {
         const resolvedProjectDir = validateProjectDir(projectDir);
-        const resolvedEnvPath = resolve(resolvedProjectDir, envFilePath ?? '.env');
+        const resolvedEnvPath = resolveProjectEnvFilePath(resolvedProjectDir, envFilePath ?? '.env');
 
         // (1) Check which keys already exist
         const allKeyNames = keys.map((k) => k.key);
@@ -627,14 +725,17 @@ export async function createMcpServer(sessionManager: SessionManager): Promise<{
         }
 
         // (3) Elicit input from the MCP client
-        const elicitation = await server.server.elicitInput({
-          message: `Enter values for ${pendingKeys.length} environment variable(s). Values are written directly to the project and never shown to the AI.`,
-          requestedSchema: {
-            type: 'object',
-            properties,
-            required,
-          },
-        });
+        const elicitation = await withElicitTimeout(
+          server.server.elicitInput({
+            message: `Enter values for ${pendingKeys.length} environment variable(s). Values are written directly to the project and never shown to the AI.`,
+            requestedSchema: {
+              type: 'object',
+              properties,
+              required,
+            },
+          }),
+          'secure_env_collect',
+        );
 
         if (elicitation.action !== 'accept' || !elicitation.content) {
           return textContent('secure_env_collect was cancelled by user.');
@@ -661,6 +762,7 @@ export async function createMcpServer(sessionManager: SessionManager): Promise<{
         const { applied, errors } = await applySecrets(provided, resolvedDestination, {
           envFilePath: resolvedEnvPath,
           environment,
+          execFn: defaultExecFn,
         });
 
         // (7) Build result — NEVER include secret values

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

@@ -7,7 +7,8 @@
  */
 
 import { execSync } from 'node:child_process';
-import { resolve } from 'node:path';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
 import { RpcClient } from '@gsd-build/rpc-client';
 import type { SdkAgentEvent, RpcInitResult, RpcCostUpdateEvent, RpcExtensionUIRequest } from '@gsd-build/rpc-client';
 import type {
@@ -188,7 +189,48 @@ export class SessionManager {
   async cancelSession(sessionId: string): Promise<void> {
     const session = this.getSession(sessionId);
     if (!session) throw new Error(`Session not found: ${sessionId}`);
+    await this._cancelSessionObject(session);
+  }
+
+  /**
+   * Cancel a session looked up by project directory.
+   *
+   * This is the fallback path for interactive sessions (started via `/gsd auto`
+   * in the terminal) and sessions from a restarted MCP server that have no
+   * registered sessionId. The sessions map is keyed by projectDir, so this
+   * lookup always succeeds for any tracked session regardless of sessionId.
+   */
+  async cancelSessionByDir(projectDir: string): Promise<void> {
+    const session = this.getSessionByDir(projectDir);
+    if (session) {
+      await this._cancelSessionObject(session);
+      return;
+    }
+    const stopped = await this.stopDetachedAutoProcess(projectDir);
+    if (!stopped) {
+      throw new Error(`Session not found for projectDir: ${projectDir}`);
+    }
+  }
+
+  private async stopDetachedAutoProcess(projectDir: string): Promise<boolean> {
+    const lockPath = join(projectDir, '.gsd', 'auto.lock');
+    if (!existsSync(lockPath)) return false;
+    try {
+      const lockData = JSON.parse(readFileSync(lockPath, 'utf-8')) as { pid?: number };
+      const pid = lockData.pid;
+      if (typeof pid !== 'number') return false;
+      try { process.kill(pid, 0); } catch { return false; }
+      process.kill(pid, 'SIGTERM');
+      return true;
+    } catch {
+      return false;
+    }
+  }
 
+  /**
+   * Internal: perform abort + stop + mark cancelled on a resolved session object.
+   */
+  private async _cancelSessionObject(session: ManagedSession): Promise<void> {
     try {
       await session.client.abort();
     } catch { /* may already be stopped */ }

package/packages/mcp-server/src/workflow-tools.test.ts

@@ -712,6 +712,50 @@ export const executeTaskComplete = async (params, projectDir) => {
     }
   });
 
+  it("gsd_plan_milestone surfaces the full-vs-sketch conditional requirement in the tool schema", () => {
+    // Regression: the four heavy slice fields (successCriteria, proofLevel,
+    // integrationClosure, observabilityImpact) are Zod-optional so sketch
+    // slices can omit them, but they are required for every other slice. That
+    // conditional requirement is invisible in the JSON Schema `required`
+    // array — agents discovered it only by hitting a -32602 error mid-call.
+    // Each heavy field's `.describe()` now states the constraint; this test
+    // pins that so future edits can't silently strip it.
+    const server = makeMockServer();
+    registerWorkflowTools(server as any);
+    const milestoneTool = server.tools.find((t) => t.name === "gsd_plan_milestone");
+    assert.ok(milestoneTool, "milestone planning tool should be registered");
+
+    const slicesParam: any = milestoneTool!.params.slices;
+    assert.ok(slicesParam, "slices parameter must be present");
+    const element: any = slicesParam._def?.element;
+    assert.ok(element, "expected z.array element schema");
+
+    // Top-level slice description should state the conditional requirement.
+    const sliceDescription: string | undefined = element.description;
+    assert.ok(
+      sliceDescription && /isSketch/i.test(sliceDescription),
+      `slice schema should describe the isSketch conditional; got: ${sliceDescription}`,
+    );
+    for (const field of ["successCriteria", "proofLevel", "integrationClosure", "observabilityImpact"]) {
+      assert.ok(
+        sliceDescription!.includes(field),
+        `slice schema description should name ${field} as part of the full-slice contract`,
+      );
+    }
+
+    // Each heavy field should carry a field-level description that marks it
+    // REQUIRED unless isSketch=true.
+    const shape: Record<string, any> = element._def.shape;
+    assert.ok(shape, "expected to introspect slice object shape");
+    for (const field of ["successCriteria", "proofLevel", "integrationClosure", "observabilityImpact"] as const) {
+      const fieldDescription: string | undefined = shape[field]?.description;
+      assert.ok(
+        fieldDescription && /REQUIRED\s+unless\s+isSketch/i.test(fieldDescription),
+        `${field} description must state "REQUIRED unless isSketch=true"; got: ${fieldDescription}`,
+      );
+    }
+  });
+
   it("gsd_plan_milestone requires sketchScope when isSketch=true and skips heavy fields", async () => {
     const base = makeTmpBase();
     try {

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

@@ -875,6 +875,17 @@ const nonEmptyStringArray = (field: string) =>
 // empty/whitespace fields at parse time. Without this, MCP callers pass "" for
 // the heavy planning fields, Zod accepts it, and the executor rejects one
 // field per call — forcing the agent into a retry loop to discover every gap.
+//
+// #4759 follow-up: the four heavy fields are Zod-optional because sketch
+// slices (isSketch=true) legitimately omit them, but they are REQUIRED for
+// every other slice. The conditional requirement is invisible in the JSON
+// Schema `required` array, so callers can only discover it from the
+// descriptions or by hitting the runtime superRefine below. The `.describe()`
+// calls below make that contract unmistakable in the tool schema sent to
+// agents; the superRefine enforces it at parse time.
+const HEAVY_FIELD_DESCRIBE = (field: string) =>
+  `${field} for this slice. REQUIRED unless isSketch=true (sketch slices defer this to refine-slice).`;
+
 const planMilestoneSliceSchema = z.object({
   sliceId: nonEmptyString("sliceId"),
   title: nonEmptyString("title"),
@@ -883,14 +894,16 @@ const planMilestoneSliceSchema = z.object({
   demo: nonEmptyString("demo"),
   goal: nonEmptyString("goal"),
   // ADR-011: heavy planning fields are optional for sketch slices; required for full slices.
-  successCriteria: z.string().optional(),
-  proofLevel: z.string().optional(),
-  integrationClosure: z.string().optional(),
-  observabilityImpact: z.string().optional(),
+  successCriteria: z.string().optional().describe(HEAVY_FIELD_DESCRIBE("successCriteria")),
+  proofLevel: z.string().optional().describe(HEAVY_FIELD_DESCRIBE("proofLevel")),
+  integrationClosure: z.string().optional().describe(HEAVY_FIELD_DESCRIBE("integrationClosure")),
+  observabilityImpact: z.string().optional().describe(HEAVY_FIELD_DESCRIBE("observabilityImpact")),
   // ADR-011 sketch-then-refine fields.
-  isSketch: z.boolean().optional().describe("ADR-011: true marks this slice as a sketch awaiting refine-slice expansion"),
+  isSketch: z.boolean().optional().describe("ADR-011: true marks this slice as a sketch awaiting refine-slice expansion. When true, successCriteria/proofLevel/integrationClosure/observabilityImpact may be omitted and sketchScope becomes required."),
   sketchScope: z.string().optional().describe("ADR-011: 2-3 sentence scope boundary, required when isSketch=true"),
-}).superRefine((slice, ctx) => {
+}).describe(
+  "Planned slice. For full slices (isSketch omitted or false): successCriteria, proofLevel, integrationClosure, and observabilityImpact are all required. For sketch slices (isSketch=true): those four fields may be omitted, but sketchScope is required.",
+).superRefine((slice, ctx) => {
   if (slice.isSketch === true) {
     if (typeof slice.sketchScope !== "string" || slice.sketchScope.trim().length === 0) {
       ctx.addIssue({

package/packages/mcp-server/tsconfig.test.json

@@ -0,0 +1,19 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "declaration": false,
+    "declarationMap": false,
+    "incremental": false,
+    "outDir": "./dist"
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/*.d.ts",
+    "src/**/*.d.ts",
+    "src/workflow-tools.test.ts"
+  ]
+}