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

package/src/resources/extensions/gsd/bootstrap/system-context.ts

@@ -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";
 
@@ -21,6 +23,11 @@ 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
@@ -158,8 +165,6 @@ export async function buildBeforeAgentStartResult(
     logWarning("bootstrap", `decisions backfill failed: ${(e as Error).message}`);
   }
 
-  const memoryBlock = await loadMemoryBlock(event.prompt ?? "");
-
   let newSkillsBlock = "";
   if (hasSkillSnapshot()) {
     const newSkills = detectNewSkills();
@@ -190,11 +195,10 @@ export async function buildBeforeAgentStartResult(
       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}`;
       }
@@ -206,6 +210,9 @@ export async function buildBeforeAgentStartResult(
   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;
@@ -218,12 +225,9 @@ export async function buildBeforeAgentStartResult(
     : "";
 
   // 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({
@@ -255,21 +259,55 @@ export function buildContextMessage(opts: {
   injection: string | null;
   forensicsInjection: string | null;
 }): { customType: string; content: string; display: false } | null {
-  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 as const };
   }
   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 as const };
   }
   if (memoryContent) {
-    return { customType: "gsd-memory", content: memoryContent, display: false as const };
+    return {
+      customType: "gsd-memory",
+      content: limitContextMessageContent(memoryContent, contextCharLimit),
+      display: false as const,
+    };
   }
   return null;
 }
 
+function getContextMessageCharLimit(): number | null {
+  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: string, limit: number | null): string {
+  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: string): string {
+  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.
  *
@@ -288,7 +326,10 @@ 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: string): Promise<string> {
+export async function loadMemoryBlock(
+  userPrompt: string,
+  opts: { includePromptRelevant?: boolean } = {},
+): Promise<string> {
   try {
     const { formatMemoriesForPrompt, getActiveMemoriesRanked, queryMemoriesRanked } = await import("../memory-store.js");
 
@@ -310,7 +351,7 @@ export async function loadMemoryBlock(userPrompt: string): Promise<string> {
 
     let relevant: typeof allRanked = [];
     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));
     }
@@ -362,14 +403,37 @@ export function loadKnowledgeBlock(gsdHomeDir: string, cwd: string): { block: st
   }
 
   const parts: string[] = [];
-  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(): number | null {
+  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: string, limit: number | null): string {
+  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(): string {
   const worktreeName = getActiveWorktreeName();
   const worktreeMainCwd = getWorktreeOriginalCwd();
@@ -423,6 +487,11 @@ function buildWorktreeContextBlock(): string {
  */
 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: string): boolean {
+  const trimmed = prompt.trim().toLowerCase().replace(/[.!?,]+$/g, "");
+  return RESUME_INTENT_PATTERNS.test(trimmed);
+}
+
 async function buildGuidedExecuteContextInjection(prompt: string, basePath: string): Promise<string | null> {
   const ensureStateDbOpen = async () => {
     const { ensureDbOpen } = await import("./dynamic-tools.js");
@@ -452,8 +521,7 @@ async function buildGuidedExecuteContextInjection(prompt: string, basePath: stri
   // 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/src/resources/extensions/gsd/clean-root-preflight.ts

@@ -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
  */
 
@@ -27,6 +27,13 @@ export interface PreflightResult {
   summary: string;
 }
 
+export interface PostflightResult {
+  restored: boolean;
+  needsManualRecovery: boolean;
+  message: string;
+  stashRef?: string;
+}
+
 function findPreflightStashRef(basePath: string, milestoneId: string, stashMarker?: string): string | null {
   const markerPrefix = `gsd-preflight-stash:${milestoneId}:`;
   let fallbackRef: string | null = null;
@@ -112,14 +119,15 @@ export function preflightCleanRoot(
  *
  * 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: string,
   milestoneId: string,
   stashMarker: string | undefined,
   notify: (message: string, level: "info" | "warning" | "error") => void,
-): void {
+): PostflightResult {
   let stashRef: string | null = null;
   try {
     stashRef = findPreflightStashRef(basePath, milestoneId, stashMarker);
@@ -127,7 +135,11 @@ export function postflightPopStash(
       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,
@@ -135,7 +147,14 @@ export function postflightPopStash(
       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.
     // Log a warning — the user needs to resolve manually, but the merge succeeded.
@@ -145,5 +164,11 @@ export function postflightPopStash(
     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/src/resources/extensions/gsd/commands-handlers.ts

@@ -26,6 +26,15 @@ 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;
@@ -72,18 +81,23 @@ export function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined,
   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}`;
+  const content = buildWorkflowDispatchContent({ workflow, workflowPath, task: prompt });
+  const savedTools = scopeGsdWorkflowToolsForDispatch(pi);
 
-  pi.sendMessage(
-    { customType: "gsd-doctor-heal", content, display: false },
-    { triggerTurn: true },
-  );
+  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). */
@@ -258,15 +272,20 @@ export async function handleTriage(ctx: ExtensionCommandContext, pi: ExtensionAP
 
   const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
   const workflow = readFileSync(workflowPath, "utf-8");
+  const savedTools = scopeGsdWorkflowToolsForDispatch(pi);
 
-  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 },
-  );
+  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: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {

package/src/resources/extensions/gsd/db/unit-dispatches.ts

@@ -98,6 +98,70 @@ function isAlreadyActiveConstraintError(err: unknown): boolean {
   return /\bUNIQUE\b|\bconstraint failed\b/i.test(msg);
 }
 
+function settleStaleActiveDispatchForUnit(input: RecordClaimInput, now: string): void {
+  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 }) as
+    | { id: number; status: DispatchStatus; worker_id: string; milestone_lease_token: number }
+    | undefined;
+
+  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 as { changes?: unknown }).changes === "number"
+      ? (result as { changes: number }).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
@@ -135,6 +199,8 @@ export function recordDispatchClaim(input: RecordClaimInput): RecordClaimResult
       };
     }
 
+    settleStaleActiveDispatchForUnit(input, now);
+
     try {
       const result = db.prepare(
         `INSERT INTO unit_dispatches (

package/src/resources/extensions/gsd/ecosystem/gsd-extension-api.ts

@@ -204,6 +204,9 @@ export function createGSDExtensionAPI(
     getAllTools: () => pi.getAllTools(),
     setActiveTools: (...args: Parameters<ExtensionAPI["setActiveTools"]>) =>
       pi.setActiveTools(...args),
+    getVisibleSkills: () => pi.getVisibleSkills(),
+    setVisibleSkills: (...args: Parameters<ExtensionAPI["setVisibleSkills"]>) =>
+      pi.setVisibleSkills(...args),
     getCommands: () => pi.getCommands(),
 
     // ── Model & thinking ───────────────────────────────────────────────

package/src/resources/extensions/gsd/guided-flow.ts

@@ -86,6 +86,8 @@ export {
 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";
 
 type AutoStartOptions = Parameters<typeof startAutoDetached>[4];
 type AutoStartLauncher = typeof startAutoDetached;
@@ -1062,46 +1064,61 @@ async function dispatchWorkflow(
     }
   }
 
-  // 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.
-  let savedTools: string[] | null = null;
-  if (unitType?.startsWith("discuss-")) {
-    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,
-    });
-  }
+  // 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: ReturnType<typeof scopeGsdWorkflowToolsForDispatch> = null;
 
-  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
-  const workflow = readFileSync(workflowPath, "utf-8");
+  try {
+    const currentTools = pi.getActiveTools();
+    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;
+    }
 
-  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 },
-  );
+    const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
+    const workflow = readFileSync(workflowPath, "utf-8");
 
-  // 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);
+    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);
   }
 }
 

package/src/resources/extensions/gsd/native-git-bridge.ts

@@ -1183,6 +1183,33 @@ export function nativeRmForce(basePath: string, paths: string[]): void {
   }
 }
 
+function runGitWorktreeAdd(
+  basePath: string,
+  wtPath: string,
+  branch: string,
+  createBranch?: boolean,
+  startPoint?: string,
+): void {
+  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: string): void {
+  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.
@@ -1198,14 +1225,20 @@ export function nativeWorktreeAdd(
   const native = loadNative();
   if (native) {
     native.gitWorktreeAdd(basePath, wtPath, branch, createBranch, startPoint);
-    return;
+    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;
+    }
   }
 
-  if (createBranch) {
-    gitExec(basePath, ["worktree", "add", "-b", branch, wtPath, startPoint ?? "HEAD"]);
-  } else {
-    gitExec(basePath, ["worktree", "add", wtPath, branch]);
-  }
+  runGitWorktreeAdd(basePath, wtPath, branch, createBranch, startPoint);
+  assertWorktreeMaterialized(wtPath);
 }
 
 /**