gsd-pi 2.80.0-dev.cf9433f56 → 2.80.0-dev.d4fc28e6b

package/dist/resources/extensions/gsd/bootstrap/system-context.js

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: System prompt and hidden context bootstrap for GSD sessions.
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { logWarning } from "../workflow-logger.js";
@@ -17,6 +19,11 @@ import { formatOverridesSection, formatShortcut, loadActiveOverrides, loadFile,
 import { toPosixPath } from "../../shared/mod.js";
 import { autoEnableCmuxPreferences } from "../commands-cmux.js";
 import { gsdHome } from "../gsd-home.js";
+const DEFAULT_CONTEXT_MESSAGE_MAX_CHARS = 4_000;
+const DEFAULT_KNOWLEDGE_MAX_CHARS = 12_000;
+const DEFAULT_CODEBASE_MAX_CHARS = 8_000;
+const MIN_CONTEXT_MESSAGE_MAX_CHARS = 1_000;
+const MIN_KNOWLEDGE_MAX_CHARS = 1_000;
 /**
  * Bundled skill triggers — resolved dynamically at runtime instead of
  * hardcoding absolute paths in the system prompt template. Only skills
@@ -135,7 +142,6 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     catch (e) {
         logWarning("bootstrap", `decisions backfill failed: ${e.message}`);
     }
-    const memoryBlock = await loadMemoryBlock(event.prompt ?? "");
     let newSkillsBlock = "";
     if (hasSkillSnapshot()) {
         const newSkills = detectNewSkills();
@@ -165,11 +171,10 @@ export async function buildBeforeAgentStartResult(event, ctx) {
             if (rawContent) {
                 // Cap injection size to ~2 000 tokens to avoid bloating every request.
                 // Full map is always available at .gsd/CODEBASE.md.
-                const MAX_CODEBASE_CHARS = 8_000;
                 const generatedMatch = rawContent.match(/Generated: (\S+)/);
                 const generatedAt = generatedMatch?.[1] ?? "unknown";
-                const content = rawContent.length > MAX_CODEBASE_CHARS
-                    ? rawContent.slice(0, MAX_CODEBASE_CHARS) + "\n\n*(truncated — see .gsd/CODEBASE.md for full map)*"
+                const content = rawContent.length > DEFAULT_CODEBASE_MAX_CHARS
+                    ? rawContent.slice(0, DEFAULT_CODEBASE_MAX_CHARS) + "\n\n*(truncated — see .gsd/CODEBASE.md for full map)*"
                     : rawContent;
                 codebaseBlock = `\n\n[PROJECT CODEBASE — File structure and descriptions (generated ${generatedAt}, auto-refreshed when GSD detects tracked file changes; use /gsd codebase stats for status)]\n\n${content}`;
             }
@@ -180,6 +185,9 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     }
     warnDeprecatedAgentInstructions();
     const injection = await buildGuidedExecuteContextInjection(event.prompt, process.cwd());
+    const memoryBlock = await loadMemoryBlock(event.prompt ?? "", {
+        includePromptRelevant: !(injection && isLowEntropyResumePrompt(event.prompt ?? "")),
+    });
     // Re-inject forensics context on follow-up turns (#2941)
     const forensicsInjection = !injection ? buildForensicsContextInjection(process.cwd(), event.prompt) : null;
     const worktreeBlock = buildWorktreeContextBlock();
@@ -188,12 +196,9 @@ export async function buildBeforeAgentStartResult(event, ctx) {
         ? `\n\n## Subagent Model\n\nWhen spawning subagents via the \`subagent\` tool, always pass \`model: "${subagentModelConfig.primary}"\` in the tool call parameters. Never omit this — always specify it explicitly.`
         : "";
     // memoryBlock is FTS-queried against the user prompt and changes per call.
-    // Removing it from `fullSystem` keeps the system-prompt cache breakpoint
-    // stable across calls — the only scoped goal of this fix. The pi-ai
-    // Anthropic adapter additionally cache-marks the last user turn, so the
-    // memoryBlock injected via the context message may itself be cached up to
-    // that boundary; that's orthogonal and unchanged from prior behavior. The
-    // load-bearing win here is preserving the system+tools cache hit. (#5019)
+    // Keeping it out of `fullSystem` preserves provider prompt-cache stability
+    // for the static system/tool prefix. The dynamic memory block rides the
+    // volatile context message instead. (#5019)
     const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${codebaseBlock}${newSkillsBlock}${worktreeBlock}${subagentModelBlock}`;
     stopContextTimer({
         systemPromptSize: fullSystem.length,
@@ -217,20 +222,49 @@ export async function buildBeforeAgentStartResult(event, ctx) {
  * filesystem and DB dependencies to exercise this routing logic in-place.
  */
 export function buildContextMessage(opts) {
-    const memoryContent = opts.memoryBlock.trim();
+    const contextCharLimit = getContextMessageCharLimit();
+    const memoryContent = markMemoryContextSupplied(opts.memoryBlock.trim());
     if (opts.injection) {
-        const content = memoryContent ? `${memoryContent}\n\n${opts.injection}` : opts.injection;
+        const content = limitContextMessageContent(memoryContent ? `${memoryContent}\n\n${opts.injection}` : opts.injection, contextCharLimit);
         return { customType: "gsd-guided-context", content, display: false };
     }
     if (opts.forensicsInjection) {
-        const content = memoryContent ? `${memoryContent}\n\n${opts.forensicsInjection}` : opts.forensicsInjection;
+        const content = limitContextMessageContent(memoryContent ? `${memoryContent}\n\n${opts.forensicsInjection}` : opts.forensicsInjection, contextCharLimit);
         return { customType: "gsd-forensics", content, display: false };
     }
     if (memoryContent) {
-        return { customType: "gsd-memory", content: memoryContent, display: false };
+        return {
+            customType: "gsd-memory",
+            content: limitContextMessageContent(memoryContent, contextCharLimit),
+            display: false,
+        };
     }
     return null;
 }
+function getContextMessageCharLimit() {
+    const raw = process.env.PI_GSD_CONTEXT_MAX_CHARS;
+    if (!raw)
+        return DEFAULT_CONTEXT_MESSAGE_MAX_CHARS;
+    if (raw === "0")
+        return null;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed < MIN_CONTEXT_MESSAGE_MAX_CHARS) {
+        return DEFAULT_CONTEXT_MESSAGE_MAX_CHARS;
+    }
+    return Math.floor(parsed);
+}
+function limitContextMessageContent(content, limit) {
+    if (!limit || content.length <= limit)
+        return content;
+    const suffix = "\n\n[GSD Context Truncated]\nFull context is available from the referenced .gsd files and tools; read on demand only if this excerpt lacks required evidence.";
+    const headBudget = Math.max(0, limit - suffix.length);
+    return `${content.slice(0, headBudget).trimEnd()}${suffix}`;
+}
+function markMemoryContextSupplied(memoryContent) {
+    if (!memoryContent)
+        return "";
+    return `[GSD Context Metadata]\n- Memory supplied: yes\n\n${memoryContent}`;
+}
 /**
  * ADR-013 step 4 — auto-injection parity for the memories table.
  *
@@ -249,7 +283,7 @@ export function buildContextMessage(opts) {
  * with a token-budget cap. Failures degrade gracefully — the function never
  * throws and returns "" so the system prompt construction continues.
  */
-export async function loadMemoryBlock(userPrompt) {
+export async function loadMemoryBlock(userPrompt, opts = {}) {
     try {
         const { formatMemoriesForPrompt, getActiveMemoriesRanked, queryMemoriesRanked } = await import("../memory-store.js");
         // Categories that belong in every turn. Pre-ADR-013 this was just
@@ -268,7 +302,7 @@ export async function loadMemoryBlock(userPrompt) {
         const criticalIds = new Set(critical.map((m) => m.id));
         let relevant = [];
         const trimmed = userPrompt.trim();
-        if (trimmed) {
+        if (trimmed && opts.includePromptRelevant !== false) {
             const hits = queryMemoriesRanked({ query: trimmed, k: QUERY_K });
             relevant = hits.map((h) => h.memory).filter((m) => !criticalIds.has(m.id));
         }
@@ -319,15 +353,37 @@ export function loadKnowledgeBlock(gsdHomeDir, cwd) {
         return { block: "", globalSizeKb: 0 };
     }
     const parts = [];
-    if (globalKnowledge)
-        parts.push(`## Global Knowledge\n\n${globalKnowledge}`);
-    if (projectKnowledge)
-        parts.push(`## Project Knowledge\n\n${projectKnowledge}`);
+    if (globalKnowledge) {
+        parts.push(`## Global Knowledge\nSource: \`${globalKnowledgePath}\`\n\n${globalKnowledge}`);
+    }
+    if (projectKnowledge) {
+        parts.push(`## Project Knowledge\nSource: \`${knowledgePath}\`\n\n${projectKnowledge}`);
+    }
+    const body = limitKnowledgeBlock(parts.join("\n\n"), getKnowledgeCharLimit());
     return {
-        block: `\n\n[KNOWLEDGE — Rules, patterns, and lessons learned]\n\n${parts.join("\n\n")}`,
+        block: `\n\n[KNOWLEDGE — Rules, patterns, and lessons learned]\n\n${body}`,
         globalSizeKb,
     };
 }
+function getKnowledgeCharLimit() {
+    const raw = process.env.PI_GSD_KNOWLEDGE_MAX_CHARS;
+    if (!raw)
+        return DEFAULT_KNOWLEDGE_MAX_CHARS;
+    if (raw === "0")
+        return null;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed < MIN_KNOWLEDGE_MAX_CHARS) {
+        return DEFAULT_KNOWLEDGE_MAX_CHARS;
+    }
+    return Math.floor(parsed);
+}
+function limitKnowledgeBlock(content, limit) {
+    if (!limit || content.length <= limit)
+        return content;
+    const suffix = "\n\n[Knowledge Truncated]\nFull KNOWLEDGE.md content remains available at the source path(s) above; read on demand only if this excerpt lacks a required rule.";
+    const headBudget = Math.max(0, limit - suffix.length);
+    return `${content.slice(0, headBudget).trimEnd()}${suffix}`;
+}
 function buildWorktreeContextBlock() {
     const worktreeName = getActiveWorktreeName();
     const worktreeMainCwd = getWorktreeOriginalCwd();
@@ -376,6 +432,10 @@ function buildWorktreeContextBlock() {
  * Tested against the trimmed, lowercased prompt with trailing punctuation stripped.
  */
 const RESUME_INTENT_PATTERNS = /^(continue|resume|ok|go|go ahead|proceed|keep going|carry on|next|yes|yeah|yep|sure|do it|let's go|pick up where you left off)$/;
+export function isLowEntropyResumePrompt(prompt) {
+    const trimmed = prompt.trim().toLowerCase().replace(/[.!?,]+$/g, "");
+    return RESUME_INTENT_PATTERNS.test(trimmed);
+}
 async function buildGuidedExecuteContextInjection(prompt, basePath) {
     const ensureStateDbOpen = async () => {
         const { ensureDbOpen } = await import("./dynamic-tools.js");
@@ -402,8 +462,7 @@ async function buildGuidedExecuteContextInjection(prompt, basePath) {
     // control/help/diagnostic prompts with unrelated execution context.
     // Phase-gated: only fire during "executing" to avoid misrouting during
     // replanning, gate evaluation, or other non-execution phases.
-    const trimmed = prompt.trim().toLowerCase().replace(/[.!?,]+$/g, "");
-    if (RESUME_INTENT_PATTERNS.test(trimmed)) {
+    if (isLowEntropyResumePrompt(prompt)) {
         await ensureStateDbOpen();
         const state = await deriveState(basePath);
         if (state.phase === "executing" && state.activeTask && state.activeMilestone && state.activeSlice) {

package/dist/resources/extensions/gsd/clean-root-preflight.js

@@ -3,13 +3,13 @@
  *
  * #2909: Adds a fast-path git status check before milestone completion merges.
  * When the working tree is dirty the user is warned and changes are auto-stashed
- * so the merge can proceed cleanly.  After the merge completes, postflightPopStash
- * restores the stashed changes.
+ * so the merge can proceed cleanly. After the merge completes, postflightPopStash
+ * restores the stashed changes and reports whether manual recovery is needed.
  *
  * Design constraints (from Trek-e approval):
  *  - Warn the user before stashing (no silent surprises)
  *  - git stash push / git stash pop only — no custom stash management layer
- *  - Stash/pop errors are logged but MUST NOT block the merge
+ *  - Stash/pop errors are logged but MUST NOT block the merge itself
  *  - Fast-path status check — clean trees pay no extra cost
  */
 import { execFileSync } from "node:child_process";
@@ -98,7 +98,8 @@ export function preflightCleanRoot(basePath, milestoneId, notify) {
  *
  * Only called when preflightCleanRoot returned stashPushed=true.
  * Any pop error (e.g. conflict) is logged and notified but does NOT throw —
- * the merge already completed successfully.
+ * the merge already completed successfully. Callers must treat
+ * needsManualRecovery=true as a dirty workspace stop, not a clean completion.
  */
 export function postflightPopStash(basePath, milestoneId, stashMarker, notify) {
     let stashRef = null;
@@ -108,7 +109,11 @@ export function postflightPopStash(basePath, milestoneId, stashMarker, notify) {
             const msg = `No matching GSD preflight stash found for milestone ${milestoneId}; leaving stash list untouched.`;
             logWarning("preflight", msg);
             notify(msg, "warning");
-            return;
+            return {
+                restored: false,
+                needsManualRecovery: true,
+                message: msg,
+            };
         }
         execFileSync("git", ["stash", "pop", stashRef], {
             cwd: basePath,
@@ -116,7 +121,14 @@ export function postflightPopStash(basePath, milestoneId, stashMarker, notify) {
             encoding: "utf-8",
             env: GIT_NO_PROMPT_ENV,
         });
-        notify(`Restored stashed changes after milestone ${milestoneId} merge.`, "info");
+        const msg = `Restored stashed changes after milestone ${milestoneId} merge.`;
+        notify(msg, "info");
+        return {
+            restored: true,
+            needsManualRecovery: false,
+            message: msg,
+            stashRef,
+        };
     }
     catch (err) {
         // Pop conflicts mean the merged code collides with the stashed changes.
@@ -127,5 +139,11 @@ export function postflightPopStash(basePath, milestoneId, stashMarker, notify) {
         const msg = `git stash pop ${stashRef ?? ""}`.trim() + ` failed after merge of milestone ${milestoneId}: ${err instanceof Error ? err.message : String(err)}. ${restoreHint}`;
         logWarning("preflight", msg);
         notify(msg, "warning");
+        return {
+            restored: false,
+            needsManualRecovery: true,
+            message: msg,
+            ...(stashRef ? { stashRef } : {}),
+        };
     }
 }

package/dist/resources/extensions/gsd/commands-handlers.js

@@ -17,6 +17,8 @@ import { isAutoActive, checkRemoteAutoSession } from "./auto.js";
 import { getAutoWorktreePath } from "./auto-worktree.js";
 import { currentDirectoryRoot, projectRoot } from "./commands/context.js";
 import { loadPrompt } from "./prompt-loader.js";
+import { buildDoctorHealIssuePayload, buildDoctorHealSummary, buildWorkflowDispatchContent, } from "./workflow-protocol.js";
+import { restoreGsdWorkflowTools, scopeGsdWorkflowToolsForDispatch, } from "./bootstrap/register-hooks.js";
 const UPDATE_REGISTRY_URL = "https://registry.npmjs.org/gsd-pi/latest";
 const UPDATE_FETCH_TIMEOUT_MS = 5000;
 // Detects a bun-installed gsd via `process.argv[1]`. Mirrors isBunInstall in
@@ -64,13 +66,19 @@ export function dispatchDoctorHeal(pi, scope, reportText, structuredIssues) {
     const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
     const workflow = readFileSync(workflowPath, "utf-8");
     const prompt = loadPrompt("doctor-heal", {
-        doctorSummary: reportText,
-        structuredIssues,
+        doctorSummary: buildDoctorHealSummary(reportText),
+        structuredIssues: buildDoctorHealIssuePayload(structuredIssues),
         scopeLabel: scope ?? "active milestone / blocking scope",
         doctorCommandSuffix: scope ? ` ${scope}` : "",
     });
-    const content = `Read the following GSD workflow protocol and execute exactly.\n\n${workflow}\n\n## Your Task\n\n${prompt}`;
-    pi.sendMessage({ customType: "gsd-doctor-heal", content, display: false }, { triggerTurn: true });
+    const content = buildWorkflowDispatchContent({ workflow, workflowPath, task: prompt });
+    const savedTools = scopeGsdWorkflowToolsForDispatch(pi);
+    try {
+        pi.sendMessage({ customType: "gsd-doctor-heal", content, display: false }, { triggerTurn: true });
+    }
+    finally {
+        restoreGsdWorkflowTools(pi, savedTools);
+    }
 }
 /** Parse doctor command args into structured flags and positionals (pure, no I/O). */
 export function parseDoctorArgs(args) {
@@ -213,11 +221,17 @@ export async function handleTriage(ctx, pi, basePath) {
     });
     const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
     const workflow = readFileSync(workflowPath, "utf-8");
-    pi.sendMessage({
-        customType: "gsd-triage",
-        content: `Read the following GSD workflow protocol and execute exactly.\n\n${workflow}\n\n## Your Task\n\n${prompt}`,
-        display: false,
-    }, { triggerTurn: true });
+    const savedTools = scopeGsdWorkflowToolsForDispatch(pi);
+    try {
+        pi.sendMessage({
+            customType: "gsd-triage",
+            content: buildWorkflowDispatchContent({ workflow, workflowPath, task: prompt }),
+            display: false,
+        }, { triggerTurn: true });
+    }
+    finally {
+        restoreGsdWorkflowTools(pi, savedTools);
+    }
 }
 export async function handleSteer(change, ctx, pi) {
     const basePath = currentDirectoryRoot();

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

@@ -26,6 +26,58 @@ function isAlreadyActiveConstraintError(err) {
     }
     return /\bUNIQUE\b|\bconstraint failed\b/i.test(msg);
 }
+function settleStaleActiveDispatchForUnit(input, now) {
+    const db = _getAdapter();
+    const active = db.prepare(`SELECT id, status, worker_id, milestone_lease_token
+     FROM unit_dispatches
+     WHERE unit_id = :unit_id
+       AND status IN ('claimed','running')
+     ORDER BY id DESC
+     LIMIT 1`).get({ ":unit_id": input.unitId });
+    if (!active)
+        return;
+    if (active.worker_id === input.workerId &&
+        active.milestone_lease_token === input.milestoneLeaseToken) {
+        return;
+    }
+    const reason = "stale-dispatch-lease-takeover";
+    const result = db.prepare(`UPDATE unit_dispatches
+     SET status = 'canceled',
+         ended_at = :ended_at,
+         exit_reason = :reason
+     WHERE id = :id
+       AND status IN ('claimed','running')
+       AND (worker_id != :worker_id OR milestone_lease_token != :token)`).run({
+        ":id": active.id,
+        ":ended_at": now,
+        ":reason": reason,
+        ":worker_id": input.workerId,
+        ":token": input.milestoneLeaseToken,
+    });
+    const changes = typeof result.changes === "number"
+        ? result.changes
+        : 0;
+    if (changes < 1)
+        return;
+    insertAuditEvent({
+        eventId: randomUUID(),
+        traceId: input.traceId,
+        turnId: input.turnId ?? undefined,
+        category: "orchestration",
+        type: "dispatch-stale-canceled",
+        ts: now,
+        payload: {
+            dispatchId: active.id,
+            unitId: input.unitId,
+            priorStatus: active.status,
+            priorWorkerId: active.worker_id,
+            priorMilestoneLeaseToken: active.milestone_lease_token,
+            takeoverWorkerId: input.workerId,
+            takeoverMilestoneLeaseToken: input.milestoneLeaseToken,
+            reason,
+        },
+    });
+}
 /**
  * Insert a new dispatch row in `claimed` state. Atomic guard against
  * double-claim (B2): the partial unique index
@@ -58,6 +110,7 @@ export function recordDispatchClaim(input) {
                 milestoneLeaseToken: input.milestoneLeaseToken,
             };
         }
+        settleStaleActiveDispatchForUnit(input, now);
         try {
             const result = db.prepare(`INSERT INTO unit_dispatches (
           trace_id, turn_id, worker_id, milestone_lease_token,

package/dist/resources/extensions/gsd/ecosystem/gsd-extension-api.js

@@ -127,6 +127,8 @@ export function createGSDExtensionAPI(pi, sharedHandlers) {
         getActiveTools: () => pi.getActiveTools(),
         getAllTools: () => pi.getAllTools(),
         setActiveTools: (...args) => pi.setActiveTools(...args),
+        getVisibleSkills: () => pi.getVisibleSkills(),
+        setVisibleSkills: (...args) => pi.setVisibleSkills(...args),
         getCommands: () => pi.getCommands(),
         // ── Model & thinking ───────────────────────────────────────────────
         setModel: (...args) => pi.setModel(...args),

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

@@ -51,6 +51,8 @@ export { showQueue, handleQueueReorder, showQueueAdd, buildExistingMilestonesCon
 import { logWarning } from "./workflow-logger.js";
 import { deleteRuntimeKv } from "./db/runtime-kv.js";
 import { PAUSED_SESSION_KV_KEY } from "./interrupted-session.js";
+import { buildWorkflowDispatchContent } from "./workflow-protocol.js";
+import { isFullGsdToolSurfaceRequested, restoreGsdWorkflowTools, scopeGsdWorkflowToolsForDispatch } from "./bootstrap/register-hooks.js";
 function scheduleAutoStartAfterIdle(ctx, pi, basePath, verboseMode, options, launch = startAutoDetached) {
     const waitForIdle = typeof ctx.waitForIdle === "function"
         ? ctx.waitForIdle.bind(ctx)
@@ -845,38 +847,55 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType)
             return;
         }
     }
-    // Scope tools for discuss flows (#2949).
+    // Scope tools for guided workflow turns (#2949, token-consumption savings).
     // Providers with grammar-based constrained decoding (xAI/Grok) return
     // "Grammar is too complex" when the combined tool schema is too large.
-    // Discuss flows only need a small subset of GSD tools — strip the heavy
-    // planning/execution/completion tools to keep the grammar within limits.
+    // Guided workflow turns only need the active unit's tool surface; strip
+    // unrelated GSD tools and broad non-GSD tools for this queued turn, then
+    // restore so the narrowed surface does not leak into future dispatches.
     let savedTools = null;
-    if (unitType?.startsWith("discuss-")) {
+    try {
         const currentTools = pi.getActiveTools();
-        savedTools = currentTools;
-        // Keep all non-GSD tools (builtins, other extensions) and only the
-        // GSD tools on the discuss allowlist.
-        const scopedTools = currentTools.filter((t) => !t.startsWith("gsd_") || DISCUSS_TOOLS_ALLOWLIST.includes(t));
-        pi.setActiveTools(scopedTools);
-        debugLog("discuss-tool-scoping", {
-            unitType,
-            before: currentTools.length,
-            after: scopedTools.length,
-            removed: currentTools.length - scopedTools.length,
-        });
-    }
-    const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
-    const workflow = readFileSync(workflowPath, "utf-8");
-    pi.sendMessage({
-        customType,
-        content: `Read the following GSD workflow protocol and execute exactly.\n\n${workflow}\n\n## Your Task\n\n${note}`,
-        display: false,
-    }, { triggerTurn: true });
-    // Restore full tool set after the message is queued. The LLM turn has
-    // already captured the scoped set — restoring prevents the narrowed
-    // tools from leaking into subsequent dispatches (#3628).
-    if (savedTools) {
-        pi.setActiveTools(savedTools);
+        savedTools = {
+            tools: currentTools,
+            visibleSkills: typeof pi.getVisibleSkills === "function" ? pi.getVisibleSkills() : undefined,
+            restoreVisibleSkills: typeof pi.setVisibleSkills === "function",
+        };
+        if (unitType?.startsWith("discuss-") && !isFullGsdToolSurfaceRequested()) {
+            // Keep all non-GSD tools (builtins, other extensions) and only the
+            // GSD tools on the discuss allowlist.
+            const scopedTools = currentTools.filter((t) => !t.startsWith("gsd_") || DISCUSS_TOOLS_ALLOWLIST.includes(t));
+            pi.setActiveTools(scopedTools);
+            const scopedState = scopeGsdWorkflowToolsForDispatch(pi, unitType);
+            savedTools = {
+                tools: currentTools,
+                visibleSkills: scopedState?.visibleSkills ?? savedTools.visibleSkills,
+                restoreVisibleSkills: scopedState?.restoreVisibleSkills ?? savedTools.restoreVisibleSkills,
+            };
+            debugLog("discuss-tool-scoping", {
+                unitType,
+                before: currentTools.length,
+                after: pi.getActiveTools().length,
+                removed: currentTools.length - pi.getActiveTools().length,
+            });
+        }
+        else {
+            savedTools = scopeGsdWorkflowToolsForDispatch(pi, unitType) ?? savedTools;
+        }
+        const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
+        const workflow = readFileSync(workflowPath, "utf-8");
+        pi.sendMessage({
+            customType,
+            content: buildWorkflowDispatchContent({ workflow, workflowPath, task: note }),
+            display: false,
+        }, { triggerTurn: true });
+    }
+    finally {
+        // Restore full tool set after the message is queued. The LLM turn has
+        // already captured the scoped set — restoring prevents the narrowed
+        // tools from leaking into subsequent dispatches (#3628). The finally
+        // block ensures restoration even if sendMessage throws.
+        restoreGsdWorkflowTools(pi, savedTools);
     }
 }
 function getStructuredQuestionsAvailability(pi, ctx) {

package/dist/resources/extensions/gsd/native-git-bridge.js

@@ -5,7 +5,7 @@
 // Both READ and WRITE operations are native — push operations remain as
 // execSync calls because git2 credential handling is too complex.
 import { execFileSync } from "node:child_process";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { GSDError, GSD_GIT_ERROR } from "./errors.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
@@ -1007,6 +1007,24 @@ export function nativeRmForce(basePath, paths) {
         gitFileExec(basePath, ["rm", "--force", "--", path], true);
     }
 }
+function runGitWorktreeAdd(basePath, wtPath, branch, createBranch, startPoint) {
+    if (createBranch) {
+        const branchRef = gitExec(basePath, ["show-ref", "--verify", `refs/heads/${branch}`], true);
+        if (branchRef) {
+            gitExec(basePath, ["worktree", "add", wtPath, branch]);
+            return;
+        }
+        gitExec(basePath, ["worktree", "add", "-b", branch, wtPath, startPoint ?? "HEAD"]);
+    }
+    else {
+        gitExec(basePath, ["worktree", "add", wtPath, branch]);
+    }
+}
+export function assertWorktreeMaterialized(wtPath) {
+    if (existsSync(join(wtPath, ".git")))
+        return;
+    throw new GSDError(GSD_GIT_ERROR, `git worktree add did not materialize a valid worktree at ${wtPath}: missing .git file`);
+}
 /**
  * Add a new git worktree.
  * Native: libgit2 worktree API.
@@ -1016,14 +1034,20 @@ export function nativeWorktreeAdd(basePath, wtPath, branch, createBranch, startP
     const native = loadNative();
     if (native) {
         native.gitWorktreeAdd(basePath, wtPath, branch, createBranch, startPoint);
-        return;
-    }
-    if (createBranch) {
-        gitExec(basePath, ["worktree", "add", "-b", branch, wtPath, startPoint ?? "HEAD"]);
-    }
-    else {
-        gitExec(basePath, ["worktree", "add", wtPath, branch]);
+        try {
+            assertWorktreeMaterialized(wtPath);
+            return;
+        }
+        catch {
+            rmSync(wtPath, { recursive: true, force: true });
+            gitExec(basePath, ["worktree", "prune"], true);
+            runGitWorktreeAdd(basePath, wtPath, branch, createBranch, startPoint);
+            assertWorktreeMaterialized(wtPath);
+            return;
+        }
     }
+    runGitWorktreeAdd(basePath, wtPath, branch, createBranch, startPoint);
+    assertWorktreeMaterialized(wtPath);
 }
 /**
  * Remove a git worktree.

package/dist/resources/extensions/gsd/orphan-stash-audit.js

@@ -0,0 +1,101 @@
+// GSD-2 + src/resources/extensions/gsd/orphan-stash-audit.ts
+// Startup sweep for orphaned gsd-preflight-stash entries left behind by
+// interrupted milestone merges (#5538-followup).
+import { execFileSync } from "node:child_process";
+import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
+/**
+ * Recognize the "already restored" failure mode of `git stash apply`.
+ *
+ * When a preflight stash captured untracked files via `--include-untracked`
+ * and those files are now present in the working tree (e.g. a prior audit
+ * run already applied this stash), `git stash apply` aborts with
+ * `<path> already exists, no checkout` and exits non-zero. That is the
+ * idempotent steady state for this audit, not a recovery failure — treat
+ * it as a no-op so repeated GSD startups stop spamming the user with
+ * warnings about stashes that have already been restored (#5538-followup
+ * peer-review feedback).
+ */
+function _isAlreadyRestoredApplyError(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const stderr = err.stderr;
+    const stderrText = typeof stderr === "string" ? stderr : stderr instanceof Uint8Array ? Buffer.from(stderr).toString("utf-8") : "";
+    if (stderrText && /already exists, no checkout/i.test(stderrText))
+        return true;
+    const message = err instanceof Error ? err.message : String(err);
+    return /already exists, no checkout/i.test(message);
+}
+export { _isAlreadyRestoredApplyError };
+/**
+ * Audit `git stash list` for orphaned `gsd-preflight-stash:M00x:*` entries.
+ *
+ * The matching merge code in `phases.ts` previously skipped the postflight
+ * pop whenever `mergeAndExit` threw, leaking the user's pre-merge working
+ * tree into the stash list. For every preflight-stash entry whose milestone
+ * is now complete (per the supplied callback), `git stash apply` is invoked —
+ * NOT `pop`. The stash entry stays in the list so the user retains a backup
+ * if the apply produces unexpected merge results. Idempotent across repeated
+ * startup runs.
+ *
+ * Failures are best-effort: a list error (no repo, git unavailable) returns
+ * an empty result. An apply error becomes a warning the user sees alongside
+ * the existing orphan-branch audit messages — startup continues.
+ */
+export function auditOrphanedPreflightStashes(basePath, isMilestoneComplete) {
+    const result = { applied: [], warnings: [] };
+    let listOutput;
+    try {
+        listOutput = execFileSync("git", ["stash", "list", "--format=%gd%x00%s"], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+            env: GIT_NO_PROMPT_ENV,
+        });
+    }
+    catch {
+        return result;
+    }
+    const MARKER_RE = /\bgsd-preflight-stash:([A-Za-z0-9_-]+):/;
+    for (const line of listOutput.split("\n")) {
+        const sep = line.indexOf("\x00");
+        if (sep < 0)
+            continue;
+        const ref = line.slice(0, sep);
+        const subject = line.slice(sep + 1);
+        if (!ref || !subject)
+            continue;
+        const match = MARKER_RE.exec(subject);
+        if (!match)
+            continue;
+        const milestoneId = match[1];
+        let complete = false;
+        try {
+            complete = isMilestoneComplete(milestoneId);
+        }
+        catch (err) {
+            result.warnings.push(`Could not determine completion status for ${milestoneId} during preflight-stash audit: ${err instanceof Error ? err.message : String(err)}.`);
+            continue;
+        }
+        if (!complete)
+            continue;
+        try {
+            execFileSync("git", ["stash", "apply", "--quiet", ref], {
+                cwd: basePath,
+                stdio: ["ignore", "pipe", "pipe"],
+                encoding: "utf-8",
+                env: GIT_NO_PROMPT_ENV,
+            });
+            result.applied.push({ milestoneId, stashRef: ref });
+        }
+        catch (err) {
+            // Idempotent steady state: stash was already applied in a prior audit
+            // run; the files exist and `git stash apply` refuses to overwrite.
+            // Skip silently so repeat runs are no-ops.
+            if (_isAlreadyRestoredApplyError(err))
+                continue;
+            result.warnings.push(`Could not apply orphaned preflight stash ${ref} (milestone ${milestoneId}): ${err instanceof Error ? err.message : String(err)}. ` +
+                `Run \`git stash apply ${ref}\` manually to restore your pre-merge changes.`);
+        }
+    }
+    return result;
+}