gsd-pi 2.80.0-dev.2be7caf18 → 2.80.0-dev.3065f7bfa

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

@@ -23,6 +23,7 @@
 // excluded from this invariant.
 
 import { createRequire } from "node:module";
+import { createHash } from "node:crypto";
 import { existsSync, copyFileSync, mkdirSync, realpathSync } from "node:fs";
 import { dirname } from "node:path";
 import type { Decision, Requirement, GateRow, GateId, GateScope, GateStatus, GateVerdict } from "./types.js";
@@ -78,6 +79,8 @@ import {
   applyMigrationV22QualityGateRepair,
   applyMigrationV23MilestoneQueue,
   applyMigrationV26MilestoneCommitAttributions,
+  applyMigrationV27ArtifactHash,
+  applyMigrationV28MemoryLastHitAt,
 } from "./db-migration-steps.js";
 import { isMemoriesFtsAvailableSchema, tryCreateMemoriesFtsSchema } from "./db-memory-fts-schema.js";
 import { createDbOpenState, type DbOpenPhase } from "./db-open-state.js";
@@ -106,7 +109,7 @@ const providerLoader = createSqliteProviderLoader({
   writeStderr: (message: string) => process.stderr.write(message),
 });
 
-export const SCHEMA_VERSION = 26;
+export const SCHEMA_VERSION = 28;
 
 function initSchema(db: DbAdapter, fileBacked: boolean): void {
   if (fileBacked) db.exec("PRAGMA journal_mode=WAL");
@@ -335,6 +338,16 @@ function migrateSchema(db: DbAdapter): void {
       recordSchemaVersion(db, 26);
     }
 
+    if (currentVersion < 27) {
+      applyMigrationV27ArtifactHash(db);
+      recordSchemaVersion(db, 27);
+    }
+
+    if (currentVersion < 28) {
+      applyMigrationV28MemoryLastHitAt(db);
+      recordSchemaVersion(db, 28);
+    }
+
     db.exec("COMMIT");
   } catch (err) {
     db.exec("ROLLBACK");
@@ -913,9 +926,10 @@ export function insertArtifact(a: {
   full_content: string;
 }): void {
   if (!currentDb) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+  const contentHash = createHash("sha256").update(a.full_content).digest("hex");
   currentDb.prepare(
-    `INSERT OR REPLACE INTO artifacts (path, artifact_type, milestone_id, slice_id, task_id, full_content, imported_at)
-     VALUES (:path, :artifact_type, :milestone_id, :slice_id, :task_id, :full_content, :imported_at)`,
+    `INSERT OR REPLACE INTO artifacts (path, artifact_type, milestone_id, slice_id, task_id, full_content, imported_at, content_hash)
+     VALUES (:path, :artifact_type, :milestone_id, :slice_id, :task_id, :full_content, :imported_at, :content_hash)`,
   ).run({
     ":path": a.path,
     ":artifact_type": a.artifact_type,
@@ -924,6 +938,7 @@ export function insertArtifact(a: {
     ":task_id": a.task_id,
     ":full_content": a.full_content,
     ":imported_at": new Date().toISOString(),
+    ":content_hash": contentHash,
   });
 }
 
@@ -1795,6 +1810,13 @@ export function reconcileWorktreeDb(
       const hasEscalationAwaiting = wtTaskInfo.some((col) => col["name"] === "escalation_awaiting_review");
       const hasEscalationArtifact = wtTaskInfo.some((col) => col["name"] === "escalation_artifact_path");
       const hasEscalationOverride = wtTaskInfo.some((col) => col["name"] === "escalation_override_applied_at");
+      const wtArtifactInfo = adapter.prepare("PRAGMA wt.table_info('artifacts')").all();
+      const hasArtifactContentHash = wtArtifactInfo.some((col) => col["name"] === "content_hash");
+      const wtMemoryInfo = adapter.prepare("PRAGMA wt.table_info('memories')").all();
+      const hasMemoryScope = wtMemoryInfo.some((col) => col["name"] === "scope");
+      const hasMemoryTags = wtMemoryInfo.some((col) => col["name"] === "tags");
+      const hasMemoryStructuredFields = wtMemoryInfo.some((col) => col["name"] === "structured_fields");
+      const hasMemoryLastHitAt = wtMemoryInfo.some((col) => col["name"] === "last_hit_at");
 
       const decConf = adapter.prepare(
         `SELECT m.id FROM decisions m INNER JOIN wt.decisions w ON m.id = w.id WHERE m.decision != w.decision OR m.choice != w.choice OR m.rationale != w.rationale OR ${
@@ -1842,12 +1864,17 @@ export function reconcileWorktreeDb(
           FROM wt.requirements
         `).run());
 
+        // V27: preserve content_hash. If the worktree predates V27 (no column),
+        // fall back to the main DB's existing hash so reconcile doesn't null
+        // out integrity fingerprints on artifacts that were unchanged in wt.
         merged.artifacts = countChanges(adapter.prepare(`
           INSERT OR REPLACE INTO artifacts (
-            path, artifact_type, milestone_id, slice_id, task_id, full_content, imported_at
+            path, artifact_type, milestone_id, slice_id, task_id, full_content, imported_at, content_hash
           )
-          SELECT path, artifact_type, milestone_id, slice_id, task_id, full_content, imported_at
-          FROM wt.artifacts
+          SELECT w.path, w.artifact_type, w.milestone_id, w.slice_id, w.task_id, w.full_content, w.imported_at,
+                 ${hasArtifactContentHash ? "w.content_hash" : "m.content_hash"}
+          FROM wt.artifacts w
+          LEFT JOIN artifacts m ON m.path = w.path
         `).run());
 
         // Merge milestones — worktree may have updated status/planning fields.
@@ -1949,15 +1976,25 @@ export function reconcileWorktreeDb(
           LEFT JOIN tasks m ON m.milestone_id = w.milestone_id AND m.slice_id = w.slice_id AND m.id = w.id
         `).run());
 
-        // Merge memories — keep worktree-learned insights
+        // Merge memories — keep worktree-learned insights.
+        // V18 (scope, tags), V21 (structured_fields), V28 (last_hit_at): for each
+        // column the wt may not yet have (older worktree DB), fall back to the
+        // main DB's existing value via LEFT JOIN so reconcile never silently
+        // resets these fields to defaults on rows that already had them.
         merged.memories = countChanges(adapter.prepare(`
           INSERT OR REPLACE INTO memories (
             seq, id, category, content, confidence, source_unit_type, source_unit_id,
-            created_at, updated_at, superseded_by, hit_count
+            created_at, updated_at, superseded_by, hit_count,
+            scope, tags, structured_fields, last_hit_at
           )
-          SELECT seq, id, category, content, confidence, source_unit_type, source_unit_id,
-                 created_at, updated_at, superseded_by, hit_count
-          FROM wt.memories
+          SELECT w.seq, w.id, w.category, w.content, w.confidence, w.source_unit_type, w.source_unit_id,
+                 w.created_at, w.updated_at, w.superseded_by, w.hit_count,
+                 ${hasMemoryScope ? "w.scope" : "COALESCE(m.scope, 'project')"},
+                 ${hasMemoryTags ? "w.tags" : "COALESCE(m.tags, '[]')"},
+                 ${hasMemoryStructuredFields ? "w.structured_fields" : "m.structured_fields"},
+                 ${hasMemoryLastHitAt ? "w.last_hit_at" : "m.last_hit_at"}
+          FROM wt.memories w
+          LEFT JOIN memories m ON m.id = w.id
         `).run());
 
         // Merge verification evidence — append-only, use INSERT OR IGNORE to avoid duplicates
@@ -3062,8 +3099,8 @@ export function updateMemoryContentRow(
 export function incrementMemoryHitCount(id: string, updatedAt: string): void {
   if (!currentDb) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
   currentDb.prepare(
-    "UPDATE memories SET hit_count = hit_count + 1, updated_at = :updated_at WHERE id = :id",
-  ).run({ ":updated_at": updatedAt, ":id": id });
+    "UPDATE memories SET hit_count = hit_count + 1, updated_at = :updated_at, last_hit_at = :last_hit_at WHERE id = :id",
+  ).run({ ":updated_at": updatedAt, ":last_hit_at": updatedAt, ":id": id });
 }
 
 export function supersedeMemoryRow(oldId: string, newId: string, updatedAt: string): void {

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

@@ -86,6 +86,36 @@ export {
 import { logWarning } from "./workflow-logger.js";
 import { deleteRuntimeKv } from "./db/runtime-kv.js";
 import { PAUSED_SESSION_KV_KEY } from "./interrupted-session.js";
+import { buildWorkflowDispatchContent } from "./workflow-protocol.js";
+import { isFullGsdToolSurfaceRequested, restoreGsdWorkflowTools, scopeGsdWorkflowToolsForDispatch } from "./bootstrap/register-hooks.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
@@ -446,7 +476,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 +509,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 +517,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 +723,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;
 }
 
@@ -1034,46 +1064,61 @@ async function dispatchWorkflow(
     }
   }
 
-  // Scope tools for discuss flows (#2949).
+  // Scope tools for guided workflow turns (#2949, token-consumption savings).
   // Providers with grammar-based constrained decoding (xAI/Grok) return
   // "Grammar is too complex" when the combined tool schema is too large.
-  // Discuss flows only need a small subset of GSD tools — strip the heavy
-  // planning/execution/completion tools to keep the grammar within limits.
-  let savedTools: string[] | null = null;
-  if (unitType?.startsWith("discuss-")) {
-    const currentTools = pi.getActiveTools();
-    savedTools = currentTools;
-    // Keep all non-GSD tools (builtins, other extensions) and only the
-    // GSD tools on the discuss allowlist.
-    const scopedTools = currentTools.filter(
-      (t) => !t.startsWith("gsd_") || DISCUSS_TOOLS_ALLOWLIST.includes(t),
-    );
-    pi.setActiveTools(scopedTools);
-    debugLog("discuss-tool-scoping", {
-      unitType,
-      before: currentTools.length,
-      after: scopedTools.length,
-      removed: currentTools.length - scopedTools.length,
-    });
-  }
+  // Guided workflow turns only need the active unit's tool surface; strip
+  // unrelated GSD tools and broad non-GSD tools for this queued turn, then
+  // restore so the narrowed surface does not leak into future dispatches.
+  let savedTools: ReturnType<typeof scopeGsdWorkflowToolsForDispatch> = null;
 
-  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
-  const workflow = readFileSync(workflowPath, "utf-8");
+  try {
+    const currentTools = pi.getActiveTools();
+    savedTools = {
+      tools: currentTools,
+      visibleSkills: typeof pi.getVisibleSkills === "function" ? pi.getVisibleSkills() : undefined,
+      restoreVisibleSkills: typeof pi.setVisibleSkills === "function",
+    };
+    if (unitType?.startsWith("discuss-") && !isFullGsdToolSurfaceRequested()) {
+      // Keep all non-GSD tools (builtins, other extensions) and only the
+      // GSD tools on the discuss allowlist.
+      const scopedTools = currentTools.filter(
+        (t) => !t.startsWith("gsd_") || DISCUSS_TOOLS_ALLOWLIST.includes(t),
+      );
+      pi.setActiveTools(scopedTools);
+      const scopedState = scopeGsdWorkflowToolsForDispatch(pi, unitType);
+      savedTools = {
+        tools: currentTools,
+        visibleSkills: scopedState?.visibleSkills ?? savedTools.visibleSkills,
+        restoreVisibleSkills: scopedState?.restoreVisibleSkills ?? savedTools.restoreVisibleSkills,
+      };
+      debugLog("discuss-tool-scoping", {
+        unitType,
+        before: currentTools.length,
+        after: pi.getActiveTools().length,
+        removed: currentTools.length - pi.getActiveTools().length,
+      });
+    } else {
+      savedTools = scopeGsdWorkflowToolsForDispatch(pi, unitType) ?? savedTools;
+    }
 
-  pi.sendMessage(
-    {
-      customType,
-      content: `Read the following GSD workflow protocol and execute exactly.\n\n${workflow}\n\n## Your Task\n\n${note}`,
-      display: false,
-    },
-    { triggerTurn: true },
-  );
+    const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
+    const workflow = readFileSync(workflowPath, "utf-8");
 
-  // Restore full tool set after the message is queued. The LLM turn has
-  // already captured the scoped set — restoring prevents the narrowed
-  // tools from leaking into subsequent dispatches (#3628).
-  if (savedTools) {
-    pi.setActiveTools(savedTools);
+    pi.sendMessage(
+      {
+        customType,
+        content: buildWorkflowDispatchContent({ workflow, workflowPath, task: note }),
+        display: false,
+      },
+      { triggerTurn: true },
+    );
+  } finally {
+    // Restore full tool set after the message is queued. The LLM turn has
+    // already captured the scoped set — restoring prevents the narrowed
+    // tools from leaking into subsequent dispatches (#3628). The finally
+    // block ensures restoration even if sendMessage throws.
+    restoreGsdWorkflowTools(pi, savedTools);
   }
 }
 

package/src/resources/extensions/gsd/memory-store.ts

@@ -44,6 +44,8 @@ export interface Memory {
    * decisions table (Step 5) with the original scope/decision/choice/etc.
    */
   structured_fields: Record<string, unknown> | null;
+  /** ISO timestamp of the most recent memory_query hit. NULL until first hit. */
+  last_hit_at: string | null;
 }
 
 export type MemoryActionCreate = {
@@ -100,6 +102,27 @@ const CATEGORY_PRIORITY: Record<string, number> = {
   preference: 5,
 };
 
+// ─── Scoring Helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Time-decay factor for memory relevance scoring.
+ * Returns 1.0 for never-hit or recently-hit memories, decaying linearly to
+ * 0.7 for memories not accessed in 90+ days. Floor at 0.7 keeps old-but-valid
+ * knowledge from being fully suppressed.
+ *
+ * Defensive parsing: invalid timestamp strings (NaN from Date.parse) are
+ * treated as "no decay" rather than propagating NaN into score arithmetic.
+ * Future timestamps (clock skew, manual DB edits) clamp to daysAgo=0 so the
+ * factor stays in the documented [0.7, 1.0] contract.
+ */
+export function memoryDecayFactor(lastHitAt: string | null): number {
+  if (!lastHitAt) return 1.0;
+  const ts = Date.parse(lastHitAt);
+  if (!Number.isFinite(ts)) return 1.0;
+  const daysAgo = Math.max(0, (Date.now() - ts) / 86_400_000);
+  return Math.max(0.7, 1.0 - 0.3 * Math.min(1.0, daysAgo / 90));
+}
+
 // ─── Row Mapping ────────────────────────────────────────────────────────────
 
 function rowToMemory(row: Record<string, unknown>): Memory {
@@ -118,6 +141,7 @@ function rowToMemory(row: Record<string, unknown>): Memory {
     scope: (row['scope'] as string) ?? 'project',
     tags: parseTags(row['tags']),
     structured_fields: parseStructuredFields(row['structured_fields']),
+    last_hit_at: (row['last_hit_at'] as string | null) ?? null,
   };
 }
 
@@ -233,15 +257,39 @@ export function queryMemoriesRanked(opts: QueryMemoriesOptions): RankedMemory[]
     : [];
 
   if (keywordHits.length === 0 && semanticHits.length === 0 && !trimmedQuery) {
-    // No query at all — fall back to the existing ranked-by-score listing.
-    return getActiveMemoriesRanked(k).map((memory) => ({
-      memory,
-      score: memory.confidence * (1 + memory.hit_count * 0.1),
-      keywordRank: null,
-      semanticRank: null,
-      confidenceBoost: memory.confidence * (1 + memory.hit_count * 0.1),
-      reason: 'ranked' as const,
-    })).filter((hit) => passesFilters(hit.memory, opts));
+    // No query at all — return top-k by decay-aware ranked score.
+    //
+    // Build the candidate pool from a direct SQL query that honors the
+    // request's activeClause (i.e. include_superseded). Using
+    // getActiveMemoriesRanked here would silently drop superseded rows even
+    // when the caller explicitly opted in, and would slice by raw score
+    // before decay/filters had a chance to reorder.
+    const candidatePool = Math.min(Math.max(k * 5, 50), 500);
+    const rows = adapter
+      .prepare(
+        `SELECT * FROM memories ${activeClause}
+         ORDER BY (confidence * (1.0 + hit_count * 0.1)) DESC
+         LIMIT :limit`,
+      )
+      .all({ ':limit': candidatePool });
+
+    const ranked: RankedMemory[] = [];
+    for (const row of rows) {
+      const memory = rowToMemory(row);
+      if (!passesFilters(memory, opts)) continue;
+      const decay = memoryDecayFactor(memory.last_hit_at);
+      const score = memory.confidence * (1 + memory.hit_count * 0.1) * decay;
+      ranked.push({
+        memory,
+        score,
+        keywordRank: null,
+        semanticRank: null,
+        confidenceBoost: score,
+        reason: 'ranked' as const,
+      });
+    }
+    ranked.sort((a, b) => b.score - a.score);
+    return ranked.slice(0, k);
   }
 
   // 3) Reciprocal rank fusion — each hit contributes 1/(rrfK + rank).
@@ -275,7 +323,7 @@ export function queryMemoriesRanked(opts: QueryMemoriesOptions): RankedMemory[]
   const ranked: RankedMemory[] = [];
   for (const entry of fused.values()) {
     if (!passesFilters(entry.memory, opts)) continue;
-    const boost = entry.memory.confidence * (1 + entry.memory.hit_count * 0.1);
+    const boost = entry.memory.confidence * (1 + entry.memory.hit_count * 0.1) * memoryDecayFactor(entry.memory.last_hit_at);
     const reason: RankedMemory['reason'] =
       entry.kwRank != null && entry.semRank != null
         ? 'both'
@@ -313,6 +361,8 @@ function passesFilters(memory: Memory, filters: QueryMemoriesFilters): boolean {
   return true;
 }
 
+let ftsWarningEmitted = false;
+
 function keywordSearch(
   adapter: NonNullable<ReturnType<typeof _getAdapter>>,
   rawQuery: string,
@@ -340,14 +390,29 @@ function keywordSearch(
     }
   }
 
-  // LIKE fallback — scans the candidate pool.
+  // LIKE fallback — scans a capped candidate pool.
+  if (!ftsWarningEmitted) {
+    ftsWarningEmitted = true;
+    logWarning('memory-store', 'FTS5 unavailable — using LIKE fallback scan (consider enabling FTS5)');
+  }
+
   const terms = rawQuery
     .toLowerCase()
     .split(/[^a-z0-9_]+/)
     .filter((t) => t.length >= 2);
   if (terms.length === 0) return [];
 
-  const rows = adapter.prepare(`SELECT * FROM memories ${activeClause}`).all();
+  const preScanCap = Math.min(limit * 20, 2000);
+  // ORDER BY confidence-weighted hit_count DESC so the cap keeps the most
+  // valuable candidates instead of the oldest-by-rowid (which would silently
+  // exclude recently-stored memories on tables larger than preScanCap).
+  const rows = adapter
+    .prepare(
+      `SELECT * FROM memories ${activeClause}
+       ORDER BY (confidence * (1.0 + hit_count * 0.1)) DESC
+       LIMIT :preScanCap`,
+    )
+    .all({ ':preScanCap': preScanCap });
   const scored: Array<{ memory: Memory; score: number }> = [];
   for (const row of rows) {
     const memory = rowToMemory(row);

package/src/resources/extensions/gsd/native-git-bridge.ts

@@ -1183,6 +1183,33 @@ export function nativeRmForce(basePath: string, paths: string[]): void {
   }
 }
 
+function runGitWorktreeAdd(
+  basePath: string,
+  wtPath: string,
+  branch: string,
+  createBranch?: boolean,
+  startPoint?: string,
+): void {
+  if (createBranch) {
+    const branchRef = gitExec(basePath, ["show-ref", "--verify", `refs/heads/${branch}`], true);
+    if (branchRef) {
+      gitExec(basePath, ["worktree", "add", wtPath, branch]);
+      return;
+    }
+    gitExec(basePath, ["worktree", "add", "-b", branch, wtPath, startPoint ?? "HEAD"]);
+  } else {
+    gitExec(basePath, ["worktree", "add", wtPath, branch]);
+  }
+}
+
+export function assertWorktreeMaterialized(wtPath: string): void {
+  if (existsSync(join(wtPath, ".git"))) return;
+  throw new GSDError(
+    GSD_GIT_ERROR,
+    `git worktree add did not materialize a valid worktree at ${wtPath}: missing .git file`,
+  );
+}
+
 /**
  * Add a new git worktree.
  * Native: libgit2 worktree API.
@@ -1198,14 +1225,20 @@ export function nativeWorktreeAdd(
   const native = loadNative();
   if (native) {
     native.gitWorktreeAdd(basePath, wtPath, branch, createBranch, startPoint);
-    return;
+    try {
+      assertWorktreeMaterialized(wtPath);
+      return;
+    } catch {
+      rmSync(wtPath, { recursive: true, force: true });
+      gitExec(basePath, ["worktree", "prune"], true);
+      runGitWorktreeAdd(basePath, wtPath, branch, createBranch, startPoint);
+      assertWorktreeMaterialized(wtPath);
+      return;
+    }
   }
 
-  if (createBranch) {
-    gitExec(basePath, ["worktree", "add", "-b", branch, wtPath, startPoint ?? "HEAD"]);
-  } else {
-    gitExec(basePath, ["worktree", "add", wtPath, branch]);
-  }
+  runGitWorktreeAdd(basePath, wtPath, branch, createBranch, startPoint);
+  assertWorktreeMaterialized(wtPath);
 }
 
 /**

package/src/resources/extensions/gsd/orphan-stash-audit.ts

@@ -0,0 +1,117 @@
+// GSD-2 + src/resources/extensions/gsd/orphan-stash-audit.ts
+// Startup sweep for orphaned gsd-preflight-stash entries left behind by
+// interrupted milestone merges (#5538-followup).
+
+import { execFileSync } from "node:child_process";
+import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
+
+export interface OrphanPreflightStashAuditResult {
+  applied: Array<{ milestoneId: string; stashRef: string }>;
+  warnings: string[];
+}
+
+/**
+ * Recognize the "already restored" failure mode of `git stash apply`.
+ *
+ * When a preflight stash captured untracked files via `--include-untracked`
+ * and those files are now present in the working tree (e.g. a prior audit
+ * run already applied this stash), `git stash apply` aborts with
+ * `<path> already exists, no checkout` and exits non-zero. That is the
+ * idempotent steady state for this audit, not a recovery failure — treat
+ * it as a no-op so repeated GSD startups stop spamming the user with
+ * warnings about stashes that have already been restored (#5538-followup
+ * peer-review feedback).
+ */
+function _isAlreadyRestoredApplyError(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const stderr = (err as { stderr?: unknown }).stderr;
+  const stderrText = typeof stderr === "string" ? stderr : stderr instanceof Uint8Array ? Buffer.from(stderr).toString("utf-8") : "";
+  if (stderrText && /already exists, no checkout/i.test(stderrText)) return true;
+  const message = err instanceof Error ? err.message : String(err);
+  return /already exists, no checkout/i.test(message);
+}
+
+export { _isAlreadyRestoredApplyError };
+
+/**
+ * Audit `git stash list` for orphaned `gsd-preflight-stash:M00x:*` entries.
+ *
+ * The matching merge code in `phases.ts` previously skipped the postflight
+ * pop whenever `mergeAndExit` threw, leaking the user's pre-merge working
+ * tree into the stash list. For every preflight-stash entry whose milestone
+ * is now complete (per the supplied callback), `git stash apply` is invoked —
+ * NOT `pop`. The stash entry stays in the list so the user retains a backup
+ * if the apply produces unexpected merge results. Idempotent across repeated
+ * startup runs.
+ *
+ * Failures are best-effort: a list error (no repo, git unavailable) returns
+ * an empty result. An apply error becomes a warning the user sees alongside
+ * the existing orphan-branch audit messages — startup continues.
+ */
+export function auditOrphanedPreflightStashes(
+  basePath: string,
+  isMilestoneComplete: (milestoneId: string) => boolean,
+): OrphanPreflightStashAuditResult {
+  const result: OrphanPreflightStashAuditResult = { applied: [], warnings: [] };
+
+  let listOutput: string;
+  try {
+    listOutput = execFileSync(
+      "git",
+      ["stash", "list", "--format=%gd%x00%s"],
+      {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+        env: GIT_NO_PROMPT_ENV,
+      },
+    );
+  } catch {
+    return result;
+  }
+
+  const MARKER_RE = /\bgsd-preflight-stash:([A-Za-z0-9_-]+):/;
+  for (const line of listOutput.split("\n")) {
+    const sep = line.indexOf("\x00");
+    if (sep < 0) continue;
+    const ref = line.slice(0, sep);
+    const subject = line.slice(sep + 1);
+    if (!ref || !subject) continue;
+
+    const match = MARKER_RE.exec(subject);
+    if (!match) continue;
+    const milestoneId = match[1];
+
+    let complete = false;
+    try {
+      complete = isMilestoneComplete(milestoneId);
+    } catch (err) {
+      result.warnings.push(
+        `Could not determine completion status for ${milestoneId} during preflight-stash audit: ${err instanceof Error ? err.message : String(err)}.`,
+      );
+      continue;
+    }
+    if (!complete) continue;
+
+    try {
+      execFileSync("git", ["stash", "apply", "--quiet", ref], {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+        env: GIT_NO_PROMPT_ENV,
+      });
+      result.applied.push({ milestoneId, stashRef: ref });
+    } catch (err) {
+      // Idempotent steady state: stash was already applied in a prior audit
+      // run; the files exist and `git stash apply` refuses to overwrite.
+      // Skip silently so repeat runs are no-ops.
+      if (_isAlreadyRestoredApplyError(err)) continue;
+      result.warnings.push(
+        `Could not apply orphaned preflight stash ${ref} (milestone ${milestoneId}): ${err instanceof Error ? err.message : String(err)}. ` +
+          `Run \`git stash apply ${ref}\` manually to restore your pre-merge changes.`,
+      );
+    }
+  }
+
+  return result;
+}

package/src/resources/extensions/gsd/parallel-orchestrator.ts

@@ -21,7 +21,7 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { gsdRoot } from "./paths.js";
 import { createWorktree, worktreePath } from "./worktree-manager.js";
-import { autoWorktreeBranch, runWorktreePostCreateHook, syncGsdStateToWorktree } from "./auto-worktree.js";
+import { autoWorktreeBranch, fastForwardReusedMilestoneBranchIfSafe, runWorktreePostCreateHook, syncGsdStateToWorktree } from "./auto-worktree.js";
 import { nativeBranchExists } from "./native-git-bridge.js";
 import { readIntegrationBranch } from "./git-service.js";
 import { resolveParallelConfig } from "./preferences.js";
@@ -471,7 +471,7 @@ export async function startParallel(
       // Create the worktree (without chdir — coordinator stays in project root)
       let wtPath: string;
       try {
-        wtPath = createMilestoneWorktree(basePath, mid);
+        wtPath = _createMilestoneWorktree(basePath, mid);
       } catch (e) {
         logWarning("parallel", `createMilestoneWorktree fallback for ${mid}: ${(e as Error).message}`);
         wtPath = worktreePath(basePath, mid);
@@ -532,13 +532,23 @@ export async function startParallel(
 /**
  * Create a git worktree for a milestone without changing the coordinator's cwd.
  * Uses milestone/<MID> branch naming (same as auto-worktree.ts).
+ *
+ * Exported with the `_` prefix purely for tests — production callers stay on
+ * the closure-private name `createMilestoneWorktree` below.
  */
-function createMilestoneWorktree(basePath: string, milestoneId: string): string {
+export function _createMilestoneWorktree(basePath: string, milestoneId: string): string {
   const branch = autoWorktreeBranch(milestoneId);
   const branchExists = nativeBranchExists(basePath, branch);
 
   let info: { name: string; path: string; branch: string; exists: boolean };
   if (branchExists) {
+    // #5549 post-merge audit (R3): match the fast-forward behavior added to
+    // `createAutoWorktree` in commit 8996cb68e. When a worker reuses an
+    // existing milestone branch, fast-forward it onto the integration branch
+    // when safe so per-worker worktrees don't fork from a stale base after a
+    // sibling milestone has merged. Same `nativeIsAncestor` + worktree-list
+    // safety guards apply.
+    fastForwardReusedMilestoneBranchIfSafe(basePath, milestoneId, branch);
     info = createWorktree(basePath, milestoneId, { branch, reuseExistingBranch: true });
   } else {
     const integrationBranch = readIntegrationBranch(basePath, milestoneId) ?? undefined;