gsd-pi 2.77.0-dev.eaa4973bc → 2.78.0-dev.aeeb2ca00

package/dist/resources/extensions/gsd/forensics.js

@@ -29,6 +29,7 @@ import { getAutoWorktreePath } from "./auto-worktree.js";
 import { loadEffectiveGSDPreferences, loadGlobalGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js";
 import { showNextAction } from "../shared/tui.js";
 import { ensurePreferencesFile, serializePreferencesToFrontmatter } from "./commands-prefs-wizard.js";
+import { summarizeWorktreeTelemetry, percentile } from "./worktree-telemetry.js";
 // ─── Duplicate Detection ──────────────────────────────────────────────────────
 const DEDUP_PROMPT_SECTION = `
 ## Pre-Investigation: Duplicate Check (REQUIRED)
@@ -214,6 +215,16 @@ export async function buildForensicReport(basePath) {
     detectCrash(crashLock, anomalies);
     detectDoctorIssues(doctorIssues, anomalies);
     detectErrorTraces(unitTraces, anomalies);
+    // 11b. #4764 — worktree lifecycle telemetry
+    let worktreeTelemetry = null;
+    try {
+        worktreeTelemetry = summarizeWorktreeTelemetry(basePath);
+        detectWorktreeOrphans(worktreeTelemetry, anomalies);
+    }
+    catch {
+        // Telemetry is best-effort — do not let an aggregator failure block the
+        // rest of the forensic report.
+    }
     detectJournalAnomalies(journalSummary, anomalies);
     return {
         gsdVersion,
@@ -232,6 +243,7 @@ export async function buildForensicReport(basePath) {
         recentUnits,
         journalSummary,
         activityLogMeta,
+        worktreeTelemetry,
     };
 }
 // ─── Activity Log Scanner ─────────────────────────────────────────────────────
@@ -630,6 +642,45 @@ function detectMissingArtifacts(completedKeys, basePath, activeMilestone, anomal
         }
     }
 }
+/**
+ * #4764 — surface worktree lifecycle and orphan signals in the forensic report.
+ *
+ * Consumes only the aggregated summary (not raw journal events) to respect
+ * the forensics memory-bloat guard in forensics-journal.test.ts — per-event
+ * detail stays in the journal itself where the LLM can query it on demand.
+ */
+function detectWorktreeOrphans(summary, anomalies) {
+    // 1. Orphan aggregate — severity depends on reason. In-progress orphans are
+    // the #4761 consumer-side signal (live work sitting on an unmerged branch).
+    for (const [reason, count] of Object.entries(summary.orphansByReason)) {
+        if (count <= 0)
+            continue;
+        const severity = reason === "in-progress-unmerged" ? "warning" : "info";
+        anomalies.push({
+            type: "worktree-orphan",
+            severity,
+            summary: `${count} worktree orphan(s) detected (${reason})`,
+            details: reason === "in-progress-unmerged"
+                ? "Auto-mode exited without completing a milestone; live work sits on an unmerged milestone branch. Run `/gsd auto` to resume, or merge manually."
+                : reason === "complete-unmerged"
+                    ? "A completed milestone's branch was never merged back to main. Run `/gsd health --fix` to resolve."
+                    : `Reason: ${reason}.`,
+        });
+    }
+    // 2. Auto-exit producer signal — #4761's upstream cause.
+    if (summary.exitsWithUnmergedWork > 0) {
+        const reasonBreakdown = Object.entries(summary.exitsByReason)
+            .filter(([, n]) => n > 0)
+            .map(([r, n]) => `${r}=${n}`)
+            .join(", ");
+        anomalies.push({
+            type: "worktree-unmerged-exit",
+            severity: "warning",
+            summary: `${summary.exitsWithUnmergedWork} auto-exit(s) left milestone work unmerged`,
+            details: `Exit reasons: ${reasonBreakdown || "(none)"} · Producer-side signal for #4761-class orphans. Inspect .gsd/journal/*.jsonl with eventType:"auto-exit" for per-exit detail.`,
+        });
+    }
+}
 function detectCrash(crashLock, anomalies) {
     if (!crashLock)
         return;
@@ -808,6 +859,39 @@ function saveForensicReport(basePath, report, problemDescription) {
             sections.push(`- Newest: ${meta.newestFile}`);
         sections.push(``);
     }
+    // #4764 — Worktree telemetry summary
+    if (report.worktreeTelemetry) {
+        const t = report.worktreeTelemetry;
+        const p50 = percentile(t.mergeDurationsMs, 0.5);
+        const p95 = percentile(t.mergeDurationsMs, 0.95);
+        sections.push(`## Worktree Telemetry`, ``);
+        sections.push(`- Worktrees created: ${t.worktreesCreated}`);
+        sections.push(`- Worktrees merged: ${t.worktreesMerged}`);
+        sections.push(`- Orphans detected: ${t.orphansDetected}`);
+        if (t.orphansDetected > 0) {
+            const breakdown = Object.entries(t.orphansByReason)
+                .map(([r, n]) => `${r}=${n}`).join(", ");
+            sections.push(`  - By reason: ${breakdown}`);
+        }
+        sections.push(`- Merge conflicts: ${t.mergeConflicts}`);
+        if (t.mergeDurationsMs.length > 0) {
+            sections.push(`- Merge duration p50 / p95: ${p50 ?? "-"} / ${p95 ?? "-"} ms (n=${t.mergeDurationsMs.length})`);
+        }
+        sections.push(`- Auto-exits leaving unmerged work: ${t.exitsWithUnmergedWork}`);
+        if (Object.keys(t.exitsByReason).length > 0) {
+            const breakdown = Object.entries(t.exitsByReason)
+                .sort((a, b) => b[1] - a[1])
+                .map(([r, n]) => `${r}=${n}`).join(", ");
+            sections.push(`  - Exit reasons: ${breakdown}`);
+        }
+        sections.push(`- Canonical-root redirects (#4761 fix fired): ${t.canonicalRedirects}`);
+        // #4765 slice-cadence counters
+        if (t.slicesMerged + t.sliceMergeConflicts + t.milestoneResquashes > 0) {
+            sections.push(`- Slices merged: ${t.slicesMerged} · Slice merge conflicts: ${t.sliceMergeConflicts}`);
+            sections.push(`- Milestone re-squashes: ${t.milestoneResquashes}`);
+        }
+        sections.push(``);
+    }
     // Journal summary
     if (report.journalSummary) {
         const js = report.journalSummary;
@@ -940,6 +1024,28 @@ function formatReportForPrompt(report) {
         sections.push(`- Total duration: ${formatDuration(totals.duration)}`);
         sections.push("");
     }
+    // #4764 — worktree telemetry (compact prompt form)
+    if (report.worktreeTelemetry) {
+        const t = report.worktreeTelemetry;
+        const hasSignal = t.worktreesCreated + t.worktreesMerged + t.orphansDetected +
+            t.exitsWithUnmergedWork + t.canonicalRedirects +
+            t.slicesMerged + t.milestoneResquashes > 0;
+        if (hasSignal) {
+            sections.push("### Worktree Telemetry");
+            sections.push(`- Created: ${t.worktreesCreated} · Merged: ${t.worktreesMerged} · Conflicts: ${t.mergeConflicts}`);
+            sections.push(`- Orphans: ${t.orphansDetected} · Unmerged exits: ${t.exitsWithUnmergedWork} · Redirects (#4761): ${t.canonicalRedirects}`);
+            if (t.orphansDetected > 0) {
+                const breakdown = Object.entries(t.orphansByReason)
+                    .map(([r, n]) => `${r}=${n}`).join(", ");
+                sections.push(`- Orphan reasons: ${breakdown}`);
+            }
+            // #4765 — slice-cadence counters (only shown when the feature was exercised)
+            if (t.slicesMerged + t.sliceMergeConflicts + t.milestoneResquashes > 0) {
+                sections.push(`- Slices merged: ${t.slicesMerged} · Slice conflicts: ${t.sliceMergeConflicts} · Re-squashes: ${t.milestoneResquashes}`);
+            }
+            sections.push("");
+        }
+    }
     // Activity log metadata
     if (report.activityLogMeta) {
         const meta = report.activityLogMeta;

package/dist/resources/extensions/gsd/gate-registry.js

@@ -37,9 +37,9 @@ export const GATE_REGISTRY = {
         id: "Q4",
         scope: "slice",
         ownerTurn: "gate-evaluate",
-        question: "What existing promises does this break?",
+        question: "Which existing requirements (R-IDs) does this slice touch, and which must be re-tested?",
         guidance: [
-            "List which existing requirements (R001, R003, etc.) are touched by this slice.",
+            "List the R-IDs (e.g. R001, R003) touched by this slice; see the milestone requirements artifact at .gsd/milestones/<id>/REQUIREMENTS.md.",
             "Identify what must be re-tested after shipping.",
             "Flag decisions that should be revisited given the new scope.",
             "If no existing requirements are affected, return verdict 'omitted'.",

package/dist/resources/extensions/gsd/git-constants.js

@@ -1,9 +1,36 @@
 /**
  * Shared git constants used across git-service and native-git-bridge.
  */
+/**
+ * Parent process env vars that, if leaked into a git child process, can
+ * silently redirect every operation to a different repo or index.
+ *
+ * Stripped from GIT_NO_PROMPT_ENV so a GSD invoked from inside a git hook,
+ * a different worktree's terminal, or any context that pre-set these vars
+ * cannot redirect GSD's git operations to the wrong target.
+ * (Issue #4980 NEW-1)
+ */
+const LEAKING_GIT_ENV_VARS = [
+    "GIT_DIR",
+    "GIT_WORK_TREE",
+    "GIT_INDEX_FILE",
+    "GIT_OBJECT_DIRECTORY",
+    "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+    "GIT_COMMON_DIR",
+    "GIT_NAMESPACE",
+];
+function buildSafeParentEnv() {
+    const safe = {};
+    for (const [k, v] of Object.entries(process.env)) {
+        if (!LEAKING_GIT_ENV_VARS.includes(k)) {
+            safe[k] = v;
+        }
+    }
+    return safe;
+}
 /** Env overlay that suppresses interactive git credential prompts and git-svn noise. */
 export const GIT_NO_PROMPT_ENV = {
-    ...process.env,
+    ...buildSafeParentEnv(),
     GIT_TERMINAL_PROMPT: "0",
     GIT_ASKPASS: "",
     GIT_SVN_ID: "",

package/dist/resources/extensions/gsd/git-self-heal.js

@@ -9,12 +9,25 @@
  * what actions were taken. `formatGitError` maps raw git errors to
  * user-friendly messages suggesting `/gsd doctor`.
  */
+import { execFileSync } from "node:child_process";
 import { existsSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { MergeConflictError } from "./git-service.js";
 import { nativeMergeAbort, nativeRebaseAbort, nativeResetHard } from "./native-git-bridge.js";
 // Re-export for consumers
 export { MergeConflictError };
+function hasWorkingTreeChanges(cwd) {
+    try {
+        return execFileSync("git", ["status", "--porcelain"], {
+            cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        }).trim().length > 0;
+    }
+    catch {
+        return true;
+    }
+}
 /**
  * Detect and clean up leftover merge/rebase state, then hard-reset.
  *
@@ -60,6 +73,20 @@ export function abortAndReset(cwd) {
             cleaned.push("rebase abort attempted (may have failed)");
         }
     }
+    // Preserve any staged or untracked user work before the hard reset.
+    // Reset --hard discards staged changes (reflog only covers committed
+    // state), so a labeled stash gives the user a recovery handle if their
+    // in-flight inspection work would otherwise be silently lost.
+    // (Issue #4980 HIGH-5)
+    if (hasWorkingTreeChanges(cwd)) {
+        try {
+            execFileSync("git", ["stash", "push", "--include-untracked", "-m", `gsd: pre-self-heal-reset ${new Date().toISOString()}`], { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" });
+            cleaned.push("stashed working tree before reset");
+        }
+        catch {
+            /* nothing to stash, or stash refused (e.g. unresolved conflicts) — proceed */
+        }
+    }
     // Always hard-reset to HEAD
     try {
         nativeResetHard(cwd);

package/dist/resources/extensions/gsd/git-service.js

@@ -7,7 +7,7 @@
  * This module centralizes the GitPreferences interface, runtime exclusion
  * paths, commit type inference, and the runGit shell helper.
  */
-import { execFileSync, execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
@@ -243,6 +243,107 @@ export function resolveMilestoneIntegrationBranch(basePath, milestoneId, prefs =
         reason: `Recorded integration branch "${recordedBranch}" for milestone ${milestoneId} no longer exists, and no safe fallback branch could be determined.`,
     };
 }
+// ─── Pre-Merge Command Tokenizer ──────────────────────────────────────────
+/**
+ * Tokenize a user-supplied pre-merge command string into argv form, with
+ * minimal support for double- and single-quoted strings. Designed to be
+ * sufficient for typical commands ("npm test", `npm run lint:ci`,
+ * `pnpm run tsc --noEmit`) without spawning a shell.
+ *
+ * Returns [] when the input is empty or whitespace-only.
+ * Throws when quoting is malformed.
+ *
+ * Used by GitServiceImpl.runPreMergeCheck to eliminate the shell-injection
+ * surface that running an arbitrary user string through a shell would create.
+ * (Issue #4980 HIGH-2)
+ */
+export function tokenizePreMergeCommand(input) {
+    const tokens = [];
+    let current = "";
+    let i = 0;
+    let quote = "";
+    let hasContent = false;
+    while (i < input.length) {
+        const ch = input[i];
+        if (quote) {
+            if (ch === quote) {
+                quote = "";
+            }
+            else if (ch === "\\" && quote === '"' && i + 1 < input.length) {
+                current += input[i + 1];
+                i += 2;
+                continue;
+            }
+            else {
+                current += ch;
+            }
+            i++;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            hasContent = true;
+            i++;
+            continue;
+        }
+        if (ch === " " || ch === "\t") {
+            if (hasContent) {
+                tokens.push(current);
+                current = "";
+                hasContent = false;
+            }
+            i++;
+            continue;
+        }
+        if (ch === "\\" && i + 1 < input.length) {
+            current += input[i + 1];
+            i += 2;
+            hasContent = true;
+            continue;
+        }
+        current += ch;
+        hasContent = true;
+        i++;
+    }
+    if (quote) {
+        throw new Error(`Unterminated ${quote === '"' ? "double" : "single"} quote in pre-merge command`);
+    }
+    if (hasContent)
+        tokens.push(current);
+    return tokens;
+}
+function containsUnquotedShellControl(input) {
+    let i = 0;
+    let quote = "";
+    while (i < input.length) {
+        const ch = input[i];
+        if (quote) {
+            if (ch === quote) {
+                quote = "";
+            }
+            else if (ch === "\\" && quote === '"' && i + 1 < input.length) {
+                i += 2;
+                continue;
+            }
+            i++;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            i++;
+            continue;
+        }
+        if (ch === "\\" && i + 1 < input.length) {
+            i += 2;
+            continue;
+        }
+        if (ch === ";" || ch === "&" || ch === "|" || ch === "`" || ch === "$" || ch === "<" || ch === ">") {
+            return true;
+        }
+        i++;
+    }
+    return false;
+}
 // ─── Git Helper ────────────────────────────────────────────────────────────
 /**
  * Strip git-svn noise from error messages.
@@ -601,8 +702,31 @@ export class GitServiceImpl {
                 return { passed: true, skipped: true };
             }
         }
+        // Tokenize and run via execFileSync (no shell). Shell metacharacters in
+        // user-supplied prefs.pre_merge_check would otherwise be interpreted as
+        // chaining/redirection (e.g. `;`, `&&`, `|`, backticks) — a privesc
+        // surface in repos with a checked-in `.gsd/PREFERENCES.md`.
+        // (Issue #4980 HIGH-2)
+        if (containsUnquotedShellControl(command)) {
+            return {
+                passed: false,
+                skipped: false,
+                command,
+                error: "pre_merge_check contains shell metacharacters (;, &&, |, $, backticks, redirects). " +
+                    "Put complex commands in a script file (e.g. './scripts/pre-merge.sh') and reference the script path instead.",
+            };
+        }
+        const tokens = tokenizePreMergeCommand(command);
+        if (tokens.length === 0) {
+            return { passed: true, skipped: true };
+        }
         try {
-            execSync(command, { cwd: this.basePath, stdio: "pipe", encoding: "utf-8" });
+            execFileSync(tokens[0], tokens.slice(1), {
+                cwd: this.basePath,
+                stdio: "pipe",
+                encoding: "utf-8",
+                env: GIT_NO_PROMPT_ENV,
+            });
             return { passed: true, skipped: false, command };
         }
         catch (err) {

package/dist/resources/extensions/gsd/gsd-db.js

@@ -135,7 +135,7 @@ function openRawDb(path) {
     const Database = providerModule;
     return new Database(path);
 }
-const SCHEMA_VERSION = 22;
+export const SCHEMA_VERSION = 22;
 function indexExists(db, name) {
     return !!db.prepare("SELECT 1 as present FROM sqlite_master WHERE type = 'index' AND name = ?").get(name);
 }
@@ -2556,6 +2556,9 @@ export function insertReplanHistory(entry) {
 export function insertAssessment(entry) {
     if (!currentDb)
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    // Idempotent: PRIMARY KEY is `path`, which is deterministic given (milestone_id, scope) per
+    // the artifact-path resolver. Retrying the same reassess-roadmap silently overwrites the row
+    // instead of accumulating duplicates.
     currentDb.prepare(`INSERT OR REPLACE INTO assessments (path, milestone_id, slice_id, task_id, status, scope, full_content, created_at)
      VALUES (:path, :milestone_id, :slice_id, :task_id, :status, :scope, :full_content, :created_at)`).run({
         ":path": entry.path,
@@ -2655,7 +2658,7 @@ function rowToGate(row) {
         scope: row["scope"],
         task_id: row["task_id"] ?? "",
         status: row["status"],
-        verdict: row["verdict"] || "",
+        verdict: row["status"] === "pending" ? null : row["verdict"],
         rationale: row["rationale"] || "",
         findings: row["findings"] || "",
         evaluated_at: row["evaluated_at"] ?? null,
@@ -2739,7 +2742,7 @@ export function getGateResults(milestoneId, sliceId, scope) {
 export function markAllGatesOmitted(milestoneId, sliceId) {
     if (!currentDb)
         return;
-    currentDb.prepare(`UPDATE quality_gates SET status = 'omitted', verdict = 'omitted', evaluated_at = :now
+    currentDb.prepare(`UPDATE quality_gates SET status = 'complete', verdict = 'omitted', evaluated_at = :now
      WHERE milestone_id = :mid AND slice_id = :sid AND status = 'pending'`).run({
         ":mid": milestoneId,
         ":sid": sliceId,

package/dist/resources/extensions/gsd/guided-flow.js

@@ -10,7 +10,7 @@ import { loadFile, saveFile } from "./files.js";
 import { isDbAvailable, getMilestoneSlices } from "./gsd-db.js";
 import { parseRoadmapSlices } from "./roadmap-slices.js";
 import { loadPrompt, inlineTemplate } from "./prompt-loader.js";
-import { buildSkillActivationBlock } from "./auto-prompts.js";
+import { buildDiscussMilestonePrompt, buildSkillActivationBlock } from "./auto-prompts.js";
 import { deriveState } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { startAutoDetached } from "./auto.js";
@@ -27,8 +27,8 @@ import { isInheritedRepo } from "./repo-identity.js";
 import { ensureGitignore, ensurePreferences, untrackRuntimeFiles } from "./gitignore.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { resolveUokFlags } from "./uok/flags.js";
-import { ensurePlanV2Graph } from "./uok/plan-v2.js";
-import { detectProjectState } from "./detection.js";
+import { ensurePlanV2Graph, isMissingFinalizedContextResult } from "./uok/plan-v2.js";
+import { detectProjectState, hasGsdBootstrapArtifacts } from "./detection.js";
 import { showProjectInit, offerMigration } from "./init-wizard.js";
 import { validateDirectory } from "./validate-directory.js";
 import { showConfirm } from "../shared/tui.js";
@@ -65,14 +65,17 @@ function runPlanV2Gate(ctx, basePath, state) {
     const prefs = loadEffectiveGSDPreferences()?.preferences;
     const uokFlags = resolveUokFlags(prefs);
     if (!uokFlags.planV2 || !needsPlanV2Gate(state))
-        return true;
+        return "pass";
     const compiled = ensurePlanV2Graph(basePath, state);
     if (!compiled.ok) {
+        if (isMissingFinalizedContextResult(compiled)) {
+            return "recover-missing-context";
+        }
         const reason = compiled.reason ?? "plan-v2 compilation failed";
         ctx.ui.notify(`Plan gate failed-closed: ${reason}. Complete plan/discuss artifacts before execution.\n\nIf this keeps happening, try: /gsd doctor heal`, "error");
-        return false;
+        return "block";
     }
-    return true;
+    return "pass";
 }
 // ─── Commit Instruction Helpers ──────────────────────────────────────────────
 /** Build commit instruction for planning prompts. .gsd/ is managed externally and always gitignored. */
@@ -255,6 +258,18 @@ function extractAssistantText(msg) {
 }
 /**
  * Return true if the assistant message contains any tool-use block.
+ *
+ * The canonical pi-ai `AssistantMessage.content` (see packages/pi-ai/src/types.ts)
+ * uses `type: "toolCall"` and `type: "serverToolUse"` for tool invocations —
+ * every provider (anthropic-direct, claude-code-cli, openai, etc.) normalizes
+ * incoming tool blocks into these two shapes before they reach guided-flow.
+ *
+ * The Anthropic API wire shape `"tool_use"` / `"server_tool_use"` does NOT appear
+ * in the internal AssistantMessage — those literals are only used when sending
+ * messages back out to the Anthropic API. Matching them here was a latent bug:
+ * `hasToolUse` returned `false` for every real tool call, which let the
+ * empty-turn nudge fire and pre-empt MCP tools that block on the user
+ * (e.g. `ask_user_questions`). See investigation in PR for #4658.
  */
 function hasToolUse(msg) {
     if (!msg)
@@ -262,7 +277,9 @@ function hasToolUse(msg) {
     const content = msg.content;
     if (!Array.isArray(content))
         return false;
-    return content.some((b) => b && typeof b === "object" && (b.type === "tool_use" || b.type === "tool-use"));
+    return content.some((b) => b &&
+        typeof b === "object" &&
+        (b.type === "toolCall" || b.type === "serverToolUse"));
 }
 /**
  * #4573 — Detect and recover from the "ready phrase without files" failure mode.
@@ -669,8 +686,13 @@ export async function showHeadlessMilestoneCreation(ctx, pi, basePath, seedConte
     const prompt = buildHeadlessDiscussPrompt(nextId, seedContext, basePath);
     // Set pending auto start (auto-mode triggers on "Milestone X ready." via checkAutoStartAfterDiscuss)
     pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, createdAt: Date.now() });
-    // Dispatch — headless milestone creation is a planning activity
-    await dispatchWorkflow(pi, prompt, "gsd-run", ctx, "plan-milestone");
+    // Dispatch as discuss-milestone. The LLM writes PROJECT.md, REQUIREMENTS.md,
+    // and CONTEXT.md, then calls gsd_plan_milestone — this is semantically the
+    // discuss path, just non-interactive. Using "plan-milestone" here caused
+    // model/tool routing to skip discuss-flow tool scoping and
+    // `checkAutoStartAfterDiscuss` guardrails that rely on the
+    // "discuss-"-prefixed unitType.
+    await dispatchWorkflow(pi, prompt, "gsd-run", ctx, "discuss-milestone");
 }
 // ─── Discuss Flow ─────────────────────────────────────────────────────────────
 /**
@@ -1236,9 +1258,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
     // A zombie .gsd/ state (symlink exists but missing PREFERENCES.md and
     // milestones/) must trigger the init wizard, not skip it (#2942).
     const gsdPath = gsdRoot(basePath);
-    const hasBootstrapArtifacts = existsSync(gsdPath)
-        && (existsSync(join(gsdPath, "PREFERENCES.md"))
-            || existsSync(join(gsdPath, "milestones")));
+    const hasBootstrapArtifacts = hasGsdBootstrapArtifacts(gsdPath);
     if (!hasBootstrapArtifacts) {
         const detection = detectProjectState(basePath);
         // v1 .planning/ detected — offer migration before anything else
@@ -1322,7 +1342,8 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
     catch (err) {
         logWarning("guided", `STATE.md rebuild failed: ${err.message}`);
     }
-    if (!runPlanV2Gate(ctx, basePath, state))
+    const planV2GateDecision = runPlanV2Gate(ctx, basePath, state);
+    if (planV2GateDecision === "block")
         return;
     if (!state.activeMilestone?.id) {
         // Guard: if a discuss session is already in flight, don't re-inject the prompt.
@@ -1397,6 +1418,11 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
     }
     const milestoneId = state.activeMilestone.id;
     const milestoneTitle = state.activeMilestone.title;
+    if (planV2GateDecision === "recover-missing-context") {
+        pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId, step: stepMode, createdAt: Date.now() });
+        await dispatchWorkflow(pi, await buildDiscussMilestonePrompt(milestoneId, milestoneTitle, basePath, getStructuredQuestionsAvailability(pi, ctx)), "gsd-discuss", ctx, "discuss-milestone");
+        return;
+    }
     // ── All milestones complete → New milestone ──────────────────────────
     if (state.phase === "complete") {
         const choice = await showNextAction(ctx, {

package/dist/resources/extensions/gsd/memory-extractor.js

@@ -62,7 +62,9 @@ export function buildMemoryLLMCall(ctx) {
         // which returns undefined for OAuth users (Claude Max / Claude Pro).
         // See: https://github.com/gsd-build/gsd-2/issues/2959
         const resolvedKeyPromise = ctx.modelRegistry.getApiKey(selectedModel).catch(() => undefined);
-        return async (system, user) => {
+        // Expose on the returned fn so tests can await resolution deterministically
+        // (avoids arbitrary setTimeout polling for an internal microtask).
+        const llmCall = async (system, user) => {
             const { completeSimple } = await import('@gsd/pi-ai');
             const resolvedApiKey = await resolvedKeyPromise;
             const result = await completeSimple(selectedModel, {
@@ -79,6 +81,10 @@ export function buildMemoryLLMCall(ctx) {
                 .map(c => c.text);
             return textParts.join('');
         };
+        // Attach the in-flight API-key resolution so tests (and callers) can
+        // `await llmCall.apiKeyReady` rather than relying on setTimeout polling.
+        llmCall.apiKeyReady = resolvedKeyPromise;
+        return llmCall;
     }
     catch {
         return null;