gsd-pi 2.82.0-dev.c22380fc3 → 2.82.0-dev.e7a7f1ed5

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

@@ -58,6 +58,7 @@ import {
 import {
   writeLock,
   clearLock,
+  clearStaleWorkerLock,
   readCrashLock,
   isLockProcessAlive,
   formatCrashInfo,
@@ -240,7 +241,7 @@ import { runAutoLoopWithUok } from "./uok/kernel.js";
 import { resolveUokFlags } from "./uok/flags.js";
 import { validateDirectory } from "./validate-directory.js";
 import { createAutoOrchestrator } from "./auto/orchestrator.js";
-import type { AutoOrchestrationModule, AutoOrchestratorDeps, DispatchAdapter } from "./auto/contracts.js";
+import type { AutoAdvanceResult, AutoOrchestrationModule, AutoOrchestratorDeps, DispatchAdapter } from "./auto/contracts.js";
 import { reconcileBeforeDispatch } from "./state-reconciliation.js";
 import { compileUnitToolContract } from "./tool-contract.js";
 import { createWorktreeSafetyModule } from "./worktree-safety.js";
@@ -316,6 +317,13 @@ import { normalizeRealPath } from "./paths.js";
 /** Throttle STATE.md rebuilds — at most once per 30 seconds */
 const STATE_REBUILD_MIN_INTERVAL_MS = 30_000;
 
+export function formatAutoStopNotification(prefix: string, totals: { cost: number; tokens: { total: number } }, unitCount: number): string {
+  return [
+    `${prefix}.`,
+    `Session: ${formatCost(totals.cost)} · ${formatTokenCount(totals.tokens.total)} tokens · ${unitCount} units`,
+  ].join("\n");
+}
+
 /**
  * Phase B — register this auto-mode process in the workers table so other
  * workers and janitors can detect liveness via heartbeat. Best-effort: if
@@ -1044,6 +1052,7 @@ export async function cleanupAfterLoopExit(ctx: ExtensionContext): Promise<void>
   // visible so the user still has a resumable auto-mode signal on screen.
   if (!s.paused) {
     ctx.ui.setStatus("gsd-auto", undefined);
+    ctx.ui.setWidget("gsd-progress", undefined);
     if (s.completionStopInProgress) {
       s.completionStopInProgress = false;
     }
@@ -1415,7 +1424,7 @@ export async function stopAuto(
       if (ledger && ledger.units.length > 0) {
         const totals = getProjectTotals(ledger.units);
         ctx?.ui.notify(
-          `${notificationPrefix}. Session: ${formatCost(totals.cost)} · ${formatTokenCount(totals.tokens.total)} tokens · ${ledger.units.length} units`,
+          formatAutoStopNotification(notificationPrefix, totals, ledger.units.length),
           "info",
         );
       } else {
@@ -1722,7 +1731,6 @@ export async function pauseAuto(
   restoreProjectRootEnv();
   restoreMilestoneLockEnv();
   s.pendingVerificationRetry = null;
-  s.verificationRetryCount.clear();
   ctx?.ui.setStatus("gsd-auto", "paused");
   ctx?.ui.setWidget("gsd-progress", undefined);
   const resumeCmd = s.stepMode ? "/gsd next" : "/gsd auto";
@@ -1839,6 +1847,13 @@ export function createWiredDispatchAdapter(
         modelRegistry,
       });
 
+      if (action.action === "stop") {
+        return {
+          kind: "blocked",
+          reason: action.reason,
+          action: action.level === "warning" ? "pause" : "stop",
+        };
+      }
       if (action.action !== "dispatch") return null;
       return {
         unitType: action.unitType,
@@ -2065,6 +2080,18 @@ export function createWiredAutoOrchestrationModule(
   return createAutoOrchestrator(deps);
 }
 
+function notifyResumeBlocked(ctx: ExtensionContext, result: Extract<AutoAdvanceResult, { kind: "blocked" }>): void {
+  const resumeCmd = s.stepMode ? "/gsd next" : "/gsd auto";
+  ctx.ui.notify(`Auto-mode blocked: ${result.reason}. Fix and run ${resumeCmd} to resume.`, "warning");
+  setLifecycleOutcome(ctx, {
+    status: "blocked",
+    title: "Auto-mode blocked",
+    detail: result.reason,
+    nextAction: `Fix the blocker, then run ${resumeCmd} to resume.`,
+    commands: ["/gsd status for overview", `${resumeCmd} to resume`, "/gsd doctor to diagnose"],
+  });
+}
+
 function ensureOrchestrationModule(ctx: ExtensionContext, pi: ExtensionAPI, basePath: string): void {
   s.orchestration = createWiredAutoOrchestrationModule(ctx, pi, basePath, lockBase());
 }
@@ -2402,7 +2429,7 @@ export async function startAuto(
     // This closes the journal gap reported in #3348 where the worker wrote side
     // effects (SUMMARY.md, DB updates) but died before emitting unit-end.
     emitCrashRecoveredUnitEnd(base, freshStartAssessment.lock);
-    clearLock(base);
+    clearStaleWorkerLock(base);
   }
 
   if (!s.paused) {
@@ -2473,6 +2500,8 @@ export async function startAuto(
     s.unitLifetimeDispatches.clear();
     if (!getLedger()) initMetrics(base);
     if (s.currentMilestoneId) setActiveMilestoneId(base, s.currentMilestoneId);
+    await openProjectDbIfPresent(base);
+    registerAutoWorkerForSession(s, base);
 
     // Re-register health level notification callback lost across process restart
     setLevelChangeCallback((_from, to, summary) => {
@@ -2580,7 +2609,12 @@ export async function startAuto(
     pi.events.emit(CMUX_CHANNELS.LOG, { preferences: loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, message: s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", level: "progress" });
 
     try {
-      await s.orchestration?.resume();
+      const resumeResult = await s.orchestration?.resume();
+      if (resumeResult?.kind === "blocked") {
+        notifyResumeBlocked(ctx, resumeResult);
+        await cleanupAfterLoopExit(ctx);
+        return;
+      }
     } catch (err) {
       debugLog("resume-orchestration-resume", { error: err instanceof Error ? err.message : String(err) });
     }
@@ -2601,6 +2635,7 @@ export async function startAuto(
   const bootstrapDeps: BootstrapDeps = {
     shouldUseWorktreeIsolation,
     registerSigtermHandler,
+    registerAutoWorkerForSession: (projectRoot) => registerAutoWorkerForSession(s, projectRoot),
     lockBase,
     buildLifecycle,
   };

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

@@ -32,6 +32,7 @@ import { shouldIgnoreAgentEndForActiveUnit } from "../auto/unit-runner-events.js
 import { resolveModelId } from "../auto-model-selection.js";
 import { resolveProjectRoot } from "../worktree.js";
 import { clearDiscussionFlowState } from "./write-gate.js";
+import { clearGuidedUnitContext } from "../guided-unit-context.js";
 import { resumeAutoAfterProviderDelay } from "./provider-error-resume.js";
 import {
   classifyError,
@@ -48,6 +49,11 @@ const MAX_NETWORK_RETRIES = 2;
 function isObjectRecord(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object";
 }
+
+export function _hasEmptyAgentEndContent(content: unknown): boolean {
+  return content == null || (Array.isArray(content) && content.length === 0);
+}
+
 /**
  * Cap on auto-resume attempts for sustained transient-provider errors.
  *
@@ -94,6 +100,14 @@ export function isUserInitiatedAbortMessage(message: string | undefined | null):
   return /\b(?:claude code process aborted by user|request aborted by user|process aborted by user)\b/i.test(message);
 }
 
+export function shouldDeferTransientErrorToCoreRetry(
+  cls: ErrorClass,
+  rawErrorMsg: string,
+): boolean {
+  if (!isTransient(cls) || cls.kind === "rate-limit") return false;
+  return !/retry failed after \d+ attempts:/i.test(rawErrorMsg);
+}
+
 function isBareClaudeCodeSessionSwitchAbortMarker(message: string | undefined | null): boolean {
   if (!message) return false;
   const normalized = message.trim().replace(/\s+/g, " ").toLowerCase();
@@ -196,6 +210,14 @@ export function resolveAgentEndErrorDisplay(
   return rawErrorMsg;
 }
 
+export function isTerminalDeletedWorktreeProviderError(
+  message: string | undefined | null,
+): boolean {
+  if (!message) return false;
+  if (!/\bdoes not exist\b/i.test(message)) return false;
+  return /[/\\]\.gsd[/\\](?:projects[/\\][^/\\]+[/\\])?worktrees[/\\][^/\\\s"']+/i.test(message);
+}
+
 async function pauseTransientWithBackoff(
   cls: ErrorClass,
   pi: ExtensionAPI,
@@ -244,9 +266,11 @@ export async function handleAgentEnd(
   // falsely report files as missing — producing a spurious "ready signal
   // rejected" loop even though the files are on disk.
   clearPathCache();
+  const basePath = resolveAgentEndBasePath();
+  clearGuidedUnitContext(basePath);
 
   try {
-    if (await checkDeepProjectSetupAfterTurn(event, ctx, resolveAgentEndBasePath())) {
+    if (await checkDeepProjectSetupAfterTurn(event, ctx, basePath)) {
       return;
     }
   } catch (err) {
@@ -254,8 +278,8 @@ export async function handleAgentEnd(
     logWarning("bootstrap", `checkDeepProjectSetupAfterTurn failed: ${message}`);
   }
 
-  if (checkAutoStartAfterDiscuss()) {
-    clearDiscussionFlowState(resolveAgentEndBasePath() ?? process.cwd());
+  if (checkAutoStartAfterDiscuss(basePath)) {
+    clearDiscussionFlowState(basePath ?? process.cwd());
     return;
   }
 
@@ -263,14 +287,14 @@ export async function handleAgentEnd(
   // are missing, `checkAutoStartAfterDiscuss` returns false silently. Surface
   // that and nudge the LLM to complete the writes before the user hits the
   // downstream "All milestones complete" warning loop.
-  if (maybeHandleReadyPhraseWithoutFiles(event)) return;
+  if (maybeHandleReadyPhraseWithoutFiles(event, basePath)) return;
 
   // #4573 — Empty-turn recovery: if the LLM announced intent in prose but
   // emitted no tool calls, nudge it to execute. Fires only when auto-mode is
   // active or a discussion autostart is pending (non-auto interactive discuss
   // is user-driven). Runs before `isAutoActive` early return so pending
   // discussions (where isAutoActive may be false) still get recovered.
-  if (maybeHandleEmptyIntentTurn(event, isAutoActive())) return;
+  if (maybeHandleEmptyIntentTurn(event, isAutoActive(), basePath)) return;
 
   if (!isAutoActive()) return;
 
@@ -310,7 +334,7 @@ export async function handleAgentEnd(
     // that carry error context — e.g. errorMessage field or non-empty content
     // indicating a mid-stream failure. (#2695)
     const content = "content" in lastMsg ? lastMsg.content : undefined;
-    const hasEmptyContent = Array.isArray(content) && content.length === 0;
+    const hasEmptyContent = _hasEmptyAgentEndContent(content);
     const hasErrorMessage = "errorMessage" in lastMsg && !!lastMsg.errorMessage;
 
     if (hasEmptyContent && !hasErrorMessage) {
@@ -355,6 +379,17 @@ export async function handleAgentEnd(
       rawErrorMsg,
       "content" in lastMsg ? lastMsg.content : undefined,
     );
+    if (
+      isAutoCompletionStopInProgress() &&
+      isTerminalDeletedWorktreeProviderError(`${rawErrorMsg}\n${displayMsg}`)
+    ) {
+      resetRetryState(retryState);
+      logWarning(
+        "bootstrap",
+        `Ignoring stale deleted-worktree provider error during terminal completion reroot: ${displayMsg || rawErrorMsg}`,
+      );
+      return;
+    }
     const errorDetail = displayMsg ? `: ${displayMsg}` : "";
     const explicitRetryAfterMs = ("retryAfterMs" in lastMsg && typeof lastMsg.retryAfterMs === "number") ? lastMsg.retryAfterMs : undefined;
 
@@ -461,7 +496,7 @@ export async function handleAgentEnd(
     // Core retries transient failures in-session after this handler.
     // Keep that behavior for non-rate-limit classes to avoid pause/retry races,
     // but let rate-limit continue into model fallback logic below (#4373).
-    if (isTransient(cls) && cls.kind !== "rate-limit") {
+    if (shouldDeferTransientErrorToCoreRetry(cls, rawErrorMsg)) {
       return;
     }
 

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

@@ -487,17 +487,18 @@ export function registerDbTools(pi: ExtensionAPI): void {
     promptGuidelines: [
       "Use gsd_plan_milestone for milestone planning instead of writing ROADMAP.md directly.",
       "Keep parameters flat and provide the full milestone planning payload, including slices.",
+      "Milestone and slice titles must not contain forward slash (/), en dash, or em dash characters.",
       "The tool validates input, writes milestone and slice planning data transactionally, renders ROADMAP.md from DB, and clears both state and parse caches after success.",
       "Use the canonical name gsd_plan_milestone; gsd_milestone_plan is only an alias.",
     ],
     parameters: Type.Object({
       // ── Core identification + content (required) ──────────────────────
       milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
-      title: Type.String({ description: "Milestone title" }),
+      title: Type.String({ description: "Milestone title; must not contain forward slash (/), en dash, or em dash characters" }),
       vision: Type.String({ description: "Milestone vision" }),
       slices: Type.Array(Type.Object({
         sliceId: Type.String({ description: "Slice ID (e.g. S01)" }),
-        title: Type.String({ description: "Slice title" }),
+        title: Type.String({ description: "Slice title; must not contain forward slash (/), en dash, or em dash characters" }),
         risk: Type.String({ description: "Slice risk" }),
         depends: Type.Array(Type.String(), { description: "Slice dependency IDs" }),
         demo: Type.String({ description: "Roadmap demo text / After this" }),
@@ -570,10 +571,10 @@ export function registerDbTools(pi: ExtensionAPI): void {
         title: Type.String({ description: "Task title" }),
         description: Type.String({ description: "Task description / steps block" }),
         estimate: Type.String({ description: "Task estimate string" }),
-        files: Type.Array(Type.String(), { description: "Files likely touched" }),
+        files: Type.Array(Type.String(), { description: "Array<string> of files likely touched; pass [\"path\"] or [], never a single string" }),
         verify: Type.String({ description: "Verification command or block" }),
-        inputs: Type.Array(Type.String(), { description: "Input files or references" }),
-        expectedOutput: Type.Array(Type.String(), { description: "Expected output files or artifacts" }),
+        inputs: Type.Array(Type.String(), { description: "Array<string> of input files or references; pass [\"path\"] or [], never a single string" }),
+        expectedOutput: Type.Array(Type.String(), { description: "Array<string> of expected output files or artifacts; pass [\"path\"] or [], never a single string" }),
         observabilityImpact: Type.Optional(Type.String({ description: "Task observability impact" })),
       }), { description: "Planned tasks for the slice" }),
       // ── Enrichment metadata (optional — defaults to empty) ────────────
@@ -650,10 +651,10 @@ export function registerDbTools(pi: ExtensionAPI): void {
       title: Type.String({ description: "Task title" }),
       description: Type.String({ description: "Task description / steps block" }),
       estimate: Type.String({ description: "Task estimate string" }),
-      files: Type.Array(Type.String(), { description: "Files likely touched" }),
+      files: Type.Array(Type.String(), { description: "Array<string> of files likely touched; pass [\"path\"] or [], never a single string" }),
       verify: Type.String({ description: "Verification command or block" }),
-      inputs: Type.Array(Type.String(), { description: "Input files or references" }),
-      expectedOutput: Type.Array(Type.String(), { description: "Expected output files or artifacts" }),
+      inputs: Type.Array(Type.String(), { description: "Array<string> of input files or references; pass [\"path\"] or [], never a single string" }),
+      expectedOutput: Type.Array(Type.String(), { description: "Array<string> of expected output files or artifacts; pass [\"path\"] or [], never a single string" }),
       observabilityImpact: Type.Optional(Type.String({ description: "Task observability impact" })),
       // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
       actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),

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

@@ -31,6 +31,7 @@ import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { extractSubagentAgentClasses } from "./subagent-input.js";
 import { approvalGateIdForUnit, isExplicitApprovalResponse, shouldPauseForUserApprovalQuestion } from "../user-input-boundary.js";
 import { resolveSkillManifest } from "../skill-manifest.js";
+import { getGuidedUnitContext } from "../guided-unit-context.js";
 
 let approvalQuestionAbortInFlight = false;
 
@@ -772,7 +773,8 @@ export function registerHooks(
     // subagent dispatch. Closes the b23 bug class where a discuss-milestone
     // turn used the host Edit tool to modify user source files.
     const dash = getAutoRuntimeSnapshot();
-    const activeUnitType = dash.currentUnit?.type;
+    const guidedUnit = getGuidedUnitContext(discussionBasePath);
+    const activeUnitType = dash.currentUnit?.type ?? guidedUnit?.unitType;
     if (activeUnitType) {
       const manifest = resolveManifest(activeUnitType);
       if (manifest) {
@@ -791,7 +793,7 @@ export function registerHooks(
         const planningGuard = shouldBlockPlanningUnit(
           event.toolName,
           planningInput,
-          dash.basePath || discussionBasePath,
+          dash.basePath || guidedUnit?.basePath || discussionBasePath,
           activeUnitType,
           manifest.tools,
           agentClasses,

package/src/resources/extensions/gsd/bootstrap/subagent-input.ts

@@ -1,20 +1,32 @@
 export function extractSubagentAgentClasses(input: unknown): string[] {
   if (!input || typeof input !== "object") return [];
 
-  const record = input as Record<string, unknown>;
   const agentClasses: string[] = [];
+  const visited = new WeakSet<object>();
   const addAgentClass = (value: unknown): void => {
-    if (typeof value === "string" && value.trim().length > 0) agentClasses.push(value.trim());
+    if (typeof value !== "string") return;
+    const normalized = value.trim().replace(/\.md$/i, "");
+    if (normalized.length > 0) agentClasses.push(normalized);
   };
-  const addFromItems = (value: unknown): void => {
+
+  const visitItems = (value: unknown): void => {
     if (!Array.isArray(value)) return;
     for (const item of value) {
-      if (item && typeof item === "object") addAgentClass((item as Record<string, unknown>).agent);
+      visit(item);
     }
   };
 
-  addAgentClass(record.agent);
-  addFromItems(record.tasks);
-  addFromItems(record.chain);
+  const visit = (value: unknown): void => {
+    if (!value || typeof value !== "object") return;
+    if (visited.has(value)) return;
+    visited.add(value);
+    const record = value as Record<string, unknown>;
+    addAgentClass(record.agent);
+    visitItems(record.tasks);
+    visitItems(record.chain);
+    visitItems(record.parallel);
+  };
+
+  visit(input);
   return agentClasses;
 }

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

@@ -5,7 +5,7 @@ import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { minimatch } from "minimatch";
 
 import { getIsolationMode } from "../preferences.js";
-import type { ToolsPolicy } from "../unit-context-manifest.js";
+import { compileSubagentPermissionContract, type ToolsPolicy } from "../unit-context-manifest.js";
 import { logWarning } from "../workflow-logger.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "../worktree-root.js";
 
@@ -65,6 +65,7 @@ const QUEUE_SAFE_TOOLS = new Set([
  *   true / false        — shell no-ops / test exit codes
  */
 const BASH_READ_ONLY_RE = /^\s*(cat|head|tail|less|more|wc|file|stat|du|df|which|type|echo|printf|ls|find|grep|rg|awk|sed\b(?!.*-i)|sort|uniq|diff|comm|tr|cut|tee\s+-a\s+\/dev\/null|git\s+(log|show|diff|status|branch|tag|remote|rev-parse|ls-files|blame|shortlog|describe|stash\s+list|config\s+--get|cat-file)|gh\s+(issue|pr|api|repo|release)\s+(view|list|diff|status|checks)|mkdir\s+-p\s+\.gsd|rtk\s|npm\s+run\s+(test|test:\w+|lint|lint:\w+|typecheck|type-check|type-check:\w+|check|verify|audit|outdated|format:check|ci|validate)\b|npm\s+(ls|list|info|view|show|outdated|audit|explain|doctor|ping|--version|-v)\b|npx\s|tsx\s|node\s+(--print|--version|-v\b)|python[23]?\s+(-c\s+'[^']*'|--version|-V\b|-m\s+(pip\s+show|pip\s+list|site))|pip[23]?\s+(show|list|freeze|check|index\s+versions)\b|jq\s|yq\s|curl\s+(-s\b|--silent\b)(?!\s+[^|>]*\s-[oO]\b)(?!\s+[^|>]*\s--output\b)[^|>]*$|openssl\s+(version|x509|s_client)|env\b|printenv\b|true\b|false\b)/;
+const BASH_VERIFICATION_RE = /^\s*(npm\s+(run\s+(build|test|test:\w+|lint|lint:\w+|typecheck|type-check|verify|ci|validate)\b|test\b)|pnpm\s+(build|test|lint|typecheck|verify)\b|yarn\s+(build|test|lint|typecheck|verify)\b|vitest\b|jest\b|go\s+test\b)/;
 
 interface InMemoryWriteGateState {
   verifiedDepthMilestones: Set<string>;
@@ -767,6 +768,9 @@ function blockReason(unitType: string, mode: string, what: string): string {
  *                    and listed in the policy's allowedSubagents.
  *   - "docs"       → like "planning" but also allows writes to paths
  *                    matching `allowedPathGlobs` relative to basePath.
+ *   - "verification"
+ *                  → allows Bash for project verification commands, but keeps
+ *                    writes restricted to .gsd/ and blocks subagent dispatch.
  *
  * `pathOrCommand` is the file path for write/edit-shaped tools and the
  * shell command for bash. Other tools ignore this argument.
@@ -804,14 +808,15 @@ export function shouldBlockPlanningUnit(
     return { block: true, reason: blockReason(unitType, policy.mode, `tool "${tool}" is not on the read-only allowlist`) };
   }
 
-  // planning / planning-dispatch / docs modes share the same surface for safe tools, bash, and subagent.
+  // planning / planning-dispatch / docs / verification modes share the same surface for safe tools, bash, and subagent.
   if (PLANNING_SAFE_TOOLS.has(tool)) return { block: false };
   if (tool.startsWith("gsd_")) return { block: false };
 
   if (PLANNING_SUBAGENT_TOOLS.has(tool)) {
     if (policy.mode === "planning-dispatch") {
       const requested = (agentClasses ?? []).map(a => a.trim()).filter(Boolean);
-      const allowedSubagents = Array.isArray(policy.allowedSubagents) ? policy.allowedSubagents : [];
+      const dispatchContract = compileSubagentPermissionContract(policy);
+      const allowedSubagents = dispatchContract.allowedSubagents;
       const allowed = new Set(allowedSubagents);
       // When agentClasses is undefined, the caller has not been updated to extract
       // agent identities yet. Block and warn so stale callers surface in telemetry
@@ -861,6 +866,17 @@ export function shouldBlockPlanningUnit(
   }
 
   if (tool === "bash") {
+    if (policy.mode === "verification") {
+      if (BASH_VERIFICATION_RE.test(pathOrCommand) || BASH_READ_ONLY_RE.test(pathOrCommand)) return { block: false };
+      return {
+        block: true,
+        reason: blockReason(
+          unitType,
+          policy.mode,
+          `bash is restricted to build/test verification commands (npm run build, npm test, etc.); cannot run "${pathOrCommand.slice(0, 80)}${pathOrCommand.length > 80 ? "…" : ""}"`,
+        ),
+      };
+    }
     if (BASH_READ_ONLY_RE.test(pathOrCommand)) return { block: false };
     return {
       block: true,

package/src/resources/extensions/gsd/clean-root-preflight.ts

@@ -8,12 +8,14 @@
  *
  * Design constraints (from Trek-e approval):
  *  - Warn the user before stashing (no silent surprises)
- *  - git stash push / git stash pop only — no custom stash management layer
- *  - Stash/pop errors are logged but MUST NOT block the merge itself
+ *  - git stash push / git stash apply+drop for targeted restore
+ *  - Stash/apply errors are logged but MUST NOT block the merge itself
  *  - Fast-path status check — clean trees pay no extra cost
  */
 
 import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { logWarning } from "./workflow-logger.js";
 import { nativeHasChanges } from "./native-git-bridge.js";
@@ -32,6 +34,148 @@ export interface PostflightResult {
   needsManualRecovery: boolean;
   message: string;
   stashRef?: string;
+  resolution?: "applied" | "already-present-dropped" | "already-present-preserved" | "manual-recovery";
+  collidedPaths?: string[];
+}
+
+function gitText(basePath: string, args: string[]): string {
+  return execFileSync("git", args, {
+    cwd: basePath,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+    env: GIT_NO_PROMPT_ENV,
+  });
+}
+
+function gitBuffer(basePath: string, args: string[]): Buffer {
+  return execFileSync("git", args, {
+    cwd: basePath,
+    stdio: ["ignore", "pipe", "pipe"],
+    env: GIT_NO_PROMPT_ENV,
+  });
+}
+
+function errorText(err: unknown): string {
+  if (!err || typeof err !== "object") return String(err);
+  const parts: string[] = [];
+  const stderr = (err as { stderr?: unknown }).stderr;
+  const stdout = (err as { stdout?: unknown }).stdout;
+  for (const value of [stderr, stdout]) {
+    if (typeof value === "string") parts.push(value);
+    else if (value instanceof Uint8Array) parts.push(Buffer.from(value).toString("utf-8"));
+  }
+  parts.push(err instanceof Error ? err.message : String(err));
+  return parts.filter(Boolean).join("\n");
+}
+
+function parseAlreadyExistsNoCheckoutPaths(text: string): string[] {
+  const paths: string[] = [];
+  for (const line of text.split(/\r?\n/)) {
+    const match = /^(.+?) already exists, no checkout$/i.exec(line.trim());
+    if (match?.[1]) paths.push(match[1]);
+  }
+  return [...new Set(paths)];
+}
+
+function readZeroDelimitedPaths(output: string): string[] {
+  return output.split("\0").filter(Boolean);
+}
+
+function listStashUntrackedPaths(basePath: string, stashRef: string): string[] | null {
+  try {
+    const output = gitText(basePath, ["ls-tree", "-r", "-z", "--name-only", `${stashRef}^3`]);
+    return readZeroDelimitedPaths(output);
+  } catch {
+    return null;
+  }
+}
+
+function listStashTrackedPaths(basePath: string, stashRef: string): string[] | null {
+  try {
+    const output = gitText(basePath, ["diff", "--name-only", "-z", `${stashRef}^1`, stashRef]);
+    return readZeroDelimitedPaths(output);
+  } catch {
+    return null;
+  }
+}
+
+function isWorktreeClean(basePath: string): boolean | null {
+  try {
+    return gitText(basePath, ["status", "--porcelain"]).trim() === "";
+  } catch {
+    return null;
+  }
+}
+
+function stashBlobEqualsWorktreeFile(basePath: string, stashRef: string, path: string): boolean | null {
+  try {
+    const worktreePath = join(basePath, path);
+    if (!existsSync(worktreePath)) return false;
+    const worktreeContent = readFileSync(worktreePath);
+    const stashContent = gitBuffer(basePath, ["show", `${stashRef}^3:${path}`]);
+    return Buffer.compare(worktreeContent, stashContent) === 0;
+  } catch {
+    return null;
+  }
+}
+
+function reconcileAlreadyPresentUntrackedStash(
+  basePath: string,
+  milestoneId: string,
+  stashRef: string,
+  err: unknown,
+): PostflightResult | null {
+  const text = errorText(err);
+  const collidedPaths = parseAlreadyExistsNoCheckoutPaths(text);
+  if (collidedPaths.length === 0) return null;
+
+  const untrackedPaths = listStashUntrackedPaths(basePath, stashRef);
+  if (!untrackedPaths || untrackedPaths.length === 0) return null;
+
+  const trackedPaths = listStashTrackedPaths(basePath, stashRef);
+  if (trackedPaths === null || trackedPaths.length > 0) return null;
+
+  const untrackedPathSet = new Set(untrackedPaths);
+  if (!collidedPaths.every((path) => untrackedPathSet.has(path))) return null;
+  if (!untrackedPaths.every((path) => existsSync(join(basePath, path)))) return null;
+  if (isWorktreeClean(basePath) !== true) return null;
+
+  const blobComparisons = untrackedPaths.map((path) => stashBlobEqualsWorktreeFile(basePath, stashRef, path));
+  if (blobComparisons.some((result) => result === null)) return null;
+  const allIdentical = blobComparisons.every(Boolean);
+  if (allIdentical) {
+    let dropped = true;
+    try {
+      execFileSync("git", ["stash", "drop", stashRef], {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+        env: GIT_NO_PROMPT_ENV,
+      });
+    } catch (err) {
+      dropped = false;
+      logWarning("preflight", `git stash drop ${stashRef} failed after identical preflight stash reconciliation: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return {
+      restored: true,
+      needsManualRecovery: false,
+      message: dropped
+        ? `Preflight stash for milestone ${milestoneId} contained files already present after merge; identical stash dropped.`
+        : `Preflight stash for milestone ${milestoneId} contained files already present after merge, but ${stashRef} could not be dropped and remains as a backup.`,
+      stashRef,
+      resolution: dropped ? "already-present-dropped" : "already-present-preserved",
+      collidedPaths,
+    };
+  }
+
+  return {
+    restored: false,
+    needsManualRecovery: false,
+    message: `Preflight stash for milestone ${milestoneId} contained untracked files already present after merge. Keeping merged files and preserving ${stashRef} as a backup.`,
+    stashRef,
+    resolution: "already-present-preserved",
+    collidedPaths,
+  };
 }
 
 function findPreflightStashRef(basePath: string, milestoneId: string, stashMarker?: string): string | null {
@@ -141,27 +285,48 @@ export function postflightPopStash(
         message: msg,
       };
     }
-    execFileSync("git", ["stash", "pop", stashRef], {
+    execFileSync("git", ["stash", "apply", stashRef], {
       cwd: basePath,
       stdio: ["ignore", "pipe", "pipe"],
       encoding: "utf-8",
       env: GIT_NO_PROMPT_ENV,
     });
+    let dropWarning: string | null = null;
+    try {
+      execFileSync("git", ["stash", "drop", stashRef], {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+        env: GIT_NO_PROMPT_ENV,
+      });
+    } catch (err) {
+      dropWarning = ` Stash was restored, but git stash drop ${stashRef} failed: ${err instanceof Error ? err.message : String(err)}.`;
+      logWarning("preflight", dropWarning.trim());
+    }
     const msg = `Restored stashed changes after milestone ${milestoneId} merge.`;
-    notify(msg, "info");
+    notify(`${msg}${dropWarning ?? ""}`, dropWarning ? "warning" : "info");
     return {
       restored: true,
       needsManualRecovery: false,
-      message: msg,
+      message: `${msg}${dropWarning ?? ""}`,
       stashRef,
+      resolution: "applied",
     };
   } catch (err) {
-    // Pop conflicts mean the merged code collides with the stashed changes.
+    if (stashRef) {
+      const reconciled = reconcileAlreadyPresentUntrackedStash(basePath, milestoneId, stashRef, err);
+      if (reconciled) {
+        logWarning("preflight", reconciled.message);
+        notify(reconciled.message, reconciled.resolution === "already-present-preserved" ? "warning" : "info");
+        return reconciled;
+      }
+    }
+    // Apply conflicts mean the merged code collides with the stashed changes.
     // Log a warning — the user needs to resolve manually, but the merge succeeded.
     const restoreHint = stashRef
-      ? `Run "git stash pop ${stashRef}" or "git stash apply ${stashRef}" manually to restore the correct stash.`
+      ? `Run "git stash apply ${stashRef}" manually to restore the correct stash, then "git stash drop ${stashRef}" after recovery.`
       : `Run "git stash list" to find the matching GSD preflight stash before restoring manually.`;
-    const msg = `git stash pop ${stashRef ?? ""}`.trim() + ` failed after merge of milestone ${milestoneId}: ${err instanceof Error ? err.message : String(err)}. ${restoreHint}`;
+    const msg = `git stash apply ${stashRef ?? ""}`.trim() + ` failed after merge of milestone ${milestoneId}: ${err instanceof Error ? err.message : String(err)}. ${restoreHint}`;
     logWarning("preflight", msg);
     notify(msg, "warning");
     return {
@@ -169,6 +334,7 @@ export function postflightPopStash(
       needsManualRecovery: true,
       message: msg,
       ...(stashRef ? { stashRef } : {}),
+      resolution: "manual-recovery",
     };
   }
 }