@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.955e4da0

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

@@ -4,7 +4,8 @@
 /**
  * GSD Worktree Manager
  *
- * Creates and manages git worktrees under .gsd/worktrees/<name>/.
+ * Creates and manages git worktrees under .gsd-worktrees/<name>/ (canonical;
+ * legacy .gsd/worktrees/<name>/ stays recognized — see worktree-placement.ts).
  * Each worktree gets its own branch (worktree/<name>) and a full
  * working copy of the project, enabling parallel work streams.
  *
@@ -12,7 +13,7 @@
  * the main branch, then dispatches an LLM-guided merge flow.
  *
  * Flow:
- *   1. create()  — git worktree add .gsd/worktrees/<name> -b worktree/<name>
+ *   1. create()  — git worktree add .gsd-worktrees/<name> -b worktree/<name>
  *   2. user works in the worktree (new plans, milestones, etc.)
  *   3. merge()   — LLM-guided reconciliation of .gsd/ artifacts back to main
  *   4. remove()  — git worktree remove + branch cleanup
@@ -48,6 +49,7 @@ import {
   normalizeWorktreePathForCompare,
   resolveWorktreeProjectRoot,
 } from "./worktree-root.js";
+import { canonicalWorktreesDir, worktreePathFor, worktreesDirs } from "./worktree-placement.js";
 
 // ─── Types ─────────────────────────────────────────────────────────────────
 
@@ -138,12 +140,20 @@ export function resolveGitDir(basePath: string): string {
   return gitPath;
 }
 
+/** Canonical container for new worktrees. For scans that must also see legacy
+ *  worktrees, use allWorktreesDirs(). */
 export function worktreesDir(basePath: string): string {
-  return join(resolveWorktreeProjectRoot(basePath), ".gsd", "worktrees");
+  return canonicalWorktreesDir(resolveWorktreeProjectRoot(basePath));
 }
 
+/** Every container a GSD worktree may live in (canonical + legacy), canonical first. */
+export function allWorktreesDirs(basePath: string): string[] {
+  return worktreesDirs(resolveWorktreeProjectRoot(basePath));
+}
+
+/** Path for worktree `name` — an existing legacy worktree keeps its location. */
 export function worktreePath(basePath: string, name: string): string {
-  return join(worktreesDir(basePath), name);
+  return worktreePathFor(resolveWorktreeProjectRoot(basePath), name);
 }
 
 export function worktreeBranchName(name: string): string {
@@ -151,20 +161,22 @@ export function worktreeBranchName(name: string): string {
 }
 
 /**
- * Validate that a path is inside the .gsd/worktrees/ directory.
- * Resolves symlinks and normalizes ".." traversals before comparison
- * so that a symlink-resolved or crafted path cannot escape containment.
+ * Validate that a path is inside a GSD worktrees container (canonical
+ * .gsd-worktrees/ or legacy .gsd/worktrees/). Resolves symlinks and
+ * normalizes ".." traversals before comparison so that a symlink-resolved
+ * or crafted path cannot escape containment.
  *
  * Used as a safety gate before any destructive operation (rmSync,
  * nativeWorktreeRemove --force) to prevent #2365-style data loss.
  */
 export function isInsideWorktreesDir(basePath: string, targetPath: string): boolean {
-  const wtDirPath = worktreesDir(basePath);
-  const wtDir = existsSync(wtDirPath) ? realpathSync(wtDirPath) : resolve(wtDirPath);
   const resolved = existsSync(targetPath) ? realpathSync(targetPath) : resolve(targetPath);
-  // The resolved path must start with the worktrees dir followed by a separator,
-  // not merely be a prefix match (e.g. ".gsd/worktrees-extra" must not match).
-  return resolved === wtDir || resolved.startsWith(wtDir + sep);
+  return allWorktreesDirs(basePath).some((wtDirPath) => {
+    const wtDir = existsSync(wtDirPath) ? realpathSync(wtDirPath) : resolve(wtDirPath);
+    // The resolved path must start with the worktrees dir followed by a separator,
+    // not merely be a prefix match (e.g. ".gsd/worktrees-extra" must not match).
+    return resolved === wtDir || resolved.startsWith(wtDir + sep);
+  });
 }
 
 function isRegisteredGitWorktreeAtPath(basePath: string, wtPath: string): boolean {
@@ -277,12 +289,12 @@ export function buildManualValidationGuidance(
 ): string | null {
   if (!milestoneId) return null;
   const validationRoot = resolveCanonicalMilestoneRoot(basePath, milestoneId);
-  const inWorktree = validationRoot.includes(`${sep}.gsd${sep}worktrees${sep}`);
+  const inWorktree = isGsdWorktreePath(validationRoot);
   const lines: string[] = [`Validate the work here: ${validationRoot}`];
   if (inWorktree) {
     lines.push(
-      "This milestone runs in a git worktree, so the code lives under the hidden " +
-        `\`.gsd/worktrees/\` path. Open it with: cd "${validationRoot}"`,
+      "This milestone runs in a git worktree, so the code lives under the " +
+        `GSD worktrees directory. Open it with: cd "${validationRoot}"`,
     );
   }
   if (opts.uatPath) {
@@ -307,24 +319,33 @@ export function createWorktree(basePath: string, name: string, opts: { branch?:
     throw new GSDError(GSD_PARSE_ERROR, `Invalid worktree name "${name}". Use only letters, numbers, hyphens, and underscores.`);
   }
 
-  const wtPath = worktreePath(basePath, name);
+  const existingPath = worktreePath(basePath, name);
   const branch = opts.branch ?? worktreeBranchName(name);
 
-  if (existsSync(wtPath)) {
+  if (existsSync(existingPath)) {
     // A valid git worktree is registered in `git worktree list` and has a .git
     // *file* with a gitdir: pointer. Leftover directories (no .git, a standalone
     // .git directory from accidental `git init`, or an orphan pointer) block
     // creation unless removed.
-    if (isRegisteredGitWorktreeAtPath(basePath, wtPath)) {
-      throw new GSDError(GSD_STALE_STATE, `Worktree "${name}" already exists at ${wtPath}`);
+    if (isRegisteredGitWorktreeAtPath(basePath, existingPath)) {
+      throw new GSDError(GSD_STALE_STATE, `Worktree "${name}" already exists at ${existingPath}`);
     }
-    removeStaleWorktreeDirectory(wtPath, name);
+    removeStaleWorktreeDirectory(existingPath, name);
   }
 
-  // Ensure the .gsd/worktrees/ directory exists
+  // New worktrees always land in the canonical container, even when a stale
+  // legacy directory was just cleaned up.
   const wtDir = worktreesDir(basePath);
+  const wtPath = join(wtDir, name);
   mkdirSync(wtDir, { recursive: true });
 
+  // When existingPath resolved to a legacy location, the canonical target may
+  // still hold a stale directory from a prior aborted creation (no .git marker).
+  // Remove it so git worktree add does not fail with "path already exists".
+  if (existingPath !== wtPath && existsSync(wtPath) && !isRegisteredGitWorktreeAtPath(basePath, wtPath)) {
+    removeStaleWorktreeDirectory(wtPath, name);
+  }
+
   // Prune any stale worktree entries from a previous removal
   nativeWorktreePrune(basePath);
 
@@ -405,7 +426,8 @@ export function createWorktree(basePath: string, name: string, opts: { branch?:
 
 /**
  * List all GSD-managed worktrees.
- * Uses native worktree list and filters to those under .gsd/worktrees/.
+ * Uses native worktree list and filters to those under a GSD worktrees
+ * container (canonical .gsd-worktrees/ or legacy .gsd/worktrees/).
  */
 export function listWorktrees(basePath: string): WorktreeInfo[] {
   basePath = normalizeBasePathForWorktreeOps(basePath);
@@ -416,12 +438,8 @@ export function listWorktrees(basePath: string): WorktreeInfo[] {
   }
   const seenRoots = new Set<string>();
   const worktreeRoots = baseVariants
-    .map(baseVariant => {
-      const path = join(baseVariant, ".gsd", "worktrees");
-      return {
-        normalized: normalizePathForComparison(path),
-      };
-    })
+    .flatMap(baseVariant => worktreesDirs(baseVariant))
+    .map(path => ({ normalized: normalizePathForComparison(path) }))
     .filter(root => {
       if (seenRoots.has(root.normalized)) return false;
       seenRoots.add(root.normalized);
@@ -794,6 +812,7 @@ export function removeWorktree(
  * This module uses a split representation (paths/exact/prefixes) for efficient matching.
  */
 const SKIP_PATHS = [
+  ".gsd-worktrees/",
   ".gsd/worktrees/",
   ".gsd/runtime/",
   ".gsd/activity/",

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

@@ -0,0 +1,63 @@
+/**
+ * Worktree Placement module — owns WHERE GSD worktrees physically live.
+ *
+ * Canonical placement: `<projectRoot>/.gsd-worktrees/<name>` — a real
+ * directory that never crosses the `.gsd` symlink managed by repo-identity.
+ * Under the external-state layout (`.gsd → ~/.gsd/projects/<hash>/`), the
+ * legacy `.gsd/worktrees/` location materialised worktrees inside the user's
+ * home directory behind an opaque hash path; the canonical sibling keeps the
+ * working copy at the project root regardless of where `.gsd` state lives.
+ *
+ * Legacy placement (`<projectRoot>/.gsd/worktrees/<name>`, possibly resolving
+ * through the symlink to `~/.gsd/projects/<hash>/worktrees/<name>`) stays
+ * recognized so in-flight milestones keep working across upgrades:
+ *   - creation always uses the canonical location;
+ *   - resolution prefers an existing legacy worktree for the same name;
+ *   - containment checks accept membership in either location.
+ *
+ * Path → project identification lives in worktree-root.ts; this module owns
+ * only the forward direction (project + name → physical path).
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/** Directory name of the canonical worktrees container at the project root. */
+export const CANONICAL_WORKTREES_DIRNAME = ".gsd-worktrees";
+
+/** Canonical container for newly created worktrees. Never crosses the `.gsd` symlink. */
+export function canonicalWorktreesDir(projectRoot: string): string {
+  return join(projectRoot, CANONICAL_WORKTREES_DIRNAME);
+}
+
+/** Legacy container (`.gsd/worktrees/`) — may resolve through the external-state symlink. */
+export function legacyWorktreesDir(projectRoot: string): string {
+  return join(projectRoot, ".gsd", "worktrees");
+}
+
+/**
+ * All containers a GSD worktree may live in, canonical first.
+ * Use for listing, scanning, and containment checks.
+ */
+export function worktreesDirs(projectRoot: string): string[] {
+  return [canonicalWorktreesDir(projectRoot), legacyWorktreesDir(projectRoot)];
+}
+
+/**
+ * Physical path for the worktree `name` under `projectRoot`.
+ *
+ * Canonical wins only when it has a `.git` marker (i.e. is a live worktree).
+ * A bare directory with no `.git` — a stale leftover from an aborted create
+ * or a partial cleanup — does not shadow an existing legacy worktree, so the
+ * legacy path is tried next. The legacy check remains a plain existsSync;
+ * callers that need a *registered* worktree validate the `.git` marker
+ * themselves (resolveCanonicalMilestoneRoot, getAutoWorktreePath).
+ * Falls back to canonical for new-worktree creation when neither path exists.
+ */
+export function worktreePathFor(projectRoot: string, name: string): string {
+  const canonical = join(canonicalWorktreesDir(projectRoot), name);
+  if (existsSync(canonical) && existsSync(join(canonical, ".git"))) return canonical;
+  const legacy = join(legacyWorktreesDir(projectRoot), name);
+  if (existsSync(legacy)) return legacy;
+  return canonical;
+}

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

@@ -10,7 +10,7 @@ import { readdirSync } from "node:fs";
 
 import { enterAutoWorktree, getAutoWorktreePath } from "./auto-worktree.js";
 import { getIsolationMode } from "./preferences.js";
-import { worktreesDir } from "./worktree-manager.js";
+import { allWorktreesDirs } from "./worktree-manager.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
 
 interface LiveWorktree {
@@ -19,15 +19,18 @@ interface LiveWorktree {
 }
 
 /**
- * Enumerate the live (valid git) auto-worktrees under <projectRoot>/.gsd/worktrees/.
+ * Enumerate the live (valid git) auto-worktrees in the project's worktree
+ * containers (canonical .gsd-worktrees/ and legacy .gsd/worktrees/).
  * Reuses getAutoWorktreePath's validation so stray directories are ignored.
  */
 function liveMilestoneWorktrees(projectRoot: string): LiveWorktree[] {
-  let names: string[];
-  try {
-    names = readdirSync(worktreesDir(projectRoot));
-  } catch {
-    return [];
+  const names = new Set<string>();
+  for (const dir of allWorktreesDirs(projectRoot)) {
+    try {
+      for (const name of readdirSync(dir)) names.add(name);
+    } catch {
+      // container absent — skip
+    }
   }
   const live: LiveWorktree[] = [];
   for (const id of names) {

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

@@ -20,10 +20,17 @@ export function normalizeWorktreePathForCompare(path: string): string {
 }
 
 /**
- * Find the GSD worktree segment in both direct project layout and the
- * symlink-resolved external-state layout used by ~/.gsd/projects/<hash>.
+ * Find the GSD worktree segment in the canonical layout (.gsd-worktrees/),
+ * the legacy direct layout (.gsd/worktrees/), and the symlink-resolved
+ * external-state layout used by ~/.gsd/projects/<hash>.
  */
 export function findWorktreeSegment(normalizedPath: string): WorktreeSegment | null {
+  const canonicalMarker = "/.gsd-worktrees/";
+  const canonicalIdx = normalizedPath.indexOf(canonicalMarker);
+  if (canonicalIdx !== -1) {
+    return { gsdIdx: canonicalIdx, afterWorktrees: canonicalIdx + canonicalMarker.length };
+  }
+
   const directMarker = "/.gsd/worktrees/";
   const directIdx = normalizedPath.indexOf(directMarker);
   if (directIdx !== -1) {
@@ -72,7 +79,8 @@ export function isGsdWorktreePath(path: string): boolean {
 export function resolveExternalStateProjectGsdFromWorktreePath(projectPath: string): string | null {
   const normalized = resolve(projectPath).replaceAll("\\", "/");
 
-  // Direct layout — parent state is resolved via repoIdentity(git root).
+  // Canonical/direct layouts — parent state is resolved via repoIdentity(git root).
+  if (normalized.includes("/.gsd-worktrees/")) return null;
   if (normalized.includes("/.gsd/worktrees/") && !normalized.includes("/.gsd/projects/")) {
     return null;
   }
@@ -139,12 +147,15 @@ function resolveProjectRootFromPath(path: string): string {
     return resolveNearestBootstrappedGsdRoot(path) ?? resolveGitWorkingTreeRoot(path) ?? path;
   }
 
+  // Slice at the first `.gsd` boundary, but never past the worktree segment:
+  // in the canonical layout (`<root>/.gsd-worktrees/<MID>/.gsd/...`) the first
+  // `/.gsd/` occurrence is the worktree-local projection dir, not the project
+  // root's state dir.
   const sepChar = path.includes("\\") ? "\\" : "/";
   const gsdMarker = `${sepChar}.gsd${sepChar}`;
   const markerIdx = path.indexOf(gsdMarker);
-  const candidate = markerIdx !== -1
-    ? path.slice(0, markerIdx)
-    : path.slice(0, segment.gsdIdx);
+  const sliceIdx = markerIdx !== -1 ? Math.min(markerIdx, segment.gsdIdx) : segment.gsdIdx;
+  const candidate = path.slice(0, sliceIdx);
 
   const gsdHomeNorm = normalizeWorktreePathForCompare(gsdHome());
   const candidateGsdPath = normalizeWorktreePathForCompare(join(candidate, ".gsd"));

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

@@ -6,6 +6,7 @@ import { execFileSync } from "node:child_process";
 import { join, resolve } from "node:path";
 
 import { normalizeWorktreePathForCompare } from "./worktree-root.js";
+import { worktreesDirs } from "./worktree-placement.js";
 import { listWorktrees } from "./worktree-manager.js";
 import { getCurrentBranch } from "./worktree.js";
 
@@ -158,10 +159,12 @@ export function createWorktreeSafetyModule(
       const projectRoot = resolve(input.projectRoot);
       const unitRoot = resolve(input.unitRoot);
       const isolationMode = input.isolationMode ?? "worktree";
-      const expectedRoot = isolationMode === "worktree"
-        ? join(projectRoot, ".gsd", "worktrees", milestoneId)
-        : projectRoot;
-      if (!samePath(unitRoot, expectedRoot)) {
+      // A milestone worktree may live in the canonical container or the
+      // legacy one (pre-placement-change worktrees keep their location).
+      const expectedRoots = isolationMode === "worktree"
+        ? worktreesDirs(projectRoot).map((dir) => join(dir, milestoneId))
+        : [projectRoot];
+      if (!expectedRoots.some((expectedRoot) => samePath(unitRoot, expectedRoot))) {
         return failure(
           "invalid-root",
           isolationMode === "worktree"
@@ -170,7 +173,7 @@ export function createWorktreeSafetyModule(
           isolationMode === "worktree"
             ? "Prepare the Unit in its canonical milestone worktree before allowing source writes."
             : "Run the Unit from the project root when worktree isolation is disabled.",
-          { expectedRoot, unitRoot },
+          { expectedRoot: expectedRoots[0], unitRoot },
         );
       }
 

package/src/resources/extensions/gsd/worktree-session-state.ts

@@ -1,4 +1,6 @@
 // GSD worktree session state
+import { findWorktreeSegment } from "./worktree-root.js";
+
 let originalCwd: string | null = null;
 
 export function getWorktreeOriginalCwd(): string | null {
@@ -15,21 +17,21 @@ export function clearWorktreeOriginalCwd(): void {
 
 export function ensureWorktreeOriginalCwdFromPath(cwd: string = process.cwd()): string | null {
   if (originalCwd) return originalCwd;
-  const marker = `${/\\/.test(cwd) ? "\\" : "/"}.gsd${/\\/.test(cwd) ? "\\" : "/"}worktrees${/\\/.test(cwd) ? "\\" : "/"}`;
-  const markerIdx = cwd.indexOf(marker);
-  if (markerIdx !== -1) {
-    originalCwd = cwd.slice(0, markerIdx);
+  const segment = findWorktreeSegment(cwd.replaceAll("\\", "/"));
+  if (segment) {
+    originalCwd = cwd.slice(0, segment.gsdIdx);
   }
   return originalCwd;
 }
 
 export function getActiveWorktreeName(): string | null {
   if (!originalCwd) return null;
-  const cwd = process.cwd();
-  const wtDir = `${originalCwd.replace(/[\\/]+$/, "")}/.gsd/worktrees`.replaceAll("\\", "/");
-  const normalizedCwd = cwd.replaceAll("\\", "/");
-  if (!normalizedCwd.startsWith(`${wtDir}/`)) return null;
-  const rel = normalizedCwd.slice(wtDir.length + 1);
-  const name = rel.split("/")[0];
+  const normalizedCwd = process.cwd().replaceAll("\\", "/");
+  const normalizedOriginal = originalCwd.replace(/[\\/]+$/, "").replaceAll("\\", "/");
+  const segment = findWorktreeSegment(normalizedCwd);
+  if (!segment) return null;
+  // Only treat the cwd as an active worktree of OUR project root.
+  if (normalizedCwd.slice(0, segment.gsdIdx) !== normalizedOriginal) return null;
+  const name = normalizedCwd.slice(segment.afterWorktrees).split("/")[0];
   return name || null;
 }

package/src/resources/extensions/gsd/worktree-state-projection.ts

@@ -74,6 +74,30 @@ const VERDICT_RE = /verdict:\s*[\w-]+/i;
  * Only overwrites when the source has a verdict — never clobbers a
  * worktree ASSESSMENT with a verdictless project-root copy.
  */
+function forceOverwriteValidationWithVerdict(
+  srcMilestoneDir: string,
+  dstMilestoneDir: string,
+  milestoneId: string,
+): void {
+  if (!existsSync(srcMilestoneDir) || !milestoneId) return;
+
+  const srcFile = join(srcMilestoneDir, `${milestoneId}-VALIDATION.md`);
+  if (!existsSync(srcFile)) return;
+
+  try {
+    const srcContent = readFileSync(srcFile, "utf-8");
+    if (!VERDICT_RE.test(srcContent)) return;
+
+    mkdirSync(dstMilestoneDir, { recursive: true });
+    safeCopy(srcFile, join(dstMilestoneDir, `${milestoneId}-VALIDATION.md`), { force: true });
+  } catch (err) {
+    logWarning(
+      "worktree",
+      `validation force-copy failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
 function forceOverwriteAssessmentsWithVerdict(
   srcMilestoneDir: string,
   dstMilestoneDir: string,
@@ -260,10 +284,10 @@ export function _projectRootToWorktreeImpl(
   // session resume the DB is rebuilt from disk, and if the stale ASSESSMENT
   // persists, checkNeedsRunUat finds no passing verdict → re-dispatches
   // run-uat indefinitely (stuck-loop ×9).
-  forceOverwriteAssessmentsWithVerdict(
-    join(prGsd, "milestones", milestoneId),
-    join(wtGsd, "milestones", milestoneId),
-  );
+  const prMilestoneDir = join(prGsd, "milestones", milestoneId);
+  const wtMilestoneDir = join(wtGsd, "milestones", milestoneId);
+  forceOverwriteValidationWithVerdict(prMilestoneDir, wtMilestoneDir, milestoneId);
+  forceOverwriteAssessmentsWithVerdict(prMilestoneDir, wtMilestoneDir);
 
   // Forward-sync completed-units.json from project root to worktree.
   // Project root is authoritative for completion state after crash recovery;
@@ -442,25 +466,41 @@ export class WorktreeStateProjection {
    * any Unit dispatches.
    */
   projectRootToWorktree(scope: MilestoneScope): void {
-    _projectRootToWorktreeImpl(
+    this.projectRootToWorktreePaths(
       scope.workspace.projectRoot,
       scope.workspace.worktreeRoot ?? scope.workspace.projectRoot,
       scope.milestoneId,
     );
   }
 
+  projectRootToWorktreePaths(
+    projectRoot: string,
+    worktreePath: string,
+    milestoneId: string | null,
+  ): void {
+    _projectRootToWorktreeImpl(projectRoot, worktreePath, milestoneId);
+  }
+
   /**
    * Project state from the auto-worktree back onto the project root for `scope`.
    * Called by the post-unit pipeline between Units.
    */
   projectWorktreeToRoot(scope: MilestoneScope): void {
-    _projectWorktreeToRootImpl(
+    this.projectWorktreeToRootPaths(
       scope.workspace.worktreeRoot ?? scope.workspace.projectRoot,
       scope.workspace.projectRoot,
       scope.milestoneId,
     );
   }
 
+  projectWorktreeToRootPaths(
+    worktreePath: string,
+    projectRoot: string,
+    milestoneId: string | null,
+  ): void {
+    _projectWorktreeToRootImpl(worktreePath, projectRoot, milestoneId);
+  }
+
   /**
    * Final projection from the auto-worktree to the project root before
    * teardown. Called by Lifecycle's exit path after a successful merge,
@@ -471,10 +511,18 @@ export class WorktreeStateProjection {
    * telemetry on what crossed the boundary.
    */
   finalizeProjectionForMerge(scope: MilestoneScope): { synced: string[] } {
-    return _finalizeProjectionForMergeImpl(
+    return this.finalizeProjectionForMergePaths(
       scope.workspace.projectRoot,
       scope.workspace.worktreeRoot ?? scope.workspace.projectRoot,
       scope.milestoneId,
     );
   }
+
+  finalizeProjectionForMergePaths(
+    projectRoot: string,
+    worktreePath: string,
+    milestoneId: string,
+  ): { synced: string[] } {
+    return _finalizeProjectionForMergeImpl(projectRoot, worktreePath, milestoneId);
+  }
 }

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

@@ -22,6 +22,7 @@
 import { randomUUID } from "node:crypto";
 import { emitJournalEvent, queryJournal } from "./journal.js";
 import type { JournalEntry } from "./journal.js";
+import type { AutoTerminalOutcome } from "./auto/contracts.js";
 
 function now(): string {
   return new Date().toISOString();
@@ -91,6 +92,21 @@ export function normalizeAutoExitReason(rawReason?: string): AutoExitReason {
                             : "other";
 }
 
+export function autoExitReasonForTerminalOutcome(
+  outcome: AutoTerminalOutcome | undefined,
+): AutoExitReason | null {
+  switch (outcome?.code) {
+    case "all-complete":
+      return "all-complete";
+    case "settlement-blocked":
+      return "blocked";
+    case "no-remaining-units":
+      return "stop";
+    default:
+      return null;
+  }
+}
+
 // ─── Emitters ────────────────────────────────────────────────────────────
 
 export function emitWorktreeCreated(

package/src/resources/extensions/shared/interview-ui.ts

@@ -62,6 +62,13 @@ export interface RoundResult {
 	/** Always false — end is handled by showWrapUpScreen, not per-question */
 	endInterview: false;
 	answers: Record<string, { selected: string | string[]; notes: string }>;
+	/**
+	 * Set to true only when the round ended because the external AbortSignal
+	 * fired (e.g. a system/host teardown), as distinct from a deliberate user
+	 * dismissal. Consumers use this to avoid laundering a system teardown into a
+	 * clean user-declined cancel. Additive/optional — native consumers ignore it.
+	 */
+	interrupted?: boolean;
 }
 
 export interface WrapUpResult {
@@ -97,6 +104,12 @@ export interface InterviewRoundOptions {
 	 * Defaults to "end interview".
 	 */
 	exitLabel?: string;
+	/**
+	 * Render as a floating overlay instead of replacing the editor. Use when the
+	 * interview must stay visible during an in-flight agent stream (e.g. claude-code-cli
+	 * MCP elicitation).
+	 */
+	overlay?: boolean;
 }
 
 export interface WrapUpOptions {
@@ -240,7 +253,7 @@ export async function showInterviewRound(
 
 		// External cancellation (e.g. remote channel won the race)
 		if (opts.signal) {
-			const onAbort = () => finish({ endInterview: false, answers: {} });
+			const onAbort = () => finish({ endInterview: false, answers: {}, interrupted: true });
 			if (opts.signal.aborted) { onAbort(); }
 			else {
 				opts.signal.addEventListener("abort", onAbort, { once: true });
@@ -845,5 +858,5 @@ export async function showInterviewRound(
 			invalidate: () => { cachedLines = undefined; },
 			handleInput,
 		};
-	});
+	}, opts.overlay ? { overlay: true } : undefined);
 }