gsd-pi 2.80.0-dev.0d763dc29 → 2.80.0-dev.2be7caf18

package/README.md

@@ -361,7 +361,7 @@ The database is authoritative for milestones, slices, tasks, requirements, decis
 
 2. **Context pre-loading** — The dispatch prompt includes inlined task plans, slice plans, prior task summaries, dependency summaries, roadmap excerpts, and decisions register. The LLM starts with everything it needs instead of spending tool calls reading files.
 
-3. **Context Mode** — Context Mode is enabled by default and gives every auto-mode unit guidance for preserving context. Agents are steered toward `gsd_exec` for noisy scans, builds, tests, and diagnostics; full stdout/stderr is saved under `.gsd/exec/` while only a short digest enters the conversation. `gsd_exec_search` lets agents reuse prior runs instead of repeating expensive checks, and `gsd_resume` reads `.gsd/last-snapshot.md` after compaction or resume. Opt out with `context_mode.enabled: false`; tune sandbox timeout/output caps with `context_mode.exec_timeout_ms`, `context_mode.exec_stdout_cap_bytes`, and `context_mode.exec_digest_chars`.
+3. **Context Mode** — Context Mode is enabled by default and gives eligible auto-mode units guidance for preserving context. Agents are steered toward `gsd_exec` for noisy scans, builds, tests, and diagnostics; capped stdout/stderr and metadata are saved under `.gsd/exec/` while only a short digest enters the conversation. `gsd_exec_search` lets agents reuse prior runs instead of repeating expensive checks, and `gsd_resume` reads a prior compaction snapshot from `.gsd/last-snapshot.md` when one exists. Opt out with `context_mode.enabled: false` to disable Context Mode guidance, snapshot injection, `gsd_exec`, `gsd_exec_search`, and `gsd_resume`; tune sandbox timeout/output caps and environment forwarding with `context_mode.exec_timeout_ms`, `context_mode.exec_stdout_cap_bytes`, `context_mode.exec_digest_chars`, and `context_mode.exec_env_allowlist`.
 
 4. **Git isolation** — When `git.isolation` is set to `worktree` or `branch`, each milestone runs on its own `milestone/<MID>` branch (in a worktree or in-place). All slice work commits sequentially — no branch switching, no merge conflicts. When the milestone completes, it's squash-merged to main as one clean commit. The default is `none` (work on the current branch), configurable via preferences. If `worktree` is configured in a repo with no committed `HEAD`, GSD temporarily behaves as `none` until the first commit exists because git worktrees need a committed start point.
 
@@ -659,10 +659,11 @@ auto_report: true
 | `unique_milestone_ids`            | Uses unique milestone names to avoid clashes when working in teams of people                          |
 | `git.isolation`                   | `none` (default), `worktree`, or `branch` — enable worktree or branch isolation for milestone work. `worktree` requires a committed `HEAD`; zero-commit repos temporarily run as `none`    |
 | `git.manage_gitignore`            | Set `false` to prevent GSD from modifying `.gitignore`                                                |
-| `context_mode.enabled`            | Context Mode is default-on; set `false` to disable `gsd_exec`, exec history guidance, and resume snapshots |
+| `context_mode.enabled`            | Context Mode is default-on; set `false` to disable prompt guidance, snapshot injection, `gsd_exec`, `gsd_exec_search`, and `gsd_resume` |
 | `context_mode.exec_timeout_ms`    | Timeout for sandboxed `gsd_exec` runs (default: 30000)                                                |
 | `context_mode.exec_stdout_cap_bytes` | Persisted stdout cap for `gsd_exec` output (default: 1048576)                                      |
 | `context_mode.exec_digest_chars`  | Trailing stdout characters returned to the agent context (default: 300)                              |
+| `context_mode.exec_env_allowlist` | Environment variables forwarded to sandboxed `gsd_exec` runs in addition to `PATH` and `HOME`        |
 | `verification_commands`           | Array of shell commands to run after task execution (e.g., `["npm run lint", "npm run test"]`)        |
 | `verification_auto_fix`           | Auto-retry on verification failures (default: true)                                                   |
 | `verification_max_retries`        | Max retries for verification failures (default: 2)                                                    |

package/dist/resources/.managed-resources-content-hash

@@ -1 +1 @@
-64e3cdf0430b5181
+8e6c04d763f9ba00

package/dist/resources/extensions/gsd/auto-prompts.js

@@ -21,6 +21,7 @@ import { assertGateCoverage, getGatesForTurn, } from "./gate-registry.js";
 import { formatDecisionsCompact, formatRequirementsCompact } from "./structured-data-formatter.js";
 import { readPhaseAnchor, formatAnchorForPrompt } from "./phase-anchor.js";
 import { composeContextModeInstructions, composeInlinedContext } from "./unit-context-composer.js";
+import { readCompactionSnapshot } from "./compaction-snapshot.js";
 import { logWarning } from "./workflow-logger.js";
 import { inlineGraphSubgraph } from "./graph-context.js";
 import { buildExtractionStepsBlock } from "./commands-extract-learnings.js";
@@ -178,8 +179,19 @@ function renderContextModeForPrompt(unitType, base, renderMode = "standalone") {
         renderMode,
     });
 }
-function prependContextModeToBlock(unitType, base, block, renderMode = "standalone") {
+function renderContextModeBlockForPrompt(unitType, base, renderMode = "standalone") {
     const contextMode = renderContextModeForPrompt(unitType, base, renderMode);
+    if (!contextMode)
+        return "";
+    if (renderMode === "nested")
+        return contextMode;
+    const snapshot = readCompactionSnapshot(base);
+    if (!snapshot?.trim())
+        return contextMode;
+    return `${contextMode}\n\n## Context Snapshot\nSource: \`.gsd/last-snapshot.md\`\n\n${snapshot.trimEnd()}`;
+}
+function prependContextModeToBlock(unitType, base, block, renderMode = "standalone") {
+    const contextMode = renderContextModeBlockForPrompt(unitType, base, renderMode);
     if (!contextMode)
         return block;
     if (!block.trim())

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

@@ -112,11 +112,12 @@ const STATE_REBUILD_MIN_INTERVAL_MS = 30_000;
  * the DB is unavailable (e.g. fresh project before init) we skip registration
  * silently rather than blocking session start.
  */
-function registerAutoWorkerForSession(session) {
+function registerAutoWorkerForSession(session, projectRootOverride) {
     if (session.workerId)
         return; // already registered (e.g. resume re-runs)
     try {
-        const projectRootRealpath = normalizeRealPath(session.scope?.workspace.projectRoot
+        const projectRootRealpath = normalizeRealPath(projectRootOverride
+            ?? session.scope?.workspace.projectRoot
             ?? (session.originalBasePath || session.basePath));
         session.workerId = registerAutoWorker({ projectRootRealpath });
     }
@@ -1631,6 +1632,10 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         lockBase,
         buildResolver,
     };
+    // Register the worker before bootstrap enters a milestone worktree.
+    // This ensures enterMilestone can claim a lease and seed dispatch claims
+    // for crash-recovery fidelity (#5405).
+    registerAutoWorkerForSession(s, base);
     const ready = await bootstrapAutoSession(s, ctx, pi, base, verboseMode, requestedStepMode, bootstrapDeps, freshStartAssessment);
     if (!ready)
         return;

package/dist/resources/extensions/gsd/bootstrap/exec-tools.js

@@ -3,21 +3,34 @@
 // Exposes the Context Mode runtime tools in-process. Default-on; opt out with
 // `context_mode.enabled: false` in preferences.
 import { Type } from "@sinclair/typebox";
+async function loadContextModePreferences(baseDir) {
+    const [{ loadEffectiveGSDPreferences }, { logWarning }] = await Promise.all([
+        import("../preferences.js"),
+        import("../workflow-logger.js"),
+    ]);
+    try {
+        return loadEffectiveGSDPreferences(baseDir)?.preferences ?? null;
+    }
+    catch (err) {
+        logWarning("tool", `Context Mode tool could not load preferences: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
 export function registerExecTools(pi) {
     pi.registerTool({
         name: "gsd_exec",
         label: "Exec (Sandboxed)",
-        description: "Run a short script (bash/node/python) in a subprocess. Full stdout/stderr persist to " +
+        description: "Run a short script (bash/node/python) in a subprocess. Capped stdout/stderr and metadata persist to " +
             ".gsd/exec/<id>.{stdout,stderr,meta.json}; only a short digest returns in context. Use " +
             "this instead of reading many files or emitting large tool outputs — e.g. have the script " +
             "count/grep/summarize and log the finding. Enabled by default; opt out via " +
             "preferences.context_mode.enabled=false.",
-        promptSnippet: "Run a bash/node/python script in a sandbox; full output is saved to disk and only a digest returns",
+        promptSnippet: "Run a bash/node/python script in a sandbox; capped output is saved to disk and only a digest returns",
         promptGuidelines: [
             "Prefer gsd_exec for analyses that would otherwise read >3 files or produce large tool output.",
             "Write scripts that log the finding (counts, matches, summaries) rather than raw dumps.",
             "The digest is the last ~300 chars of stdout — size your log output accordingly.",
-            "Need the full output? Read the stdout_path returned in details (file on local disk).",
+            "Need persisted output? Read the stdout_path returned in details (file on local disk).",
         ],
         parameters: Type.Object({
             runtime: Type.Union([Type.Literal("bash"), Type.Literal("node"), Type.Literal("python")], { description: "Interpreter: bash (-c), node (-e), or python3 (-c)." }),
@@ -30,21 +43,11 @@ export function registerExecTools(pi) {
             })),
         }),
         async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-            const [{ executeGsdExec }, { loadEffectiveGSDPreferences }, { logWarning }] = await Promise.all([
-                import("../tools/exec-tool.js"),
-                import("../preferences.js"),
-                import("../workflow-logger.js"),
-            ]);
-            let prefs = null;
-            try {
-                prefs = loadEffectiveGSDPreferences();
-            }
-            catch (err) {
-                logWarning("tool", `gsd_exec could not load preferences: ${err instanceof Error ? err.message : String(err)}`);
-            }
+            const { executeGsdExec } = await import("../tools/exec-tool.js");
+            const baseDir = process.cwd();
             return executeGsdExec(params, {
-                baseDir: process.cwd(),
-                preferences: prefs?.preferences ?? null,
+                baseDir,
+                preferences: await loadContextModePreferences(baseDir),
             });
         },
     });
@@ -56,7 +59,7 @@ export function registerExecTools(pi) {
         promptSnippet: "Search prior gsd_exec runs by substring, runtime, or failing-only filter",
         promptGuidelines: [
             "Use this before re-running an expensive analysis — the prior run's stdout file may still answer.",
-            "The preview shows the trailing ~300 chars of stdout; read stdout_path for the full transcript.",
+            "The preview shows the trailing ~300 chars of stdout; read stdout_path for persisted output.",
         ],
         parameters: Type.Object({
             query: Type.Optional(Type.String({ description: "Substring matched against id and purpose (case-insensitive)." })),
@@ -68,8 +71,10 @@ export function registerExecTools(pi) {
         }),
         async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
             const { executeExecSearch } = await import("../tools/exec-search-tool.js");
+            const baseDir = process.cwd();
             return executeExecSearch(params, {
-                baseDir: process.cwd(),
+                baseDir,
+                preferences: await loadContextModePreferences(baseDir),
             });
         },
     });
@@ -87,8 +92,10 @@ export function registerExecTools(pi) {
         parameters: Type.Object({}),
         async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
             const { executeResume } = await import("../tools/resume-tool.js");
+            const baseDir = process.cwd();
             return executeResume(params, {
-                baseDir: process.cwd(),
+                baseDir,
+                preferences: await loadContextModePreferences(baseDir),
             });
         },
     });

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -52,6 +52,25 @@ async function applyDisabledModelProviderPolicy(ctx) {
         // Non-fatal: keep default provider visibility if preferences cannot be loaded.
     }
 }
+/**
+ * Bridge `context_management.compaction_threshold_percent` from GSD preferences
+ * into the agent's runtime compaction settings (#5475). The preference is
+ * validated to (0.5, 0.95) at load time, but defense-in-depth normalization
+ * here protects against a stale or hand-edited prefs file. Calling with
+ * `undefined` clears any prior override so a removed preference does not leak.
+ */
+async function applyCompactionThresholdOverride(ctx) {
+    try {
+        const { loadEffectiveGSDPreferences } = await import("../preferences.js");
+        const prefs = loadEffectiveGSDPreferences();
+        const raw = prefs?.preferences.context_management?.compaction_threshold_percent;
+        const value = typeof raw === "number" && Number.isFinite(raw) && raw > 0 && raw < 1 ? raw : undefined;
+        ctx.setCompactionThresholdOverride(value);
+    }
+    catch {
+        // Non-fatal: leave any existing override in place.
+    }
+}
 export function resolveNotificationStoreBasePath(cwd = process.cwd()) {
     return resolveWorktreeProjectRoot(cwd);
 }
@@ -101,6 +120,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         await resetAskUserQuestionsTurnCache();
         await syncServiceTierStatus(ctx);
         await applyDisabledModelProviderPolicy(ctx);
+        await applyCompactionThresholdOverride(ctx);
         // Skip MCP auto-prep when running inside an auto-worktree (see session_switch below).
         const { isInAutoWorktree } = await import("../auto-worktree.js");
         if (!isInAutoWorktree(process.cwd())) {
@@ -149,6 +169,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         clearDiscussionFlowState(process.cwd());
         await syncServiceTierStatus(ctx);
         await applyDisabledModelProviderPolicy(ctx);
+        await applyCompactionThresholdOverride(ctx);
         // Skip MCP auto-prep when running inside an auto-worktree. The worktree
         // already has .mcp.json from createAutoWorktree, and re-running the writer
         // post-chdir rewrites the file mid-run (non-idempotent due to cwd-relative

package/dist/resources/extensions/gsd/prompts/parallel-research-slices.md

@@ -16,7 +16,7 @@ Dispatch ALL slices simultaneously using the `subagent` tool in **parallel mode*
 
 1. Call `subagent` with `tasks: [...]` containing one entry per slice below
 2. Wait for ALL subagents to complete
-3. Verify each slice's RESEARCH file was written (check the `.gsd/{{mid}}/` directory)
+3. Verify each slice's RESEARCH file was written (check `.gsd/milestones/{{mid}}/slices/<slice-id>/`)
 4. If a subagent failed to write its RESEARCH file, retry it **once** individually
 5. If it fails a second time, write a partial RESEARCH file for that slice with a `## BLOCKER` section explaining the failure — do NOT retry again
 6. Report which slices completed research and which (if any) needed a blocker note

package/dist/resources/extensions/gsd/prompts/quick-task.md

@@ -17,11 +17,7 @@ You are executing a GSD quick task — a lightweight, focused unit of work outsi
 5. Verify your work:
    - Run tests if applicable.
    - Verify both happy path and failure modes for non-trivial changes.
-6. Commit your changes atomically:
-   - Use conventional commit messages (feat:, fix:, refactor:, etc.)
-   - Stage only relevant files — never commit secrets or runtime files.
-   - Commit logical units separately if the task involves distinct changes.
-   - Quick tasks run outside the auto-mode lifecycle — there is no system auto-commit, so commit directly here.
+6. {{commitInstruction}}
 7. Write a brief summary to `{{summaryPath}}`:
    - Quick tasks operate outside the milestone/slice/task DB structure, so `gsd_summary_save` (which requires a `milestone_id`) cannot be used here. Write the file directly.
 

package/dist/resources/extensions/gsd/prompts/validate-milestone.md

@@ -27,13 +27,13 @@ Roadmap, slice summaries, assessments, requirements, decisions, and project cont
 Call `subagent` with `tasks: [...]` containing ALL THREE reviewers simultaneously:
 
 **Reviewer A - Requirements Coverage**
-Prompt: "Review milestone {{milestoneId}} requirements coverage. Working directory: {{workingDirectory}}. Read `.gsd/{{milestoneId}}/REQUIREMENTS.md` or equivalent. For each requirement, check slice SUMMARY files in `.gsd/{{milestoneId}}/` and mark COVERED, PARTIAL, or MISSING. Output table: Requirement | Status | Evidence. End with one-line verdict: PASS if all covered, NEEDS-ATTENTION if partials exist, FAIL if any missing."
+Prompt: "Review milestone {{milestoneId}} requirements coverage. Working directory: {{workingDirectory}}. Read `.gsd/REQUIREMENTS.md` or use the inlined requirements context. For each requirement, check slice SUMMARY files under `.gsd/milestones/{{milestoneId}}/slices/` and mark COVERED, PARTIAL, or MISSING. Output table: Requirement | Status | Evidence. End with one-line verdict: PASS if all covered, NEEDS-ATTENTION if partials exist, FAIL if any missing."
 
 **Reviewer B - Cross-Slice Integration**
 Prompt: "Review milestone {{milestoneId}} cross-slice integration. Working directory: {{workingDirectory}}. Read `{{roadmapPath}}` and find the boundary map (produces/consumes contracts). For each boundary, confirm producer SUMMARY produced the artifact and consumer SUMMARY consumed it. Output table: Boundary | Producer Summary | Consumer Summary | Status. End with one-line verdict: PASS if all boundaries honored, NEEDS-ATTENTION if any gaps."
 
 **Reviewer C - Assessment & Acceptance Criteria**
-Prompt: "Review milestone {{milestoneId}} assessment evidence and acceptance criteria. Working directory: {{workingDirectory}}. Read `.gsd/{{milestoneId}}/CONTEXT.md` for criteria. Check slice ASSESSMENT files. Verify each criterion maps to a passing assessment or clear SUMMARY evidence. Then review inlined milestone verification classes. For each non-empty planned class, output table: Class | Planned Check | Evidence | Verdict. Use the exact class names `Contract`, `Integration`, `Operational`, and `UAT` whenever those classes are present. If no verification classes were planned, say that explicitly. Output sections `Acceptance Criteria` with checklist `[ ] Criterion | Evidence`, and `Verification Classes` with the table. End with one-line verdict: PASS if all criteria and classes are covered, NEEDS-ATTENTION if gaps exist."
+Prompt: "Review milestone {{milestoneId}} assessment evidence and acceptance criteria. Working directory: {{workingDirectory}}. Read `.gsd/milestones/{{milestoneId}}/{{milestoneId}}-CONTEXT.md` for criteria. Check slice SUMMARY/UAT files under `.gsd/milestones/{{milestoneId}}/slices/`. Verify each criterion maps to passing evidence. Then review inlined milestone verification classes. For each non-empty planned class, output table: Class | Planned Check | Evidence | Verdict. Use the exact class names `Contract`, `Integration`, `Operational`, and `UAT` whenever those classes are present. If no verification classes were planned, say that explicitly. Output sections `Acceptance Criteria` with checklist `[ ] Criterion | Evidence`, and `Verification Classes` with the table. End with one-line verdict: PASS if all criteria and classes are covered, NEEDS-ATTENTION if gaps exist."
 
 ### Step 2 - Synthesize Findings
 

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

@@ -8,8 +8,8 @@
  * Quick tasks live in `.gsd/quick/` and are tracked in STATE.md's
  * "Quick Tasks Completed" table.
  */
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
 import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
 import { GitServiceImpl, runGit } from "./git-service.js";
@@ -64,6 +64,37 @@ function ensureQuickDir(basePath, taskNum, slug) {
     mkdirSync(taskDir, { recursive: true });
     return taskDir;
 }
+function isPathInside(parent, child) {
+    const rel = relative(parent, child);
+    return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
+}
+function isExternalGsdRoot(basePath, root) {
+    try {
+        return !isPathInside(realpathSync(basePath), realpathSync(root));
+    }
+    catch {
+        return !isPathInside(basePath, root);
+    }
+}
+export function buildQuickCommitInstruction(basePath, root) {
+    const externalState = isExternalGsdRoot(basePath, root);
+    if (externalState) {
+        return [
+            "Commit repo changes atomically, but do not stage or commit `.gsd/quick/...`:",
+            "   - `.gsd/` resolves outside this git repository, so Git cannot stage quick-task summary files from the project repo.",
+            "   - Write the quick summary file directly at the requested path; that file is persisted by GSD external state.",
+            "   - Stage and commit only implementation/test/docs files that live inside the repository.",
+            "   - If the task only writes quick-task research/summary files and no repository files changed, do not run `git commit`; report that there was nothing in the project repo to commit.",
+        ].join("\n");
+    }
+    return [
+        "Commit your changes atomically:",
+        "   - Use conventional commit messages (feat:, fix:, refactor:, etc.)",
+        "   - Stage only relevant files — never commit secrets or runtime files.",
+        "   - Commit logical units separately if the task involves distinct changes.",
+        "   - Quick tasks run outside the auto-mode lifecycle — there is no system auto-commit, so commit directly here.",
+    ].join("\n");
+}
 function quickReturnStatePath(basePath) {
     return join(gsdRoot(basePath), "runtime", "quick-return.json");
 }
@@ -198,6 +229,7 @@ export async function handleQuick(args, ctx, pi) {
         taskDir: taskDirRel,
         branch: actualBranch,
         summaryPath,
+        commitInstruction: buildQuickCommitInstruction(basePath, root),
         date,
         taskNum: String(taskNum),
         slug,

package/dist/resources/extensions/gsd/tools/context-mode-tool-result.js

@@ -0,0 +1,15 @@
+// Project/App: GSD-2
+// File Purpose: Shared Context Mode tool result helpers.
+export function contextModeDisabledResult(operation) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: `${operation} is disabled by \`context_mode.enabled: false\` in preferences. ` +
+                    "Remove that override or set it to true to re-enable Context Mode tools.",
+            },
+        ],
+        details: { operation, error: "context_mode_disabled" },
+        isError: true,
+    };
+}

package/dist/resources/extensions/gsd/tools/exec-search-tool.js

@@ -3,7 +3,12 @@
 // Scans .gsd/exec/*.meta.json and returns a ranked summary so agents can
 // re-discover past runs without re-executing. Read-only; no DB writes.
 import { searchExecHistory } from "../exec-history.js";
+import { isContextModeEnabled } from "../preferences-types.js";
+import { contextModeDisabledResult } from "./context-mode-tool-result.js";
 export function executeExecSearch(params, opts) {
+    if (!isContextModeEnabled(opts.preferences)) {
+        return contextModeDisabledResult("gsd_exec_search");
+    }
     const searchOpts = {
         query: typeof params.query === "string" ? params.query : undefined,
         runtime: params.runtime,

package/dist/resources/extensions/gsd/tools/exec-tool.js

@@ -5,6 +5,7 @@
 // for MCP return.
 import { EXEC_DEFAULTS, runExecSandbox, } from "../exec-sandbox.js";
 import { isContextModeEnabled } from "../preferences-types.js";
+import { contextModeDisabledResult } from "./context-mode-tool-result.js";
 export function buildExecOptions(baseDir, cfg, extras) {
     const allowlist = Array.isArray(cfg?.exec_env_allowlist) ? cfg.exec_env_allowlist : EXEC_DEFAULTS.envAllowlist;
     const stdoutCap = clampNumber(cfg?.exec_stdout_cap_bytes, EXEC_DEFAULTS.stdoutCapBytes, 4_096, 16_777_216);
@@ -33,19 +34,6 @@ function clampNumber(value, fallback, min, max) {
 function isEnabled(prefs) {
     return isContextModeEnabled(prefs);
 }
-function disabledResult() {
-    return {
-        content: [
-            {
-                type: "text",
-                text: "gsd_exec is disabled by `context_mode.enabled: false` in preferences. Remove that " +
-                    "override (or set it to true) to re-enable sandboxed tool-output execution.",
-            },
-        ],
-        details: { operation: "gsd_exec", error: "context_mode_disabled" },
-        isError: true,
-    };
-}
 function paramError(message) {
     return {
         content: [{ type: "text", text: `Error: ${message}` }],
@@ -55,7 +43,7 @@ function paramError(message) {
 }
 export async function executeGsdExec(params, deps) {
     if (!isEnabled(deps.preferences))
-        return disabledResult();
+        return contextModeDisabledResult("gsd_exec");
     const runtime = params.runtime;
     if (runtime !== "bash" && runtime !== "node" && runtime !== "python") {
         return paramError(`invalid runtime "${String(runtime)}" — must be bash | node | python`);
@@ -67,7 +55,7 @@ export async function executeGsdExec(params, deps) {
     if (Buffer.byteLength(script, "utf8") > 200_000) {
         return paramError("script exceeds the 200 KB length limit");
     }
-    const opts = buildExecOptions(deps.baseDir, deps.preferences?.context_mode, { now: deps.now, generateId: deps.generateId });
+    const opts = buildExecOptions(deps.baseDir, deps.preferences?.context_mode, { env: deps.env, now: deps.now, generateId: deps.generateId });
     const run = deps.run ?? runExecSandbox;
     try {
         const result = await run({

package/dist/resources/extensions/gsd/tools/resume-tool.js

@@ -2,7 +2,12 @@
 // agents can re-orient after compaction or session resume without
 // re-deriving project memory state.
 import { readCompactionSnapshot } from "../compaction-snapshot.js";
+import { isContextModeEnabled } from "../preferences-types.js";
+import { contextModeDisabledResult } from "./context-mode-tool-result.js";
 export function executeResume(_params, opts) {
+    if (!isContextModeEnabled(opts.preferences)) {
+        return contextModeDisabledResult("gsd_resume");
+    }
     const snapshot = readCompactionSnapshot(opts.baseDir);
     if (snapshot == null) {
         return {

package/dist/resources/extensions/gsd/unit-context-composer.js

@@ -80,7 +80,15 @@ const CONTEXT_MODE_LANE_LABELS = {
     orchestration: "orchestration",
     docs: "documentation",
 };
-const CONTEXT_MODE_GUIDANCE = "Use `gsd_exec` for noisy commands, `gsd_exec_search` before reruns, and `gsd_resume` after compaction or resume.";
+const CONTEXT_MODE_GUIDANCE_BY_LANE = {
+    interview: "Use `gsd_resume` to restore prior discussion, `gsd_exec` for noisy discovery, and `gsd_exec_search` before repeating scans.",
+    research: "Use `gsd_exec` for noisy research scans, `gsd_exec_search` before reruns, and `gsd_resume` to restore prior findings.",
+    planning: "Use `gsd_resume` for planning continuity, `gsd_exec` for noisy checks, and `gsd_exec_search` before rerunning diagnostics.",
+    execution: "Use `gsd_exec` for builds, tests, and diagnostics, `gsd_exec_search` before reruns, and `gsd_resume` after compaction or resume.",
+    verification: "Use `gsd_exec` for verification commands, `gsd_exec_search` to reuse prior evidence, and `gsd_resume` after compaction or resume.",
+    orchestration: "Use `gsd_resume` before resuming orchestration, `gsd_exec_search` to reuse prior runs, and `gsd_exec` for noisy coordination checks.",
+    docs: "Use `gsd_resume` for prior context, `gsd_exec_search` for saved evidence, and `gsd_exec` for noisy doc validation commands.",
+};
 /**
  * Render the Context Mode instruction lane for a unit type. Unknown unit
  * types, disabled config, and explicit `contextMode: "none"` all omit the
@@ -93,14 +101,15 @@ export function composeContextModeInstructions(unitType, opts) {
     if (!manifest || manifest.contextMode === "none")
         return "";
     const lane = CONTEXT_MODE_LANE_LABELS[manifest.contextMode];
+    const guidance = CONTEXT_MODE_GUIDANCE_BY_LANE[manifest.contextMode];
     if (opts.renderMode === "nested") {
-        return `Context Mode (${lane} lane): ${CONTEXT_MODE_GUIDANCE}`;
+        return `Context Mode (${lane} lane): ${guidance}`;
     }
     return [
         "## Context Mode",
         "",
         `Lane: **${lane} lane**.`,
-        CONTEXT_MODE_GUIDANCE,
+        guidance,
     ].join("\n");
 }
 const SECTION_SEPARATOR = "\n\n---\n\n";