gsd-pi 2.49.0-dev.de3d9f6 → 2.50.0-dev.9476db8

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

@@ -6,7 +6,8 @@
  * manages create, enter, detect, and teardown for auto-mode worktrees.
  */
 import { existsSync, cpSync, readFileSync, readdirSync, mkdirSync, realpathSync, rmSync, unlinkSync, lstatSync as lstatSyncFn, } from "node:fs";
-import { isAbsolute, join } from "node:path";
+import { isAbsolute, join, sep as pathSep } from "node:path";
+import { homedir } from "node:os";
 import { GSDError, GSD_IO_ERROR, GSD_GIT_ERROR } from "./errors.js";
 import { reconcileWorktreeDb, isDbAvailable, getMilestone, getMilestoneSlices, } from "./gsd-db.js";
 import { atomicWriteSync } from "./atomic-write.js";
@@ -20,6 +21,35 @@ import { debugLog } from "./debug-logger.js";
 import { logWarning } from "./workflow-logger.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { nativeGetCurrentBranch, nativeDetectMainBranch, nativeWorkingTreeStatus, nativeAddAllWithExclusions, nativeCommit, nativeCheckoutBranch, nativeMergeSquash, nativeConflictFiles, nativeCheckoutTheirs, nativeAddPaths, nativeRmForce, nativeBranchDelete, nativeBranchExists, nativeDiffNumstat, nativeUpdateRef, nativeIsAncestor, } from "./native-git-bridge.js";
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+// ─── Shared Constants & Helpers ─────────────────────────────────────────────
+/**
+ * Root-level .gsd/ state files synced between worktree and project root.
+ * Single source of truth — used by syncGsdStateToWorktree, syncWorktreeStateBack,
+ * and the dispatch-level sync functions.
+ */
+const ROOT_STATE_FILES = [
+    "DECISIONS.md",
+    "REQUIREMENTS.md",
+    "PROJECT.md",
+    "KNOWLEDGE.md",
+    "OVERRIDES.md",
+    "QUEUE.md",
+    "completed-units.json",
+    "metrics.json",
+];
+/**
+ * Check if two filesystem paths resolve to the same real location.
+ * Returns false if either path cannot be resolved (e.g. doesn't exist).
+ */
+function isSamePath(a, b) {
+    try {
+        return realpathSync(a) === realpathSync(b);
+    }
+    catch {
+        return false;
+    }
+}
 // ─── Module State ──────────────────────────────────────────────────────────
 /** Original project root before chdir into auto-worktree. */
 let originalBase = null;
@@ -70,6 +100,187 @@ function clearProjectRootStateFiles(basePath, milestoneId) {
         }
     }
 }
+// ─── Dispatch-Level Sync (project root ↔ worktree) ──────────────────────────
+/**
+ * Sync milestone artifacts from project root INTO worktree before deriveState.
+ * Covers the case where the LLM wrote artifacts to the main repo filesystem
+ * (e.g. via absolute paths) but the worktree has stale data. Also deletes
+ * gsd.db in the worktree so it rebuilds from fresh disk state (#853).
+ * Non-fatal — sync failure should never block dispatch.
+ */
+export function syncProjectRootToWorktree(projectRoot, worktreePath_, milestoneId) {
+    if (!worktreePath_ || !projectRoot || worktreePath_ === projectRoot)
+        return;
+    if (!milestoneId)
+        return;
+    const prGsd = join(projectRoot, ".gsd");
+    const wtGsd = join(worktreePath_, ".gsd");
+    // Copy milestone directory from project root to worktree — additive only.
+    // force:false prevents cpSync from overwriting existing worktree files.
+    // Without this, worktree-authoritative files (e.g. VALIDATION.md written
+    // by validate-milestone) get clobbered by stale project root copies,
+    // causing an infinite re-validation loop (#1886).
+    safeCopyRecursive(join(prGsd, "milestones", milestoneId), join(wtGsd, "milestones", milestoneId), { force: false });
+    // Forward-sync completed-units.json from project root to worktree.
+    // Project root is authoritative for completion state after crash recovery;
+    // without this, the worktree re-dispatches already-completed units (#1886).
+    safeCopy(join(prGsd, "completed-units.json"), join(wtGsd, "completed-units.json"), { force: true });
+    // Delete worktree gsd.db so it rebuilds from the freshly synced files.
+    // Stale DB rows are the root cause of the infinite skip loop (#853).
+    try {
+        const wtDb = join(wtGsd, "gsd.db");
+        if (existsSync(wtDb)) {
+            unlinkSync(wtDb);
+        }
+    }
+    catch {
+        /* non-fatal */
+    }
+}
+/**
+ * Sync dispatch-critical .gsd/ state files from worktree to project root.
+ * Only runs when inside an auto-worktree (worktreePath differs from projectRoot).
+ * Copies: STATE.md + active milestone directory (roadmap, slice plans, task summaries).
+ * Non-fatal — sync failure should never block dispatch.
+ */
+export function syncStateToProjectRoot(worktreePath_, projectRoot, milestoneId) {
+    if (!worktreePath_ || !projectRoot || worktreePath_ === projectRoot)
+        return;
+    if (!milestoneId)
+        return;
+    const wtGsd = join(worktreePath_, ".gsd");
+    const prGsd = join(projectRoot, ".gsd");
+    // 1. STATE.md — the quick-glance status used by initial deriveState()
+    safeCopy(join(wtGsd, "STATE.md"), join(prGsd, "STATE.md"), { force: true });
+    // 2. Milestone directory — ROADMAP, slice PLANs, task summaries
+    // Copy the entire milestone .gsd subtree so deriveState reads current checkboxes
+    safeCopyRecursive(join(wtGsd, "milestones", milestoneId), join(prGsd, "milestones", milestoneId), { force: true });
+    // 3. metrics.json — session cost/token tracking (#2313).
+    // Without this, metrics accumulated in the worktree are invisible from the
+    // project root and never appear in the dashboard or skill-health reports.
+    safeCopy(join(wtGsd, "metrics.json"), join(prGsd, "metrics.json"), { force: true });
+    // 4. Runtime records — unit dispatch state used by selfHealRuntimeRecords().
+    // Without this, a crash during a unit leaves the runtime record only in the
+    // worktree. If the next session resolves basePath before worktree re-entry,
+    // selfHeal can't find or clear the stale record (#769).
+    safeCopyRecursive(join(wtGsd, "runtime", "units"), join(prGsd, "runtime", "units"), { force: true });
+}
+// ─── Resource Staleness ───────────────────────────────────────────────────
+/**
+ * Read the resource version (semver) from the managed-resources manifest.
+ * Uses gsdVersion instead of syncedAt so that launching a second session
+ * doesn't falsely trigger staleness (#804).
+ */
+export function readResourceVersion() {
+    const agentDir = process.env.GSD_CODING_AGENT_DIR || join(gsdHome, "agent");
+    const manifestPath = join(agentDir, "managed-resources.json");
+    try {
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+        return typeof manifest?.gsdVersion === "string"
+            ? manifest.gsdVersion
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if managed resources have been updated since session start.
+ * Returns a warning message if stale, null otherwise.
+ */
+export function checkResourcesStale(versionOnStart) {
+    if (versionOnStart === null)
+        return null;
+    const current = readResourceVersion();
+    if (current === null)
+        return null;
+    if (current !== versionOnStart) {
+        return "GSD resources were updated since this session started. Restart gsd to load the new code.";
+    }
+    return null;
+}
+// ─── Stale Worktree Escape ────────────────────────────────────────────────
+/**
+ * Detect and escape a stale worktree cwd (#608).
+ *
+ * After milestone completion + merge, the worktree directory is removed but
+ * the process cwd may still point inside `.gsd/worktrees/<MID>/`.
+ * When a new session starts, `process.cwd()` is passed as `base` to startAuto
+ * and all subsequent writes land in the wrong directory. This function detects
+ * that scenario and chdir back to the project root.
+ *
+ * Returns the corrected base path.
+ */
+export function escapeStaleWorktree(base) {
+    // Direct layout: /.gsd/worktrees/
+    const directMarker = `${pathSep}.gsd${pathSep}worktrees${pathSep}`;
+    let idx = base.indexOf(directMarker);
+    if (idx === -1) {
+        // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/
+        const symlinkRe = new RegExp(`\\${pathSep}\\.gsd\\${pathSep}projects\\${pathSep}[a-f0-9]+\\${pathSep}worktrees\\${pathSep}`);
+        const match = base.match(symlinkRe);
+        if (!match || match.index === undefined)
+            return base;
+        idx = match.index;
+    }
+    // base is inside .gsd/worktrees/<something> — extract the project root
+    const projectRoot = base.slice(0, idx);
+    // Guard: If the candidate project root's .gsd IS the user-level ~/.gsd,
+    // the string-slice heuristic matched the wrong /.gsd/ boundary. This happens
+    // when .gsd is a symlink into ~/.gsd/projects/<hash> and process.cwd()
+    // resolved through the symlink. Returning ~ would be catastrophic (#1676).
+    const candidateGsd = join(projectRoot, ".gsd").replaceAll("\\", "/");
+    const gsdHomePath = gsdHome.replaceAll("\\", "/");
+    if (candidateGsd === gsdHomePath || candidateGsd.startsWith(gsdHomePath + "/")) {
+        // Don't chdir to home — return base unchanged.
+        // resolveProjectRoot() in worktree.ts has the full git-file-based recovery
+        // and will be called by the caller (startAuto → projectRoot()).
+        return base;
+    }
+    try {
+        process.chdir(projectRoot);
+    }
+    catch {
+        // If chdir fails, return the original — caller will handle errors downstream
+        return base;
+    }
+    return projectRoot;
+}
+/**
+ * Clean stale runtime unit files for completed milestones.
+ *
+ * After restart, stale runtime/units/*.json from prior milestones can
+ * cause deriveState to resume the wrong milestone (#887). Removes files
+ * for milestones that have a SUMMARY (fully complete).
+ */
+export function cleanStaleRuntimeUnits(gsdRootPath, hasMilestoneSummary) {
+    const runtimeUnitsDir = join(gsdRootPath, "runtime", "units");
+    if (!existsSync(runtimeUnitsDir))
+        return 0;
+    let cleaned = 0;
+    try {
+        for (const file of readdirSync(runtimeUnitsDir)) {
+            if (!file.endsWith(".json"))
+                continue;
+            const midMatch = file.match(/(M\d+(?:-[a-z0-9]{6})?)/);
+            if (!midMatch)
+                continue;
+            if (hasMilestoneSummary(midMatch[1])) {
+                try {
+                    unlinkSync(join(runtimeUnitsDir, file));
+                    cleaned++;
+                }
+                catch {
+                    /* non-fatal */
+                }
+            }
+        }
+    }
+    catch {
+        /* non-fatal */
+    }
+    return cleaned;
+}
 // ─── Worktree ↔ Main Repo Sync (#1311) ──────────────────────────────────────
 /**
  * Sync .gsd/ state from the main repo into the worktree.
@@ -90,29 +301,12 @@ export function syncGsdStateToWorktree(mainBasePath, worktreePath_) {
     const wtGsd = gsdRoot(worktreePath_);
     const synced = [];
     // If both resolve to the same directory (symlink), no sync needed
-    try {
-        const mainResolved = realpathSync(mainGsd);
-        const wtResolved = realpathSync(wtGsd);
-        if (mainResolved === wtResolved)
-            return { synced };
-    }
-    catch {
-        // Can't resolve — proceed with sync as a safety measure
-    }
+    if (isSamePath(mainGsd, wtGsd))
+        return { synced };
     if (!existsSync(mainGsd) || !existsSync(wtGsd))
         return { synced };
     // Sync root-level .gsd/ files (DECISIONS, REQUIREMENTS, PROJECT, KNOWLEDGE, etc.)
-    const rootFiles = [
-        "DECISIONS.md",
-        "REQUIREMENTS.md",
-        "PROJECT.md",
-        "KNOWLEDGE.md",
-        "OVERRIDES.md",
-        "QUEUE.md",
-        "completed-units.json",
-        "metrics.json",
-    ];
-    for (const f of rootFiles) {
+    for (const f of ROOT_STATE_FILES) {
         const src = join(mainGsd, f);
         const dst = join(wtGsd, f);
         if (existsSync(src) && !existsSync(dst)) {
@@ -241,15 +435,8 @@ export function syncWorktreeStateBack(mainBasePath, worktreePath, milestoneId) {
     const wtGsd = gsdRoot(worktreePath);
     const synced = [];
     // If both resolve to the same directory (symlink), no sync needed
-    try {
-        const mainResolved = realpathSync(mainGsd);
-        const wtResolved = realpathSync(wtGsd);
-        if (mainResolved === wtResolved)
-            return { synced };
-    }
-    catch {
-        // Can't resolve — proceed with sync
-    }
+    if (isSamePath(mainGsd, wtGsd))
+        return { synced };
     if (!existsSync(wtGsd) || !existsSync(mainGsd))
         return { synced };
     // ── 0. Pre-upgrade worktree DB reconciliation ────────────────────────
@@ -274,17 +461,7 @@ export function syncWorktreeStateBack(mainBasePath, worktreePath, milestoneId) {
     // Also includes QUEUE.md, completed-units.json, and metrics.json which are
     // written during milestone closeout and lost on teardown without explicit sync
     // (#1787, #2313).
-    const rootFiles = [
-        "DECISIONS.md",
-        "REQUIREMENTS.md",
-        "PROJECT.md",
-        "KNOWLEDGE.md",
-        "OVERRIDES.md",
-        "QUEUE.md",
-        "completed-units.json",
-        "metrics.json",
-    ];
-    for (const f of rootFiles) {
+    for (const f of ROOT_STATE_FILES) {
         const src = join(wtGsd, f);
         const dst = join(mainGsd, f);
         if (existsSync(src)) {
@@ -321,92 +498,59 @@ export function syncWorktreeStateBack(mainBasePath, worktreePath, milestoneId) {
  * Sync a single milestone directory from worktree to main.
  * Copies milestone-level .md files, slice-level files, and task summaries.
  */
+/** Copy matching files from srcDir to dstDir (non-fatal per file). */
+function syncDirFiles(srcDir, dstDir, filter, synced, prefix) {
+    try {
+        for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+            if (!entry.isFile() || !filter(entry.name))
+                continue;
+            try {
+                cpSync(join(srcDir, entry.name), join(dstDir, entry.name), { force: true });
+                synced.push(`${prefix}${entry.name}`);
+            }
+            catch {
+                /* non-fatal */
+            }
+        }
+    }
+    catch {
+        /* non-fatal — srcDir may not be readable */
+    }
+}
 function syncMilestoneDir(wtGsd, mainGsd, mid, synced) {
     const wtMilestoneDir = join(wtGsd, "milestones", mid);
     const mainMilestoneDir = join(mainGsd, "milestones", mid);
     if (!existsSync(wtMilestoneDir))
         return;
     mkdirSync(mainMilestoneDir, { recursive: true });
+    const isMd = (name) => name.endsWith(".md");
     // Sync milestone-level files (SUMMARY, VALIDATION, ROADMAP, CONTEXT)
+    syncDirFiles(wtMilestoneDir, mainMilestoneDir, isMd, synced, `milestones/${mid}/`);
+    // Sync slice-level files (summaries, UATs) and task summaries (#1678)
+    const wtSlicesDir = join(wtMilestoneDir, "slices");
+    const mainSlicesDir = join(mainMilestoneDir, "slices");
+    if (!existsSync(wtSlicesDir))
+        return;
     try {
-        for (const entry of readdirSync(wtMilestoneDir, { withFileTypes: true })) {
-            if (entry.isFile() && entry.name.endsWith(".md")) {
-                const src = join(wtMilestoneDir, entry.name);
-                const dst = join(mainMilestoneDir, entry.name);
-                try {
-                    cpSync(src, dst, { force: true });
-                    synced.push(`milestones/${mid}/${entry.name}`);
-                }
-                catch {
-                    /* non-fatal */
-                }
+        for (const sliceEntry of readdirSync(wtSlicesDir, { withFileTypes: true })) {
+            if (!sliceEntry.isDirectory())
+                continue;
+            const sid = sliceEntry.name;
+            const wtSliceDir = join(wtSlicesDir, sid);
+            const mainSliceDir = join(mainSlicesDir, sid);
+            mkdirSync(mainSliceDir, { recursive: true });
+            syncDirFiles(wtSliceDir, mainSliceDir, isMd, synced, `milestones/${mid}/slices/${sid}/`);
+            const wtTasksDir = join(wtSliceDir, "tasks");
+            const mainTasksDir = join(mainSliceDir, "tasks");
+            if (existsSync(wtTasksDir)) {
+                mkdirSync(mainTasksDir, { recursive: true });
+                syncDirFiles(wtTasksDir, mainTasksDir, isMd, synced, `milestones/${mid}/slices/${sid}/tasks/`);
             }
         }
     }
     catch {
         /* non-fatal */
     }
-    // Sync slice-level files (summaries, UATs)
-    const wtSlicesDir = join(wtMilestoneDir, "slices");
-    const mainSlicesDir = join(mainMilestoneDir, "slices");
-    if (existsSync(wtSlicesDir)) {
-        try {
-            for (const sliceEntry of readdirSync(wtSlicesDir, {
-                withFileTypes: true,
-            })) {
-                if (!sliceEntry.isDirectory())
-                    continue;
-                const sid = sliceEntry.name;
-                const wtSliceDir = join(wtSlicesDir, sid);
-                const mainSliceDir = join(mainSlicesDir, sid);
-                mkdirSync(mainSliceDir, { recursive: true });
-                for (const fileEntry of readdirSync(wtSliceDir, {
-                    withFileTypes: true,
-                })) {
-                    if (fileEntry.isFile() && fileEntry.name.endsWith(".md")) {
-                        const src = join(wtSliceDir, fileEntry.name);
-                        const dst = join(mainSliceDir, fileEntry.name);
-                        try {
-                            cpSync(src, dst, { force: true });
-                            synced.push(`milestones/${mid}/slices/${sid}/${fileEntry.name}`);
-                        }
-                        catch {
-                            /* non-fatal */
-                        }
-                    }
-                    else if (fileEntry.isDirectory() && fileEntry.name === "tasks") {
-                        // Recurse into tasks/ subdirectory to sync task summaries (#1678).
-                        // Without this, T01-SUMMARY.md etc. are silently dropped on
-                        // worktree teardown because the loop only processes isFile() entries.
-                        const wtTasksDir = join(wtSliceDir, "tasks");
-                        const mainTasksDir = join(mainSliceDir, "tasks");
-                        mkdirSync(mainTasksDir, { recursive: true });
-                        try {
-                            for (const taskEntry of readdirSync(wtTasksDir, { withFileTypes: true })) {
-                                if (taskEntry.isFile() && taskEntry.name.endsWith(".md")) {
-                                    const taskSrc = join(wtTasksDir, taskEntry.name);
-                                    const taskDst = join(mainTasksDir, taskEntry.name);
-                                    try {
-                                        cpSync(taskSrc, taskDst, { force: true });
-                                        synced.push(`milestones/${mid}/slices/${sid}/tasks/${taskEntry.name}`);
-                                    }
-                                    catch {
-                                        /* non-fatal */
-                                    }
-                                }
-                            }
-                        }
-                        catch {
-                            /* non-fatal: tasks dir read failure */
-                        }
-                    }
-                }
-            }
-        }
-        catch {
-            /* non-fatal */
-        }
-    }
 }
 // ─── Worktree Post-Create Hook (#597) ────────────────────────────────────────
 /**

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

@@ -16,7 +16,7 @@ import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
 import { gsdRoot, resolveMilestoneFile, resolveMilestonePath, resolveDir, milestonesDir, } from "./paths.js";
 import { invalidateAllCaches } from "./cache.js";
 import { clearActivityLogState } from "./activity-log.js";
-import { synthesizeCrashRecovery, getDeepDiagnostic, } from "./session-forensics.js";
+import { synthesizeCrashRecovery, getDeepDiagnostic, readActiveMilestoneId, } from "./session-forensics.js";
 import { writeLock, clearLock, readCrashLock, isLockProcessAlive, } from "./crash-recovery.js";
 import { acquireSessionLock, getSessionLockStatus, releaseSessionLock, updateSessionLock, } from "./session-lock.js";
 import { resolveAutoSupervisorConfig, loadEffectiveGSDPreferences, getIsolationMode, } from "./preferences.js";
@@ -25,7 +25,6 @@ import { getBudgetAlertLevel, getNewBudgetAlertLevel, getBudgetEnforcementAction
 import { markToolStart as _markToolStart, markToolEnd as _markToolEnd, getOldestInFlightToolAgeMs as _getOldestInFlightToolAgeMs, clearInFlightTools, } from "./auto-tool-tracking.js";
 import { closeoutUnit } from "./auto-unit-closeout.js";
 import { selectAndApplyModel, resolveModelId } from "./auto-model-selection.js";
-import { syncProjectRootToWorktree, checkResourcesStale, escapeStaleWorktree, } from "./auto-worktree-sync.js";
 import { resetRoutingHistory, recordOutcome } from "./routing-history.js";
 import { resetHookState, runPreDispatchHooks, restoreHookState, clearPersistedHookState, } from "./post-unit-hooks.js";
 import { runGSDDoctor, rebuildState } from "./doctor.js";
@@ -39,7 +38,7 @@ import { atomicWriteSync } from "./atomic-write.js";
 import { autoCommitCurrentBranch, captureIntegrationBranch, detectWorktreeName, getCurrentBranch, getMainBranch, setActiveMilestoneId, } from "./worktree.js";
 import { GitServiceImpl } from "./git-service.js";
 import { getPriorSliceCompletionBlocker } from "./dispatch-guard.js";
-import { createAutoWorktree, enterAutoWorktree, teardownAutoWorktree, isInAutoWorktree, getAutoWorktreePath, mergeMilestoneToMain, autoWorktreeBranch, syncWorktreeStateBack, } from "./auto-worktree.js";
+import { createAutoWorktree, enterAutoWorktree, teardownAutoWorktree, isInAutoWorktree, getAutoWorktreePath, mergeMilestoneToMain, autoWorktreeBranch, syncWorktreeStateBack, syncProjectRootToWorktree, checkResourcesStale, escapeStaleWorktree, } from "./auto-worktree.js";
 import { pruneQueueOrder } from "./queue-order.js";
 import { debugLog, isDebugEnabled, writeDebugSummary } from "./debug-logger.js";
 import { reconcileMergeState, } from "./auto-recovery.js";
@@ -59,7 +58,6 @@ import { bootstrapAutoSession } from "./auto-start.js";
 import { autoLoop, resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight } from "./auto-loop.js";
 import { WorktreeResolver, } from "./worktree-resolver.js";
 import { reorderForCaching } from "./prompt-ordering.js";
-// Worktree sync, resource staleness, stale worktree escape → auto-worktree-sync.ts
 // ─── Session State ─────────────────────────────────────────────────────────
 import { AutoSession, } from "./auto/session.js";
 export { MAX_UNIT_DISPATCHES, STUB_RECOVERY_THRESHOLD, MAX_LIFETIME_DISPATCHES, NEW_SESSION_TIMEOUT_MS, } from "./auto/session.js";
@@ -706,7 +704,11 @@ function buildLoopDeps() {
         resolveModelId,
         startUnitSupervision,
         // Prompt helpers
-        getDeepDiagnostic,
+        getDeepDiagnostic: (basePath) => {
+            const mid = readActiveMilestoneId(basePath);
+            const wtPath = mid ? getAutoWorktreePath(basePath, mid) : undefined;
+            return getDeepDiagnostic(basePath, wtPath ?? undefined);
+        },
         isDbAvailable,
         reorderForCaching,
         // Filesystem

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

@@ -1042,4 +1042,93 @@ export function registerDbTools(pi) {
     };
     pi.registerTool(reassessRoadmapTool);
     registerAlias(pi, reassessRoadmapTool, "gsd_roadmap_reassess", "gsd_reassess_roadmap");
+    // ─── gsd_save_gate_result ──────────────────────────────────────────────
+    const saveGateResultExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const dbAvailable = await ensureDbOpen();
+        if (!dbAvailable) {
+            return {
+                content: [{ type: "text", text: "Error: GSD database is not available." }],
+                details: { operation: "save_gate_result", error: "db_unavailable" },
+            };
+        }
+        const validGates = ["Q3", "Q4", "Q5", "Q6", "Q7", "Q8"];
+        if (!validGates.includes(params.gateId)) {
+            return {
+                content: [{ type: "text", text: `Error: Invalid gateId "${params.gateId}". Must be one of: ${validGates.join(", ")}` }],
+                details: { operation: "save_gate_result", error: "invalid_gate_id" },
+            };
+        }
+        const validVerdicts = ["pass", "flag", "omitted"];
+        if (!validVerdicts.includes(params.verdict)) {
+            return {
+                content: [{ type: "text", text: `Error: Invalid verdict "${params.verdict}". Must be one of: ${validVerdicts.join(", ")}` }],
+                details: { operation: "save_gate_result", error: "invalid_verdict" },
+            };
+        }
+        try {
+            const { saveGateResult } = await import("../gsd-db.js");
+            const { invalidateStateCache } = await import("../state.js");
+            saveGateResult({
+                milestoneId: params.milestoneId,
+                sliceId: params.sliceId,
+                gateId: params.gateId,
+                taskId: params.taskId ?? "",
+                verdict: params.verdict,
+                rationale: params.rationale,
+                findings: params.findings ?? "",
+            });
+            invalidateStateCache();
+            return {
+                content: [{ type: "text", text: `Gate ${params.gateId} result saved: verdict=${params.verdict}` }],
+                details: { operation: "save_gate_result", gateId: params.gateId, verdict: params.verdict },
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logError("tool", `gsd_save_gate_result failed: ${msg}`, { tool: "gsd_save_gate_result", error: String(err) });
+            return {
+                content: [{ type: "text", text: `Error saving gate result: ${msg}` }],
+                details: { operation: "save_gate_result", error: msg },
+            };
+        }
+    };
+    const saveGateResultTool = {
+        name: "gsd_save_gate_result",
+        label: "Save Gate Result",
+        description: "Save the result of a quality gate evaluation (Q3-Q8) to the GSD database. " +
+            "Called by gate evaluation sub-agents after analyzing a specific quality question.",
+        promptSnippet: "Save quality gate evaluation result (verdict, rationale, findings)",
+        promptGuidelines: [
+            "Use gsd_save_gate_result after evaluating a quality gate question.",
+            "gateId must be one of: Q3, Q4, Q5, Q6, Q7, Q8.",
+            "verdict must be: pass (no concerns), flag (concerns found), or omitted (not applicable).",
+            "rationale should be a one-sentence justification for the verdict.",
+            "findings should contain detailed markdown analysis (or empty string if omitted).",
+        ],
+        parameters: Type.Object({
+            milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
+            sliceId: Type.String({ description: "Slice ID (e.g. S01)" }),
+            gateId: Type.String({ description: "Gate ID: Q3, Q4, Q5, Q6, Q7, or Q8" }),
+            taskId: Type.Optional(Type.String({ description: "Task ID for task-scoped gates (Q5/Q6/Q7)" })),
+            verdict: Type.String({ description: "pass, flag, or omitted" }),
+            rationale: Type.String({ description: "One-sentence justification" }),
+            findings: Type.Optional(Type.String({ description: "Detailed markdown findings" })),
+        }),
+        execute: saveGateResultExecute,
+        renderCall(args, theme) {
+            let text = theme.fg("toolTitle", theme.bold("save_gate_result "));
+            text += theme.fg("accent", args.gateId ?? "");
+            text += theme.fg("dim", ` → ${args.verdict ?? ""}`);
+            return new Text(text, 0, 0);
+        },
+        renderResult(result, _options, theme) {
+            const d = result.details;
+            if (result.isError || d?.error) {
+                return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
+            }
+            const color = d?.verdict === "flag" ? "warning" : "success";
+            return new Text(theme.fg(color, `${d?.gateId}: ${d?.verdict}`), 0, 0);
+        },
+    };
+    pi.registerTool(saveGateResultTool);
 }

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 { isDepthVerified, isQueuePhaseActive, markDepthVerified, resetWriteGateState, shouldBlockContextWrite } from "./write-gate.js";
+import { clearDiscussionFlowState, isDepthVerified, isQueuePhaseActive, markDepthVerified, resetWriteGateState, shouldBlockContextWrite } from "./write-gate.js";
 import { isBlockedStateFile, isBashWriteToStateFile, BLOCKED_WRITE_ERROR } from "../write-intercept.js";
 import { getDiscussionMilestoneId } from "../guided-flow.js";
 import { loadToolApiKeys } from "../commands-config.js";
@@ -63,6 +63,13 @@ export function registerHooks(pi) {
             // ignore
         }
     });
+    pi.on("session_switch", async (_event, ctx) => {
+        resetWriteGateState();
+        resetToolCallLoopGuard();
+        clearDiscussionFlowState();
+        await syncServiceTierStatus(ctx);
+        loadToolApiKeys();
+    });
     pi.on("before_agent_start", async (event, ctx) => {
         return buildBeforeAgentStartResult(event, ctx);
     });

package/dist/resources/extensions/gsd/branch-patterns.js

@@ -0,0 +1,13 @@
+/**
+ * GSD branch naming patterns — single source of truth.
+ *
+ * gsd/<worktree>/<milestone>/<slice>  → SLICE_BRANCH_RE
+ * gsd/quick/<id>-<slug>               → QUICK_BRANCH_RE
+ * gsd/<workflow>/<...>                 → WORKFLOW_BRANCH_RE (non-milestone gsd/ branches)
+ */
+/** Matches gsd/ slice branches: gsd/[worktree/]M001[-hash]/S01 */
+export const SLICE_BRANCH_RE = /^gsd\/(?:([a-zA-Z0-9_-]+)\/)?(M\d+(?:-[a-z0-9]{6})?)\/(S\d+)$/;
+/** Matches gsd/quick/ task branches */
+export const QUICK_BRANCH_RE = /^gsd\/quick\//;
+/** Matches gsd/ workflow branches (non-milestone, e.g. gsd/workflow-name/...) */
+export const WORKFLOW_BRANCH_RE = /^gsd\/(?!M\d)[\w-]+\//;