gsd-pi 2.80.0-dev.0aaa4fc17 → 2.80.0-dev.1486c1899

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

@@ -59,6 +59,7 @@ import {
   isLockProcessAlive,
   formatCrashInfo,
   emitCrashRecoveredUnitEnd,
+  emitOpenUnitEndForUnit,
 } from "./crash-recovery.js";
 import {
   acquireSessionLock,
@@ -200,6 +201,8 @@ import {
   detectWorkingTreeActivity,
 } from "./auto-supervisor.js";
 import { isDbAvailable, getMilestone } from "./gsd-db.js";
+import { markLatestActiveForWorkerCanceled } from "./db/unit-dispatches.js";
+import { writeUnitRuntimeRecord } from "./unit-runtime.js";
 import { countPendingCaptures } from "./captures.js";
 import { CMUX_CHANNELS, type CmuxLogLevel } from "../shared/cmux-events.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
@@ -293,11 +296,15 @@ 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: AutoSession): void {
+function registerAutoWorkerForSession(
+  session: AutoSession,
+  projectRootOverride?: string,
+): void {
   if (session.workerId) return; // already registered (e.g. resume re-runs)
   try {
     const projectRootRealpath = normalizeRealPath(
-      session.scope?.workspace.projectRoot
+      projectRootOverride
+        ?? session.scope?.workspace.projectRoot
         ?? (session.originalBasePath || session.basePath),
     );
     session.workerId = registerAutoWorker({ projectRootRealpath });
@@ -501,9 +508,54 @@ export {
   getBudgetEnforcementAction,
 } from "./auto-budget.js";
 
+function closeOutSignalInterruptedUnit(currentBasePath: string): void {
+  const currentUnit = s.currentUnit;
+  if (!currentUnit) return;
+
+  const reason = "Auto-mode process received a termination signal";
+  const errorContext: ErrorContext = {
+    message: reason,
+    category: "aborted",
+    isTransient: false,
+  };
+  const basePath = s.basePath || currentBasePath;
+
+  try {
+    emitOpenUnitEndForUnit(basePath, currentUnit.type, currentUnit.id, "cancelled", errorContext);
+  } catch (err) {
+    logWarning("engine", `signal unit-end cleanup failed: ${getErrorMessage(err)}`, { file: "auto.ts" });
+  }
+
+  try {
+    writeUnitRuntimeRecord(basePath, currentUnit.type, currentUnit.id, currentUnit.startedAt, {
+      phase: "crashed",
+      lastProgressAt: Date.now(),
+      lastProgressKind: "signal",
+    });
+  } catch (err) {
+    logWarning("engine", `signal runtime cleanup failed: ${getErrorMessage(err)}`, { file: "auto.ts" });
+  }
+
+  try {
+    if (s.workerId) markLatestActiveForWorkerCanceled(s.workerId, "signal-exit");
+  } catch (err) {
+    logWarning("engine", `signal dispatch cleanup failed: ${getErrorMessage(err)}`, { file: "auto.ts" });
+  }
+
+  try {
+    resolveAgentEndCancelled(errorContext);
+  } catch (err) {
+    logWarning("engine", `signal resolve cleanup failed: ${getErrorMessage(err)}`, { file: "auto.ts" });
+  }
+}
+
 /** Wrapper: register SIGTERM handler and store reference. */
 function registerSigtermHandler(currentBasePath: string): void {
-  s.sigtermHandler = _registerSigtermHandler(currentBasePath, s.sigtermHandler);
+  s.sigtermHandler = _registerSigtermHandler(
+    currentBasePath,
+    s.sigtermHandler,
+    () => closeOutSignalInterruptedUnit(currentBasePath),
+  );
 }
 
 /** Wrapper: deregister SIGTERM handler and clear reference. */
@@ -2057,6 +2109,11 @@ export async function startAuto(
     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,

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

@@ -153,9 +153,29 @@ export async function handleAgentEnd(
   if (maybeHandleEmptyIntentTurn(event, isAutoActive())) return;
 
   if (!isAutoActive()) return;
-  if (isSessionSwitchInFlight()) return;
 
   const lastMsg = event.messages[event.messages.length - 1];
+  if (isSessionSwitchInFlight()) {
+    if (lastMsg && "stopReason" in lastMsg && lastMsg.stopReason === "error") {
+      const rawErrorMsg = ("errorMessage" in lastMsg && lastMsg.errorMessage) ? String(lastMsg.errorMessage) : "";
+      if (isUserInitiatedAbortMessage(rawErrorMsg)) {
+        resolveAgentEndCancelled({
+          message: rawErrorMsg,
+          category: "aborted",
+          isTransient: false,
+        });
+      }
+    } else if (lastMsg && "stopReason" in lastMsg && lastMsg.stopReason === "aborted") {
+      const content = "content" in lastMsg ? lastMsg.content : undefined;
+      const hasEmptyContent = Array.isArray(content) && content.length === 0;
+      const hasErrorMessage = "errorMessage" in lastMsg && !!lastMsg.errorMessage;
+      if (!hasEmptyContent || hasErrorMessage) {
+        resolveAgentEndCancelled(_buildAbortedPauseContext(lastMsg as { errorMessage?: unknown }));
+      }
+    }
+    return;
+  }
+
   if (lastMsg && "stopReason" in lastMsg && lastMsg.stopReason === "aborted") {
     // Empty content with aborted stopReason is a non-fatal agent stop (the LLM
     // chose to end without producing output). Only pause on genuine fatal aborts

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

@@ -6,23 +6,36 @@
 import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 
+async function loadContextModePreferences(baseDir: string) {
+  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: 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 " +
+      "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",
+      "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(
@@ -40,20 +53,11 @@ export function registerExecTools(pi: ExtensionAPI): void {
       ),
     }),
     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: 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)}`);
-      }
+      const { executeGsdExec } = await import("../tools/exec-tool.js");
+      const baseDir = process.cwd();
       return executeGsdExec(params as Parameters<typeof executeGsdExec>[0], {
-        baseDir: process.cwd(),
-        preferences: prefs?.preferences ?? null,
+        baseDir,
+        preferences: await loadContextModePreferences(baseDir),
       });
     },
   });
@@ -67,7 +71,7 @@ export function registerExecTools(pi: ExtensionAPI): void {
     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)." })),
@@ -81,8 +85,10 @@ export function registerExecTools(pi: ExtensionAPI): void {
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
       const { executeExecSearch } = await import("../tools/exec-search-tool.js");
+      const baseDir = process.cwd();
       return executeExecSearch(params as Parameters<typeof executeExecSearch>[0], {
-        baseDir: process.cwd(),
+        baseDir,
+        preferences: await loadContextModePreferences(baseDir),
       });
     },
   });
@@ -102,8 +108,10 @@ export function registerExecTools(pi: ExtensionAPI): void {
     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 as Parameters<typeof executeResume>[0], {
-        baseDir: process.cwd(),
+        baseDir,
+        preferences: await loadContextModePreferences(baseDir),
       });
     },
   });

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

@@ -65,6 +65,26 @@ async function applyDisabledModelProviderPolicy(ctx: ExtensionContext): Promise<
   }
 }
 
+/**
+ * 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: ExtensionContext): Promise<void> {
+  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: string = process.cwd()): string {
   return resolveWorktreeProjectRoot(cwd);
 }
@@ -123,6 +143,7 @@ export function registerHooks(
     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())) {
@@ -172,6 +193,7 @@ export function registerHooks(
     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/src/resources/extensions/gsd/db/unit-dispatches.ts

@@ -359,6 +359,47 @@ export function markCanceled(dispatchId: number, reason: string): void {
   ).run({ ":id": dispatchId, ":ended_at": now, ":reason": reason });
 }
 
+/**
+ * Best-effort signal/crash cleanup: cancel the latest active dispatch owned by
+ * a worker when the process is exiting before the normal loop can settle it.
+ */
+export function markLatestActiveForWorkerCanceled(workerId: string, reason: string): boolean {
+  if (!isDbAvailable()) return false;
+  const now = new Date().toISOString();
+  const db = _getAdapter()!;
+  const result = transaction(() => {
+    return db.prepare(
+      `UPDATE unit_dispatches
+       SET status = 'canceled', ended_at = :ended_at, exit_reason = :reason
+       WHERE id = (
+         SELECT id FROM unit_dispatches
+         WHERE worker_id = :worker_id
+           AND status IN ('pending','claimed','running')
+         ORDER BY id DESC
+         LIMIT 1
+       )`,
+    ).run({
+      ":ended_at": now,
+      ":reason": reason,
+      ":worker_id": workerId,
+    });
+  });
+  const changes =
+    typeof (result as { changes?: unknown }).changes === "number"
+      ? (result as { changes: number }).changes
+      : 0;
+  if (changes <= 0) return false;
+  insertAuditEvent({
+    eventId: randomUUID(),
+    traceId: workerId,
+    category: "orchestration",
+    type: "dispatch-canceled",
+    ts: now,
+    payload: { workerId, reason },
+  });
+  return true;
+}
+
 /**
  * Fetch the most recent N dispatches for a unit. Used by recordDispatchClaim
  * callers to compute attempt_n and by detect-stuck.ts (B3) to consult

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

@@ -87,6 +87,34 @@ import { logWarning } from "./workflow-logger.js";
 import { deleteRuntimeKv } from "./db/runtime-kv.js";
 import { PAUSED_SESSION_KV_KEY } from "./interrupted-session.js";
 
+type AutoStartOptions = Parameters<typeof startAutoDetached>[4];
+type AutoStartLauncher = typeof startAutoDetached;
+
+function scheduleAutoStartAfterIdle(
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+  basePath: string,
+  verboseMode: boolean,
+  options?: AutoStartOptions,
+  launch: AutoStartLauncher = startAutoDetached,
+): void {
+  const waitForIdle =
+    typeof (ctx as { waitForIdle?: unknown }).waitForIdle === "function"
+      ? ctx.waitForIdle.bind(ctx)
+      : async () => {};
+  void waitForIdle()
+    .then(() => {
+      setTimeout(() => launch(ctx, pi, basePath, verboseMode, options), 0);
+    })
+    .catch((err) => {
+      const message = err instanceof Error ? err.message : String(err);
+      ctx.ui.notify(`Auto-start failed while waiting for the prior turn to settle: ${message}`, "error");
+      logWarning("guided", `auto-start idle wait failed: ${message}`);
+    });
+}
+
+export const _scheduleAutoStartAfterIdleForTest = scheduleAutoStartAfterIdle;
+
 // ─── Scope-based validator wrappers ──────────────────────────────────────────
 // These thin wrappers accept a MilestoneScope so callers that already hold a
 // pinned scope never have to re-derive (basePath, milestoneId) separately.
@@ -446,7 +474,7 @@ async function dispatchNextDeepProjectSetupStage(entry: PendingDeepProjectSetupE
 
   if (!hasPendingDeepStage(prefs, entry.basePath)) {
     pendingDeepProjectSetupMap.delete(entry.basePath);
-    startAutoDetached(entry.ctx, entry.pi, entry.basePath, false, { step: entry.step });
+    scheduleAutoStartAfterIdle(entry.ctx, entry.pi, entry.basePath, false, { step: entry.step });
     return true;
   }
 
@@ -479,7 +507,7 @@ async function dispatchNextDeepProjectSetupStage(entry: PendingDeepProjectSetupE
       entry.ctx.ui.notify(result.reason, result.level);
     } else if (hasPendingDeepStage(prefs, entry.basePath)) {
       pendingDeepProjectSetupMap.delete(entry.basePath);
-      startAutoDetached(entry.ctx, entry.pi, entry.basePath, false, { step: entry.step });
+      scheduleAutoStartAfterIdle(entry.ctx, entry.pi, entry.basePath, false, { step: entry.step });
       return true;
     }
     return false;
@@ -487,7 +515,7 @@ async function dispatchNextDeepProjectSetupStage(entry: PendingDeepProjectSetupE
 
   if (!USER_DRIVEN_DEEP_SETUP_UNITS.has(result.unitType)) {
     pendingDeepProjectSetupMap.delete(entry.basePath);
-    startAutoDetached(entry.ctx, entry.pi, entry.basePath, false, { step: entry.step });
+    scheduleAutoStartAfterIdle(entry.ctx, entry.pi, entry.basePath, false, { step: entry.step });
     return true;
   }
 
@@ -693,7 +721,7 @@ export function checkAutoStartAfterDiscuss(): boolean {
 
   pendingAutoStartMap.delete(basePath);
   ctx.ui.notify(`Milestone ${milestoneId} ready.`, "success");
-  startAutoDetached(ctx, pi, basePath, false, { step });
+  scheduleAutoStartAfterIdle(ctx, pi, basePath, false, { step });
   return true;
 }
 

package/src/resources/extensions/gsd/preferences-types.ts

@@ -32,7 +32,7 @@ export interface ContextManagementConfig {
 /**
  * Opt-in tool-output sandboxing for sub-sessions. When enabled, the gsd_exec
  * MCP tool runs scripts in an isolated subprocess and returns only a short
- * digest to the calling agent's context window; full stdout/stderr persist
+ * digest to the calling agent's context window; capped stdout/stderr persist
  * in the project memory store and can be retrieved by id later.
  *
  * Inspired by mksglu/context-mode (Elastic License 2.0). This is an

package/src/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/src/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/src/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/src/resources/extensions/gsd/quick.ts

@@ -10,8 +10,8 @@
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
-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";
@@ -77,6 +77,40 @@ function ensureQuickDir(basePath: string, taskNum: number, slug: string): string
   return taskDir;
 }
 
+function isPathInside(parent: string, child: string): boolean {
+  const rel = relative(parent, child);
+  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
+}
+
+function isExternalGsdRoot(basePath: string, root: string): boolean {
+  try {
+    return !isPathInside(realpathSync(basePath), realpathSync(root));
+  } catch {
+    return !isPathInside(basePath, root);
+  }
+}
+
+export function buildQuickCommitInstruction(basePath: string, root: string): string {
+  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: string): string {
   return join(gsdRoot(basePath), "runtime", "quick-return.json");
 }
@@ -246,6 +280,7 @@ export async function handleQuick(
     taskDir: taskDirRel,
     branch: actualBranch,
     summaryPath,
+    commitInstruction: buildQuickCommitInstruction(basePath, root),
     date,
     taskNum: String(taskNum),
     slug,

package/src/resources/extensions/gsd/tests/auto-loop.test.ts

@@ -10,6 +10,8 @@ import {
   _resetPendingResolve,
   _hasPendingResolveForTest,
   _setActiveSession,
+  _setSessionSwitchInFlight,
+  _consumePendingSwitchCancellation,
   isSessionSwitchInFlight,
 } from "../auto/resolve.js";
 import { runUnit } from "../auto/run-unit.js";
@@ -206,6 +208,28 @@ test("runUnit returns cancelled when session creation fails", async () => {
   assert.equal(pi.calls.length, 0);
 });
 
+test("runUnit clears queued switch cancellation when session creation fails", async () => {
+  _resetPendingResolve();
+
+  const ctx = makeMockCtx();
+  const pi = makeMockPi();
+  const s = makeMockSession({
+    newSessionThrows: "connection refused",
+    onNewSessionStart: () => {
+      resolveAgentEndCancelled({
+        message: "Claude Code process aborted by user",
+        category: "aborted",
+        isTransient: false,
+      });
+    },
+  });
+
+  const result = await runUnit(ctx, pi, s, "task", "T01", "prompt");
+
+  assert.equal(result.status, "cancelled");
+  assert.equal(_consumePendingSwitchCancellation(), null);
+});
+
 test("runUnit returns cancelled when session creation times out", async () => {
   _resetPendingResolve();
 
@@ -221,6 +245,34 @@ test("runUnit returns cancelled when session creation times out", async () => {
   assert.equal(pi.calls.length, 0);
 });
 
+test("runUnit consumes a cancellation queued during session switch before dispatch", async () => {
+  _resetPendingResolve();
+
+  const ctx = makeMockCtx();
+  const pi = makeMockPi();
+  let cancellationQueued = false;
+  const s = makeMockSession({
+    newSessionDelayMs: 10,
+    onNewSessionStart: () => {
+      setTimeout(() => {
+        cancellationQueued = !resolveAgentEndCancelled({
+          message: "Claude Code process aborted by user",
+          category: "aborted",
+          isTransient: false,
+        });
+      }, 0);
+    },
+  });
+
+  const result = await runUnit(ctx, pi, s, "plan-slice", "M009/S01", "prompt");
+
+  assert.equal(cancellationQueued, true);
+  assert.equal(result.status, "cancelled");
+  assert.equal(result.errorContext?.category, "aborted");
+  assert.equal(result.errorContext?.message, "Claude Code process aborted by user");
+  assert.equal(pi.calls.length, 0, "queued switch cancellation must prevent prompt dispatch");
+});
+
 test("runUnit keeps the session-switch guard across a late newSession settlement", async () => {
   _resetPendingResolve();
   mock.timers.enable();
@@ -2089,6 +2141,25 @@ test("resolveAgentEndCancelled without args produces no errorContext field", asy
   assert.equal(resolved.errorContext, undefined, "errorContext must not be present when no args passed");
 });
 
+test("resolveAgentEndCancelled queues cancellation that arrives during session switch", () => {
+  _resetPendingResolve();
+
+  _setSessionSwitchInFlight(true);
+  const resolved = resolveAgentEndCancelled({
+    message: "Claude Code process aborted by user",
+    category: "aborted",
+    isTransient: false,
+  });
+
+  assert.equal(resolved, false);
+  const pending = _consumePendingSwitchCancellation();
+  assert.ok(pending?.errorContext, "queued cancellation should preserve errorContext");
+  assert.equal(pending.errorContext.category, "aborted");
+  assert.equal(pending.errorContext.message, "Claude Code process aborted by user");
+  assert.equal(_consumePendingSwitchCancellation(), null);
+  _resetPendingResolve();
+});
+
 // ─── #1571: artifact verification retry ──────────────────────────────────────
 
 test("autoLoop re-iterates when postUnitPreVerification returns retry (#1571)", async () => {

package/src/resources/extensions/gsd/tests/auto-recovery.test.ts

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 
-import { verifyExpectedArtifact, hasImplementationArtifacts, resolveExpectedArtifactPath, diagnoseExpectedArtifact, buildLoopRemediationSteps, writeBlockerPlaceholder } from "../auto-recovery.ts";
+import { verifyExpectedArtifact, hasImplementationArtifacts, resolveExpectedArtifactPath, diagnoseExpectedArtifact, buildLoopRemediationSteps, writeBlockerPlaceholder, refreshRecoveryDbForArtifact } from "../auto-recovery.ts";
 import { resolveMilestoneFile } from "../paths.ts";
 import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertGateRow, insertTask, getMilestoneCommitAttributionShas } from "../gsd-db.ts";
 import { clearParseCache } from "../files.ts";
@@ -175,6 +175,19 @@ test("resolveExpectedArtifactPath returns correct path for all slice-level types
   }
 });
 
+test("refreshRecoveryDbForArtifact treats missing execute-task DB rows as fatal mismatches", () => {
+  makeTmpProject();
+
+  const result = refreshRecoveryDbForArtifact("execute-task", "M001/S01/T01");
+
+  assert.deepEqual(result, {
+    ok: false,
+    fatal: true,
+    reason: "execute-task-artifact-db-missing",
+    message: "Stuck recovery found execute-task M001/S01/T01 artifacts, but no matching DB task row exists after refresh.",
+  });
+});
+
 // ─── diagnoseExpectedArtifact ─────────────────────────────────────────────
 
 test("diagnoseExpectedArtifact returns description for known types", () => {

package/src/resources/extensions/gsd/tests/compaction-snapshot.test.ts

@@ -121,3 +121,14 @@ test('executeResume: reports friendly empty state when no snapshot exists', () =
     cleanup(base);
   }
 });
+
+test('executeResume: returns disabled error when context_mode.enabled=false', () => {
+  const base = freshBase();
+  try {
+    const result = executeResume({}, { baseDir: base, preferences: { context_mode: { enabled: false } } });
+    assert.equal(result.isError, true);
+    assert.equal((result.details as { error?: string }).error, 'context_mode_disabled');
+  } finally {
+    cleanup(base);
+  }
+});