gsd-pi 2.76.0-dev.82e249f7b → 2.76.0-dev.97807402

package/src/resources/extensions/gsd/auto-worktree.ts

@@ -238,14 +238,6 @@ function clearProjectRootStateFiles(basePath: string, milestoneId: string): void
   }
 }
 
-function isProjectGsdSymlink(basePath: string): boolean {
-  try {
-    return lstatSyncFn(join(basePath, ".gsd")).isSymbolicLink();
-  } catch {
-    return false;
-  }
-}
-
 // ─── Build Artifact Auto-Resolve ─────────────────────────────────────────────
 
 /** Patterns for machine-generated build artifacts that can be safely
@@ -1664,54 +1656,15 @@ export function mergeMilestoneToMain(
     }
   }
 
-  // 7. Stash any pre-existing dirty files so the squash merge is not
-  //    blocked by unrelated local changes (#2151).  clearProjectRootStateFiles
-  //    only removes untracked .gsd/ files; tracked dirty files elsewhere (e.g.
-  //    .planning/work-state.json with stash conflict markers) are invisible to
-  //    that cleanup but will cause `git merge --squash` to reject.
-  let stashed = false;
-  try {
-    const status = execFileSync("git", ["status", "--porcelain"], {
-      cwd: originalBasePath_,
-      stdio: ["ignore", "pipe", "pipe"],
-      encoding: "utf-8",
-    }).trim();
-    if (status) {
-      // Use --include-untracked to stash untracked files that would block
-      // the squash merge, but EXCLUDE .gsd/milestones/ (#2505).
-      // --include-untracked without exclusion sweeps queued milestone
-      // CONTEXT files into the stash. If stash pop later fails, those files
-      // are permanently trapped in the stash entry and lost on the next
-      // stash push or drop.
-      //
-      // When `.gsd` itself is a symlink, Git rejects pathspecs below it
-      // ("beyond a symbolic link"). In that layout, exclude the whole symlink
-      // and keep stashing real project files that could block the merge.
-      const stashPathspecs = isProjectGsdSymlink(originalBasePath_)
-        ? [".", ":(exclude).gsd"]
-        : [":(exclude).gsd/milestones"];
-      execFileSync(
-        "git",
-        [
-          "stash", "push", "--include-untracked",
-          "-m", `gsd: pre-merge stash for ${milestoneId}`,
-          "--", ...stashPathspecs,
-        ],
-        { cwd: originalBasePath_, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
-      );
-      stashed = true;
-    }
-  } catch (err) {
-    // Stash failure is non-fatal — proceed without stash and let the merge
-    // report the dirty tree if it fails.
-    logWarning("worktree", `git stash failed: ${err instanceof Error ? err.message : String(err)}`);
-  }
-
-  // 7a. Shelter queued milestone directories before the squash merge (#2505).
+  // 7. Shelter queued milestone directories before the squash merge (#2505).
   // The milestone branch may contain copies of queued milestone dirs (via
   // copyPlanningArtifacts), so `git merge --squash` rejects when those same
   // files exist as untracked in the working tree. Temporarily move them to
   // a backup location, then restore after the merge+commit.
+  //
+  // MUST run BEFORE the pre-merge stash (step 7a) so `--include-untracked`
+  // does not sweep queued CONTEXT files into the stash. If stash pop later
+  // fails, files trapped inside the stash are permanently lost (#2505).
   const milestonesDir = join(gsdRoot(originalBasePath_), "milestones");
   const shelterDir = join(gsdRoot(originalBasePath_), ".milestone-shelter");
   const shelteredDirs: string[] = [];
@@ -1759,6 +1712,35 @@ export function mergeMilestoneToMain(
     logWarning("worktree", `milestone shelter operation failed: ${err instanceof Error ? err.message : String(err)}`);
   }
 
+  // 7a. Stash pre-existing dirty files so the squash merge is not blocked by
+  //     unrelated local changes (#2151). Includes untracked files to handle
+  //     locally-added files that conflict with tracked files on the milestone
+  //     branch. Passing NO pathspec lets git skip gitignored paths silently;
+  //     adding an explicit pathspec trips a `git add`-style fatal on ignored
+  //     entries (e.g. a gitignored `.gsd` symlink under ADR-002) (#4573).
+  //     Queued CONTEXT files under `.gsd/milestones/*` are already sheltered
+  //     in step 7 above, so they won't be swept into the stash.
+  let stashed = false;
+  try {
+    const status = execFileSync("git", ["status", "--porcelain"], {
+      cwd: originalBasePath_,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    }).trim();
+    if (status) {
+      execFileSync(
+        "git",
+        ["stash", "push", "--include-untracked", "-m", `gsd: pre-merge stash for ${milestoneId}`],
+        { cwd: originalBasePath_, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
+      );
+      stashed = true;
+    }
+  } catch (err) {
+    // Stash failure is non-fatal — proceed without stash and let the merge
+    // report the dirty tree if it fails.
+    logWarning("worktree", `git stash failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
   // 7b. Clean up stale merge state before attempting squash merge (#2912).
   // A leftover MERGE_HEAD (from a previous failed merge, libgit2 native path,
   // or interrupted operation) causes `git merge --squash` to refuse with

package/src/resources/extensions/gsd/auto.ts

@@ -182,7 +182,6 @@ import {
   unitVerb,
   formatAutoElapsed as _formatAutoElapsed,
   formatWidgetTokens,
-  hideFooter,
   type WidgetStateAccessors,
 } from "./auto-dashboard.js";
 import {
@@ -330,8 +329,8 @@ export function startAutoDetached(
 }
 
 /** Returns true if the project is configured for `isolation:worktree` mode. */
-export function shouldUseWorktreeIsolation(): boolean {
-  const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
+export function shouldUseWorktreeIsolation(basePath?: string): boolean {
+  const prefs = loadEffectiveGSDPreferences(basePath)?.preferences?.git;
   if (prefs?.isolation === "worktree") return true;
   // Default is false — worktree isolation requires explicit opt-in
   return false;
@@ -424,7 +423,7 @@ export function getAutoDashboardData(): AutoDashboardData {
   const rtkSavings = sessionId && s.basePath
     ? getRtkSessionSavings(s.basePath, sessionId)
     : null;
-  const rtkEnabled = loadEffectiveGSDPreferences()?.preferences.experimental?.rtk === true;
+  const rtkEnabled = loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences.experimental?.rtk === true;
   // Pending capture count — lazy check, non-fatal
   let pendingCaptureCount = 0;
   try {
@@ -648,7 +647,7 @@ function buildSnapshotOpts(
   gitStatus?: "ok" | "failed";
   gitError?: string;
 } & Record<string, unknown> {
-  const prefs = loadEffectiveGSDPreferences()?.preferences;
+  const prefs = loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences;
   const uokFlags = resolveUokFlags(prefs);
   return {
     ...(s.autoStartTime > 0 ? { autoSessionKey: String(s.autoStartTime) } : {}),
@@ -686,7 +685,7 @@ function handleLostSessionLock(
   restoreProjectRootEnv();
   restoreMilestoneLockEnv();
   deregisterSigtermHandler();
-  clearCmuxSidebar(loadEffectiveGSDPreferences()?.preferences);
+  clearCmuxSidebar(loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences);
   const base = lockBase();
   const lockFilePath = base ? join(gsdRoot(base), "auto.lock") : "unknown";
   const recoverySuggestion = "\nTo recover, run: gsd doctor --fix";
@@ -706,7 +705,6 @@ function handleLostSessionLock(
   );
   ctx?.ui.setStatus("gsd-auto", undefined);
   ctx?.ui.setWidget("gsd-progress", undefined);
-  ctx?.ui.setFooter(undefined);
   if (ctx) initHealthWidget(ctx);
 }
 
@@ -742,7 +740,6 @@ function cleanupAfterLoopExit(ctx: ExtensionContext): void {
   if (!s.paused) {
     ctx.ui.setStatus("gsd-auto", undefined);
     ctx.ui.setWidget("gsd-progress", undefined);
-    ctx.ui.setFooter(undefined);
     initHealthWidget(ctx);
   }
 
@@ -764,7 +761,7 @@ export async function stopAuto(
   reason?: string,
 ): Promise<void> {
   if (!s.active && !s.paused) return;
-  const loadedPreferences = loadEffectiveGSDPreferences()?.preferences;
+  const loadedPreferences = loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences;
   const reasonSuffix = reason ? ` — ${reason}` : "";
 
   try {
@@ -1018,7 +1015,6 @@ export async function stopAuto(
     // UI cleanup
     ctx?.ui.setStatus("gsd-auto", undefined);
     ctx?.ui.setWidget("gsd-progress", undefined);
-    ctx?.ui.setFooter(undefined);
     if (ctx) initHealthWidget(ctx);
     restoreProjectRootEnv();
     restoreMilestoneLockEnv();
@@ -1121,7 +1117,6 @@ export async function pauseAuto(
   s.verificationRetryCount.clear();
   ctx?.ui.setStatus("gsd-auto", "paused");
   ctx?.ui.setWidget("gsd-progress", undefined);
-  ctx?.ui.setFooter(undefined);
   if (ctx) initHealthWidget(ctx);
   const resumeCmd = s.stepMode ? "/gsd next" : "/gsd auto";
   ctx?.ui.notify(
@@ -1495,7 +1490,7 @@ export async function startAuto(
     // ── Auto-worktree / branch-mode: re-enter on resume ──
     if (
       s.currentMilestoneId &&
-      getIsolationMode() !== "none" &&
+      getIsolationMode(s.originalBasePath || s.basePath) !== "none" &&
       s.originalBasePath &&
       !isInAutoWorktree(s.basePath) &&
       !detectWorktreeName(s.basePath) &&
@@ -1509,7 +1504,7 @@ export async function startAuto(
     registerSigtermHandler(lockBase());
 
     ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
-    ctx.ui.setFooter(hideFooter);
+    ctx.ui.setWidget("gsd-health", undefined);
     ctx.ui.notify(
       s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.",
       "info",
@@ -1534,7 +1529,7 @@ export async function startAuto(
     await openProjectDbIfPresent(s.basePath);
     try {
       await rebuildState(s.basePath);
-      syncCmuxSidebar(loadEffectiveGSDPreferences()?.preferences, await deriveState(s.basePath));
+      syncCmuxSidebar(loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, await deriveState(s.basePath));
     } catch (e) {
       debugLog("resume-rebuild-state-failed", {
         error: e instanceof Error ? e.message : String(e),
@@ -1584,7 +1579,7 @@ export async function startAuto(
       "resuming",
       s.currentMilestoneId ?? "unknown",
     );
-    logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "progress");
+    logCmuxEvent(loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "progress");
 
     captureProjectRootEnv(s.originalBasePath || s.basePath);
     startAutoCommandPolling(s.basePath);
@@ -1622,12 +1617,12 @@ export async function startAuto(
 
   captureProjectRootEnv(s.originalBasePath || s.basePath);
   try {
-    syncCmuxSidebar(loadEffectiveGSDPreferences()?.preferences, await deriveState(s.basePath));
+    syncCmuxSidebar(loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, await deriveState(s.basePath));
   } catch (err) {
     // Best-effort only — sidebar sync must never block auto-mode startup
     logWarning("engine", `cmux sync failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
   }
-  logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, requestedStepMode ? "Step-mode started." : "Auto-mode started.", "progress");
+  logCmuxEvent(loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, requestedStepMode ? "Step-mode started." : "Auto-mode started.", "progress");
 
   startAutoCommandPolling(s.basePath);
 

package/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts

@@ -1,7 +1,12 @@
 import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 
 import { logWarning } from "../workflow-logger.js";
-import { checkAutoStartAfterDiscuss } from "../guided-flow.js";
+import {
+  checkAutoStartAfterDiscuss,
+  maybeHandleReadyPhraseWithoutFiles,
+  maybeHandleEmptyIntentTurn,
+  resetEmptyTurnCounter,
+} from "../guided-flow.js";
 import { getAutoDashboardData, getAutoModeStartModel, isAutoActive, pauseAuto, setCurrentDispatchedModelId } from "../auto.js";
 import { getNextFallbackModel, resolveModelWithFallbacksForUnit } from "../preferences.js";
 import { pauseAutoForProviderError } from "../provider-error-pause.js";
@@ -75,6 +80,20 @@ export async function handleAgentEnd(
     clearDiscussionFlowState();
     return;
   }
+
+  // #4573 — When the LLM emits "Milestone X ready." but the required files
+  // are missing, `checkAutoStartAfterDiscuss` returns false silently. Surface
+  // that and nudge the LLM to complete the writes before the user hits the
+  // downstream "All milestones complete" warning loop.
+  if (maybeHandleReadyPhraseWithoutFiles(event)) return;
+
+  // #4573 — Empty-turn recovery: if the LLM announced intent in prose but
+  // emitted no tool calls, nudge it to execute. Fires only when auto-mode is
+  // active or a discussion autostart is pending (non-auto interactive discuss
+  // is user-driven). Runs before `isAutoActive` early return so pending
+  // discussions (where isAutoActive may be false) still get recovered.
+  if (maybeHandleEmptyIntentTurn(event, isAutoActive())) return;
+
   if (!isAutoActive()) return;
   if (isSessionSwitchInFlight()) return;
 
@@ -336,6 +355,9 @@ export async function handleAgentEnd(
   // ── Success path ─────────────────────────────────────────────────────────
   try {
     resetRetryState(retryState);
+    // #4573 — Reset the empty-turn counter on any successful agent turn so
+    // transient stalls don't accumulate across independent units.
+    resetEmptyTurnCounter();
     resolveAgentEnd(event);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);

package/src/resources/extensions/gsd/bootstrap/db-tools.ts

@@ -35,6 +35,19 @@ function registerAlias(pi: ExtensionAPI, toolDef: any, aliasName: string, canoni
   });
 }
 
+/**
+ * Read a tool result's structured payload, accommodating MCP's `details` →
+ * `structuredContent` rename (#4472, #4477). In-process executions still
+ * deliver the payload on `result.details`; MCP-routed executions deliver it
+ * on `result.structuredContent` (post `adaptExecutorResult` transform). All
+ * `renderResult` callbacks in this file route through this helper so a future
+ * field rename only needs to be applied in one place.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- result shape varies by tool
+function readDetails(result: any): any {
+  return result?.details ?? result?.structuredContent;
+}
+
 export function registerDbTools(pi: ExtensionAPI): void {
   // ─── gsd_decision_save (formerly gsd_save_decision) ─────────────────────
 
@@ -110,7 +123,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       return new Text(text, 0, 0);
     },
     renderResult(result: any, _options: any, theme: any) {
-      const d = result.details;
+      const d = readDetails(result);
       if (result.isError || d?.error) {
         return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
       }
@@ -188,7 +201,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       return new Text(text, 0, 0);
     },
     renderResult(result: any, _options: any, theme: any) {
-      const d = result.details;
+      const d = readDetails(result);
       if (result.isError || d?.error) {
         return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
       }
@@ -273,7 +286,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       return new Text(text, 0, 0);
     },
     renderResult(result: any, _options: any, theme: any) {
-      const d = result.details;
+      const d = readDetails(result);
       if (result.isError || d?.error) {
         return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
       }
@@ -322,7 +335,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       return new Text(text, 0, 0);
     },
     renderResult(result: any, _options: any, theme: any) {
-      const d = result.details;
+      const d = readDetails(result);
       if (result.isError || d?.error) {
         return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
       }
@@ -406,7 +419,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       return new Text(theme.fg("toolTitle", theme.bold("milestone_generate_id")), 0, 0);
     },
     renderResult(result: any, _options: any, theme: any) {
-      const d = result.details;
+      const d = readDetails(result);
       if (result.isError || d?.error) {
         return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
       }
@@ -1074,13 +1087,31 @@ export function registerDbTools(pi: ExtensionAPI): void {
       text += theme.fg("dim", ` → ${args.verdict ?? ""}`);
       return new Text(text, 0, 0);
     },
+    /**
+     * Render the save_gate_result tool output for the TUI.
+     *
+     * Prefers structured fields, but falls back to `content[0].text` when the
+     * structured payload is empty. Defensive: the structural fix on this
+     * branch plumbs `details` through MCP via `structuredContent`, but older
+     * hosts, a future handler that forgets `structuredContent`, or any drop
+     * of non-standard return fields would otherwise render as
+     * "undefined: undefined". Same fallback applies to error rendering, and
+     * we strip a leading `Error:` from the fallback text to avoid producing
+     * `Error: Error: ...`.
+     */
     renderResult(result: any, _options: any, theme: any) {
-      const d = result.details;
+      const d = readDetails(result);
       if (result.isError || d?.error) {
-        return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
+        const rawMsg = d?.error ?? result.content?.[0]?.text ?? "unknown";
+        const msg = rawMsg.replace(/^\s*Error:\s*/i, "");
+        return new Text(theme.fg("error", `Error: ${msg}`), 0, 0);
+      }
+      if (!d?.gateId || !d?.verdict) {
+        const text = result.content?.[0]?.text ?? "Gate result saved";
+        return new Text(theme.fg("success", text), 0, 0);
       }
-      const color = d?.verdict === "flag" ? "warning" : "success";
-      return new Text(theme.fg(color, `${d?.gateId}: ${d?.verdict}`), 0, 0);
+      const color = d.verdict === "flag" ? "warning" : "success";
+      return new Text(theme.fg(color, `${d.gateId}: ${d.verdict}`), 0, 0);
     },
   };
 

package/src/resources/extensions/gsd/bootstrap/exec-tools.ts

@@ -0,0 +1,109 @@
+// GSD2 — Exec (context-mode) tool registration.
+//
+// Exposes the `gsd_exec` tool over MCP. Opt-in: disabled unless
+// `context_mode.enabled: true` is set in preferences.
+
+import { Type } from "@sinclair/typebox";
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+
+import { executeGsdExec } from "../tools/exec-tool.js";
+import { executeExecSearch } from "../tools/exec-search-tool.js";
+import { executeResume } from "../tools/resume-tool.js";
+import { loadEffectiveGSDPreferences } from "../preferences.js";
+import { logWarning } from "../workflow-logger.js";
+
+export function registerExecTools(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "gsd_exec",
+    label: "Exec (Sandboxed)",
+    description:
+      "Run a short script (bash/node/python) in a subprocess. Full stdout/stderr 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",
+    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).",
+    ],
+    parameters: Type.Object({
+      runtime: Type.Union(
+        [Type.Literal("bash"), Type.Literal("node"), Type.Literal("python")],
+        { description: "Interpreter: bash (-c), node (-e), or python3 (-c)." },
+      ),
+      script: Type.String({ description: "Script body. Keep output small (log the finding, not the data)." }),
+      purpose: Type.Optional(Type.String({ description: "Short label recorded in meta.json for later review." })),
+      timeout_ms: Type.Optional(
+        Type.Number({
+          description: "Per-invocation timeout (ms). Capped at 600000. Default from preferences.",
+          minimum: 1_000,
+          maximum: 600_000,
+        }),
+      ),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      let prefs: Awaited<ReturnType<typeof loadEffectiveGSDPreferences>> | null = null;
+      try {
+        prefs = loadEffectiveGSDPreferences();
+      } catch (err) {
+        logWarning("tool", `gsd_exec could not load preferences: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      return executeGsdExec(params as Parameters<typeof executeGsdExec>[0], {
+        baseDir: process.cwd(),
+        preferences: prefs?.preferences ?? null,
+      });
+    },
+  });
+
+  pi.registerTool({
+    name: "gsd_exec_search",
+    label: "Search gsd_exec History",
+    description:
+      "List prior gsd_exec runs (most recent first) from .gsd/exec/*.meta.json. Useful for " +
+      "rediscovering the stdout_path of an earlier run without re-executing it. Read-only.",
+    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.",
+    ],
+    parameters: Type.Object({
+      query: Type.Optional(Type.String({ description: "Substring matched against id and purpose (case-insensitive)." })),
+      runtime: Type.Optional(
+        Type.Union([Type.Literal("bash"), Type.Literal("node"), Type.Literal("python")], {
+          description: "Restrict to one runtime.",
+        }),
+      ),
+      failing_only: Type.Optional(Type.Boolean({ description: "Only non-zero exit codes and timeouts." })),
+      limit: Type.Optional(Type.Number({ description: "Max results (default 20, cap 200)", minimum: 1, maximum: 200 })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      return executeExecSearch(params as Parameters<typeof executeExecSearch>[0], {
+        baseDir: process.cwd(),
+      });
+    },
+  });
+
+  pi.registerTool({
+    name: "gsd_resume",
+    label: "Resume (Read Snapshot)",
+    description:
+      "Return the contents of .gsd/last-snapshot.md — a ≤2 KB digest of top memories, recent " +
+      "gsd_exec runs, and active context, written automatically on session_before_compact. Use " +
+      "this after compaction or session resume to re-orient quickly.",
+    promptSnippet: "Read the pre-compaction snapshot to re-orient after context loss",
+    promptGuidelines: [
+      "Call this right after a session resumes if you feel you've lost durable context.",
+      "The snapshot is a summary — use memory_query or gsd_exec_search for detail.",
+    ],
+    parameters: Type.Object({}),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      return executeResume(params as Parameters<typeof executeResume>[0], {
+        baseDir: process.cwd(),
+      });
+    },
+  });
+}

package/src/resources/extensions/gsd/bootstrap/register-extension.ts

@@ -8,6 +8,7 @@ import type { GSDEcosystemBeforeAgentStartHandler } from "../ecosystem/gsd-exten
 import { loadEcosystemExtensions } from "../ecosystem/loader.js";
 import { registerDbTools } from "./db-tools.js";
 import { registerDynamicTools } from "./dynamic-tools.js";
+import { registerExecTools } from "./exec-tools.js";
 import { registerJournalTools } from "./journal-tools.js";
 import { registerMemoryTools } from "./memory-tools.js";
 import { registerQueryTools } from "./query-tools.js";
@@ -100,6 +101,7 @@ export function registerGsdExtension(pi: ExtensionAPI): void {
     ["journal-tools", () => registerJournalTools(pi)],
     ["query-tools", () => registerQueryTools(pi)],
     ["memory-tools", () => registerMemoryTools(pi)],
+    ["exec-tools", () => registerExecTools(pi)],
     ["shortcuts", () => registerShortcuts(pi)],
     ["hooks", () => registerHooks(pi, ecosystemHandlers)],
     ["ecosystem", () => {

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -18,7 +18,7 @@ import { loadToolApiKeys } from "../commands-config.js";
 import { loadFile, saveFile, formatContinue } from "../files.js";
 import { deriveState } from "../state.js";
 import { getAutoDashboardData, isAutoActive, isAutoPaused, markToolEnd, markToolStart, recordToolInvocationError } from "../auto.js";
-import { hideFooter } from "../auto-dashboard.js";
+
 import { isParallelActive, shutdownParallel } from "../parallel-orchestrator.js";
 import { checkToolCallLoop, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
 import { saveActivityLog } from "../activity-log.js";
@@ -48,7 +48,9 @@ export function registerHooks(
     initNotificationStore(process.cwd());
     installNotifyInterceptor(ctx);
     initNotificationWidget(ctx);
-    initHealthWidget(ctx);
+    if (!isAutoActive()) {
+      initHealthWidget(ctx);
+    }
     resetWriteGateState();
     resetToolCallLoopGuard();
     resetAskUserQuestionsCache();
@@ -90,7 +92,7 @@ export function registerHooks(
     }
     loadToolApiKeys();
     if (isAutoActive()) {
-      ctx.ui.setFooter(hideFooter);
+      ctx.ui.setWidget("gsd-health", undefined);
     }
   });
 
@@ -113,7 +115,7 @@ export function registerHooks(
     }
     loadToolApiKeys();
     if (isAutoActive()) {
-      ctx.ui.setFooter(hideFooter);
+      ctx.ui.setWidget("gsd-health", undefined);
     }
   });
 
@@ -225,6 +227,42 @@ export function registerHooks(
     }));
   });
 
+  // Context-mode snapshot: write .gsd/last-snapshot.md before compaction so
+  // agents can call gsd_resume (or Read the file) to re-orient. Opt-in via
+  // preferences.context_mode.enabled. Runs after the auto-cancel handler
+  // above — if that one returned cancel:true, pi still fires us but the
+  // compaction won't actually happen; the snapshot is still useful then,
+  // since auto may pause and resume later.
+  pi.on("session_before_compact", async () => {
+    try {
+      const { loadEffectiveGSDPreferences } = await import("../preferences.js");
+      const { isContextModeEnabled } = await import("../preferences-types.js");
+      const prefs = loadEffectiveGSDPreferences();
+      if (!isContextModeEnabled(prefs?.preferences)) return;
+      const { writeCompactionSnapshot } = await import("../compaction-snapshot.js");
+      const { ensureDbOpen } = await import("./dynamic-tools.js");
+      await ensureDbOpen();
+      const basePath = process.cwd();
+      let activeContext: string | null = null;
+      try {
+        const state = await deriveState(basePath);
+        if (state.activeMilestone && state.activeSlice && state.activeTask) {
+          activeContext =
+            `Active: ${state.activeMilestone.id} / ${state.activeSlice.id} / ${state.activeTask.id}` +
+            (state.activeTask.title ? ` — ${state.activeTask.title}` : "");
+        }
+      } catch {
+        /* non-fatal */
+      }
+      writeCompactionSnapshot(basePath, { activeContext });
+    } catch (err) {
+      safetyLogWarning(
+        "context-mode",
+        `failed to write compaction snapshot: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  });
+
   pi.on("session_shutdown", async (_event, ctx: ExtensionContext) => {
     if (isParallelActive()) {
       try {

package/src/resources/extensions/gsd/bootstrap/write-gate.ts

@@ -117,9 +117,21 @@ function normalizeWriteGateSnapshot(value: unknown): WriteGateSnapshot {
   };
 }
 
+const EMPTY_SNAPSHOT: WriteGateSnapshot = {
+  verifiedDepthMilestones: [],
+  activeQueuePhase: false,
+  pendingGateId: null,
+};
+
 export function loadWriteGateSnapshot(basePath: string = process.cwd()): WriteGateSnapshot {
   const path = writeGateSnapshotPath(basePath);
-  if (!existsSync(path)) return currentWriteGateSnapshot();
+  if (!existsSync(path)) {
+    // When persist mode is active and the file has been deleted, treat it as a
+    // full state reset so deleting the file clears the HARD BLOCK gate.
+    // In non-persist mode the file is never written, so fall back to in-memory.
+    if (shouldPersistWriteGateSnapshot()) return EMPTY_SNAPSHOT;
+    return currentWriteGateSnapshot();
+  }
   try {
     return normalizeWriteGateSnapshot(JSON.parse(readFileSync(path, "utf-8")));
   } catch {