gsd-pi 2.65.0-dev.6cc5110 → 2.65.0-dev.800ece0

package/dist/resources/extensions/gsd/auto/finalize-timeout.js

@@ -6,6 +6,8 @@
  *
  * Leaf module — no imports from auto/ to avoid circular dependencies.
  */
+/** Timeout for postUnitPreVerification in runFinalize (ms). */
+export const FINALIZE_PRE_TIMEOUT_MS = 60_000;
 /** Timeout for postUnitPostVerification in runFinalize (ms). */
 export const FINALIZE_POST_TIMEOUT_MS = 60_000;
 /**

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

@@ -24,7 +24,7 @@ import { resolveEngine } from "../engine-resolver.js";
 export async function autoLoop(ctx, pi, s, deps) {
     debugLog("autoLoop", { phase: "enter" });
     let iteration = 0;
-    const loopState = { recentUnits: [], stuckRecoveryAttempts: 0 };
+    const loopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 };
     let consecutiveErrors = 0;
     const recentErrorMessages = [];
     while (s.active) {
@@ -202,7 +202,7 @@ export async function autoLoop(ctx, pi, s, deps) {
             if (unitPhaseResult.action === "break")
                 break;
             // ── Phase 5: Finalize ───────────────────────────────────────────────
-            const finalizeResult = await runFinalize(ic, iterData, sidecarItem);
+            const finalizeResult = await runFinalize(ic, iterData, loopState, sidecarItem);
             if (finalizeResult.action === "break")
                 break;
             if (finalizeResult.action === "continue")

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

@@ -7,7 +7,7 @@
  * Imports from: auto/types, auto/detect-stuck, auto/run-unit, auto/loop-deps
  */
 import { importExtensionModule } from "@gsd/pi-coding-agent";
-import { MAX_RECOVERY_CHARS, BUDGET_THRESHOLDS, } from "./types.js";
+import { MAX_RECOVERY_CHARS, BUDGET_THRESHOLDS, MAX_FINALIZE_TIMEOUTS, } from "./types.js";
 import { detectStuck } from "./detect-stuck.js";
 import { runUnit } from "./run-unit.js";
 import { debugLog } from "../debug-logger.js";
@@ -20,7 +20,7 @@ import { gsdRoot } from "../paths.js";
 import { atomicWriteSync } from "../atomic-write.js";
 import { verifyExpectedArtifact, diagnoseExpectedArtifact, buildLoopRemediationSteps } from "../auto-recovery.js";
 import { writeUnitRuntimeRecord } from "../unit-runtime.js";
-import { withTimeout, FINALIZE_POST_TIMEOUT_MS } from "./finalize-timeout.js";
+import { withTimeout, FINALIZE_PRE_TIMEOUT_MS, FINALIZE_POST_TIMEOUT_MS } from "./finalize-timeout.js";
 import { getEligibleSlices } from "../slice-parallel-eligibility.js";
 import { startSliceParallel } from "../slice-parallel-orchestrator.js";
 import { isDbAvailable, getMilestoneSlices } from "../gsd-db.js";
@@ -1040,7 +1040,7 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
  * Phase 5: Post-unit finalize — pre/post verification, UAT pause, step-wizard.
  * Returns break/continue/next to control the outer loop.
  */
-export async function runFinalize(ic, iterData, sidecarItem) {
+export async function runFinalize(ic, iterData, loopState, sidecarItem) {
     const { ctx, pi, s, deps } = ic;
     const { pauseAfterUatDispatch } = iterData;
     debugLog("autoLoop", { phase: "finalize", iteration: ic.iteration });
@@ -1058,13 +1058,44 @@ export async function runFinalize(ic, iterData, sidecarItem) {
         updateProgressWidget: deps.updateProgressWidget,
     };
     // Pre-verification processing (commit, doctor, state rebuild, etc.)
+    // Timeout guard: if postUnitPreVerification hangs (e.g., safety harness
+    // deadlock, browser teardown hang, worktree sync stall), force-continue
+    // after timeout so the auto-loop is not permanently frozen (#3757).
+    //
+    // On timeout, null out s.currentUnit so the timed-out task's late async
+    // mutations are harmless — postUnitPreVerification guards all side effects
+    // behind `if (s.currentUnit)`. The next iteration sets a fresh currentUnit.
     // Sidecar items use lightweight pre-verification opts
     const preVerificationOpts = sidecarItem
         ? sidecarItem.kind === "hook"
             ? { skipSettleDelay: true, skipWorktreeSync: true }
             : { skipSettleDelay: true }
         : undefined;
-    const preResult = await deps.postUnitPreVerification(postUnitCtx, preVerificationOpts);
+    const preUnitSnapshot = s.currentUnit
+        ? { type: s.currentUnit.type, id: s.currentUnit.id, startedAt: s.currentUnit.startedAt }
+        : null;
+    const preResultGuard = await withTimeout(deps.postUnitPreVerification(postUnitCtx, preVerificationOpts), FINALIZE_PRE_TIMEOUT_MS, "postUnitPreVerification");
+    if (preResultGuard.timedOut) {
+        // Detach session from the timed-out unit so late async completions
+        // cannot mutate state for the next unit (#3757).
+        s.currentUnit = null;
+        loopState.consecutiveFinalizeTimeouts++;
+        debugLog("autoLoop", {
+            phase: "pre-verification-timeout",
+            iteration: ic.iteration,
+            unitType: iterData.unitType,
+            unitId: iterData.unitId,
+            consecutiveTimeouts: loopState.consecutiveFinalizeTimeouts,
+        });
+        if (loopState.consecutiveFinalizeTimeouts >= MAX_FINALIZE_TIMEOUTS) {
+            ctx.ui.notify(`postUnitPreVerification timed out ${loopState.consecutiveFinalizeTimeouts} consecutive times — stopping auto-mode to prevent budget waste`, "error");
+            await deps.stopAuto(ctx, pi, `${loopState.consecutiveFinalizeTimeouts} consecutive finalize timeouts`);
+            return { action: "break", reason: "finalize-timeout-escalation" };
+        }
+        ctx.ui.notify(`postUnitPreVerification timed out after ${FINALIZE_PRE_TIMEOUT_MS / 1000}s for ${iterData.unitType} ${iterData.unitId} (${loopState.consecutiveFinalizeTimeouts}/${MAX_FINALIZE_TIMEOUTS}) — continuing to next iteration`, "warning");
+        return { action: "next", data: undefined };
+    }
+    const preResult = preResultGuard.value;
     if (preResult === "dispatched") {
         debugLog("autoLoop", {
             phase: "exit",
@@ -1119,13 +1150,23 @@ export async function runFinalize(ic, iterData, sidecarItem) {
     // auto-loop is not permanently frozen (#2344).
     const postResultGuard = await withTimeout(deps.postUnitPostVerification(postUnitCtx), FINALIZE_POST_TIMEOUT_MS, "postUnitPostVerification");
     if (postResultGuard.timedOut) {
+        // Detach session from the timed-out unit so late async completions
+        // cannot mutate state for the next unit (#3757).
+        s.currentUnit = null;
+        loopState.consecutiveFinalizeTimeouts++;
         debugLog("autoLoop", {
             phase: "post-verification-timeout",
             iteration: ic.iteration,
             unitType: iterData.unitType,
             unitId: iterData.unitId,
+            consecutiveTimeouts: loopState.consecutiveFinalizeTimeouts,
         });
-        ctx.ui.notify(`postUnitPostVerification timed out after ${FINALIZE_POST_TIMEOUT_MS / 1000}s for ${iterData.unitType} ${iterData.unitId} — continuing to next iteration`, "warning");
+        if (loopState.consecutiveFinalizeTimeouts >= MAX_FINALIZE_TIMEOUTS) {
+            ctx.ui.notify(`postUnitPostVerification timed out ${loopState.consecutiveFinalizeTimeouts} consecutive times — stopping auto-mode to prevent budget waste`, "error");
+            await deps.stopAuto(ctx, pi, `${loopState.consecutiveFinalizeTimeouts} consecutive finalize timeouts`);
+            return { action: "break", reason: "finalize-timeout-escalation" };
+        }
+        ctx.ui.notify(`postUnitPostVerification timed out after ${FINALIZE_POST_TIMEOUT_MS / 1000}s for ${iterData.unitType} ${iterData.unitId} (${loopState.consecutiveFinalizeTimeouts}/${MAX_FINALIZE_TIMEOUTS}) — continuing to next iteration`, "warning");
         return { action: "next", data: undefined };
     }
     const postResult = postResultGuard.value;
@@ -1141,5 +1182,7 @@ export async function runFinalize(ic, iterData, sidecarItem) {
         debugLog("autoLoop", { phase: "exit", reason: "step-wizard" });
         return { action: "break", reason: "step-wizard" };
     }
+    // Both pre and post verification completed without timeout — reset counter
+    loopState.consecutiveFinalizeTimeouts = 0;
     return { action: "next", data: undefined };
 }

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

@@ -21,3 +21,5 @@ export const BUDGET_THRESHOLDS = [
     { pct: 80, label: "Approaching budget ceiling — 80%", notifyLevel: "warning", cmuxLevel: "warning" },
     { pct: 75, label: "Budget 75%", notifyLevel: "info", cmuxLevel: "progress" },
 ];
+/** Max consecutive finalize timeouts before hard-stopping auto-mode. */
+export const MAX_FINALIZE_TIMEOUTS = 3;

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

@@ -9,6 +9,7 @@ import { getCurrentBranch } from "./worktree.js";
 import { getActiveHook } from "./post-unit-hooks.js";
 import { getLedger, getProjectTotals } from "./metrics.js";
 import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
+import { formatShortcut } from "./files.js";
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { truncateToWidth, visibleWidth } from "@gsd/pi-tui";
@@ -725,7 +726,7 @@ export function updateProgressWidget(ctx, unitType, unitId, state, accessors, ti
                 // Hints line
                 const hintParts = [];
                 hintParts.push("esc pause");
-                hintParts.push(process.platform === "darwin" ? "⌃⌥G dashboard" : "Ctrl+Alt+G dashboard");
+                hintParts.push(`${formatShortcut("Ctrl+Alt+G")} dashboard`);
                 const hintStr = theme.fg("dim", hintParts.join(" | "));
                 const commitStr = lastCommit
                     ? theme.fg("dim", `${lastCommit.timeAgo} ago: ${commitMsg}`)

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

@@ -20,11 +20,12 @@ import { synthesizeCrashRecovery } from "./session-forensics.js";
 import { writeLock, clearLock, readCrashLock, formatCrashInfo, isLockProcessAlive, } from "./crash-recovery.js";
 import { acquireSessionLock, releaseSessionLock, updateSessionLock, } from "./session-lock.js";
 import { ensureGitignore, untrackRuntimeFiles } from "./gitignore.js";
-import { nativeIsRepo, nativeInit, nativeAddAll, nativeCommit, nativeGetCurrentBranch, nativeDetectMainBranch, nativeCheckoutBranch, } from "./native-git-bridge.js";
+import { nativeIsRepo, nativeInit, nativeAddAll, nativeCommit, nativeGetCurrentBranch, nativeDetectMainBranch, nativeCheckoutBranch, nativeBranchList, nativeBranchListMerged, nativeBranchDelete, nativeWorktreeRemove, } from "./native-git-bridge.js";
 import { GitServiceImpl } from "./git-service.js";
 import { captureIntegrationBranch, detectWorktreeName, setActiveMilestoneId, } from "./worktree.js";
 import { getAutoWorktreePath } from "./auto-worktree.js";
 import { readResourceVersion, cleanStaleRuntimeUnits } from "./auto-worktree.js";
+import { worktreePath as getWorktreeDir, isInsideWorktreesDir } from "./worktree-manager.js";
 import { initMetrics } from "./metrics.js";
 import { initRoutingHistory } from "./routing-history.js";
 import { restoreHookState, resetHookState } from "./post-unit-hooks.js";
@@ -35,7 +36,7 @@ import { hideFooter } from "./auto-dashboard.js";
 import { debugLog, enableDebug, isDebugEnabled, getDebugLogPath, } from "./debug-logger.js";
 import { logWarning, logError } from "./workflow-logger.js";
 import { parseUnitId } from "./unit-id.js";
-import { existsSync, mkdirSync, readdirSync, statSync, unlinkSync, } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, rmSync, statSync, unlinkSync, } from "node:fs";
 import { join } from "node:path";
 import { sep as pathSep } from "node:path";
 import { resolveProjectRootDbPath } from "./bootstrap/dynamic-tools.js";
@@ -62,6 +63,117 @@ export async function openProjectDbIfPresent(basePath) {
         logWarning("engine", `gsd-db: failed to open existing database: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
+/**
+ * Audit for orphaned milestone branches at bootstrap.
+ *
+ * After a milestone completes, the teardown step (merge branch → main,
+ * delete branch, remove worktree) runs as a post-completion engine step.
+ * If the session ends between completion and teardown, the branch and
+ * worktree are orphaned — the DB says "complete" so auto-mode won't
+ * re-enter the milestone, and the teardown is never retried.
+ *
+ * This audit runs on every fresh bootstrap to catch that gap:
+ * 1. Lists all local `milestone/*` branches.
+ * 2. For each, checks if the milestone's DB status is "complete".
+ * 3. If the branch is already merged into main → deletes the branch
+ *    and cleans up any orphaned worktree directory (safe, no data loss).
+ * 4. If the branch is NOT merged → preserves it and warns the user
+ *    so they can merge manually (data safety first).
+ *
+ * Returns a summary of actions taken for the caller to surface via notify.
+ */
+export function auditOrphanedMilestoneBranches(basePath, isolationMode) {
+    const recovered = [];
+    const warnings = [];
+    // Skip in none mode — no milestone branches are created
+    if (isolationMode === "none")
+        return { recovered, warnings };
+    // Skip if DB not available — can't determine completion status
+    if (!isDbAvailable())
+        return { recovered, warnings };
+    let milestoneBranches;
+    try {
+        milestoneBranches = nativeBranchList(basePath, "milestone/*");
+    }
+    catch {
+        // git branch list failed — skip audit
+        return { recovered, warnings };
+    }
+    if (milestoneBranches.length === 0)
+        return { recovered, warnings };
+    // Detect main branch for merge-check
+    let mainBranch;
+    try {
+        mainBranch = nativeDetectMainBranch(basePath);
+    }
+    catch {
+        mainBranch = "main";
+    }
+    // Get branches already merged into main
+    let mergedBranches;
+    try {
+        mergedBranches = new Set(nativeBranchListMerged(basePath, mainBranch, "milestone/*"));
+    }
+    catch {
+        mergedBranches = new Set();
+    }
+    for (const branch of milestoneBranches) {
+        const milestoneId = branch.replace(/^milestone\//, "");
+        const milestone = getMilestone(milestoneId);
+        // Only audit completed milestones
+        if (!milestone || milestone.status !== "complete")
+            continue;
+        const isMerged = mergedBranches.has(branch);
+        if (isMerged) {
+            // Branch is merged — safe to delete branch and clean up worktree dir
+            try {
+                nativeBranchDelete(basePath, branch, true);
+                recovered.push(`Deleted merged branch ${branch} for completed milestone ${milestoneId}.`);
+            }
+            catch (err) {
+                warnings.push(`Failed to delete merged branch ${branch}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            // Clean up orphaned worktree directory if it exists
+            const wtDir = getWorktreeDir(basePath, milestoneId);
+            if (existsSync(wtDir)) {
+                // Try git worktree remove first (handles registered worktrees)
+                try {
+                    nativeWorktreeRemove(basePath, wtDir, true);
+                }
+                catch (e) {
+                    // Not a registered worktree — expected for orphaned dirs
+                    logWarning("engine", `worktree remove failed (expected for orphaned dirs): ${e instanceof Error ? e.message : String(e)}`);
+                }
+                // If the directory still exists after git worktree remove (either it
+                // wasn't registered or the remove was a noop), fall back to direct
+                // filesystem removal — but only inside .gsd/worktrees/ for safety (#2365).
+                if (existsSync(wtDir)) {
+                    if (isInsideWorktreesDir(basePath, wtDir)) {
+                        try {
+                            rmSync(wtDir, { recursive: true, force: true });
+                            recovered.push(`Removed orphaned worktree directory for ${milestoneId}.`);
+                        }
+                        catch (err2) {
+                            warnings.push(`Failed to remove worktree directory for ${milestoneId}: ${err2 instanceof Error ? err2.message : String(err2)}`);
+                        }
+                    }
+                    else {
+                        warnings.push(`Orphaned worktree directory for ${milestoneId} is outside .gsd/worktrees/ — skipping removal for safety.`);
+                    }
+                }
+                else {
+                    recovered.push(`Removed orphaned worktree directory for ${milestoneId}.`);
+                }
+            }
+        }
+        else {
+            // Branch is NOT merged — preserve for safety, warn the user
+            warnings.push(`Branch ${branch} exists for completed milestone ${milestoneId} but is NOT merged into ${mainBranch}. ` +
+                `This may contain unmerged work. Merge manually or run \`/gsd health --fix\` to resolve.`);
+        }
+    }
+    return { recovered, warnings };
+}
 export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, requestedStepMode, deps) {
     const { shouldUseWorktreeIsolation, registerSigtermHandler, lockBase, buildResolver, } = deps;
     const lockResult = acquireSessionLock(base);
@@ -191,6 +303,26 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         // Open the project-root DB before deriveState so DB-backed state
         // derivation (queue-order, task status) works on a cold start (#2841).
         await openProjectDbIfPresent(base);
+        // ── Orphaned milestone branch audit ──
+        // Catches completed milestones whose teardown (merge + branch delete)
+        // was lost due to session ending between completion and teardown.
+        // Must run after DB open and before worktree entry.
+        try {
+            const auditResult = auditOrphanedMilestoneBranches(base, getIsolationMode());
+            for (const msg of auditResult.recovered) {
+                ctx.ui.notify(`Orphan audit: ${msg}`, "info");
+            }
+            for (const msg of auditResult.warnings) {
+                ctx.ui.notify(`Orphan audit: ${msg}`, "warning");
+            }
+            if (auditResult.recovered.length > 0) {
+                debugLog("orphan-audit", { recovered: auditResult.recovered, warnings: auditResult.warnings });
+            }
+        }
+        catch (err) {
+            // Non-fatal — the audit is defensive, never block bootstrap
+            logWarning("bootstrap", `orphaned milestone branch audit failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
         let state = await deriveState(base);
         // Stale worktree state recovery (#654)
         if (state.activeMilestone &&

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

@@ -3,7 +3,7 @@ import { isToolCallEventType } from "@gsd/pi-coding-agent";
 import { buildMilestoneFileName, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
 import { buildBeforeAgentStartResult } from "./system-context.js";
 import { handleAgentEnd } from "./agent-end-recovery.js";
-import { clearDiscussionFlowState, isDepthVerified, isQueuePhaseActive, markDepthVerified, resetWriteGateState, shouldBlockContextWrite, shouldBlockQueueExecution } from "./write-gate.js";
+import { clearDiscussionFlowState, isDepthVerified, isDepthConfirmationAnswer, isQueuePhaseActive, markDepthVerified, resetWriteGateState, shouldBlockContextWrite, shouldBlockQueueExecution } from "./write-gate.js";
 import { isBlockedStateFile, isBashWriteToStateFile, BLOCKED_WRITE_ERROR } from "../write-intercept.js";
 import { cleanupQuickBranch } from "../quick.js";
 import { getDiscussionMilestoneId } from "../guided-flow.js";
@@ -230,7 +230,12 @@ export function registerHooks(pi) {
         const questions = event.input?.questions ?? [];
         for (const question of questions) {
             if (typeof question.id === "string" && question.id.includes("depth_verification")) {
-                markDepthVerified();
+                // Only unlock the gate if the user selected the first option (confirmation).
+                // Cross-references against the question's defined options to reject free-form "Other" text.
+                const answer = details.response?.answers?.[question.id];
+                if (isDepthConfirmationAnswer(answer?.selected, question.options)) {
+                    markDepthVerified();
+                }
                 break;
             }
         }

package/dist/resources/extensions/gsd/bootstrap/system-context.js

@@ -12,7 +12,7 @@ import { hasSkillSnapshot, detectNewSkills, formatSkillsXml } from "../skill-dis
 import { getActiveAutoWorktreeContext } from "../auto-worktree.js";
 import { getActiveWorktreeName, getWorktreeOriginalCwd } from "../worktree-command.js";
 import { deriveState } from "../state.js";
-import { formatOverridesSection, loadActiveOverrides, loadFile, parseContinue, parseSummary } from "../files.js";
+import { formatOverridesSection, formatShortcut, loadActiveOverrides, loadFile, parseContinue, parseSummary } from "../files.js";
 import { toPosixPath } from "../../shared/mod.js";
 import { markCmuxPromptShown, shouldPromptToEnableCmux } from "../../cmux/index.js";
 const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
@@ -60,6 +60,8 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     const systemContent = loadPrompt("system", {
         bundledSkillsTable: buildBundledSkillsTable(),
         templatesDir: getTemplatesDir(),
+        shortcutDashboard: formatShortcut("Ctrl+Alt+G"),
+        shortcutShell: formatShortcut("Ctrl+Alt+B"),
     });
     const loadedPreferences = loadEffectiveGSDPreferences();
     if (shouldPromptToEnableCmux(loadedPreferences?.preferences)) {

package/dist/resources/extensions/gsd/bootstrap/write-gate.js

@@ -43,6 +43,30 @@ export function clearDiscussionFlowState() {
 export function markDepthVerified() {
     depthVerificationDone = true;
 }
+/**
+ * Check whether a depth_verification answer confirms the discussion is complete.
+ * Uses structural validation: the selected answer must exactly match the first
+ * option label from the question definition (the confirmation option by convention).
+ * This rejects free-form "Other" text, decline options, and garbage input without
+ * coupling to any specific label substring.
+ *
+ * @param selected  The answer's selected value from details.response.answers[id].selected
+ * @param options   The question's options array from event.input.questions[n].options
+ */
+export function isDepthConfirmationAnswer(selected, options) {
+    const value = Array.isArray(selected) ? selected[0] : selected;
+    if (typeof value !== "string" || !value)
+        return false;
+    // If options are available, structurally validate: selected must exactly match
+    // the first option (confirmation) label. Rejects free-form "Other" and decline options.
+    if (Array.isArray(options) && options.length > 0) {
+        const confirmLabel = options[0]?.label;
+        return typeof confirmLabel === "string" && value === confirmLabel;
+    }
+    // Fallback when options aren't available (e.g., older call sites):
+    // accept only if it contains "(Recommended)" — the prompt convention suffix.
+    return value.includes("(Recommended)");
+}
 export function shouldBlockContextWrite(toolName, inputPath, milestoneId, depthVerified, queuePhaseActive) {
     if (toolName !== "write")
         return { block: false };
@@ -56,7 +80,13 @@ export function shouldBlockContextWrite(toolName, inputPath, milestoneId, depthV
         return { block: false };
     return {
         block: true,
-        reason: `Blocked: Cannot write to milestone CONTEXT.md during discussion phase without depth verification. Call ask_user_questions with question id "depth_verification" first to confirm discussion depth before writing context.`,
+        reason: [
+            `HARD BLOCK: Cannot write to milestone CONTEXT.md without depth verification.`,
+            `This is a mechanical gate — you MUST NOT proceed, retry, or rationalize past this block.`,
+            `Required action: call ask_user_questions with question id containing "depth_verification".`,
+            `The user MUST select the "(Recommended)" confirmation option to unlock this gate.`,
+            `If the user declines, cancels, or the tool fails, you must re-ask — not bypass.`,
+        ].join(" "),
     };
 }
 /**

package/dist/resources/extensions/gsd/commands/handlers/core.js

@@ -5,6 +5,7 @@ import { runEnvironmentChecks } from "../../doctor-environment.js";
 import { deriveState } from "../../state.js";
 import { handleCmux } from "../../commands-cmux.js";
 import { projectRoot } from "../context.js";
+import { formatShortcut } from "../../files.js";
 export function showHelp(ctx) {
     const lines = [
         "GSD — Get Shit Done\n",
@@ -20,12 +21,12 @@ export function showHelp(ctx) {
         "  /gsd new-milestone  Create milestone from headless context (used by gsd headless)",
         "",
         "VISIBILITY",
-        "  /gsd status         Show progress dashboard  (Ctrl+Alt+G)",
+        `  /gsd status         Show progress dashboard  (${formatShortcut("Ctrl+Alt+G")})`,
         "  /gsd visualize      Interactive 10-tab TUI (progress, timeline, deps, metrics, health, agent, changes, knowledge, captures, export)",
         "  /gsd queue          Show queued/dispatched units and execution order",
         "  /gsd history        View execution history  [--cost] [--phase] [--model] [N]",
         "  /gsd changelog      Show categorized release notes  [version]",
-        "  /gsd notifications  View persistent notification history  [clear|tail|filter]  (Ctrl+Alt+N)",
+        `  /gsd notifications  View persistent notification history  [clear|tail|filter]  (${formatShortcut("Ctrl+Alt+N")})`,
         "",
         "COURSE CORRECTION",
         "  /gsd steer <desc>   Apply user override to active work",

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

@@ -52,6 +52,23 @@ export function clearParseCache() {
     for (const cb of _cacheClearCallbacks)
         cb();
 }
+// ─── Platform shortcuts ───────────────────────────────────────────────────
+const IS_MAC = process.platform === "darwin";
+/**
+ * Format a keyboard shortcut for the current OS.
+ * Input: modifier key combo like "Ctrl+Alt+G"
+ * Output: "⌃⌥G" on macOS, "Ctrl+Alt+G" on Windows/Linux.
+ */
+export function formatShortcut(combo) {
+    if (!IS_MAC)
+        return combo;
+    return combo
+        .replace(/Ctrl\+Alt\+/i, "⌃⌥")
+        .replace(/Ctrl\+/i, "⌃")
+        .replace(/Alt\+/i, "⌥")
+        .replace(/Shift\+/i, "⇧")
+        .replace(/Cmd\+/i, "⌘");
+}
 // ─── Helpers ───────────────────────────────────────────────────────────────
 /** Extract the text after a heading at a given level, up to the next heading of same or higher level. */
 export function extractSection(body, heading, level = 2) {

package/dist/resources/extensions/gsd/gsd-db.js

@@ -391,6 +391,28 @@ function migrateSchema(db) {
     const currentVersion = row ? row["v"] : 0;
     if (currentVersion >= SCHEMA_VERSION)
         return;
+    // Backup database before migration so a mid-migration crash doesn't
+    // leave a partially-migrated DB with no recovery path.
+    // WAL-safe: checkpoint first to flush WAL into the main DB file, then copy.
+    if (currentPath && currentPath !== ":memory:" && existsSync(currentPath)) {
+        try {
+            const backupPath = `${currentPath}.backup-v${currentVersion}`;
+            if (!existsSync(backupPath)) {
+                // Flush WAL to main DB file before copying — without this, the backup
+                // may be missing committed data that only exists in the -wal file.
+                try {
+                    db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+                }
+                catch { /* checkpoint is best-effort */ }
+                copyFileSync(currentPath, backupPath);
+            }
+        }
+        catch (backupErr) {
+            // Log but proceed — blocking migration leaves the DB stuck at an old
+            // schema version permanently on read-only or full filesystems.
+            logWarning("db", `Pre-migration backup failed: ${backupErr instanceof Error ? backupErr.message : String(backupErr)}`);
+        }
+    }
     db.exec("BEGIN");
     try {
         if (currentVersion < 2) {
@@ -937,8 +959,20 @@ export function _resetProvider() {
 export function upsertDecision(d) {
     if (!currentDb)
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
-    currentDb.prepare(`INSERT OR REPLACE INTO decisions (id, when_context, scope, decision, choice, rationale, revisable, made_by, superseded_by)
-     VALUES (:id, :when_context, :scope, :decision, :choice, :rationale, :revisable, :made_by, :superseded_by)`).run({
+    // Use ON CONFLICT DO UPDATE instead of INSERT OR REPLACE to preserve the
+    // seq column. INSERT OR REPLACE deletes then reinserts, resetting seq and
+    // corrupting decision ordering in DECISIONS.md after reconcile replay.
+    currentDb.prepare(`INSERT INTO decisions (id, when_context, scope, decision, choice, rationale, revisable, made_by, superseded_by)
+     VALUES (:id, :when_context, :scope, :decision, :choice, :rationale, :revisable, :made_by, :superseded_by)
+     ON CONFLICT(id) DO UPDATE SET
+       when_context = excluded.when_context,
+       scope = excluded.scope,
+       decision = excluded.decision,
+       choice = excluded.choice,
+       rationale = excluded.rationale,
+       revisable = excluded.revisable,
+       made_by = excluded.made_by,
+       superseded_by = excluded.superseded_by`).run({
         ":id": d.id,
         ":when_context": d.when_context,
         ":scope": d.scope,

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

@@ -1,4 +1,4 @@
-export { isDepthVerified, isQueuePhaseActive, setQueuePhaseActive, shouldBlockContextWrite, shouldBlockQueueExecution, } from "./bootstrap/write-gate.js";
+export { isDepthConfirmationAnswer, isDepthVerified, isQueuePhaseActive, setQueuePhaseActive, shouldBlockContextWrite, shouldBlockQueueExecution, } from "./bootstrap/write-gate.js";
 export default async function registerExtension(pi) {
     const { registerGsdExtension } = await import("./bootstrap/register-extension.js");
     registerGsdExtension(pi);

package/dist/resources/extensions/gsd/notification-overlay.js

@@ -1,6 +1,6 @@
 // GSD Extension — Notification History Overlay
 // Scrollable panel showing all persisted notifications with severity filtering.
-// Toggled with Ctrl+Alt+N or opened from /gsd notifications.
+// Toggled with Ctrl+Alt+N (⌃⌥N on macOS) or opened from /gsd notifications.
 import { truncateToWidth, visibleWidth, matchesKey, Key } from "@gsd/pi-tui";
 import { readNotifications, markAllRead, clearNotifications, } from "./notification-store.js";
 import { padRight, joinColumns } from "../shared/mod.js";

package/dist/resources/extensions/gsd/notification-widget.js

@@ -3,6 +3,7 @@
 // the most recent notification message. Refreshes every 5 seconds.
 // Widget key: "gsd-notifications", placement: "belowEditor"
 import { getUnreadCount, readNotifications } from "./notification-store.js";
+import { formatShortcut } from "./files.js";
 // ─── Pure rendering ──���────────────────────────���─────────────────────────
 export function buildNotificationWidgetLines() {
     const unread = getUnreadCount();
@@ -18,7 +19,7 @@ export function buildNotificationWidgetLines() {
     const truncated = latest.message.length > msgMax
         ? latest.message.slice(0, msgMax - 1) + "…"
         : latest.message;
-    return [`  ${icon} [${badge}]  ${truncated}  (Ctrl+Alt+N to view)`];
+    return [`  ${icon} [${badge}]  ${truncated}  (${formatShortcut("Ctrl+Alt+N")} to view)`];
 }
 // ─── Widget init ────────────────────────────────────────────────────────
 const REFRESH_INTERVAL_MS = 5_000;

package/dist/resources/extensions/gsd/parallel-monitor-overlay.js

@@ -2,7 +2,7 @@
  * GSD Parallel Monitor Overlay
  *
  * Full-screen TUI overlay showing real-time parallel worker progress.
- * Opened via `/gsd parallel watch` or Ctrl+Alt+P.
+ * Opened via `/gsd parallel watch` or Ctrl+Alt+P (⌃⌥P on macOS).
  * Reads the same data sources as `scripts/parallel-monitor.mjs` but
  * renders as a native pi-tui overlay with theme integration.
  */

package/dist/resources/extensions/gsd/pre-execution-checks.js

@@ -197,8 +197,7 @@ export async function checkPackageExistence(tasks, _basePath) {
 export function normalizeFilePath(filePath) {
     if (!filePath)
         return filePath;
-    // Strip backtick wrapping from LLM-generated paths (#3649)
-    let normalized = filePath.replace(/`/g, "");
+    let normalized = extractPathFromAnnotation(filePath);
     // Normalize path separators to forward slashes
     normalized = normalized.replace(/\\/g, "/");
     // Remove leading ./
@@ -213,6 +212,21 @@ export function normalizeFilePath(filePath) {
     }
     return normalized;
 }
+function extractPathFromAnnotation(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return trimmed;
+    const backtickMatch = trimmed.match(/^`([^`]+)`(?:\s+[—–-]\s+.*)?$/);
+    if (backtickMatch) {
+        return backtickMatch[1].trim();
+    }
+    const annotatedMatch = trimmed.match(/^(.+?)\s+[—–-]\s+.+$/);
+    if (annotatedMatch) {
+        return annotatedMatch[1].trim();
+    }
+    // Fall back to the original behavior for already-plain paths.
+    return trimmed.replace(/`/g, "");
+}
 /**
  * Build a set of files that will be created by tasks up to (but not including) taskIndex.
  * All paths are normalized for consistent comparison.

package/dist/resources/extensions/gsd/prompts/discuss.md

@@ -114,6 +114,8 @@ If they clarify, absorb the correction and re-verify.
 
 The depth verification is the required write-gate. Do **not** add another meta "ready to proceed?" checkpoint immediately after it unless there is still material ambiguity.
 
+**CRITICAL — Non-bypassable gate:** The system mechanically blocks CONTEXT.md writes until the user selects the "(Recommended)" option. If the user declines, cancels, or the tool fails, you MUST re-ask — never rationalize past the block ("tool not responding, I'll proceed" is forbidden). The gate exists to protect the user's work; treat a block as an instruction, not an obstacle to work around.
+
 ## Wrap-up Gate
 
 Once the depth checklist is fully satisfied, move directly into requirements and roadmap preview. Do not insert a separate "are you ready to continue?" gate unless the user explicitly wants to keep brainstorming or you still see material ambiguity.

package/dist/resources/extensions/gsd/prompts/guided-discuss-milestone.md

@@ -100,6 +100,8 @@ If they clarify, absorb the correction and re-verify.
 
 The depth verification is the only required confirmation gate. Do not add a second "ready to proceed?" gate after it.
 
+**CRITICAL — Non-bypassable gate:** The system mechanically blocks CONTEXT.md writes until the user selects the "(Recommended)" option. If the user declines, cancels, or the tool fails, you MUST re-ask — never rationalize past the block ("tool not responding, I'll proceed" is forbidden). The gate exists to protect the user's work; treat a block as an instruction, not an obstacle to work around.
+
 ---
 
 ## Output

package/dist/resources/extensions/gsd/prompts/queue.md

@@ -103,6 +103,8 @@ The user confirms or corrects before you write. One depth verification per miles
 
 **If you skip this step, the system will block the CONTEXT.md write and return an error telling you to complete verification first.**
 
+**CRITICAL — Non-bypassable gate:** The system mechanically blocks CONTEXT.md writes until the user selects the "(Recommended)" option. If the user declines, cancels, or the tool fails, you MUST re-ask — never rationalize past the block ("tool not responding, I'll proceed" is forbidden). The gate exists to protect the user's work; treat a block as an instruction, not an obstacle to work around.
+
 ## Output Phase
 
 Once the user is satisfied, in a single pass for **each** new milestone:

package/dist/resources/extensions/gsd/prompts/system.md

@@ -131,8 +131,8 @@ Templates showing the expected format for each artifact type are in:
 - `/gsd status` - progress dashboard overlay
 - `/gsd queue` - queue future milestones (safe while auto-mode is running)
 - `/gsd quick <task>` - quick task with GSD guarantees (atomic commits, state tracking) but no milestone ceremony
-- `Ctrl+Alt+G` - toggle dashboard overlay
-- `Ctrl+Alt+B` - show shell processes
+- `{{shortcutDashboard}}` - toggle dashboard overlay
+- `{{shortcutShell}}` - show shell processes
 
 ## Execution Heuristics