gsd-pi 2.79.0-dev.ece5fd8ba → 2.80.0-dev.710c06e97

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

@@ -31,7 +31,7 @@ import { selectAndApplyModel, resolveModelId, clearToolBaseline } from "./auto-m
 import { resetRoutingHistory, recordOutcome } from "./routing-history.js";
 import { resetHookState, runPreDispatchHooks, restoreHookState, clearPersistedHookState, } from "./post-unit-hooks.js";
 import { runGSDDoctor, rebuildState } from "./doctor.js";
-import { preDispatchHealthGate, resetProactiveHealing, setLevelChangeCallback, } from "./doctor-proactive.js";
+import { preDispatchHealthGate, recordHealthSnapshot, resetProactiveHealing, setLevelChangeCallback, } from "./doctor-proactive.js";
 import { clearSkillSnapshot } from "./skill-discovery.js";
 import { captureAvailableSkills, resetSkillTelemetry, } from "./skill-telemetry.js";
 import { getRtkSessionSavings } from "../shared/rtk-session-stats.js";
@@ -43,7 +43,7 @@ import { isAbsolute, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { readFileSync, existsSync, mkdirSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
-import { autoCommitCurrentBranch, captureIntegrationBranch, detectWorktreeName, getCurrentBranch, getMainBranch, setActiveMilestoneId, } from "./worktree.js";
+import { autoCommitCurrentBranch, captureIntegrationBranch, detectWorktreeName, getCurrentBranch, getMainBranch, setActiveMilestoneId, resolveProjectRoot, } from "./worktree.js";
 import { GitServiceImpl } from "./git-service.js";
 import { getPriorSliceCompletionBlocker } from "./dispatch-guard.js";
 import { createAutoWorktree, enterAutoWorktree, enterBranchModeForMilestone, teardownAutoWorktree, isInAutoWorktree, getAutoWorktreePath, mergeMilestoneToMain, autoWorktreeBranch, syncWorktreeStateBack, syncProjectRootToWorktree, checkResourcesStale, escapeStaleWorktree, } from "./auto-worktree.js";
@@ -82,6 +82,7 @@ import { resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSess
 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 { WorktreeResolver, } from "./worktree-resolver.js";
 import { reorderForCaching } from "./prompt-ordering.js";
 export { STUB_RECOVERY_THRESHOLD, NEW_SESSION_TIMEOUT_MS, } from "./auto/session.js";
@@ -904,6 +905,12 @@ export async function stopAuto(ctx, pi, reason) {
         // 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();
     }
@@ -953,6 +960,7 @@ export async function pauseAuto(ctx, _pi, _errorContext) {
             activeRunDir: s.activeRunDir,
             autoStartTime: s.autoStartTime,
             milestoneLock: s.sessionMilestoneLock ?? undefined,
+            pauseReason: _errorContext?.message,
         };
         setRuntimeKv("global", "", PAUSED_SESSION_KV_KEY, pausedMeta);
     }
@@ -992,6 +1000,12 @@ export async function pauseAuto(ctx, _pi, _errorContext) {
     // Unblock pending unitPromise so autoLoop exits cleanly (#1799)
     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();
@@ -1041,6 +1055,132 @@ function buildResolverDeps() {
 function buildResolver() {
     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, _pi, dispatchBasePath, runtimeBasePath = resolveProjectRoot(dispatchBasePath)) {
+    const flowId = `auto-orchestrator-${Date.now()}`;
+    let seq = 0;
+    const deps = {
+        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", 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, pi, basePath) {
+    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.
@@ -1398,6 +1538,7 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
             // s.basePath may have been updated to a worktree path by enterMilestone.
             rebuildScope(s.basePath, s.currentMilestoneId);
         }
+        ensureOrchestrationModule(ctx, pi, s.basePath || base);
         registerSigtermHandler(lockBase());
         ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
         ctx.ui.setWidget("gsd-health", undefined);
@@ -1457,6 +1598,12 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
             clearPausedSession("paused-session DB cleanup failed (resume activation)");
         }
         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,
@@ -1482,6 +1629,7 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
     // 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 {
@@ -1492,6 +1640,12 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         logWarning("engine", `cmux sync failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
     }
     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
     await runAutoLoopWithUok({
@@ -1576,6 +1730,9 @@ export async function dispatchHookUnit(ctx, pi, hookName, triggerUnitType, trigg
         s.pendingQuickTasks = [];
     }
     s.basePath = targetBasePath;
+    if (!s.orchestration) {
+        ensureOrchestrationModule(ctx, pi, s.basePath);
+    }
     const hookUnitType = `hook/${hookName}`;
     const hookStartedAt = Date.now();
     s.currentUnit = {

package/dist/resources/extensions/gsd/bootstrap/agent-end-recovery.js

@@ -1,10 +1,11 @@
+// GSD-2 + src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts - Handles provider and agent-end recovery for GSD auto-mode.
 import { logWarning } from "../workflow-logger.js";
 import { checkDeepProjectSetupAfterTurn, checkAutoStartAfterDiscuss, maybeHandleReadyPhraseWithoutFiles, maybeHandleEmptyIntentTurn, resetEmptyTurnCounter, } from "../guided-flow.js";
 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";
@@ -39,6 +40,19 @@ function resolveAgentEndBasePath() {
         return undefined;
     }
 }
+export function _buildAbortedPauseContext(lastMsg) {
+    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) {
+    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, pi, ctx, errorDetail, isRateLimit) {
     retryState.consecutiveTransientCount += 1;
     const baseRetryAfterMs = "retryAfterMs" in cls ? cls.retryAfterMs : 15_000;
@@ -134,7 +148,7 @@ export async function handleAgentEnd(pi, event, ctx) {
             }
             return;
         }
-        await pauseAuto(ctx, pi);
+        await pauseAuto(ctx, pi, _buildAbortedPauseContext(lastMsg));
         return;
     }
     if (lastMsg && "stopReason" in lastMsg && lastMsg.stopReason === "error") {
@@ -142,6 +156,14 @@ export async function handleAgentEnd(pi, event, ctx) {
         // 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/dist/resources/extensions/gsd/bootstrap/db-tools.js

@@ -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 { Text } from "@gsd/pi-tui";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
@@ -5,6 +7,7 @@ import { ensureDbOpen } from "./dynamic-tools.js";
 import { loadWriteGateSnapshot, shouldBlockRootArtifactSaveInSnapshot } from "./write-gate.js";
 import { StringEnum } from "@gsd/pi-ai";
 import { logError } from "../workflow-logger.js";
+import { incrementLegacyTelemetry } from "../legacy-telemetry.js";
 async function loadWorkflowExecutors() {
     return import("../tools/workflow-tool-executors.js");
 }
@@ -14,11 +17,18 @@ async function loadWorkflowExecutors() {
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- toolDef shape matches ToolDefinition but typing it fully requires generics
 function registerAlias(pi, toolDef, aliasName, canonicalName) {
+    const execute = typeof toolDef.execute === "function"
+        ? async (...args) => {
+            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,
     });
 }
 function requirementRootWriteGuard(operation) {

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -2,7 +2,7 @@ import { join } from "node:path";
 import { isToolCallEventType } from "@gsd/pi-coding-agent";
 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";
@@ -16,6 +16,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";
 // Skip the welcome screen on the very first session_start — cli.ts already
@@ -51,6 +52,14 @@ async function applyDisabledModelProviderPolicy(ctx) {
         // Non-fatal: keep default provider visibility if preferences cannot be loaded.
     }
 }
+export function resolveNotificationStoreBasePath(cwd = process.cwd()) {
+    return resolveWorktreeProjectRoot(cwd);
+}
+function initSessionNotifications(ctx) {
+    initNotificationStore(resolveNotificationStoreBasePath());
+    installNotifyInterceptor(ctx);
+    initNotificationWidget(ctx);
+}
 async function writeContextModeCompactionSnapshot(basePath) {
     try {
         const { loadEffectiveGSDPreferences } = await import("../preferences.js");
@@ -81,9 +90,7 @@ async function writeContextModeCompactionSnapshot(basePath) {
 }
 export function registerHooks(pi, ecosystemHandlers) {
     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);
@@ -135,8 +142,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
     });
     pi.on("session_switch", async (_event, ctx) => {
-        initNotificationStore(process.cwd());
-        installNotifyInterceptor(ctx);
+        initSessionNotifications(ctx);
         resetWriteGateState(process.cwd());
         resetToolCallLoopGuard();
         await resetAskUserQuestionsTurnCache();
@@ -426,6 +432,16 @@ export function registerHooks(pi, ecosystemHandlers) {
                     return planningGuard;
             }
         }
+        // ── 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/dist/resources/extensions/gsd/bootstrap/write-gate.js

@@ -1,7 +1,9 @@
-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 { logWarning } from "../workflow-logger.js";
+import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "../worktree-root.js";
 /**
  * Regex matching milestone CONTEXT.md file names in both legacy M001
  * and unique M001-abc123 formats. Exported so regex-hardening tests
@@ -728,3 +730,129 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
     // 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) {
+    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 = [];
+        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, container) {
+    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, targetPath, effectiveBasePath, isAutoLive, currentUnitType) {
+    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/dist/resources/extensions/gsd/commands-ship.js

@@ -1,9 +1,5 @@
-/**
- * GSD Command — /gsd ship
- *
- * Creates a PR from milestone artifacts: generates title + body from
- * roadmap, slice summaries, and metrics, then opens via `gh pr create`.
- */
+// Project/App: GSD-2
+// File Purpose: Ship command for creating pull requests from GSD milestone evidence.
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { readFile } from "node:fs/promises";
@@ -14,6 +10,7 @@ import { nativeGetCurrentBranch, nativeDetectMainBranch } from "./native-git-bri
 import { formatDuration } from "../shared/format-utils.js";
 import { parseEvalReviewFrontmatter } from "./eval-review-schema.js";
 import { currentDirectoryRoot } from "./commands/context.js";
+import { buildPrEvidence } from "./pr-evidence.js";
 function git(basePath, args) {
     return execFileSync("git", args, { cwd: basePath, encoding: "utf-8" }).trim();
 }
@@ -114,66 +111,46 @@ export async function checkSliceEvalReview(basePath, milestoneId, sliceId) {
     };
 }
 function generatePRContent(basePath, milestoneId, milestoneTitle) {
-    const title = `feat: ${milestoneTitle || milestoneId}`;
-    const sections = [];
-    // TL;DR
-    sections.push("## TL;DR\n");
-    sections.push(`**What:** Ship milestone ${milestoneId} — ${milestoneTitle || "(untitled)"}`);
-    sections.push(`**Why:** Milestone work complete, ready for review.`);
-    sections.push(`**How:** See slice summaries below.\n`);
-    // What — slice summaries
     const summaries = collectSliceSummaries(basePath, milestoneId);
-    if (summaries.length > 0) {
-        sections.push("## What\n");
-        sections.push(summaries.join("\n\n"));
-        sections.push("");
-    }
-    // Roadmap status
+    const roadmapItems = [];
     const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
     if (roadmapPath && existsSync(roadmapPath)) {
         try {
             const roadmap = readFileSync(roadmapPath, "utf-8");
             const checkboxLines = roadmap.split("\n").filter((l) => /^\s*-\s*\[[ x]\]/.test(l));
-            if (checkboxLines.length > 0) {
-                sections.push("## Roadmap\n");
-                sections.push(checkboxLines.join("\n"));
-                sections.push("");
-            }
+            roadmapItems.push(...checkboxLines);
         }
         catch {
             // non-fatal
         }
     }
-    // Metrics
+    const metrics = [];
     const ledger = getLedger();
     const units = ledger?.units ?? loadLedgerFromDisk(basePath)?.units ?? [];
     if (units.length > 0) {
         const totals = getProjectTotals(units);
         const byModel = aggregateByModel(units);
-        sections.push("## Metrics\n");
-        sections.push(`- **Units executed:** ${units.length}`);
-        sections.push(`- **Total cost:** ${formatCost(totals.cost)}`);
-        sections.push(`- **Tokens:** ${formatTokenCount(totals.tokens.input)} input / ${formatTokenCount(totals.tokens.output)} output`);
+        metrics.push(`**Units executed:** ${units.length}`);
+        metrics.push(`**Total cost:** ${formatCost(totals.cost)}`);
+        metrics.push(`**Tokens:** ${formatTokenCount(totals.tokens.input)} input / ${formatTokenCount(totals.tokens.output)} output`);
         if (totals.duration > 0) {
-            sections.push(`- **Duration:** ${formatDuration(totals.duration)}`);
+            metrics.push(`**Duration:** ${formatDuration(totals.duration)}`);
         }
         if (byModel.length > 0) {
-            sections.push(`- **Models:** ${byModel.map((m) => `${m.model} (${m.units} units)`).join(", ")}`);
+            metrics.push(`**Models:** ${byModel.map((m) => `${m.model} (${m.units} units)`).join(", ")}`);
         }
-        sections.push("");
-    }
-    // Change type checklist
-    sections.push("## Change type\n");
-    sections.push("- [x] `feat` — New feature or capability");
-    sections.push("- [ ] `fix` — Bug fix");
-    sections.push("- [ ] `refactor` — Code restructuring");
-    sections.push("- [ ] `test` — Adding or updating tests");
-    sections.push("- [ ] `docs` — Documentation only");
-    sections.push("- [ ] `chore` — Build, CI, or tooling changes\n");
-    // AI disclosure
-    sections.push("---\n");
-    sections.push("*This PR was prepared with AI assistance (GSD auto-mode).*");
-    return { title, body: sections.join("\n") };
+    }
+    return buildPrEvidence({
+        milestoneId,
+        milestoneTitle,
+        changeType: "feat",
+        summaries,
+        roadmapItems,
+        metrics,
+        testsRun: ["Run `npm run verify:pr` before marking this PR ready."],
+        rollbackNotes: ["Revert the merge commit or close the PR before merge if review finds a regression."],
+        how: "Generated from GSD milestone slice summaries, roadmap status, and local metrics.",
+    });
 }
 export async function handleShip(args, ctx, _pi) {
     const basePath = currentDirectoryRoot();