gsd-pi 2.79.0-dev.ece5fd8ba → 2.80.0-dev.4ea7d80e7

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

@@ -147,6 +147,7 @@ import {
   MergeConflictError,
   parseSliceBranch,
   setActiveMilestoneId,
+  resolveProjectRoot,
 } from "./worktree.js";
 import { GitServiceImpl } from "./git-service.js";
 import { getPriorSliceCompletionBlocker } from "./dispatch-guard.js";
@@ -231,6 +232,8 @@ import type { ErrorContext } from "./auto/types.js";
 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 } from "./auto/contracts.js";
 // Slice-level parallelism (#2340)
 import { getEligibleSlices } from "./slice-parallel-eligibility.js";
 import { startSliceParallel } from "./slice-parallel-orchestrator.js";
@@ -417,6 +420,17 @@ export function _synthesizePausedSessionRecoveryForTest(
   return synthesizePausedSessionRecovery(basePath, unitType, unitId, sessionFile);
 }
 
+const DETACHED_AUTO_KEEPALIVE_INTERVAL_MS = 30_000;
+
+function withDetachedAutoKeepalive<T>(run: Promise<T>): Promise<T> {
+  const keepAlive = setInterval(() => {}, DETACHED_AUTO_KEEPALIVE_INTERVAL_MS);
+  return run.finally(() => {
+    clearInterval(keepAlive);
+  });
+}
+
+export const _withDetachedAutoKeepaliveForTest = withDetachedAutoKeepalive;
+
 export function startAutoDetached(
   ctx: ExtensionCommandContext,
   pi: ExtensionAPI,
@@ -428,7 +442,7 @@ export function startAutoDetached(
     milestoneLock?: string | null;
   },
 ): void {
-  void startAuto(ctx, pi, base, verboseMode, options).catch((err) => {
+  void withDetachedAutoKeepalive(startAuto(ctx, pi, base, verboseMode, options)).catch((err) => {
     const message = getErrorMessage(err);
     ctx.ui.notify(`Auto-start failed: ${message}`, "error");
     logWarning("engine", `auto start error: ${message}`, { file: "auto.ts" });
@@ -1208,6 +1222,12 @@ export async function stopAuto(
     // changes the user made between sessions (#4959 / CodeRabbit).
     if (pi) clearToolBaseline(pi);
 
+    try {
+      await s.orchestration?.stop(reason ?? "stop");
+    } catch (err) {
+      debugLog("stop-orchestration-stop", { error: err instanceof Error ? err.message : String(err) });
+    }
+
     // Reset all session state in one call
     s.reset();
   }
@@ -1264,6 +1284,7 @@ export async function pauseAuto(
       activeRunDir: s.activeRunDir,
       autoStartTime: s.autoStartTime,
       milestoneLock: s.sessionMilestoneLock ?? undefined,
+      pauseReason: _errorContext?.message,
     };
     setRuntimeKv("global", "", PAUSED_SESSION_KV_KEY, pausedMeta);
   } catch (err) {
@@ -1306,6 +1327,12 @@ export async function pauseAuto(
   resolveAgentEnd({ messages: [] });
   _resetPendingResolve();
 
+  try {
+    await s.orchestration?.stop("pause");
+  } catch (err) {
+    debugLog("pause-orchestration-stop", { error: err instanceof Error ? err.message : String(err) });
+  }
+
   s.active = false;
   s.paused = true;
   deactivateGSD();
@@ -1363,6 +1390,141 @@ function buildResolver(): WorktreeResolver {
   return new WorktreeResolver(s, buildResolverDeps());
 }
 
+/**
+ * Thin entry glue for the new Auto Orchestration module.
+ *
+ * This intentionally wires only dispatch + error notification today, with
+ * no behavior changes to the existing auto loop. It provides a concrete seam
+ * the next refactor steps can adopt incrementally.
+ */
+export function createWiredAutoOrchestrationModule(
+  ctx: ExtensionContext,
+  _pi: ExtensionAPI,
+  dispatchBasePath: string,
+  runtimeBasePath = resolveProjectRoot(dispatchBasePath),
+): AutoOrchestrationModule {
+  const flowId = `auto-orchestrator-${Date.now()}`;
+  let seq = 0;
+
+  const deps: AutoOrchestratorDeps = {
+    dispatch: {
+      async decideNextUnit() {
+        const state = await deriveState(dispatchBasePath);
+        const active = state.activeMilestone;
+        if (!active) return null;
+
+        const prefs = loadEffectiveGSDPreferences(dispatchBasePath)?.preferences;
+        const action = await resolveDispatch({
+          basePath: dispatchBasePath,
+          mid: active.id,
+          midTitle: active.title,
+          state,
+          prefs,
+        });
+
+        if (action.action !== "dispatch") return null;
+        return {
+          unitType: action.unitType,
+          unitId: action.unitId,
+          reason: action.matchedRule ?? "dispatch",
+          preconditions: [],
+        };
+      },
+    },
+    recovery: {
+      async classifyAndRecover(input) {
+        const reason = input.error instanceof Error ? input.error.message : String(input.error ?? "unknown auto error");
+        return { action: "escalate" as const, reason };
+      },
+    },
+    worktree: {
+      async prepareForUnit() {},
+      async syncAfterUnit() {},
+      async cleanupOnStop() {},
+    },
+    health: {
+      async preAdvanceGate() {
+        const gate = await preDispatchHealthGate(dispatchBasePath);
+        return {
+          allow: gate.proceed,
+          reason: gate.reason,
+        };
+      },
+      async postAdvanceRecord(result) {
+        if (result.kind === "error") {
+          recordHealthSnapshot(1, 0, 0, [{
+            code: "orchestration-error",
+            message: result.reason ?? "orchestration error",
+            severity: "error",
+            unitId: "orchestration",
+          }], [], "orchestration");
+        } else if (result.kind === "blocked") {
+          recordHealthSnapshot(0, 1, 0, [{
+            code: "orchestration-blocked",
+            message: result.reason ?? "orchestration blocked",
+            severity: "warning",
+            unitId: "orchestration",
+          }], [], "orchestration");
+        }
+      },
+    },
+    runtime: {
+      async ensureLockOwnership() {
+        const status = getSessionLockStatus(runtimeBasePath);
+        if (!status.valid || status.failureReason === "pid-mismatch") {
+          throw new Error("session lock held by another process");
+        }
+      },
+      async journalTransition(event) {
+        const eventType = event.name === "start"
+          ? "iteration-start"
+          : event.name === "resume"
+            ? "iteration-start"
+            : event.name === "advance"
+              ? "dispatch-match"
+              : event.name === "advance-blocked"
+                ? "guard-block"
+                : event.name === "advance-stopped"
+                  ? "dispatch-stop"
+                  : event.name === "advance-error"
+                    ? "iteration-end"
+                    : event.name === "advance-paused" || event.name === "advance-retry"
+                      ? "guard-block"
+                      : event.name === "stop"
+                      ? "terminal"
+                      : "iteration-end";
+
+        _emitJournalEvent(runtimeBasePath, {
+          ts: new Date().toISOString(),
+          flowId,
+          seq: ++seq,
+          eventType,
+          data: {
+            source: "auto-orchestrator",
+            name: event.name,
+            reason: event.reason,
+            unitType: event.unitType,
+            unitId: event.unitId,
+          },
+        });
+      },
+    },
+    notifications: {
+      async notifyLifecycle(event) {
+        if (event.name === "error") {
+          ctx.ui.notify(event.detail ?? "auto orchestration error", "error");
+        }
+      },
+    },
+  };
+
+  return createAutoOrchestrator(deps);
+}
+
+function ensureOrchestrationModule(ctx: ExtensionContext, pi: ExtensionAPI, basePath: string): void {
+  s.orchestration = createWiredAutoOrchestrationModule(ctx, pi, basePath, lockBase());
+}
+
 /**
  * Build the LoopDeps object from auto.ts private scope.
  * This bundles all private functions that autoLoop needs without exporting them.
@@ -1785,6 +1947,7 @@ export async function startAuto(
       rebuildScope(s.basePath, s.currentMilestoneId);
     }
 
+    ensureOrchestrationModule(ctx, pi, s.basePath || base);
     registerSigtermHandler(lockBase());
 
     ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
@@ -1868,6 +2031,11 @@ 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();
+    } catch (err) {
+      debugLog("resume-orchestration-resume", { error: err instanceof Error ? err.message : String(err) });
+    }
     startAutoCommandPolling(s.basePath);
     await runAutoLoopWithUok({
       ctx,
@@ -1904,7 +2072,7 @@ export async function startAuto(
   // Build scope after bootstrap has populated s.basePath / s.originalBasePath /
   // s.currentMilestoneId (including worktree setup inside bootstrapAutoSession).
   rebuildScope(s.basePath, s.currentMilestoneId);
-
+  ensureOrchestrationModule(ctx, pi, s.basePath || base);
   captureProjectRootEnv(s.originalBasePath || s.basePath);
   registerAutoWorkerForSession(s);
   try {
@@ -1915,6 +2083,12 @@ export async function startAuto(
   }
   pi.events.emit(CMUX_CHANNELS.LOG, { preferences: loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, message: requestedStepMode ? "Step-mode started." : "Auto-mode started.", level: "progress" });
 
+  try {
+    await s.orchestration?.start({ basePath: s.basePath, trigger: "auto-loop" });
+  } catch (err) {
+    debugLog("start-orchestration-start", { error: err instanceof Error ? err.message : String(err) });
+  }
+
   startAutoCommandPolling(s.basePath);
 
   // Dispatch the first unit
@@ -2037,6 +2211,9 @@ export async function dispatchHookUnit(
   }
 
   s.basePath = targetBasePath;
+  if (!s.orchestration) {
+    ensureOrchestrationModule(ctx, pi, s.basePath);
+  }
 
   const hookUnitType = `hook/${hookName}`;
   const hookStartedAt = Date.now();

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

@@ -1,3 +1,5 @@
+// GSD-2 + src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts - Handles provider and agent-end recovery for GSD auto-mode.
+
 import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 
 import { logWarning } from "../workflow-logger.js";
@@ -12,7 +14,7 @@ import { clearPathCache } from "../paths.js";
 import { getAutoDashboardData, getAutoModeStartModel, isAutoActive, pauseAuto, setCurrentDispatchedModelId } from "../auto.js";
 import { getNextFallbackModel, resolveModelWithFallbacksForUnit } from "../preferences.js";
 import { pauseAutoForProviderError } from "../provider-error-pause.js";
-import { isSessionSwitchInFlight, resolveAgentEnd } from "../auto/resolve.js";
+import { isSessionSwitchInFlight, resolveAgentEnd, resolveAgentEndCancelled } from "../auto/resolve.js";
 import { resolveModelId } from "../auto-model-selection.js";
 import { resolveProjectRoot } from "../worktree.js";
 import { clearDiscussionFlowState } from "./write-gate.js";
@@ -56,6 +58,24 @@ function resolveAgentEndBasePath(): string | undefined {
   }
 }
 
+export function _buildAbortedPauseContext(lastMsg: { errorMessage?: unknown }): {
+  message: string;
+  category: "aborted";
+  isTransient: true;
+} {
+  const hasErrorMessage = Object.prototype.hasOwnProperty.call(lastMsg, "errorMessage") && !!lastMsg.errorMessage;
+  return {
+    message: hasErrorMessage ? String(lastMsg.errorMessage) : "Operation aborted",
+    category: "aborted",
+    isTransient: true,
+  };
+}
+
+export function isUserInitiatedAbortMessage(message: string | undefined | null): boolean {
+  if (!message) return false;
+  return /\b(?:claude code process aborted by user|request aborted by user|process aborted by user)\b/i.test(message);
+}
+
 async function pauseTransientWithBackoff(
   cls: ErrorClass,
   pi: ExtensionAPI,
@@ -159,7 +179,7 @@ export async function handleAgentEnd(
       return;
     }
 
-    await pauseAuto(ctx, pi);
+    await pauseAuto(ctx, pi, _buildAbortedPauseContext(lastMsg as { errorMessage?: unknown }));
     return;
   }
   if (lastMsg && "stopReason" in lastMsg && lastMsg.stopReason === "error") {
@@ -167,6 +187,14 @@ export async function handleAgentEnd(
     // is in the assistant message text content. Fall back to content when
     // errorMessage looks uninformative.
     const rawErrorMsg = ("errorMessage" in lastMsg && lastMsg.errorMessage) ? String(lastMsg.errorMessage) : "";
+    if (isUserInitiatedAbortMessage(rawErrorMsg)) {
+      resolveAgentEndCancelled({
+        message: rawErrorMsg,
+        category: "aborted",
+        isTransient: false,
+      });
+      return;
+    }
     const isUseless = !rawErrorMsg || /^(success|ok|true|error|unknown)$/i.test(rawErrorMsg.trim());
     // #3588: When errorMessage is uninformative, extract the real error from
     // the assistant message text content for display purposes only.

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

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Registers DB-backed GSD workflow tools and compatibility aliases.
 import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 import { Text } from "@gsd/pi-tui";
@@ -8,6 +10,7 @@ import { loadWriteGateSnapshot, shouldBlockRootArtifactSaveInSnapshot } from "./
 import { StringEnum } from "@gsd/pi-ai";
 import { logError } from "../workflow-logger.js";
 import { getErrorMessage } from "../error-utils.js";
+import { incrementLegacyTelemetry } from "../legacy-telemetry.js";
 
 async function loadWorkflowExecutors(): Promise<typeof import("../tools/workflow-tool-executors.js")> {
   return import("../tools/workflow-tool-executors.js");
@@ -19,11 +22,19 @@ async function loadWorkflowExecutors(): Promise<typeof import("../tools/workflow
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- toolDef shape matches ToolDefinition but typing it fully requires generics
 function registerAlias(pi: ExtensionAPI, toolDef: any, aliasName: string, canonicalName: string): void {
+  const execute = typeof toolDef.execute === "function"
+    ? async (...args: any[]) => {
+        incrementLegacyTelemetry("legacy.mcpAliasUsed");
+        return toolDef.execute(...args);
+      }
+    : toolDef.execute;
+
   pi.registerTool({
     ...toolDef,
     name: aliasName,
     description: toolDef.description + ` (alias for ${canonicalName} — prefer the canonical name)`,
     promptGuidelines: [`Alias for ${canonicalName} — prefer the canonical name.`],
+    execute,
   });
 }
 

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

@@ -7,7 +7,7 @@ import type { GSDEcosystemBeforeAgentStartHandler } from "../ecosystem/gsd-exten
 import { updateSnapshot } from "../ecosystem/gsd-extension-api.js";
 
 import { buildMilestoneFileName, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
-import { canonicalToolName, clearDiscussionFlowState, isDepthConfirmationAnswer, isQueuePhaseActive, markApprovalGateVerified, markDepthVerified, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
+import { canonicalToolName, clearDiscussionFlowState, isDepthConfirmationAnswer, isQueuePhaseActive, markApprovalGateVerified, markDepthVerified, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, shouldBlockWorktreeWrite, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
 import { resolveManifest } from "../unit-context-manifest.js";
 import { isBlockedStateFile, isBashWriteToStateFile, BLOCKED_WRITE_ERROR } from "../write-intercept.js";
 import { loadFile, saveFile, formatContinue } from "../files.js";
@@ -22,6 +22,7 @@ import { logWarning as safetyLogWarning } from "../workflow-logger.js";
 import { installNotifyInterceptor } from "./notify-interceptor.js";
 import { initNotificationStore } from "../notification-store.js";
 import { initNotificationWidget } from "../notification-widget.js";
+import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { extractSubagentAgentClasses } from "./subagent-input.js";
 import { approvalGateIdForUnit, isExplicitApprovalResponse, shouldPauseForUserApprovalQuestion } from "../user-input-boundary.js";
 
@@ -64,6 +65,16 @@ async function applyDisabledModelProviderPolicy(ctx: ExtensionContext): Promise<
   }
 }
 
+export function resolveNotificationStoreBasePath(cwd: string = process.cwd()): string {
+  return resolveWorktreeProjectRoot(cwd);
+}
+
+function initSessionNotifications(ctx: ExtensionContext): void {
+  initNotificationStore(resolveNotificationStoreBasePath());
+  installNotifyInterceptor(ctx);
+  initNotificationWidget(ctx);
+}
+
 async function writeContextModeCompactionSnapshot(basePath: string): Promise<void> {
   try {
     const { loadEffectiveGSDPreferences } = await import("../preferences.js");
@@ -101,9 +112,7 @@ export function registerHooks(
   ecosystemHandlers: GSDEcosystemBeforeAgentStartHandler[],
 ): void {
   pi.on("session_start", async (_event, ctx) => {
-    initNotificationStore(process.cwd());
-    installNotifyInterceptor(ctx);
-    initNotificationWidget(ctx);
+    initSessionNotifications(ctx);
     if (!isAutoActive()) {
       const { initHealthWidget } = await import("../health-widget.js");
       initHealthWidget(ctx);
@@ -156,8 +165,7 @@ export function registerHooks(
   });
 
   pi.on("session_switch", async (_event, ctx) => {
-    initNotificationStore(process.cwd());
-    installNotifyInterceptor(ctx);
+    initSessionNotifications(ctx);
     resetWriteGateState(process.cwd());
     resetToolCallLoopGuard();
     await resetAskUserQuestionsTurnCache();
@@ -474,6 +482,22 @@ export function registerHooks(
       }
     }
 
+    // ── Worktree-isolation write gate (#5199) ────────────────────────────
+    // Block planning-write tools from landing code at the project root when
+    // git.isolation=worktree but auto-mode hasn't created the milestone
+    // worktree yet. Without this, writes silently orphan outside git history.
+    if (isToolCallEventType("write", event) || isToolCallEventType("edit", event)) {
+      const wtBasePath = resolveWorktreeProjectRoot(dash.basePath ?? discussionBasePath);
+      const wtGuard = shouldBlockWorktreeWrite(
+        event.toolName,
+        event.input.path,
+        wtBasePath,
+        isAutoActive(),
+        dash.currentUnit?.type,
+      );
+      if (wtGuard.block) return wtGuard;
+    }
+
     // ── Single-writer engine: block direct writes to STATE.md ──────────
     // Covers write, edit, and bash tools to prevent bypass vectors.
     if (isToolCallEventType("write", event)) {

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

@@ -1,10 +1,12 @@
-import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 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 { logWarning } from "../workflow-logger.js";
+import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "../worktree-root.js";
 
 /**
  * Regex matching milestone CONTEXT.md file names in both legacy M001
@@ -882,3 +884,135 @@ export function shouldBlockPlanningUnit(
   // avoids breaking gsd_* MCP tools or future safe additions.
   return { block: false };
 }
+
+// ─── Worktree isolation write gate (#5199) ────────────────────────────────
+//
+// When `git.isolation: worktree` is configured, the per-unit commit pipeline
+// only runs inside the auto-mode loop (`auto-post-unit.ts`). If the LLM
+// authors code at the project root before auto-mode is started, those writes
+// land in the working tree but never reach a commit — they're silently
+// orphaned outside git history. This guard blocks those writes at the
+// tool_call seam so the agent receives a clear error instead.
+
+const WORKTREE_GATE_BOOTSTRAP_UNITS = new Set([
+  "discuss-milestone",
+  "plan-milestone",
+  "init",
+]);
+
+function realpathOrResolve(p: string): string {
+  const abs = resolve(p);
+  try {
+    return realpathSync(abs);
+  } catch {
+    // Path doesn't exist (yet) — realpath the deepest existing ancestor so
+    // platforms where /tmp -> /private/tmp don't break containment checks.
+    let dir = abs;
+    const tail: string[] = [];
+    while (dir && dir !== resolve(dir, "..")) {
+      try {
+        const real = realpathSync(dir);
+        return tail.length ? join(real, ...tail.reverse()) : real;
+      } catch {
+        const idx = dir.lastIndexOf(sep);
+        if (idx <= 0) break;
+        tail.push(dir.slice(idx + 1));
+        dir = dir.slice(0, idx) || sep;
+      }
+    }
+    return abs;
+  }
+}
+
+function isPathContained(target: string, container: string): boolean {
+  if (target === container) return true;
+  return target.startsWith(container.endsWith(sep) ? container : container + sep);
+}
+
+/**
+ * Block planning-write tool calls that would land code at the project root
+ * while `git.isolation: worktree` is in effect and auto-mode hasn't created
+ * (or flipped cwd into) the milestone worktree.
+ *
+ * Pure / unit-testable. Callers in `register-hooks.ts` supply the resolved
+ * project root and current auto liveness; this function does no I/O beyond
+ * realpath resolution.
+ *
+ * Allow rules (in order):
+ *   1. Tool isn't a planning-write (write/edit/multi_edit/notebook_edit).
+ *   2. `GSD_DISABLE_WORKTREE_WRITE_GUARD=1` self-hosting bypass.
+ *   3. Isolation mode is not "worktree".
+ *   4. Active unit is a bootstrap unit (discuss-milestone/plan-milestone/init).
+ *   5. Target is inside `<projectRoot>/.gsd/worktrees/` (a real worktree).
+ *   6. Target is inside `<projectRoot>/.gsd/` and isn't masquerading as a
+ *      worktrees sibling (rejects the `.gsd/worktrees-extra/…` prefix trick).
+ *   7. Auto is live AND `effectiveBasePath` is itself a `.gsd/worktrees/…` path.
+ *
+ * Otherwise: block with a message that points the agent at `/gsd` to start
+ * auto-mode.
+ */
+export function shouldBlockWorktreeWrite(
+  toolName: string,
+  targetPath: string,
+  effectiveBasePath: string,
+  isAutoLive: boolean,
+  currentUnitType?: string | null,
+): { block: boolean; reason?: string } {
+  const tool = canonicalToolName(toolName);
+  if (!PLANNING_WRITE_TOOLS.has(tool)) return { block: false };
+  if (process.env.GSD_DISABLE_WORKTREE_WRITE_GUARD === "1") return { block: false };
+  if (getIsolationMode(effectiveBasePath) !== "worktree") return { block: false };
+  if (currentUnitType && WORKTREE_GATE_BOOTSTRAP_UNITS.has(currentUnitType)) return { block: false };
+
+  if (!targetPath) {
+    return {
+      block: true,
+      reason: [
+        `HARD BLOCK: ${tool} called with empty path while \`git.isolation: worktree\` is configured`,
+        `and auto-mode is not active. Refusing to allow writes that cannot be located.`,
+      ].join(" "),
+    };
+  }
+
+  // Resolve the target relative to the project root, then realpath to defeat
+  // symlink-based escapes and prefix tricks (e.g. .gsd/worktrees-extra/).
+  const projectRoot = resolveWorktreeProjectRoot(effectiveBasePath);
+  const absTarget = isAbsolute(targetPath) ? targetPath : resolve(projectRoot, targetPath);
+  const realTarget = realpathOrResolve(absTarget);
+  const realRoot = realpathOrResolve(projectRoot);
+  const realGsd = realpathOrResolve(join(projectRoot, ".gsd"));
+  const realWorktreesDir = realpathOrResolve(join(projectRoot, ".gsd", "worktrees"));
+
+  // Allow writes inside the legitimate worktrees subtree.
+  if (isPathContained(realTarget, realWorktreesDir)) return { block: false };
+
+  // Allow writes to .gsd/ planning artifacts, but reject siblings whose name
+  // starts with "worktrees" (the worktrees-extra prefix trick — case 4).
+  if (isPathContained(realTarget, realGsd)) {
+    const rel = relative(realGsd, realTarget);
+    const firstSeg = rel.split(/[\/\\]/)[0] ?? "";
+    if (!firstSeg.startsWith("worktrees")) return { block: false };
+    // fall through: looks like worktrees<something> sibling — block
+  }
+
+  // Auto is live and the caller is operating inside a worktree path —
+  // host tool's write happens in worktree context; let it through.
+  if (isAutoLive && isGsdWorktreePath(effectiveBasePath)) return { block: false };
+
+  // Block. Provide enough context that the agent can self-correct.
+  const displayTarget = isPathContained(realTarget, realRoot)
+    ? relative(realRoot, realTarget) || "."
+    : realTarget;
+  return {
+    block: true,
+    reason: [
+      `HARD BLOCK: Worktree isolation is configured (\`git.isolation: worktree\`) but auto-mode is`,
+      `not running and the target "${displayTarget}" is not inside \`.gsd/worktrees/<MID>/\`.`,
+      `Code edits at the project root would be lost — only the auto-mode commit pipeline`,
+      `(auto-post-unit) commits work, and it never runs outside the loop.`,
+      `Required action: start auto-mode with \`/gsd\` so the milestone worktree is created,`,
+      `then write inside it. To disable this guard for self-hosting development, set`,
+      `GSD_DISABLE_WORKTREE_WRITE_GUARD=1.`,
+    ].join(" "),
+  };
+}

package/src/resources/extensions/gsd/commands-extract-learnings.ts

@@ -222,14 +222,19 @@ Using the \`write\` tool, persist the full structured report to
 LEARNINGS.md is the full, cited audit trail. Write it first — subsequent steps
 feed from its content.
 
-### Step 3 — Optionally pre-query the memory store for semantic duplicates
+### Step 3 — Run one bounded duplicate check
 
-Before persisting any extracted item in Steps 4–6, you may call
-\`memory_query\` with 2–3 keywords from the item to check whether the
-memory store already holds a semantically equivalent entry at high
-confidence. Skip those items in their respective steps. The memory store
-is the single source of truth for cross-session durable knowledge — no
-other persistence call is part of this flow.
+Before persisting extracted items in Steps 4–6, do at most one duplicate-check
+pass for the durable Decisions, Lessons, and Patterns from this milestone. Use
+the already-written LEARNINGS.md content and call \`memory_query\` once with a
+compact keyword summary for the whole batch. If that result clearly shows a
+semantically equivalent high-confidence memory for an item, mark only that item
+as already captured and skip it in its respective persistence step.
+
+Do not re-read milestone artefacts or repeat memory queries category-by-category
+after this point. The memory store is the single source of truth for
+cross-session durable knowledge — no other persistence call is part of this
+flow.
 
 ### Step 4 — Persist Patterns via \`capture_thought\`
 
@@ -268,11 +273,11 @@ later projection back to a human-visible decisions register stays lossless
 
 ### Step 7 — Deduplication rule (applies to Steps 4, 5, 6)
 
-Before each \`capture_thought\` call, optionally call \`memory_query\` with 2–3
-keywords from the entry. If a semantically equivalent memory is returned at
-high confidence, skip the capture entirely. Prefer skipping a near-duplicate
-over creating a second slightly-different row — redundancy degrades the
-signal.
+Use only the duplicate-check result from Step 3. If that bounded check returned
+a semantically equivalent memory at high confidence for an extracted item, skip
+the capture entirely. Otherwise, persist the item once via \`capture_thought\`.
+Prefer skipping a near-duplicate over creating a second slightly-different row
+— redundancy degrades the signal.
 
 ### Step 8 — Surprises stay only in LEARNINGS.md