gsd-pi 2.80.0-dev.c5f2443b3 → 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/bootstrap/write-gate.js

@@ -1,7 +1,9 @@
-import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { minimatch } from "minimatch";
+import { getIsolationMode } from "../preferences.js";
 import { logWarning } from "../workflow-logger.js";
+import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "../worktree-root.js";
 /**
  * Regex matching milestone CONTEXT.md file names in both legacy M001
  * and unique M001-abc123 formats. Exported so regex-hardening tests
@@ -728,3 +730,129 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
     // avoids breaking gsd_* MCP tools or future safe additions.
     return { block: false };
 }
+// ─── Worktree isolation write gate (#5199) ────────────────────────────────
+//
+// When `git.isolation: worktree` is configured, the per-unit commit pipeline
+// only runs inside the auto-mode loop (`auto-post-unit.ts`). If the LLM
+// authors code at the project root before auto-mode is started, those writes
+// land in the working tree but never reach a commit — they're silently
+// orphaned outside git history. This guard blocks those writes at the
+// tool_call seam so the agent receives a clear error instead.
+const WORKTREE_GATE_BOOTSTRAP_UNITS = new Set([
+    "discuss-milestone",
+    "plan-milestone",
+    "init",
+]);
+function realpathOrResolve(p) {
+    const abs = resolve(p);
+    try {
+        return realpathSync(abs);
+    }
+    catch {
+        // Path doesn't exist (yet) — realpath the deepest existing ancestor so
+        // platforms where /tmp -> /private/tmp don't break containment checks.
+        let dir = abs;
+        const tail = [];
+        while (dir && dir !== resolve(dir, "..")) {
+            try {
+                const real = realpathSync(dir);
+                return tail.length ? join(real, ...tail.reverse()) : real;
+            }
+            catch {
+                const idx = dir.lastIndexOf(sep);
+                if (idx <= 0)
+                    break;
+                tail.push(dir.slice(idx + 1));
+                dir = dir.slice(0, idx) || sep;
+            }
+        }
+        return abs;
+    }
+}
+function isPathContained(target, container) {
+    if (target === container)
+        return true;
+    return target.startsWith(container.endsWith(sep) ? container : container + sep);
+}
+/**
+ * Block planning-write tool calls that would land code at the project root
+ * while `git.isolation: worktree` is in effect and auto-mode hasn't created
+ * (or flipped cwd into) the milestone worktree.
+ *
+ * Pure / unit-testable. Callers in `register-hooks.ts` supply the resolved
+ * project root and current auto liveness; this function does no I/O beyond
+ * realpath resolution.
+ *
+ * Allow rules (in order):
+ *   1. Tool isn't a planning-write (write/edit/multi_edit/notebook_edit).
+ *   2. `GSD_DISABLE_WORKTREE_WRITE_GUARD=1` self-hosting bypass.
+ *   3. Isolation mode is not "worktree".
+ *   4. Active unit is a bootstrap unit (discuss-milestone/plan-milestone/init).
+ *   5. Target is inside `<projectRoot>/.gsd/worktrees/` (a real worktree).
+ *   6. Target is inside `<projectRoot>/.gsd/` and isn't masquerading as a
+ *      worktrees sibling (rejects the `.gsd/worktrees-extra/…` prefix trick).
+ *   7. Auto is live AND `effectiveBasePath` is itself a `.gsd/worktrees/…` path.
+ *
+ * Otherwise: block with a message that points the agent at `/gsd` to start
+ * auto-mode.
+ */
+export function shouldBlockWorktreeWrite(toolName, targetPath, effectiveBasePath, isAutoLive, currentUnitType) {
+    const tool = canonicalToolName(toolName);
+    if (!PLANNING_WRITE_TOOLS.has(tool))
+        return { block: false };
+    if (process.env.GSD_DISABLE_WORKTREE_WRITE_GUARD === "1")
+        return { block: false };
+    if (getIsolationMode(effectiveBasePath) !== "worktree")
+        return { block: false };
+    if (currentUnitType && WORKTREE_GATE_BOOTSTRAP_UNITS.has(currentUnitType))
+        return { block: false };
+    if (!targetPath) {
+        return {
+            block: true,
+            reason: [
+                `HARD BLOCK: ${tool} called with empty path while \`git.isolation: worktree\` is configured`,
+                `and auto-mode is not active. Refusing to allow writes that cannot be located.`,
+            ].join(" "),
+        };
+    }
+    // Resolve the target relative to the project root, then realpath to defeat
+    // symlink-based escapes and prefix tricks (e.g. .gsd/worktrees-extra/).
+    const projectRoot = resolveWorktreeProjectRoot(effectiveBasePath);
+    const absTarget = isAbsolute(targetPath) ? targetPath : resolve(projectRoot, targetPath);
+    const realTarget = realpathOrResolve(absTarget);
+    const realRoot = realpathOrResolve(projectRoot);
+    const realGsd = realpathOrResolve(join(projectRoot, ".gsd"));
+    const realWorktreesDir = realpathOrResolve(join(projectRoot, ".gsd", "worktrees"));
+    // Allow writes inside the legitimate worktrees subtree.
+    if (isPathContained(realTarget, realWorktreesDir))
+        return { block: false };
+    // Allow writes to .gsd/ planning artifacts, but reject siblings whose name
+    // starts with "worktrees" (the worktrees-extra prefix trick — case 4).
+    if (isPathContained(realTarget, realGsd)) {
+        const rel = relative(realGsd, realTarget);
+        const firstSeg = rel.split(/[\/\\]/)[0] ?? "";
+        if (!firstSeg.startsWith("worktrees"))
+            return { block: false };
+        // fall through: looks like worktrees<something> sibling — block
+    }
+    // Auto is live and the caller is operating inside a worktree path —
+    // host tool's write happens in worktree context; let it through.
+    if (isAutoLive && isGsdWorktreePath(effectiveBasePath))
+        return { block: false };
+    // Block. Provide enough context that the agent can self-correct.
+    const displayTarget = isPathContained(realTarget, realRoot)
+        ? relative(realRoot, realTarget) || "."
+        : realTarget;
+    return {
+        block: true,
+        reason: [
+            `HARD BLOCK: Worktree isolation is configured (\`git.isolation: worktree\`) but auto-mode is`,
+            `not running and the target "${displayTarget}" is not inside \`.gsd/worktrees/<MID>/\`.`,
+            `Code edits at the project root would be lost — only the auto-mode commit pipeline`,
+            `(auto-post-unit) commits work, and it never runs outside the loop.`,
+            `Required action: start auto-mode with \`/gsd\` so the milestone worktree is created,`,
+            `then write inside it. To disable this guard for self-hosting development, set`,
+            `GSD_DISABLE_WORKTREE_WRITE_GUARD=1.`,
+        ].join(" "),
+    };
+}

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

@@ -3,19 +3,44 @@
  *
  * #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";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { logWarning } from "./workflow-logger.js";
 import { nativeHasChanges } from "./native-git-bridge.js";
+function findPreflightStashRef(basePath, milestoneId, stashMarker) {
+    const markerPrefix = `gsd-preflight-stash:${milestoneId}:`;
+    let fallbackRef = null;
+    try {
+        const list = execFileSync("git", ["stash", "list", "--format=%gd%x00%s"], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+            env: GIT_NO_PROMPT_ENV,
+        });
+        for (const line of list.split("\n")) {
+            const [ref, subject] = line.split("\x00");
+            if (!ref || !subject)
+                continue;
+            if (stashMarker && subject.includes(stashMarker))
+                return ref;
+            if (!fallbackRef && subject.includes(markerPrefix))
+                fallbackRef = ref;
+        }
+    }
+    catch (err) {
+        logWarning("preflight", `stash list failed before restore: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return fallbackRef;
+}
 /**
  * Check the working tree for dirty files before a milestone merge.
  *
@@ -47,7 +72,8 @@ export function preflightCleanRoot(basePath, milestoneId, notify) {
     notify(warnMsg, "warning");
     // Push the stash
     try {
-        execFileSync("git", ["stash", "push", "--include-untracked", "-m", "gsd-preflight-stash"], {
+        const stashMarker = `gsd-preflight-stash:${milestoneId}:${process.pid}:${Date.now()}:${process.hrtime.bigint().toString(36)}`;
+        execFileSync("git", ["stash", "push", "--include-untracked", "-m", `gsd-preflight-stash [${stashMarker}]`], {
             cwd: basePath,
             stdio: ["ignore", "pipe", "pipe"],
             encoding: "utf-8",
@@ -55,6 +81,7 @@ export function preflightCleanRoot(basePath, milestoneId, notify) {
         });
         return {
             stashPushed: true,
+            stashMarker,
             summary: `Stashed uncommitted changes before merge (milestone ${milestoneId}).`,
         };
     }
@@ -71,23 +98,52 @@ 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, notify) {
+export function postflightPopStash(basePath, milestoneId, stashMarker, notify) {
+    let stashRef = null;
     try {
-        execFileSync("git", ["stash", "pop"], {
+        stashRef = findPreflightStashRef(basePath, milestoneId, stashMarker);
+        if (!stashRef) {
+            const msg = `No matching GSD preflight stash found for milestone ${milestoneId}; leaving stash list untouched.`;
+            logWarning("preflight", msg);
+            notify(msg, "warning");
+            return {
+                restored: false,
+                needsManualRecovery: true,
+                message: msg,
+            };
+        }
+        execFileSync("git", ["stash", "pop", stashRef], {
             cwd: basePath,
             stdio: ["ignore", "pipe", "pipe"],
             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.
-        const msg = `git stash pop failed after merge of milestone ${milestoneId}: ${err instanceof Error ? err.message : String(err)}. Run "git stash pop" manually to restore your changes.`;
+        const restoreHint = stashRef
+            ? `Run "git stash pop ${stashRef}" or "git stash apply ${stashRef}" manually to restore the correct stash.`
+            : `Run "git stash list" to find the matching GSD preflight stash before restoring manually.`;
+        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/dispatcher.js

@@ -33,5 +33,10 @@ export async function handleGSDCommand(args, ctx, pi) {
     }
     if (handled)
         return;
+    if (trimmed.includes(" ")) {
+        const { handleDo } = await import("../commands-do.js");
+        await handleDo(trimmed, ctx, pi);
+        return;
+    }
     ctx.ui.notify(`Unknown: /gsd ${trimmed}. Run /gsd help for available commands.`, "warning");
 }

package/dist/resources/extensions/gsd/commands-extract-learnings.js

@@ -114,14 +114,19 @@ Using the \`write\` tool, persist the full structured report to
 LEARNINGS.md is the full, cited audit trail. Write it first — subsequent steps
 feed from its content.
 
-### Step 3 — Optionally pre-query the memory store for semantic duplicates
+### Step 3 — Run one bounded duplicate check
 
-Before persisting any extracted item in Steps 4–6, you may call
-\`memory_query\` with 2–3 keywords from the item to check whether the
-memory store already holds a semantically equivalent entry at high
-confidence. Skip those items in their respective steps. The memory store
-is the single source of truth for cross-session durable knowledge — no
-other persistence call is part of this flow.
+Before persisting extracted items in Steps 4–6, do at most one duplicate-check
+pass for the durable Decisions, Lessons, and Patterns from this milestone. Use
+the already-written LEARNINGS.md content and call \`memory_query\` once with a
+compact keyword summary for the whole batch. If that result clearly shows a
+semantically equivalent high-confidence memory for an item, mark only that item
+as already captured and skip it in its respective persistence step.
+
+Do not re-read milestone artefacts or repeat memory queries category-by-category
+after this point. The memory store is the single source of truth for
+cross-session durable knowledge — no other persistence call is part of this
+flow.
 
 ### Step 4 — Persist Patterns via \`capture_thought\`
 
@@ -160,11 +165,11 @@ later projection back to a human-visible decisions register stays lossless
 
 ### Step 7 — Deduplication rule (applies to Steps 4, 5, 6)
 
-Before each \`capture_thought\` call, optionally call \`memory_query\` with 2–3
-keywords from the entry. If a semantically equivalent memory is returned at
-high confidence, skip the capture entirely. Prefer skipping a near-duplicate
-over creating a second slightly-different row — redundancy degrades the
-signal.
+Use only the duplicate-check result from Step 3. If that bounded check returned
+a semantically equivalent memory at high confidence for an extracted item, skip
+the capture entirely. Otherwise, persist the item once via \`capture_thought\`.
+Prefer skipping a near-duplicate over creating a second slightly-different row
+— redundancy degrades the signal.
 
 ### Step 8 — Surprises stay only in LEARNINGS.md
 

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/context-budget.js

@@ -7,7 +7,7 @@
  *
  * @see D001 (module location), D002 (200K fallback), D003 (section-boundary truncation)
  */
-import { getCharsPerToken } from "./token-counter.js";
+import { getCharsPerToken, isAccurateCountingAvailable, countTokensSync, } from "./token-counter.js";
 // ─── Budget ratio constants ──────────────────────────────────────────────────
 // Percentages of total context window allocated to each budget category.
 // These are applied after tokens→chars conversion.
@@ -23,6 +23,22 @@ const CHARS_PER_TOKEN = 4;
 const DEFAULT_CONTEXT_WINDOW = 200_000;
 /** Conservative effective context for Claude Code subscription routing (#4676) */
 const CLAUDE_CODE_EFFECTIVE_CONTEXT_WINDOW = 200_000;
+/**
+ * Cached empirical chars-per-token from a tiktoken probe, keyed by provider.
+ * countTokensSync's fallback path is provider-aware, so we cache per-provider
+ * to preserve that distinction once the encoder warms. The cl100k_base encoder
+ * itself gives a stable ratio for ASCII English so a single probe per provider
+ * key is sufficient. Empty map means "not yet probed" or "encoder unavailable".
+ */
+const _empiricalCharsPerTokenByProvider = new Map();
+/**
+ * Test hook — clears the empirical chars-per-token cache so test cases that
+ * assert against the static char-ratio fallback aren't polluted by a prior
+ * tiktoken-warmed run in the same process. Production code must not call this.
+ */
+export function _resetEmpiricalCacheForTest() {
+    _empiricalCharsPerTokenByProvider.clear();
+}
 /** Percentage of context consumed before suggesting a continue-here checkpoint */
 const CONTINUE_THRESHOLD_PERCENT = 70;
 // ─── Task count bounds ───────────────────────────────────────────────────────
@@ -46,7 +62,26 @@ const TASK_COUNT_TIERS = [
 export function computeBudgets(contextWindow, provider) {
     const effectiveWindow = contextWindow > 0 ? contextWindow : DEFAULT_CONTEXT_WINDOW;
     const charsPerToken = provider ? getCharsPerToken(provider) : CHARS_PER_TOKEN;
-    const totalChars = effectiveWindow * charsPerToken;
+    // Prefer the tiktoken encoder for total-char estimation when it has been
+    // warmed (initTokenCounter resolved). The cl100k_base ratio is stable for
+    // ASCII English, so probe once per provider and cache — computeBudgets is
+    // called multiple times per prompt build and the probe encode is otherwise
+    // wasted work.
+    let totalChars;
+    if (isAccurateCountingAvailable()) {
+        const providerKey = provider ?? "__default__";
+        let empirical = _empiricalCharsPerTokenByProvider.get(providerKey);
+        if (empirical === undefined) {
+            const probe = "the quick brown fox jumps over the lazy dog ".repeat(64);
+            const probeTokens = countTokensSync(probe, provider);
+            empirical = probeTokens > 0 ? probe.length / probeTokens : charsPerToken;
+            _empiricalCharsPerTokenByProvider.set(providerKey, empirical);
+        }
+        totalChars = effectiveWindow * empirical;
+    }
+    else {
+        totalChars = effectiveWindow * charsPerToken;
+    }
     return {
         summaryBudgetChars: Math.floor(totalChars * SUMMARY_RATIO),
         inlineContextBudgetChars: Math.floor(totalChars * INLINE_CONTEXT_RATIO),