gsd-pi 2.82.0 → 3.0.0-dev.04f5ccf82

package/src/resources/extensions/gsd/verification-gate.ts

@@ -4,7 +4,7 @@
 // First non-empty source wins.
 
 import { spawnSync, type SpawnSyncReturns } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, type Dirent } from "node:fs";
 import { join, basename } from "node:path";
 import type { AuditWarning, RuntimeError, VerificationCheck, VerificationResult } from "./types.js";
 import { DEFAULT_COMMAND_TIMEOUT_MS } from "./constants.js";
@@ -44,7 +44,9 @@ const PACKAGE_SCRIPT_KEYS = ["typecheck", "lint", "test"] as const;
  *   1. Explicit preference commands
  *   2. Task plan verify field (split on &&)
  *   3. package.json scripts (typecheck, lint, test)
- *   4. None found
+ *   4. Python pytest project markers
+ *   5. Dependency-free Node test files
+ *   6. None found
  */
 export function discoverCommands(options: DiscoverCommandsOptions): DiscoveredCommands {
   // 1. Preference commands
@@ -91,10 +93,89 @@ export function discoverCommands(options: DiscoverCommandsOptions): DiscoveredCo
     }
   }
 
-  // 4. Nothing found
+  const pythonCommand = discoverPythonPytestCommand(options.cwd);
+  if (pythonCommand) {
+    return { commands: [pythonCommand], source: "python-project" };
+  }
+
+  const nodeTestCommand = discoverNodeTestFileCommand(options.cwd);
+  if (nodeTestCommand) {
+    return { commands: [nodeTestCommand], source: "node-test-file" };
+  }
+
+  // 6. Nothing found
   return { commands: [], source: "none" };
 }
 
+function discoverNodeTestFileCommand(cwd: string): string | null {
+  let entries: Dirent[];
+  try {
+    entries = readdirSync(cwd, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  const testFile = entries
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name)
+    .filter((name) => /^test-[A-Za-z0-9._-]+\.js$|^[A-Za-z0-9._-]+\.test\.js$/.test(name))
+    .sort()[0];
+
+  return testFile ? `node ${testFile}` : null;
+}
+
+function discoverPythonPytestCommand(cwd: string): string | null {
+  const hasPythonTestFiles = hasPythonTests(join(cwd, "tests"));
+  const hasPytestConfig = existsSync(join(cwd, "pytest.ini"));
+  const pyprojectPath = join(cwd, "pyproject.toml");
+  const hasPyproject = existsSync(pyprojectPath);
+
+  if (!hasPythonTestFiles && !hasPytestConfig && !hasPyproject) {
+    return null;
+  }
+
+  if (hasPytestConfig || hasPythonTestFiles) {
+    return "python3 -m pytest";
+  }
+
+  try {
+    const pyproject = readFileSync(pyprojectPath, "utf-8");
+    if (
+      pyproject.includes("[tool.pytest]") ||
+      pyproject.includes("[tool.pytest.") ||
+      pyproject.includes("[pytest]") ||
+      pyproject.includes("[tool:pytest]")
+    ) {
+      return "python3 -m pytest";
+    }
+  } catch {
+    // Ignore unreadable pyproject.toml and fall through.
+  }
+
+  return null;
+}
+
+function hasPythonTests(dir: string): boolean {
+  let entries: Dirent[];
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+
+  for (const entry of entries) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory() && hasPythonTests(path)) {
+      return true;
+    }
+    if (entry.isFile() && /^test_.*\.py$|^.*_test\.py$/.test(entry.name)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
 // ─── Failure Context Formatting ──────────────────────────────────────────────
 
 /** Maximum chars of stderr to include per failed check in failure context. */
@@ -144,7 +225,7 @@ export function formatFailureContext(result: VerificationResult): string {
 // ─── Gate Execution ─────────────────────────────────────────────────────────
 
 /** Characters that indicate shell injection when found in a command string. */
-const SHELL_INJECTION_PATTERN = /[;|`]|\$\(/;
+const SHELL_INJECTION_PATTERN = /[;|`<>]|\$\(/;
 
 /**
  * Known executable first-tokens that are safe to run.
@@ -182,6 +263,7 @@ const KNOWN_COMMAND_PREFIXES = new Set([
  * Heuristics (any true → prose-like):
  *   1. First token starts with an uppercase letter and the string has 4+ words
  *   2. String contains commas followed by spaces (prose clause structure)
+ *   3. First token has no ASCII letters or digits and the string has 4+ words
  */
 export function isLikelyCommand(cmd: string): boolean {
   const trimmed = cmd.trim();
@@ -208,6 +290,9 @@ export function isLikelyCommand(cmd: string): boolean {
   // First token has uppercase letters and no path separators → prose
   if (/[A-Z]/.test(firstToken) && !firstToken.includes("/")) return false;
 
+  // Non-ASCII prose with multiple words should not be executed as a command.
+  if (!/[A-Za-z0-9]/.test(firstToken) && tokens.length >= 4) return false;
+
   return true;
 }
 
@@ -215,9 +300,19 @@ export function isLikelyCommand(cmd: string): boolean {
  * Validate a command string for obvious shell injection patterns.
  * Returns the command unchanged if safe, or null if suspicious.
  */
+export function validateVerificationCommand(cmd: string): { ok: true } | { ok: false; reason: string } {
+  if (SHELL_INJECTION_PATTERN.test(cmd)) {
+    return { ok: false, reason: "contains shell control syntax such as pipes, redirects, semicolons, backticks, or command substitution" };
+  }
+  if (!isLikelyCommand(cmd)) {
+    return { ok: false, reason: "does not look like a runnable command" };
+  }
+  return { ok: true };
+}
+
 function sanitizeCommand(cmd: string): string | null {
-  if (SHELL_INJECTION_PATTERN.test(cmd)) return null;
-  if (!isLikelyCommand(cmd)) return null;
+  const validation = validateVerificationCommand(cmd);
+  if (!validation.ok) return null;
   return cmd;
 }
 
@@ -229,6 +324,30 @@ export interface RunVerificationGateOptions {
   commandTimeoutMs?: number;
 }
 
+export interface VerificationTarget {
+  id: string;
+  cwd: string;
+  preferenceCommands?: string[];
+}
+
+function mergeDiscoverySource(
+  sources: VerificationResult["discoverySource"][],
+): VerificationResult["discoverySource"] {
+  if (sources.length === 0) return "none";
+  const first = sources[0];
+  if (sources.every((source) => source === first)) return first;
+  const precedence: VerificationResult["discoverySource"][] = [
+    "preference",
+    "task-plan",
+    "package-json",
+    "python-project",
+  ];
+  for (const source of precedence) {
+    if (sources.includes(source)) return source;
+  }
+  return "none";
+}
+
 /**
  * Run the verification gate: discover commands, execute each via spawnSync,
  * and return a structured result.
@@ -305,6 +424,51 @@ export function runVerificationGate(options: RunVerificationGateOptions): Verifi
   };
 }
 
+export function runVerificationGateForTargets(options: {
+  targets: VerificationTarget[];
+  preferenceCommands?: string[];
+  taskPlanVerify?: string;
+  commandTimeoutMs?: number;
+}): VerificationResult {
+  const timestamp = Date.now();
+  if (options.targets.length === 0) {
+    return {
+      passed: true,
+      checks: [],
+      discoverySource: "none",
+      timestamp,
+    };
+  }
+
+  const checks: VerificationCheck[] = [];
+  const sources: VerificationResult["discoverySource"][] = [];
+  let passed = true;
+
+  for (const target of options.targets) {
+    const result = runVerificationGate({
+      cwd: target.cwd,
+      preferenceCommands: options.preferenceCommands ?? target.preferenceCommands,
+      taskPlanVerify: options.taskPlanVerify,
+      commandTimeoutMs: options.commandTimeoutMs,
+    });
+    passed = passed && result.passed;
+    sources.push(result.discoverySource);
+    for (const check of result.checks) {
+      checks.push({
+        ...check,
+        command: target.id === "project" ? check.command : `[${target.id}] ${check.command}`,
+      });
+    }
+  }
+
+  return {
+    passed,
+    checks,
+    discoverySource: mergeDiscoverySource(sources),
+    timestamp,
+  };
+}
+
 // ─── Runtime Error Capture ──────────────────────────────────────────────────
 
 /** Maximum characters of browser console text to retain per entry. */

package/src/resources/extensions/gsd/verification-verdict.ts

@@ -0,0 +1,47 @@
+// Project/App: GSD-2
+// File Purpose: Host-owned verification verdict policy for auto-mode units.
+
+import type { VerificationResult as VerificationGateResult } from "./types.js";
+
+export type VerificationVerdictReason =
+  | "passed"
+  | "no-host-checks"
+  | "checks-failed";
+
+export interface VerificationVerdict {
+  passed: boolean;
+  reason: VerificationVerdictReason;
+  retryable: boolean;
+  failureContext: string;
+}
+
+export function decideVerificationVerdict(
+  unitType: string,
+  result: VerificationGateResult,
+): VerificationVerdict {
+  if (unitType === "execute-task" && result.discoverySource === "none" && result.checks.length === 0) {
+    return {
+      passed: false,
+      reason: "no-host-checks",
+      retryable: false,
+      failureContext:
+        "No runnable host-owned verification command was discovered. Add project verification_commands or a runnable task-plan Verify command before completing this execute-task.",
+    };
+  }
+
+  if (!result.passed) {
+    return {
+      passed: false,
+      reason: "checks-failed",
+      retryable: true,
+      failureContext: "",
+    };
+  }
+
+  return {
+    passed: true,
+    reason: "passed",
+    retryable: false,
+    failureContext: "",
+  };
+}

package/src/resources/extensions/gsd/watch/header-renderer.ts

@@ -63,10 +63,16 @@ function rightAlign(left: string, right: string, width: number): string {
   return truncateToWidth(left + " ".repeat(gap) + right, width, "");
 }
 
-function frameLine(content: string, width: number): string {
-  if (width < 3) return truncateToWidth(content, Math.max(0, width), "");
-  const innerWidth = Math.max(0, width - 2);
-  return `${color("│", colors.border)}${padVisible(content, innerWidth)}${color("│", colors.border)}`;
+/** Left indent for borderless panel content. */
+const PANEL_INDENT = "  ";
+
+/**
+ * Indent a content line for the borderless header. No side bars are drawn, so
+ * terminal text selection copies clean content instead of `│` chars.
+ */
+function panelLine(content: string, width: number): string {
+  const innerWidth = Math.max(0, width - PANEL_INDENT.length);
+  return PANEL_INDENT + truncateToWidth(content, innerWidth, "");
 }
 
 // ─── Data Readers ─────────────────────────────────────────────────────────────
@@ -79,8 +85,9 @@ function frameLine(content: string, width: number): string {
 export function readModelFromPreferences(): string {
   try {
     const prefs = loadEffectiveGSDPreferences();
-    if (!prefs?.preferences.models) return "default";
-    const m = prefs.preferences.models as Record<string, unknown>;
+    const models = prefs?.preferences?.models;
+    if (!models) return "default";
+    const m = models as Record<string, unknown>;
     // Try common phases in priority order
     for (const phase of ["execution", "planning", "research", "discuss", "subagent"]) {
       const val = m[phase];
@@ -236,11 +243,13 @@ export function formatMcpRow(servers: string[], width: number): string {
 export function renderHeaderLines(data: HeaderData, width: number): string[] {
   if (width < 40) return renderStackedHeader(data, width);
   const outerWidth = width;
-  const innerWidth = Math.max(0, outerWidth - 2);
+  const innerWidth = Math.max(0, outerWidth - PANEL_INDENT.length);
   const logoLines = GSD_LOGO;
   const logoWidth = Math.max(...logoLines.map((line) => visibleWidth(line)));
-  const gap = ` ${color("│", colors.dim)} `;
-  const panelWidth = innerWidth - logoWidth - visibleWidth(gap);
+  // Plain spaces, not a `│` divider — a vertical bar here would be dragged
+  // into every copied logo row.
+  const gap = "   ";
+  const panelWidth = innerWidth - logoWidth - gap.length;
 
   if (panelWidth < 44) {
     return renderStackedHeader(data, width);
@@ -280,14 +289,14 @@ export function renderHeaderLines(data: HeaderData, width: number): string[] {
     ),
   ];
 
-  const lines = [
-    color("╭" + "─".repeat(Math.max(0, outerWidth - 2)) + "╮", colors.border),
-  ];
+  const lines: string[] = [];
   for (let i = 0; i < logoLines.length; i++) {
     const logo = padVisible(color(logoLines[i], colors.border), logoWidth);
-    lines.push(frameLine(`${logo}${gap}${panelLines[i] ?? ""}`, outerWidth));
+    lines.push(panelLine(`${logo}${gap}${panelLines[i] ?? ""}`, outerWidth));
   }
-  lines.push(color("╰" + "─".repeat(Math.max(0, outerWidth - 2)) + "╯", colors.border));
+  // Closing rule only — it sits on its own line, so selecting header content
+  // never picks it up.
+  lines.push(color("─".repeat(Math.max(0, outerWidth)), colors.border));
   return lines;
 }
 
@@ -299,22 +308,24 @@ function renderStackedHeader(data: HeaderData, width: number): string[] {
   if (outerWidth < 3) {
     return [color(truncateToWidth("GSD", outerWidth, ""), colors.accent)];
   }
-  const lines: string[] = [color("╭" + "─".repeat(Math.max(0, outerWidth - 2)) + "╮", colors.border)];
+  const innerWidth = Math.max(0, outerWidth - PANEL_INDENT.length);
+  const lines: string[] = [];
 
   // Title
-  lines.push(frameLine(`${color("GSD", colors.accent)} ${bold(color("Project Console", colors.text))}`, outerWidth));
+  lines.push(panelLine(`${color("GSD", colors.accent)} ${bold(color("Project Console", colors.text))}`, outerWidth));
 
   // Info
-  lines.push(frameLine(formatInfoLine("Project", data.directory, outerWidth - 2), outerWidth));
-  lines.push(frameLine(formatInfoLine("Command", "/gsd start", outerWidth - 2), outerWidth));
-  lines.push(frameLine(formatInfoLine("Branch", data.branch, outerWidth - 2), outerWidth));
-  lines.push(frameLine(formatInfoLine("Model", data.model, outerWidth - 2), outerWidth));
+  lines.push(panelLine(formatInfoLine("Project", data.directory, innerWidth), outerWidth));
+  lines.push(panelLine(formatInfoLine("Command", "/gsd start", innerWidth), outerWidth));
+  lines.push(panelLine(formatInfoLine("Branch", data.branch, innerWidth), outerWidth));
+  lines.push(panelLine(formatInfoLine("Model", data.model, innerWidth), outerWidth));
 
   // MCP
-  const mcpRow = formatMcpRow(data.mcpServers, Math.max(1, outerWidth - 7));
-  if (mcpRow) lines.push(frameLine(`${color("MCP", colors.muted)} ${mcpRow}`, outerWidth));
-  lines.push(frameLine(`${color("/gsd to begin", colors.accent)}  ${color("/gsd help", colors.muted)}`, outerWidth));
-  lines.push(color("╰" + "─".repeat(Math.max(0, outerWidth - 2)) + "╯", colors.border));
+  const mcpRow = formatMcpRow(data.mcpServers, Math.max(1, innerWidth - 5));
+  if (mcpRow) lines.push(panelLine(`${color("MCP", colors.muted)} ${mcpRow}`, outerWidth));
+  lines.push(panelLine(`${color("/gsd to begin", colors.accent)}  ${color("/gsd help", colors.muted)}`, outerWidth));
+  // Closing rule on its own line keeps header content copy-clean.
+  lines.push(color("─".repeat(outerWidth), colors.border));
 
   return lines;
 }

package/src/resources/extensions/gsd/workflow-logger.ts

@@ -65,6 +65,10 @@ export type LogComponent =
   | "memory-embeddings" // Memory layer embedding generation
   | "memory-ingest"     // Memory layer ingestion pipeline
   | "memory-backfill"   // ADR-013: decisions->memories backfill
+  | "memory-consolidation" // ADR-013: legacy memory surface gap scanner
+  | "knowledge-backfill" // ADR-013: KNOWLEDGE.md->memories backfill
+  | "knowledge-projection" // ADR-013: KNOWLEDGE.md projection renderer
+  | "knowledge-capture" // ADR-013: KNOWLEDGE.md capture pipeline
   | "memory-store"      // Memory CRUD layer — surfaces SQLite/store-level faults (#4967)
   | "context-mode"     // Context-mode exec sandbox and compaction snapshot
   | "preflight"        // Clean-root preflight gate at milestone completion

package/src/resources/extensions/gsd/workflow-manifest.ts

@@ -109,6 +109,7 @@ export function snapshotState(): StateManifest {
     proof_level: (r["proof_level"] as string) ?? "",
     integration_closure: (r["integration_closure"] as string) ?? "",
     observability_impact: (r["observability_impact"] as string) ?? "",
+    target_repositories: JSON.parse((r["target_repositories"] as string) || "[]"),
     sequence: toNumeric(r["sequence"], 0) as number,
     replan_triggered_at: (r["replan_triggered_at"] as string) ?? null,
     is_sketch: toNumeric(r["is_sketch"], 0) as number,
@@ -141,6 +142,7 @@ export function snapshotState(): StateManifest {
     expected_output: JSON.parse((r["expected_output"] as string) || "[]"),
     observability_impact: (r["observability_impact"] as string) ?? "",
     full_plan_md: (r["full_plan_md"] as string) ?? "",
+    target_repositories: JSON.parse((r["target_repositories"] as string) || "[]"),
     sequence: toNumeric(r["sequence"], 0) as number,
     blocker_source: (r["blocker_source"] as string) ?? "",
     escalation_pending: toNumeric(r["escalation_pending"], 0) as number,

package/src/resources/extensions/gsd/workflow-mcp.ts

@@ -18,6 +18,7 @@ export interface WorkflowCapabilityOptions {
   unitType?: string;
   authMode?: "apiKey" | "oauth" | "externalCli" | "none";
   baseUrl?: string;
+  activeTools?: string[];
 }
 
 const MCP_WORKFLOW_TOOL_SURFACE = new Set([
@@ -383,6 +384,15 @@ function hasAskUserQuestionsTool(activeTools: string[]): boolean {
   });
 }
 
+function hasRequiredTool(requiredTool: string, activeTools: string[]): boolean {
+  return activeTools.some((toolName) => {
+    if (toolName === requiredTool) return true;
+    if (!toolName.startsWith("mcp__")) return false;
+    const toolSeparator = toolName.indexOf("__", "mcp__".length);
+    return toolSeparator >= 0 && toolName.slice(toolSeparator + 2) === requiredTool;
+  });
+}
+
 function workflowMcpStructuredQuestionsOptIn(env: NodeJS.ProcessEnv = process.env): boolean {
   const value = env.GSD_WORKFLOW_MCP_STRUCTURED_QUESTIONS;
   return value === "1" || value === "true";
@@ -423,8 +433,15 @@ export function getWorkflowTransportSupportError(
     return `Provider ${providerLabel} cannot run ${surface}${unitLabel}: the GSD workflow MCP server is not configured or discoverable. Detected Claude Code model but no workflow MCP. Please run /gsd mcp init . from your project root. You can also configure GSD_WORKFLOW_MCP_COMMAND, build packages/mcp-server/dist/cli.js, or install gsd-mcp-server on PATH.`;
   }
 
-  const missing = [...new Set(requiredTools)].filter((tool) => !MCP_WORKFLOW_TOOL_SURFACE.has(tool));
+  const uniqueRequired = [...new Set(requiredTools)];
+  const missing = (options.activeTools && options.activeTools.length > 0)
+    ? uniqueRequired.filter((tool) => !hasRequiredTool(tool, options.activeTools!))
+    : uniqueRequired.filter((tool) => !MCP_WORKFLOW_TOOL_SURFACE.has(tool));
   if (missing.length === 0) return null;
 
+  if (options.activeTools && options.activeTools.length > 0) {
+    return `Provider ${providerLabel} cannot run ${surface}${unitLabel}: this unit requires ${missing.join(", ")}, but the active runtime toolset currently exposes only ${options.activeTools.slice().sort().join(", ")}.`;
+  }
+
   return `Provider ${providerLabel} cannot run ${surface}${unitLabel}: this unit requires ${missing.join(", ")}, but the workflow MCP transport currently exposes only ${Array.from(MCP_WORKFLOW_TOOL_SURFACE).sort().join(", ")}.`;
 }

package/src/resources/extensions/gsd/workflow-projections.ts

@@ -195,11 +195,11 @@ export function renderSummaryContent(
 
   // ── Frontmatter (YAML list format, matches parseSummary() expectations) ──
   const keyFilesYaml = taskRow.key_files && taskRow.key_files.length > 0
-    ? taskRow.key_files.map(f => `  - ${f}`).join("\n")
-    : "  - (none)";
+    ? `\n${taskRow.key_files.map(f => `  - ${f}`).join("\n")}`
+    : " []";
   const keyDecisionsYaml = taskRow.key_decisions && taskRow.key_decisions.length > 0
-    ? taskRow.key_decisions.map(d => `  - ${d}`).join("\n")
-    : "  - (none)";
+    ? `\n${taskRow.key_decisions.map(d => `  - ${d}`).join("\n")}`
+    : " []";
 
   // Derive verification_result from evidence if available
   const evidenceList = evidence ?? [];
@@ -230,10 +230,8 @@ export function renderSummaryContent(
 id: ${taskRow.id}
 parent: ${sliceId}
 milestone: ${milestoneId}
-key_files:
-${keyFilesYaml}
-key_decisions:
-${keyDecisionsYaml}
+key_files:${keyFilesYaml}
+key_decisions:${keyDecisionsYaml}
 duration: ${taskRow.duration || ""}
 verification_result: ${verificationResult}
 completed_at: ${taskRow.completed_at || ""}

package/src/resources/extensions/gsd/worktree-lifecycle.ts

@@ -23,6 +23,7 @@ import { join } from "node:path";
 
 import type { AutoSession } from "./auto/session.js";
 import { debugLog } from "./debug-logger.js";
+import { logWarning } from "./workflow-logger.js";
 import { emitJournalEvent } from "./journal.js";
 import { emitWorktreeCreated, emitWorktreeMerged } from "./worktree-telemetry.js";
 import {
@@ -76,6 +77,13 @@ import {
   teardownAutoWorktree,
 } from "./auto-worktree.js";
 
+const recentWorktreeMergeFailures = new Map<string, number>();
+const MERGE_FAILURE_DEDUPE_MS = 60_000;
+
+export function resetRecentWorktreeMergeFailuresForTest(): void {
+  recentWorktreeMergeFailures.clear();
+}
+
 // ─── Types ───────────────────────────────────────────────────────────────
 
 export interface NotifyCtx {
@@ -513,19 +521,9 @@ export function _enterMilestoneCore(
     };
   }
 
-  if (s.isolationDegraded) {
-    debugLog("WorktreeLifecycle", {
-      action: "enterMilestone",
-      milestoneId,
-      skipped: true,
-      reason: "isolation-degraded",
-    });
-    return { ok: false, reason: "isolation-degraded" };
-  }
-
   // Phase B: claim a milestone lease before any worktree mutation. Two
   // workers cannot enter the same milestone concurrently. Best-effort:
-  // skip if no worker registered (single-worker fallback) or DB
+  // warn if no worker registered (single-worker fallback) or skip if DB
   // unavailable; reuse existing lease if we already hold it on this
   // milestone (re-entry within the same session).
   if (s.workerId) {
@@ -618,6 +616,11 @@ export function _enterMilestoneCore(
         });
       }
     }
+  } else {
+    logWarning(
+      "worktree",
+      `enterMilestone(${milestoneId}) ran before auto worker registration; milestone lease was not claimed.`,
+    );
   }
 
   // Resolve the project root for worktree operations via shared helper.
@@ -626,6 +629,38 @@ export function _enterMilestoneCore(
   const basePath = resolveWorktreeProjectRoot(s.basePath, s.originalBasePath);
   const mode = getIsolationMode(basePath);
 
+  if (s.isolationDegraded) {
+    if (mode === "worktree") {
+      try {
+        lifecycleEnterBranchMode(deps, basePath, milestoneId);
+        s.basePath = basePath;
+        rebuildGitService(s, deps);
+        invalidateAllCaches();
+        ctx.notify(
+          `Worktree isolation is degraded. Fell back to branch milestone/${milestoneId}.`,
+          "warning",
+        );
+        return { ok: true, mode: "branch", path: basePath };
+      } catch (err) {
+        debugLog("WorktreeLifecycle", {
+          action: "enterMilestone",
+          milestoneId,
+          skipped: true,
+          reason: "isolation-degraded",
+          fallback: "branch-failed",
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+    debugLog("WorktreeLifecycle", {
+      action: "enterMilestone",
+      milestoneId,
+      skipped: true,
+      reason: "isolation-degraded",
+    });
+    return { ok: false, reason: "isolation-degraded" };
+  }
+
   if (mode === "none") {
     debugLog("WorktreeLifecycle", {
       action: "enterMilestone",
@@ -836,6 +871,32 @@ function rebuildGitService(
   s.gitService = deps.gitServiceFactory(s.basePath);
 }
 
+function emitWorktreeMergeFailedOnce(
+  basePath: string,
+  milestoneId: string,
+  err: unknown,
+): void {
+  const msg = err instanceof Error ? err.message : String(err);
+  const errorCategory = err instanceof Error ? err.name : "Error";
+  const now = Date.now();
+  const key = `${basePath}\0${milestoneId}\0${errorCategory}`;
+  const previous = recentWorktreeMergeFailures.get(key);
+  if (previous && now - previous < MERGE_FAILURE_DEDUPE_MS) return;
+  for (const [candidate, ts] of recentWorktreeMergeFailures) {
+    if (now - ts >= MERGE_FAILURE_DEDUPE_MS) {
+      recentWorktreeMergeFailures.delete(candidate);
+    }
+  }
+  emitJournalEvent(basePath, {
+    ts: new Date().toISOString(),
+    flowId: randomUUID(),
+    seq: 0,
+    eventType: "worktree-merge-failed",
+    data: { milestoneId, error: msg },
+  });
+  recentWorktreeMergeFailures.set(key, now);
+}
+
 // ─── Session-less merge entry (ADR-016 phase 2 / A1) ─────────────────────
 
 /**
@@ -985,13 +1046,7 @@ function _mergeWorktreeModeImpl(
       error: msg,
       fallback: "chdir-to-project-root",
     });
-    emitJournalEvent(originalBasePath || worktreeBasePath, {
-      ts: new Date().toISOString(),
-      flowId: randomUUID(),
-      seq: 0,
-      eventType: "worktree-merge-failed",
-      data: { milestoneId, error: msg },
-    });
+    emitWorktreeMergeFailedOnce(originalBasePath || worktreeBasePath, milestoneId, err);
     // Surface a clear, actionable error. Worktree and milestone branch
     // are intentionally preserved — nothing has been deleted. User can
     // retry /gsd dispatch complete-milestone or merge manually once the
@@ -1181,6 +1236,11 @@ export function mergeMilestoneStandalone(
 ): MergeStandaloneResult {
   const { originalBasePath, worktreeBasePath, milestoneId, notify } = mctx;
   validateMilestoneId(milestoneId);
+  if (!originalBasePath && !worktreeBasePath) {
+    throw new Error(
+      `Internal error: mergeMilestoneStandalone(${milestoneId}) requires originalBasePath or worktreeBasePath.`,
+    );
+  }
 
   if (mctx.isolationDegraded) {
     if (originalBasePath) {
@@ -1702,16 +1762,34 @@ export class WorktreeLifecycle {
   }
 
   /**
-   * Restore `s.basePath` to `s.originalBasePath` and rebuild `s.gitService`.
-   * No-op when `originalBasePath` is empty (fresh sessions).
+   * Restore `s.basePath` to `s.originalBasePath`, chdir process cwd, and
+   * rebuild `s.gitService`. No-op when `originalBasePath` is empty (fresh
+   * sessions).
    *
    * Used by error/cleanup paths that need the session to behave as if the
    * worktree was never entered. Does NOT teardown the worktree directory —
    * callers that need teardown go through `exitMilestone({ merge: false })`.
+   *
+   * ADR-016 phase 3 (#5693): chdir lives inside the verb so callers do not
+   * pair `restoreToProjectRoot()` with a redundant `process.chdir`. The
+   * chdir runs BEFORE the throwable work (`rebuildGitService`, cache
+   * invalidation) so that cleanup-path cwd is restored even if the
+   * downstream rebuild throws. The chdir itself is best-effort; failure is
+   * logged via debugLog and swallowed.
    */
   restoreToProjectRoot(): void {
     if (!this.s.originalBasePath) return;
     this.s.basePath = this.s.originalBasePath;
+    try {
+      process.chdir(this.s.basePath);
+    } catch (err) {
+      debugLog("WorktreeLifecycle", {
+        action: "restoreToProjectRoot",
+        result: "chdir-failed",
+        basePath: this.s.basePath,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
     rebuildGitService(this.s, this.deps);
     invalidateAllCaches();
   }