gsd-pi 2.24.0 → 2.26.0

package/README.md

@@ -32,11 +32,13 @@ Full documentation is available in the [`docs/`](./docs/) directory:
 - **[Token Optimization](./docs/token-optimization.md)** — profiles, context compression, complexity routing (v2.17)
 - **[Cost Management](./docs/cost-management.md)** — budgets, tracking, projections
 - **[Git Strategy](./docs/git-strategy.md)** — worktree isolation, branching, merge behavior
+- **[Parallel Orchestration](./docs/parallel-orchestration.md)** — run multiple milestones simultaneously
 - **[Working in Teams](./docs/working-in-teams.md)** — unique IDs, shared artifacts
 - **[Skills](./docs/skills.md)** — bundled skills, discovery, custom authoring
 - **[Commands Reference](./docs/commands.md)** — all commands and keyboard shortcuts
 - **[Architecture](./docs/architecture.md)** — system design and dispatch pipeline
-- **[Troubleshooting](./docs/troubleshooting.md)** — common issues, doctor, recovery
+- **[Troubleshooting](./docs/troubleshooting.md)** — common issues, doctor, forensics, recovery
+- **[VS Code Extension](./vscode-extension/README.md)** — chat participant, sidebar dashboard, RPC integration
 - **[Migration from v1](./docs/migration.md)** — `.planning` → `.gsd` migration
 
 ---
@@ -111,9 +113,11 @@ Each slice flows through phases automatically:
 
 ```
 Research → Plan → Execute (per task) → Complete → Reassess Roadmap → Next Slice
+                                                                      ↓ (all slices done)
+                                                              Validate Milestone → Complete Milestone
 ```
 
-**Research** scouts the codebase and relevant docs. **Plan** decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded. **Complete** writes the summary, UAT script, marks the roadmap, and commits. **Reassess** checks if the roadmap still makes sense given what was learned.
+**Research** scouts the codebase and relevant docs. **Plan** decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded. **Complete** writes the summary, UAT script, marks the roadmap, and commits. **Reassess** checks if the roadmap still makes sense given what was learned. **Validate Milestone** runs a reconciliation gate after all slices complete — comparing roadmap success criteria against actual results before sealing the milestone.
 
 ### `/gsd auto` — The Main Event
 
@@ -555,7 +559,13 @@ Anthropic, OpenAI, Google (Gemini), OpenRouter, GitHub Copilot, Amazon Bedrock,
 
 If you have a **Claude Max**, **Codex**, or **GitHub Copilot** subscription, you can use those directly — Pi handles the OAuth flow. No API key needed.
 
-> **Note:** Using OAuth tokens from subscription plans (e.g. Claude Max) outside their native applications may not be explicitly permitted by the provider's Terms of Service. GSD supports API key authentication for all providers as an alternative. Use at your own discretion.
+> **⚠️ Important:** Using OAuth tokens from subscription plans outside their native applications may violate the provider's Terms of Service. In particular:
+>
+> - **Google Gemini** — Using Gemini CLI or Antigravity OAuth tokens in third-party tools has resulted in **Google account suspensions**. This affects your entire Google account, not just the Gemini service. **Use a Gemini API key instead.**
+> - **Claude Max** — Anthropic's ToS may not explicitly permit OAuth use outside Claude's own applications.
+> - **GitHub Copilot** — Usage outside GitHub's own tools may be restricted by your subscription terms.
+>
+> GSD supports API key authentication for all providers as the safe alternative. **We strongly recommend using API keys over OAuth for Google Gemini.**
 
 ### OpenRouter
 

package/dist/headless.js

@@ -137,18 +137,37 @@ function formatProgress(event, verbose) {
 // ---------------------------------------------------------------------------
 // Completion Detection
 // ---------------------------------------------------------------------------
-const TERMINAL_KEYWORDS = ['complete', 'stopped', 'blocked'];
+/**
+ * Detect genuine auto-mode termination notifications.
+ *
+ * Only matches the actual stop signals emitted by stopAuto():
+ *   "Auto-mode stopped..."
+ *   "Step-mode stopped..."
+ *
+ * Does NOT match progress notifications that happen to contain words like
+ * "complete" or "stopped" (e.g., "Override resolved — rewrite-docs completed",
+ * "All slices are complete — nothing to discuss", "Skipped 5+ completed units").
+ *
+ * Blocked detection is separate — checked via isBlockedNotification.
+ */
+const TERMINAL_PREFIXES = ['auto-mode stopped', 'step-mode stopped'];
 const IDLE_TIMEOUT_MS = 15_000;
+// new-milestone is a long-running creative task where the LLM may pause
+// between tool calls (e.g. after mkdir, before writing files). Use a
+// longer idle timeout to avoid killing the session prematurely (#808).
+const NEW_MILESTONE_IDLE_TIMEOUT_MS = 120_000;
 function isTerminalNotification(event) {
     if (event.type !== 'extension_ui_request' || event.method !== 'notify')
         return false;
     const message = String(event.message ?? '').toLowerCase();
-    return TERMINAL_KEYWORDS.some((kw) => message.includes(kw));
+    return TERMINAL_PREFIXES.some((prefix) => message.startsWith(prefix));
 }
 function isBlockedNotification(event) {
     if (event.type !== 'extension_ui_request' || event.method !== 'notify')
         return false;
-    return String(event.message ?? '').toLowerCase().includes('blocked');
+    const message = String(event.message ?? '').toLowerCase();
+    // Blocked notifications come through stopAuto as "Auto-mode stopped (Blocked: ...)"
+    return message.includes('blocked:');
 }
 function isMilestoneReadyNotification(event) {
     if (event.type !== 'extension_ui_request' || event.method !== 'notify')
@@ -285,6 +304,7 @@ export async function runHeadless(options) {
     });
     // Idle timeout — fallback completion detection
     let idleTimer = null;
+    const effectiveIdleTimeout = isNewMilestone ? NEW_MILESTONE_IDLE_TIMEOUT_MS : IDLE_TIMEOUT_MS;
     function resetIdleTimer() {
         if (idleTimer)
             clearTimeout(idleTimer);
@@ -292,7 +312,7 @@ export async function runHeadless(options) {
             idleTimer = setTimeout(() => {
                 completed = true;
                 resolveCompletion();
-            }, IDLE_TIMEOUT_MS);
+            }, effectiveIdleTimeout);
         }
     }
     // Overall timeout

package/dist/models-resolver.d.ts

@@ -19,14 +19,3 @@
  * @returns The path to use for models.json
  */
 export declare function resolveModelsJsonPath(): string;
-/**
- * Check if both GSD and PI models.json files exist.
- */
-export declare function hasBothModelsFiles(): boolean;
-/**
- * Get the paths to both models.json files.
- */
-export declare function getModelsPaths(): {
-    gsd: string;
-    pi: string;
-};

package/dist/models-resolver.js

@@ -33,18 +33,3 @@ export function resolveModelsJsonPath() {
     }
     return GSD_MODELS_PATH;
 }
-/**
- * Check if both GSD and PI models.json files exist.
- */
-export function hasBothModelsFiles() {
-    return existsSync(GSD_MODELS_PATH) && existsSync(PI_MODELS_PATH);
-}
-/**
- * Get the paths to both models.json files.
- */
-export function getModelsPaths() {
-    return {
-        gsd: GSD_MODELS_PATH,
-        pi: PI_MODELS_PATH,
-    };
-}

package/dist/resource-loader.d.ts

@@ -1,7 +1,6 @@
 import { DefaultResourceLoader } from '@gsd/pi-coding-agent';
 export declare function discoverExtensionEntryPaths(extensionsDir: string): string[];
 export declare function readManagedResourceVersion(agentDir: string): string | null;
-export declare function readManagedResourceSyncedAt(agentDir: string): number | null;
 export declare function getNewerManagedResourceVersion(agentDir: string, currentVersion: string): string | null;
 /**
  * Syncs all bundled resources to agentDir (~/.gsd/agent/) on every launch.

package/dist/resource-loader.js

@@ -97,15 +97,6 @@ export function readManagedResourceVersion(agentDir) {
         return null;
     }
 }
-export function readManagedResourceSyncedAt(agentDir) {
-    try {
-        const manifest = JSON.parse(readFileSync(getManagedResourceManifestPath(agentDir), 'utf-8'));
-        return typeof manifest?.syncedAt === 'number' ? manifest.syncedAt : null;
-    }
-    catch {
-        return null;
-    }
-}
 export function getNewerManagedResourceVersion(agentDir, currentVersion) {
     const managedVersion = readManagedResourceVersion(agentDir);
     if (!managedVersion) {

package/dist/resources/GSD-WORKFLOW.md

@@ -565,25 +565,28 @@ One commit per slice. Individually revertable. Reads like a changelog.
 
 ```
 gsd/M001/S01:
-  test(S01): round-trip tests passing
+  test(S01/T03): round-trip tests passing
   feat(S01/T03): file writer with round-trip fidelity
-  chore(S01/T03): auto-commit after task
   feat(S01/T02): markdown parser for plan files
-  chore(S01/T02): auto-commit after task
   feat(S01/T01): core types and interfaces
-  chore(S01/T01): auto-commit after task
+  docs(S01): add slice plan
 ```
 
 ### Commit Conventions
 
 | When | Format | Example |
 |------|--------|---------|
-| Auto-commit (dirty state) | `chore(S01/T02): auto-commit after task` | Automatic save of work in progress |
-| After task verified | `feat(S01/T02): <what was built>` | The real work |
-| Plan/docs committed | `docs(S01): add slice plan` | Bundled with first task |
-| Slice squash to main | `type(M001/S01): <slice title>` | Type inferred from title (`feat`, `fix`, `docs`, etc.) |
+| Task completed | `{type}(S01/T02): <one-liner from summary>` | Type inferred from title (`feat`, `fix`, `test`, etc.) |
+| Plan/docs committed | `docs(S01): add slice plan` | Planning artifacts |
+| Slice squash to main | `type(M001/S01): <slice title>` | Type inferred from title |
+| State rebuild | `chore(S01/T02): auto-commit after state-rebuild` | Bookkeeping only |
 
-Commit types: `feat`, `fix`, `test`, `refactor`, `docs`, `chore`
+The system reads the task summary after execution and builds a meaningful commit message:
+- **Subject**: `{type}({sliceId}/{taskId}): {one-liner}` — the one-liner from the summary frontmatter
+- **Type**: Inferred from the task title and one-liner (`feat`, `fix`, `test`, `refactor`, `docs`, `perf`, `chore`)
+- **Body**: Key files from the summary frontmatter (up to 8 files listed)
+
+Commit types: `feat`, `fix`, `test`, `refactor`, `docs`, `perf`, `chore`
 
 ### Squash Merge Message
 

package/dist/resources/extensions/async-jobs/index.ts

@@ -54,6 +54,14 @@ export default function AsyncJobs(pi: ExtensionAPI) {
 					? output.slice(0, maxLen) + "\n\n[... truncated, use await_job for full output]"
 					: output;
 
+				// Deliver as follow-up without triggering a new LLM turn (#875).
+				// When the agent is streaming: the message is queued and picked up
+				// by the agent loop's getFollowUpMessages() after the current turn.
+				// When the agent is idle: the message is appended to context so it's
+				// visible on the next user-initiated prompt. Previously triggerTurn:true
+				// caused spurious autonomous turns — the model would interpret completed
+				// job output as requiring action and cascade into unbounded self-reinforcing
+				// loops (running more commands, spawning more jobs, burning context).
 				pi.sendMessage(
 					{
 						customType: "async_job_result",
@@ -64,7 +72,7 @@ export default function AsyncJobs(pi: ExtensionAPI) {
 						].join("\n"),
 						display: true,
 					},
-					{ deliverAs: "followUp", triggerTurn: true },
+					{ deliverAs: "followUp" },
 				);
 			},
 		});

package/dist/resources/extensions/bg-shell/index.ts

@@ -66,6 +66,7 @@ import { waitForReady } from "./readiness-detector.js";
 import { queryShellEnv, sendAndWait, runOnSession } from "./interaction.js";
 import { formatUptime, formatTokenCount, resolveBgShellPersistenceCwd } from "./utilities.js";
 import { BgManagerOverlay } from "./overlay.js";
+import { toPosixPath } from "../shared/path-display.js";
 
 // ── Re-exports for consumers ───────────────────────────────────────────────
 
@@ -337,7 +338,7 @@ export default function (pi: ExtensionAPI) {
 					text += `  type: ${bg.processType}\n`;
 					text += `  status: ${bg.status}\n`;
 					text += `  command: ${bg.command}\n`;
-					text += `  cwd: ${bg.cwd}`;
+					text += `  cwd: ${toPosixPath(bg.cwd)}`;
 
 					if (bg.group) text += `\n  group: ${bg.group}`;
 					if (bg.readyPort) text += `\n  ready_port: ${bg.readyPort}`;
@@ -694,7 +695,7 @@ export default function (pi: ExtensionAPI) {
 					}
 
 					let text = `Shell environment for ${bg.id} (${bg.label}):\n`;
-					text += `  cwd: ${envResult.cwd}\n`;
+					text += `  cwd: ${toPosixPath(envResult.cwd)}\n`;
 					text += `  shell: ${envResult.shell}\n`;
 
 					const envEntries = Object.entries(envResult.env);

package/dist/resources/extensions/bg-shell/overlay.ts

@@ -328,12 +328,9 @@ export class BgManagerOverlay {
 		return this.box(inner, width);
 	}
 
-	private renderOutput(width: number): string[] {
+	private processStatusHeader(p: typeof this.viewingProcess, activeTab: "output" | "events"): { statusIcon: string; headerLine: string } {
 		const th = this.theme;
-		const p = this.viewingProcess;
-		if (!p) return [""];
-		const inner: string[] = [];
-
+		if (!p) return { statusIcon: "", headerLine: "" };
 		const statusIcon = p.alive
 			? (p.status === "ready" ? th.fg("success", "●")
 				: p.status === "error" ? th.fg("error", "●")
@@ -343,9 +340,21 @@ export class BgManagerOverlay {
 		const uptime = th.fg("dim", formatUptime(Date.now() - p.startedAt));
 		const typeTag = th.fg("dim", `[${p.processType}]`);
 		const portInfo = p.ports.length > 0 ? th.fg("dim", ` :${p.ports.join(",")}`) : "";
-		const tabIndicator = th.fg("accent", "[Output]") + " " + th.fg("dim", "Events");
+		const tabIndicator = activeTab === "output"
+			? th.fg("accent", "[Output]") + " " + th.fg("dim", "Events")
+			: th.fg("dim", "Output") + " " + th.fg("accent", "[Events]");
+		const headerLine = `${statusIcon} ${name} ${typeTag} ${uptime}${portInfo}  ${tabIndicator}`;
+		return { statusIcon, headerLine };
+	}
+
+	private renderOutput(width: number): string[] {
+		const th = this.theme;
+		const p = this.viewingProcess;
+		if (!p) return [""];
+		const inner: string[] = [];
 
-		inner.push(`${statusIcon} ${name} ${typeTag} ${uptime}${portInfo}  ${tabIndicator}`);
+		const { headerLine } = this.processStatusHeader(p, "output");
+		inner.push(headerLine);
 		inner.push("");
 
 		// Unified buffer is already chronologically interleaved
@@ -384,16 +393,8 @@ export class BgManagerOverlay {
 		if (!p) return [""];
 		const inner: string[] = [];
 
-		const statusIcon = p.alive
-			? (p.status === "ready" ? th.fg("success", "●")
-				: p.status === "error" ? th.fg("error", "●")
-				: th.fg("warning", "●"))
-			: th.fg("dim", "○");
-		const name = th.fg("muted", p.label);
-		const uptime = th.fg("dim", formatUptime(Date.now() - p.startedAt));
-		const tabIndicator = th.fg("dim", "Output") + " " + th.fg("accent", "[Events]");
-
-		inner.push(`${statusIcon} ${name} ${uptime}  ${tabIndicator}`);
+		const { headerLine } = this.processStatusHeader(p, "events");
+		inner.push(headerLine);
 		inner.push("");
 
 		if (p.events.length === 0) {

package/dist/resources/extensions/get-secrets-from-user.ts

@@ -369,32 +369,14 @@ async function applySecrets(
 		}
 	}
 
-	if (destination === "vercel" && opts.exec) {
+	if ((destination === "vercel" || destination === "convex") && opts.exec) {
 		const env = opts.environment ?? "development";
 		for (const { key, value } of provided) {
+			const cmd = destination === "vercel"
+				? `printf %s ${shellEscapeSingle(value)} | vercel env add ${key} ${env}`
+				: `npx convex env set ${key} ${shellEscapeSingle(value)}`;
 			try {
-				const result = await opts.exec("sh", [
-					"-c",
-					`printf %s ${shellEscapeSingle(value)} | vercel env add ${key} ${env}`,
-				]);
-				if (result.code !== 0) {
-					errors.push(`${key}: ${result.stderr.slice(0, 200)}`);
-				} else {
-					applied.push(key);
-				}
-			} catch (err: any) {
-				errors.push(`${key}: ${err.message}`);
-			}
-		}
-	}
-
-	if (destination === "convex" && opts.exec) {
-		for (const { key, value } of provided) {
-			try {
-				const result = await opts.exec("sh", [
-					"-c",
-					`npx convex env set ${key} ${shellEscapeSingle(value)}`,
-				]);
+				const result = await opts.exec("sh", ["-c", cmd]);
 				if (result.code !== 0) {
 					errors.push(`${key}: ${result.stderr.slice(0, 200)}`);
 				} else {

package/dist/resources/extensions/gsd/activity-log.ts

@@ -103,10 +103,10 @@ export function saveActivityLog(
   basePath: string,
   unitType: string,
   unitId: string,
-): void {
+): string | null {
   try {
     const entries = ctx.sessionManager.getEntries();
-    if (!entries || entries.length === 0) return;
+    if (!entries || entries.length === 0) return null;
 
     const activityDir = join(gsdRoot(basePath), "activity");
     mkdirSync(activityDir, { recursive: true });
@@ -116,7 +116,7 @@ export function saveActivityLog(
     const unitKey = `${unitType}\0${safeUnitId}`;
     // Use lightweight fingerprint instead of serializing all entries (#611)
     const key = snapshotKey(unitType, safeUnitId, entries);
-    if (state.lastSnapshotKeyByUnit.get(unitKey) === key) return;
+    if (state.lastSnapshotKeyByUnit.get(unitKey) === key) return null;
 
     const filePath = nextActivityFilePath(activityDir, state, unitType, safeUnitId);
     // Stream entries to disk line-by-line instead of building one massive string (#611).
@@ -131,9 +131,11 @@ export function saveActivityLog(
     }
     state.nextSeq += 1;
     state.lastSnapshotKeyByUnit.set(unitKey, key);
+    return filePath;
   } catch (e) {
     // Don't let logging failures break auto-mode
     void e;
+    return null;
   }
 }
 

package/dist/resources/extensions/gsd/auto-prompts.ts

@@ -637,6 +637,12 @@ export async function buildPlanSlicePrompt(
   const executorContextConstraints = formatExecutorConstraints();
 
   const outputRelPath = relSliceFile(base, mid, sid, "PLAN");
+  const prefs = loadEffectiveGSDPreferences();
+  const commitDocsEnabled = prefs?.preferences?.git?.commit_docs !== false;
+  const commitInstruction = commitDocsEnabled
+    ? `Commit: \`docs(${sid}): add slice plan\``
+    : "Do not commit — planning docs are not tracked in git for this project.";
+
   return loadPrompt("plan-slice", {
     workingDirectory: base,
     milestoneId: mid, sliceId: sid, sliceTitle: sTitle,
@@ -647,6 +653,7 @@ export async function buildPlanSlicePrompt(
     inlinedContext,
     dependencySummaries: depContent,
     executorContextConstraints,
+    commitInstruction,
   });
 }
 
@@ -1071,6 +1078,12 @@ export async function buildReassessRoadmapPrompt(
     // Non-fatal — captures module may not be available
   }
 
+  const reassessPrefs = loadEffectiveGSDPreferences();
+  const reassessCommitDocsEnabled = reassessPrefs?.preferences?.git?.commit_docs !== false;
+  const reassessCommitInstruction = reassessCommitDocsEnabled
+    ? `Commit: \`docs(${mid}): reassess roadmap after ${completedSliceId}\``
+    : "Do not commit — planning docs are not tracked in git for this project.";
+
   return loadPrompt("reassess-roadmap", {
     workingDirectory: base,
     milestoneId: mid,
@@ -1081,6 +1094,7 @@ export async function buildReassessRoadmapPrompt(
     assessmentPath,
     inlinedContext,
     deferredCaptures,
+    commitInstruction: reassessCommitInstruction,
   });
 }
 

package/dist/resources/extensions/gsd/auto-recovery.ts

@@ -90,6 +90,10 @@ export function resolveExpectedArtifactPath(unitType: string, unitId: string, ba
       const dir = resolveMilestonePath(base, mid);
       return dir ? join(dir, buildMilestoneFileName(mid, "SUMMARY")) : null;
     }
+    case "replan-slice": {
+      const dir = resolveSlicePath(base, mid, sid!);
+      return dir ? join(dir, buildSliceFileName(sid!, "REPLAN")) : null;
+    }
     case "rewrite-docs":
       return null;
     default:
@@ -127,10 +131,9 @@ export function verifyExpectedArtifact(unitType: string, unitId: string, base: s
   }
 
   const absPath = resolveExpectedArtifactPath(unitType, unitId, base);
-  // Unit types with no verifiable artifact always pass (e.g. replan-slice).
-  // For all other types, null means the parent directory is missing on disk
-  // — treat as stale completion state so the key gets evicted (#313).
-  if (!absPath) return unitType === "replan-slice";
+  // For unit types with no verifiable artifact (null path), the parent directory
+  // is missing on disk — treat as stale completion state so the key gets evicted (#313).
+  if (!absPath) return false;
   if (!existsSync(absPath)) return false;
 
   // plan-slice must produce a plan with actual task entries, not just a scaffold.

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

@@ -6,7 +6,7 @@
  * manages create, enter, detect, and teardown for auto-mode worktrees.
  */
 
-import { existsSync, cpSync, readFileSync, realpathSync, utimesSync } from "node:fs";
+import { existsSync, cpSync, readFileSync, writeFileSync, readdirSync, mkdirSync, realpathSync, utimesSync, unlinkSync } from "node:fs";
 import { isAbsolute, join, resolve } from "node:path";
 import { copyWorktreeDb, reconcileWorktreeDb, isDbAvailable } from "./gsd-db.js";
 import { execSync, execFileSync } from "node:child_process";
@@ -134,6 +134,112 @@ export function autoWorktreeBranch(milestoneId: string): string {
  * Atomic: chdir + originalBase update happen in the same try block
  * to prevent split-brain.
  */
+
+/**
+ * Forward-merge plan checkbox state from the project root into a freshly
+ * re-attached worktree (#778).
+ *
+ * When auto-mode stops via crash (not graceful stop), the milestone branch
+ * HEAD may be behind the filesystem state at the project root because
+ * syncStateToProjectRoot() runs after every task completion but the final
+ * git commit may not have happened before the crash. On restart the worktree
+ * is re-attached to the branch HEAD, which has [ ] for the crashed task,
+ * causing verifyExpectedArtifact() to fail and triggering an infinite
+ * dispatch/skip loop.
+ *
+ * Fix: after re-attaching, read every *.md plan file in the milestone
+ * directory at the project root and apply any [x] checkbox states that are
+ * ahead of the worktree version (forward-only: never downgrade [x] → [ ]).
+ *
+ * This is safe because syncStateToProjectRoot() is the authoritative source
+ * of post-task state at the project root — it writes the same [x] the LLM
+ * produced, then the auto-commit follows. If the commit never happened, the
+ * filesystem copy is still valid and correct.
+ */
+function reconcilePlanCheckboxes(projectRoot: string, wtPath: string, milestoneId: string): void {
+  const srcMilestone = join(projectRoot, ".gsd", "milestones", milestoneId);
+  const dstMilestone = join(wtPath, ".gsd", "milestones", milestoneId);
+  if (!existsSync(srcMilestone) || !existsSync(dstMilestone)) return;
+
+  // Walk all markdown files in the milestone directory (plans, summaries, etc.)
+  function walkMd(dir: string): string[] {
+    const results: string[] = [];
+    try {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+          results.push(...walkMd(full));
+        } else if (entry.isFile() && entry.name.endsWith(".md")) {
+          results.push(full);
+        }
+      }
+    } catch { /* non-fatal */ }
+    return results;
+  }
+
+  for (const srcFile of walkMd(srcMilestone)) {
+    const rel = srcFile.slice(srcMilestone.length);
+    const dstFile = dstMilestone + rel;
+    if (!existsSync(dstFile)) continue; // only reconcile existing files
+
+    let srcContent: string;
+    let dstContent: string;
+    try {
+      srcContent = readFileSync(srcFile, "utf-8");
+      dstContent = readFileSync(dstFile, "utf-8");
+    } catch { continue; }
+
+    if (srcContent === dstContent) continue;
+
+    // Extract all checked task IDs from the source (project root)
+    // Pattern: - [x] **T<id>: or - [x] **S<id>: (case-insensitive x)
+    const checkedRe = /^- \[[xX]\] \*\*([TS]\d+):/gm;
+    const srcChecked = new Set<string>();
+    for (const m of srcContent.matchAll(checkedRe)) srcChecked.add(m[1]);
+
+    if (srcChecked.size === 0) continue;
+
+    // Forward-apply: replace [ ] → [x] for any IDs that are checked in src
+    let updated = dstContent;
+    let changed = false;
+    for (const id of srcChecked) {
+      const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const uncheckedRe = new RegExp(`^(- )\\[ \\]( \\*\\*${escapedId}:)`, "gm");
+      if (uncheckedRe.test(updated)) {
+        updated = updated.replace(
+          new RegExp(`^(- )\\[ \\]( \\*\\*${escapedId}:)`, "gm"),
+          "$1[x]$2",
+        );
+        changed = true;
+      }
+    }
+
+    if (changed) {
+      try {
+        writeFileSync(dstFile, updated, "utf-8");
+      } catch { /* non-fatal */ }
+    }
+  }
+
+  // Also forward-merge completed-units.json (set-union)
+  const srcKeys = join(projectRoot, ".gsd", "completed-units.json");
+  const dstKeys = join(wtPath, ".gsd", "completed-units.json");
+  if (existsSync(srcKeys)) {
+    try {
+      const src: string[] = JSON.parse(readFileSync(srcKeys, "utf-8"));
+      let dst: string[] = [];
+      if (existsSync(dstKeys)) {
+        try { dst = JSON.parse(readFileSync(dstKeys, "utf-8")); } catch { /* ignore corrupt */ }
+      }
+      const merged = [...new Set([...dst, ...src])];
+      if (merged.length > dst.length) {
+        mkdirSync(join(wtPath, ".gsd"), { recursive: true });
+        writeFileSync(dstKeys, JSON.stringify(merged), "utf-8");
+      }
+    } catch { /* non-fatal */ }
+  }
+}
+
 export function createAutoWorktree(basePath: string, milestoneId: string): string {
   const branch = autoWorktreeBranch(milestoneId);
 
@@ -166,6 +272,18 @@ export function createAutoWorktree(basePath: string, milestoneId: string): strin
   // not always fully synced.
   if (!branchExists) {
     copyPlanningArtifacts(basePath, info.path);
+  } else {
+    // Re-attaching to an existing branch: forward-merge any plan checkpoint
+    // state from the project root into the worktree (#778).
+    //
+    // If auto-mode stopped via crash, the milestone branch HEAD may lag behind
+    // the project root filesystem because syncStateToProjectRoot() ran after
+    // task completion but the auto-commit never fired. On restart the worktree
+    // is re-created from the branch HEAD (which has [ ] for the crashed task),
+    // causing verifyExpectedArtifact() to return false → stale-key eviction →
+    // infinite dispatch/skip loop. Reconciling here ensures the worktree sees
+    // the same [x] state that syncStateToProjectRoot() wrote to the root.
+    reconcilePlanCheckboxes(basePath, info.path, milestoneId);
   }
 
   // Run user-configured post-create hook (#597) — e.g. copy .env, symlink assets
@@ -194,7 +312,8 @@ export function createAutoWorktree(basePath: string, milestoneId: string): strin
 
 /**
  * Copy .gsd/ planning artifacts from source repo to a new worktree.
- * Copies milestones/, DECISIONS.md, REQUIREMENTS.md, PROJECT.md, QUEUE.md.
+ * Copies milestones/, DECISIONS.md, REQUIREMENTS.md, PROJECT.md, QUEUE.md,
+ * STATE.md, KNOWLEDGE.md, and OVERRIDES.md.
  * Skips runtime files (auto.lock, metrics.json, etc.) and the worktrees/ dir.
  * Best-effort — failures are non-fatal since auto-mode can recreate artifacts.
  */
@@ -212,7 +331,7 @@ function copyPlanningArtifacts(srcBase: string, wtPath: string): void {
   }
 
   // Copy top-level planning files
-  for (const file of ["DECISIONS.md", "REQUIREMENTS.md", "PROJECT.md", "QUEUE.md"]) {
+  for (const file of ["DECISIONS.md", "REQUIREMENTS.md", "PROJECT.md", "QUEUE.md", "STATE.md", "KNOWLEDGE.md", "OVERRIDES.md"]) {
     const src = join(srcGsd, file);
     if (existsSync(src)) {
       try {
@@ -441,6 +560,16 @@ export function mergeMilestoneToMain(
   //    when main is already checked out in the project-root worktree, #757)
   const currentBranchAtBase = nativeGetCurrentBranch(originalBasePath_);
   if (currentBranchAtBase !== mainBranch) {
+    // Remove untracked .gsd/ state files that may conflict with the branch
+    // being checked out. These are regenerated by doctor/rebuildState and
+    // are not meaningful in the main working tree — the worktree had the
+    // real state. Without this, `git checkout main` fails with
+    // "Your local changes would be overwritten" (#827).
+    const gsdStateFiles = ["STATE.md", "completed-units.json", "auto.lock"];
+    for (const f of gsdStateFiles) {
+      const p = join(originalBasePath_, ".gsd", f);
+      try { unlinkSync(p); } catch { /* non-fatal — file may not exist */ }
+    }
     nativeCheckoutBranch(originalBasePath_, mainBranch);
   }