gsd-pi 2.82.0-dev.3709f22a5 → 2.82.0-dev.4285182e8

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

@@ -0,0 +1,202 @@
+import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { loadFile } from "./files.js";
+import { resolveMilestoneFile } from "./paths.js";
+import { deriveState } from "./state.js";
+import { executeValidateMilestone } from "./tools/workflow-tool-executors.js";
+import {
+  VALIDATION_VERDICTS,
+  extractVerdict,
+  isValidMilestoneVerdict,
+  type ValidationVerdict,
+} from "./verdict-parser.js";
+
+const USAGE =
+  'Usage: /gsd verdict <pass|needs-attention|needs-remediation> [--milestone Mxxx] [--rationale "..."]';
+
+interface ParsedArgs {
+  verdict?: ValidationVerdict;
+  milestoneId?: string;
+  rationale?: string;
+}
+
+interface ParsedValidation {
+  verdict: string | undefined;
+  remediationRound: number;
+  successCriteriaChecklist: string;
+  sliceDeliveryAudit: string;
+  crossSliceIntegration: string;
+  requirementCoverage: string;
+  verificationClasses?: string;
+  verdictRationale: string;
+  remediationPlan?: string;
+}
+
+function tokenize(raw: string): string[] {
+  const tokens: string[] = [];
+  const re = /"([^"]*)"|(\S+)/g;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(raw)) !== null) {
+    tokens.push(match[1] ?? match[2]);
+  }
+  return tokens;
+}
+
+function parseArgs(raw: string): ParsedArgs | { error: string } {
+  const tokens = tokenize(raw);
+  const out: ParsedArgs = {};
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i];
+    if (t === "--milestone") {
+      const next = tokens[++i];
+      if (!next) return { error: "--milestone requires a milestone ID" };
+      out.milestoneId = next;
+    } else if (t === "--rationale") {
+      const next = tokens[++i];
+      if (next == null) return { error: "--rationale requires a value" };
+      out.rationale = next;
+    } else if (!out.verdict) {
+      if (!isValidMilestoneVerdict(t)) {
+        return {
+          error: `Invalid verdict "${t}". Must be one of: ${VALIDATION_VERDICTS.join(", ")}`,
+        };
+      }
+      out.verdict = t;
+    } else {
+      return { error: `Unexpected argument: ${t}` };
+    }
+  }
+  return out;
+}
+
+function extractRemediationRound(content: string): number {
+  const fm = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!fm) return 0;
+  const m = fm[1].match(/^remediation_round:\s*(\d+)/im);
+  return m ? Number.parseInt(m[1], 10) : 0;
+}
+
+function extractSection(content: string, heading: string): string | undefined {
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  // Match section bodies bounded by the next "## " heading or end-of-string.
+  // Leading "\n" prefix lets a single pattern handle first-line headings too.
+  // No /m flag — we want `$` to mean end-of-string, not end-of-line.
+  const re = new RegExp(`\\n## ${escaped}\\s*\\n([\\s\\S]*?)(?=\\n## |$)`);
+  const m = ("\n" + content).match(re);
+  if (!m) return undefined;
+  return m[1].replace(/\s+$/, "");
+}
+
+export function parseValidationFile(content: string): ParsedValidation {
+  return {
+    verdict: extractVerdict(content),
+    remediationRound: extractRemediationRound(content),
+    successCriteriaChecklist: extractSection(content, "Success Criteria Checklist") ?? "",
+    sliceDeliveryAudit: extractSection(content, "Slice Delivery Audit") ?? "",
+    crossSliceIntegration: extractSection(content, "Cross-Slice Integration") ?? "",
+    requirementCoverage: extractSection(content, "Requirement Coverage") ?? "",
+    verificationClasses: extractSection(content, "Verification Class Compliance"),
+    verdictRationale: extractSection(content, "Verdict Rationale") ?? "",
+    remediationPlan: extractSection(content, "Remediation Plan"),
+  };
+}
+
+export async function handleVerdict(
+  rawArgs: string,
+  ctx: ExtensionCommandContext,
+  basePath: string,
+): Promise<void> {
+  if (!rawArgs.trim()) {
+    ctx.ui.notify(USAGE, "warning");
+    return;
+  }
+
+  const parsed = parseArgs(rawArgs);
+  if ("error" in parsed) {
+    ctx.ui.notify(`${parsed.error}\n${USAGE}`, "warning");
+    return;
+  }
+  if (!parsed.verdict) {
+    ctx.ui.notify(USAGE, "warning");
+    return;
+  }
+
+  let milestoneId = parsed.milestoneId;
+  if (!milestoneId) {
+    const state = await deriveState(basePath);
+    if (!state.activeMilestone) {
+      ctx.ui.notify(
+        "No active milestone — pass --milestone Mxxx to target a specific milestone.",
+        "warning",
+      );
+      return;
+    }
+    milestoneId = state.activeMilestone.id;
+  }
+
+  const validationPath = resolveMilestoneFile(basePath, milestoneId, "VALIDATION");
+  if (!validationPath) {
+    ctx.ui.notify(
+      `No VALIDATION file found for ${milestoneId}. Run gsd_validate_milestone first to produce one.`,
+      "warning",
+    );
+    return;
+  }
+  const existing = await loadFile(validationPath);
+  if (!existing) {
+    ctx.ui.notify(
+      `Could not read VALIDATION file for ${milestoneId} (${validationPath}).`,
+      "warning",
+    );
+    return;
+  }
+
+  const current = parseValidationFile(existing);
+
+  if (parsed.verdict !== "pass" && !parsed.rationale) {
+    ctx.ui.notify(
+      `--rationale is required when overriding to ${parsed.verdict}.`,
+      "warning",
+    );
+    return;
+  }
+
+  const verdictRationale =
+    parsed.rationale ?? "Manually overridden via /gsd verdict";
+
+  const result = await executeValidateMilestone(
+    {
+      milestoneId,
+      verdict: parsed.verdict,
+      remediationRound: current.remediationRound,
+      successCriteriaChecklist: current.successCriteriaChecklist,
+      sliceDeliveryAudit: current.sliceDeliveryAudit,
+      crossSliceIntegration: current.crossSliceIntegration,
+      requirementCoverage: current.requirementCoverage,
+      verificationClasses: current.verificationClasses,
+      verdictRationale,
+      remediationPlan: current.remediationPlan,
+    },
+    basePath,
+  );
+
+  if (result.isError) {
+    const msg =
+      result.content[0]?.type === "text" ? result.content[0].text : "Unknown error";
+    ctx.ui.notify(msg, "error");
+    return;
+  }
+
+  const prevVerdict = current.verdict ?? "unknown";
+  ctx.ui.notify(
+    `Milestone ${milestoneId} verdict: ${prevVerdict} -> ${parsed.verdict}`,
+    "success",
+  );
+
+  if (parsed.verdict === "needs-remediation") {
+    ctx.ui.notify(
+      "Follow up with gsd_reassess_roadmap to add remediation slices, then re-run /gsd auto.",
+      "info",
+    );
+  }
+}

package/src/resources/extensions/gsd/crash-recovery.ts

@@ -31,8 +31,10 @@ import {
   findStaleWorkerForProject,
   getAllAutoWorkers,
   markWorkerCrashed,
+  markWorkerStopping,
   type AutoWorkerRow,
 } from "./db/auto-workers.js";
+import { forceReleaseLeasesForWorker } from "./db/milestone-leases.js";
 import { markLatestActiveForWorkerCanceled, type DispatchStatus } from "./db/unit-dispatches.js";
 import { getRuntimeKv, setRuntimeKv, deleteRuntimeKv } from "./db/runtime-kv.js";
 import { _getAdapter, isDbAvailable } from "./gsd-db.js";
@@ -219,9 +221,21 @@ export function clearLock(basePath: string): void {
   if (!isDbAvailable()) return;
   try {
     const projectRoot = normalizeRealPath(basePath);
+    const staleWorker = findStaleWorkerForProject(projectRoot);
+    if (staleWorker) {
+      markWorkerCrashed(staleWorker.worker_id);
+      forceReleaseLeasesForWorker(staleWorker.worker_id);
+      deleteRuntimeKv("worker", staleWorker.worker_id, SESSION_FILE_KV_KEY);
+      return;
+    }
     const worker = findActiveWorkerForCurrentProcess(projectRoot);
-    if (!worker) return;
-    deleteRuntimeKv("worker", worker.worker_id, SESSION_FILE_KV_KEY);
+    if (worker) deleteRuntimeKv("worker", worker.worker_id, SESSION_FILE_KV_KEY);
+
+    const stale = findStaleWorkerForProject(projectRoot);
+    if (stale) {
+      markWorkerStopping(stale.worker_id);
+      deleteRuntimeKv("worker", stale.worker_id, SESSION_FILE_KV_KEY);
+    }
   } catch {
     // Best-effort.
   }

package/src/resources/extensions/gsd/db/milestone-leases.ts

@@ -255,6 +255,32 @@ export function releaseMilestoneLease(
   });
 }
 
+/**
+ * Force-release all held leases for a worker.
+ *
+ * Used by crash recovery once PID liveness has confirmed the worker is dead.
+ * No fencing token is required because this path is cleanup-only for a
+ * non-running process.
+ */
+export function forceReleaseLeasesForWorker(workerId: string): number {
+  if (!isDbAvailable()) return 0;
+  const db = _getAdapter()!;
+  let changes = 0;
+  transaction(() => {
+    const result = db.prepare(
+      `UPDATE milestone_leases
+       SET status = 'released'
+       WHERE worker_id = :worker_id
+         AND status = 'held'`,
+    ).run({ ":worker_id": workerId });
+    changes =
+      typeof (result as { changes?: unknown }).changes === "number"
+        ? (result as { changes: number }).changes
+        : 0;
+  });
+  return changes;
+}
+
 /**
  * Read current lease row for diagnostics. Returns null if no row exists.
  */

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

@@ -837,7 +837,7 @@ export function detectWorktreeOrphans(
       type: "worktree-unmerged-exit",
       severity: "warning",
       summary: `${summary.exitsWithUnmergedWork} auto-exit(s) left milestone work unmerged`,
-      details: `Exit reasons: ${reasonBreakdown || "(none)"} · Producer-side signal for #4761-class orphans. Inspect .gsd/journal/*.jsonl with eventType:"auto-exit" for per-exit detail.`,
+      details: `Exit reasons: ${reasonBreakdown || "(none)"} · Producer-side signal for orphaned worktrees. Inspect .gsd/journal/*.jsonl with eventType:"auto-exit" for per-exit detail.`,
     });
   }
 }
@@ -1056,7 +1056,7 @@ function saveForensicReport(basePath: string, report: ForensicReport, problemDes
         .map(([r, n]) => `${r}=${n}`).join(", ");
       sections.push(`  - Exit reasons: ${breakdown}`);
     }
-    sections.push(`- Canonical-root redirects (#4761 fix fired): ${t.canonicalRedirects}`);
+    sections.push(`- Canonical-root redirects: ${t.canonicalRedirects}`);
     // #4765 slice-cadence counters
     if (t.slicesMerged + t.sliceMergeConflicts + t.milestoneResquashes > 0) {
       sections.push(`- Slices merged: ${t.slicesMerged} · Slice merge conflicts: ${t.sliceMergeConflicts}`);
@@ -1220,7 +1220,7 @@ function formatReportForPrompt(report: ForensicReport): string {
     if (hasSignal) {
       sections.push("### Worktree Telemetry");
       sections.push(`- Created: ${t.worktreesCreated} · Merged: ${t.worktreesMerged} · Conflicts: ${t.mergeConflicts}`);
-      sections.push(`- Orphans: ${t.orphansDetected} · Unmerged exits: ${t.exitsWithUnmergedWork} · Redirects (#4761): ${t.canonicalRedirects}`);
+      sections.push(`- Orphans: ${t.orphansDetected} · Unmerged exits: ${t.exitsWithUnmergedWork} · Redirects: ${t.canonicalRedirects}`);
       if (t.orphansDetected > 0) {
         const breakdown = Object.entries(t.orphansByReason)
           .map(([r, n]) => `${r}=${n}`).join(", ");

package/src/resources/extensions/gsd/git-service.ts

@@ -388,6 +388,9 @@ export function readIntegrationBranch(basePath: string, milestoneId: string): st
   }
 }
 
+/** Re-export for backward compatibility — canonical definitions in branch-patterns.ts */
+export { QUICK_BRANCH_RE, WORKFLOW_BRANCH_RE } from "./branch-patterns.js";
+
 /**
  * Persist the integration branch for a milestone.
  *
@@ -398,14 +401,14 @@ export function readIntegrationBranch(basePath: string, milestoneId: string): st
  *
  * The file is committed immediately so the metadata is persisted in git.
  */
-/** Re-export for backward compatibility — canonical definitions in branch-patterns.ts */
-export { QUICK_BRANCH_RE, WORKFLOW_BRANCH_RE } from "./branch-patterns.js";
-
 export function writeIntegrationBranch(
   basePath: string,
   milestoneId: string,
   branch: string,
 ): void {
+  // Never persist milestone branches as integration targets.
+  // They are ephemeral execution branches and can cause self-diff corruption.
+  if (branch.startsWith("milestone/")) return;
   // Don't record slice branches as the integration target
   if (SLICE_BRANCH_RE.test(branch)) return;
   // Don't record quick-task branches — they are ephemeral and merge back

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

@@ -111,13 +111,14 @@ const providerLoader = createSqliteProviderLoader({
 
 export const SCHEMA_VERSION = 28;
 
-function initSchema(db: DbAdapter, fileBacked: boolean): void {
-  if (fileBacked) db.exec("PRAGMA journal_mode=WAL");
+function initSchema(db: DbAdapter, fileBacked: boolean, dbPath: string | null): void {
+  const conservativeFilePragmas = fileBacked && _isLikelyWslDrvFsPathForTest(dbPath);
+  if (fileBacked) db.exec(conservativeFilePragmas ? "PRAGMA journal_mode=DELETE" : "PRAGMA journal_mode=WAL");
   if (fileBacked) db.exec("PRAGMA busy_timeout = 5000");
-  if (fileBacked) db.exec("PRAGMA synchronous = NORMAL");
+  if (fileBacked) db.exec(conservativeFilePragmas ? "PRAGMA synchronous = FULL" : "PRAGMA synchronous = NORMAL");
   if (fileBacked) db.exec("PRAGMA auto_vacuum = INCREMENTAL");
   if (fileBacked) db.exec("PRAGMA cache_size = -8000");   // 8 MB page cache
-  if (fileBacked && process.platform !== "darwin") db.exec("PRAGMA mmap_size = 67108864");  // 64 MB mmap
+  if (fileBacked && !conservativeFilePragmas && process.platform !== "darwin") db.exec("PRAGMA mmap_size = 67108864");  // 64 MB mmap
   db.exec("PRAGMA temp_store = MEMORY");
   db.exec("PRAGMA foreign_keys = ON");
 
@@ -156,6 +157,17 @@ function initSchema(db: DbAdapter, fileBacked: boolean): void {
   migrateSchema(db);
 }
 
+export function _isLikelyWslDrvFsPathForTest(dbPath: string | null): boolean {
+  if (!dbPath || process.platform !== "linux") return false;
+  const drvFsPathPattern = /^\/mnt\/[a-z](?:\/|$)/i;
+  if (drvFsPathPattern.test(dbPath)) return true;
+  try {
+    return drvFsPathPattern.test(realpathSync(dbPath));
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Create the FTS5 virtual table for memories plus the triggers that keep it
  * in sync with the base table. FTS5 may be unavailable on stripped-down
@@ -605,14 +617,14 @@ export function openDatabase(path: string): boolean {
   const adapter = createDbAdapter(rawDb);
   const fileBacked = path !== ":memory:";
   try {
-    initSchema(adapter, fileBacked);
+    initSchema(adapter, fileBacked, path);
   } catch (err) {
     // Corrupt freelist: DDL fails with "malformed" but VACUUM can rebuild.
     // Attempt VACUUM recovery before giving up (see #2519).
     if (fileBacked && err instanceof Error && err.message?.includes("malformed")) {
       try {
         adapter.exec("VACUUM");
-        initSchema(adapter, fileBacked);
+        initSchema(adapter, fileBacked, path);
         process.stderr.write("gsd-db: recovered corrupt database via VACUUM\n");
       } catch (retryErr) {
         _dbOpenState.recordError("vacuum-recovery", retryErr);

package/src/resources/extensions/gsd/guided-flow-queue.ts

@@ -23,6 +23,7 @@ import { nativeAddPaths, nativeCommit } from "./native-git-bridge.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { loadQueueOrder, sortByQueueOrder, saveQueueOrder } from "./queue-order.js";
 import { findMilestoneIds, nextMilestoneId } from "./milestone-ids.js";
+import { isFutureMilestoneStatus } from "./status-guards.js";
 
 // ─── Queue Entry Point ──────────────────────────────────────────────────────
 
@@ -63,7 +64,7 @@ export async function showQueue(
 
   // ── Count pending milestones ────────────────────────────────────────
   const pendingMilestones = state.registry.filter(
-    m => m.status === "pending" || m.status === "active",
+    m => isFutureMilestoneStatus(m.status) || m.status === "active",
   );
   const completeCount = state.registry.filter(m => m.status === "complete").length;
   const parkedCount = state.registry.filter(m => m.status === "parked").length;
@@ -182,7 +183,7 @@ export async function showQueueAdd(
     ? `Currently executing: ${state.activeMilestone.id} — ${state.activeMilestone.title} (phase: ${state.phase}).`
     : "No milestone currently active.";
 
-  const pendingCount = state.registry.filter(m => m.status === "pending").length;
+  const pendingCount = state.registry.filter(m => isFutureMilestoneStatus(m.status)).length;
   const completeCount = state.registry.filter(m => m.status === "complete").length;
 
   const preamble = [
@@ -284,7 +285,7 @@ export async function buildExistingMilestonesContext(
 
     // For active/pending/parked milestones, include the roadmap if it exists
     // (shows what's planned but not yet built)
-    if (status === "active" || status === "pending" || status === "parked") {
+    if (status === "active" || isFutureMilestoneStatus(status) || status === "parked") {
       const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
       if (roadmapFile) {
         const content = await loadFile(roadmapFile);

package/src/resources/extensions/gsd/guided-flow.ts

@@ -48,6 +48,7 @@ import { getIsolationMode, loadEffectiveGSDPreferences } from "./preferences.js"
 import { resolveUokFlags } from "./uok/flags.js";
 import { ensurePlanV2Graph, isMissingFinalizedContextResult } from "./uok/plan-v2.js";
 import { detectProjectState, hasGsdBootstrapArtifacts } from "./detection.js";
+import { isFutureMilestoneStatus } from "./status-guards.js";
 import { showProjectInit, offerMigration } from "./init-wizard.js";
 import { validateDirectory } from "./validate-directory.js";
 import { showConfirm } from "../shared/tui.js";
@@ -1042,6 +1043,7 @@ async function dispatchWorkflow(
             ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider)
             : undefined,
         baseUrl: result.appliedModel?.baseUrl ?? ctx.model?.baseUrl,
+        activeTools: typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [],
       },
     );
     if (compatibilityError) {
@@ -1471,7 +1473,7 @@ export async function showDiscuss(
   // No active milestone (or corrupted milestone with undefined id) —
   // check for pending milestones to discuss instead
   if (!state.activeMilestone?.id) {
-    const pendingMilestones = state.registry.filter(m => m.status === "pending");
+    const pendingMilestones = state.registry.filter(m => isFutureMilestoneStatus(m.status));
     if (pendingMilestones.length === 0) {
       ctx.ui.notify("No active milestone. Run /gsd to create one first.", "warning");
       return;
@@ -1583,7 +1585,7 @@ export async function showDiscuss(
 
   if (pendingSlices.length === 0) {
     // All slices complete — but queued milestones may still need discussion (#3150)
-    const pendingMilestones = state.registry.filter(m => m.status === "pending");
+    const pendingMilestones = state.registry.filter(m => isFutureMilestoneStatus(m.status));
     if (pendingMilestones.length > 0) {
       await showDiscussQueuedMilestone(ctx, pi, basePath, pendingMilestones);
       return;
@@ -1607,7 +1609,7 @@ export async function showDiscuss(
     // If all pending slices are discussed, check for queued milestones before exiting (#3150)
     const allDiscussed = pendingSlices.every(s => discussedMap.get(s.id));
     if (allDiscussed) {
-      const pendingMilestones = state.registry.filter(m => m.status === "pending");
+      const pendingMilestones = state.registry.filter(m => isFutureMilestoneStatus(m.status));
       if (pendingMilestones.length > 0) {
         await showDiscussQueuedMilestone(ctx, pi, basePath, pendingMilestones);
         return;
@@ -1643,7 +1645,7 @@ export async function showDiscuss(
     });
 
     // Offer access to queued milestones when any exist
-    const pendingMilestones = state.registry.filter(m => m.status === "pending");
+    const pendingMilestones = state.registry.filter(m => isFutureMilestoneStatus(m.status));
     if (pendingMilestones.length > 0) {
       actions.push({
         id: "discuss_queued_milestone",
@@ -1718,10 +1720,11 @@ async function showDiscussQueuedMilestone(
     const hasContext = !!resolveMilestoneFile(basePath, m.id, "CONTEXT");
     const hasDraft = !hasContext && !!resolveMilestoneFile(basePath, m.id, "CONTEXT-DRAFT");
     const contextStatus = hasContext ? "context ✓" : hasDraft ? "draft context" : "no context yet";
+    const statusLabel = m.status === "planned" ? "planned" : "queued";
     return {
       id: m.id,
       label: `${m.id}: ${m.title}`,
-      description: `[queued] · ${contextStatus}`,
+      description: `[${statusLabel}] · ${contextStatus}`,
       recommended: i === 0,
     };
   });

package/src/resources/extensions/gsd/markdown-renderer.ts

@@ -32,7 +32,7 @@ import {
   resolveMilestoneFile,
   resolveSliceFile,
   resolveSlicePath,
-  resolveTasksDir,
+  gsdProjectionRoot,
   gsdRoot,
   buildTaskFileName,
   buildSliceFileName,
@@ -48,7 +48,11 @@ import { clearPathCache } from "./paths.js";
  * E.g. "/project/.gsd/milestones/M001/M001-ROADMAP.md" → "milestones/M001/M001-ROADMAP.md"
  */
 function toArtifactPath(absPath: string, basePath: string): string {
-  const root = gsdRoot(basePath);
+  const projectionRoot = gsdProjectionRoot(basePath);
+  const projectionRel = relative(projectionRoot, absPath);
+  const root = projectionRel && !projectionRel.startsWith("..") && !projectionRel.startsWith("/")
+    ? projectionRoot
+    : gsdRoot(basePath);
   const rel = relative(root, absPath);
   // Normalize to forward slashes for consistent DB keys
   return rel.replace(/\\/g, "/");
@@ -374,10 +378,9 @@ export async function renderPlanFromDb(
     throw new Error(`no tasks found for ${milestoneId}/${sliceId}`);
   }
 
-  const slicePath = resolveSlicePath(basePath, milestoneId, sliceId)
-    ?? join(gsdRoot(basePath), "milestones", milestoneId, "slices", sliceId);
-  const absPath = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN")
-    ?? join(slicePath, `${sliceId}-PLAN.md`);
+  const slicePath = join(gsdProjectionRoot(basePath), "milestones", milestoneId, "slices", sliceId);
+  mkdirSync(slicePath, { recursive: true });
+  const absPath = join(slicePath, `${sliceId}-PLAN.md`);
   const artifactPath = toArtifactPath(absPath, basePath);
   const sliceGates = getGateResults(milestoneId, sliceId, "slice");
   const content = renderSlicePlanMarkdown(slice, tasks, sliceGates);
@@ -408,8 +411,7 @@ export async function renderTaskPlanFromDb(
     throw new Error(`task ${milestoneId}/${sliceId}/${taskId} not found`);
   }
 
-  const tasksDir = resolveTasksDir(basePath, milestoneId, sliceId)
-    ?? join(gsdRoot(basePath), "milestones", milestoneId, "slices", sliceId, "tasks");
+  const tasksDir = join(gsdProjectionRoot(basePath), "milestones", milestoneId, "slices", sliceId, "tasks");
   mkdirSync(tasksDir, { recursive: true });
   const absPath = join(tasksDir, buildTaskFileName(taskId, "PLAN"));
   const artifactPath = toArtifactPath(absPath, basePath);

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

@@ -357,6 +357,11 @@ export function resolveGsdPathContract(
   };
 }
 
+export function gsdProjectionRoot(basePath: string): string {
+  const contract = resolveGsdPathContract(basePath);
+  return normalizeRealPath(contract.worktreeGsd ?? contract.projectGsd);
+}
+
 /**
  * Invalidate the gsdRoot cache.
  * Use ONLY at session-reset boundaries: workspace switch, process exit, or

package/src/resources/extensions/gsd/queue-reorder-ui.ts

@@ -43,6 +43,7 @@ export async function showQueueReorder(
     const items = [...pending];
     let cursor = 0;
     let grabbed = false;
+    let scrollOffset = 0;
     let cachedLines: string[] | undefined;
     let validation: DependencyValidation;
 
@@ -154,8 +155,10 @@ export async function showQueueReorder(
 
       const ui = makeUI(theme, width);
       const lines: string[] = [];
+      const queueRows: string[] = [];
       const push = (...rows: string[][]) => { for (const r of rows) lines.push(...r); };
       const add = (s: string) => truncateToWidth(s, width);
+      let cursorQueueRow = 0;
 
       const headerText = grabbed ? "  Queue Reorder — Moving Item" : "  Queue Reorder";
       push(ui.bar(), ui.blank(), ui.header(headerText), ui.blank());
@@ -188,11 +191,13 @@ export async function showQueueReorder(
         const label = item.title && item.title !== item.id ? `${item.id}  ${item.title}` : item.id;
 
         if (isCursor && grabbed) {
-          lines.push(add(`  ${theme.fg("warning", `▸▸ ${num}. ${label}`)}`));
+          cursorQueueRow = queueRows.length;
+          queueRows.push(add(`  ${theme.fg("warning", `▸▸ ${num}. ${label}`)}`));
         } else if (isCursor) {
-          lines.push(add(`  ${theme.fg("accent", `${GLYPH.cursor} ${num}. ${label}`)}`));
+          cursorQueueRow = queueRows.length;
+          queueRows.push(add(`  ${theme.fg("accent", `${GLYPH.cursor} ${num}. ${label}`)}`));
         } else {
-          lines.push(add(`    ${theme.fg("text", `${num}. ${label}`)}`));
+          queueRows.push(add(`    ${theme.fg("text", `${num}. ${label}`)}`));
         }
 
         // depends_on annotations
@@ -201,36 +206,37 @@ export async function showQueueReorder(
           if (completedIds.has(dep)) continue;
           const pairKey = `${item.id}:${dep}`;
           if (violatedPairs.has(pairKey)) {
-            lines.push(add(`       ${theme.fg("warning", `${GLYPH.statusWarning} depends_on: ${dep} — auto-removed on confirm`)}`));
+            queueRows.push(add(`       ${theme.fg("warning", `${GLYPH.statusWarning} depends_on: ${dep} — auto-removed on confirm`)}`));
           } else if (redundantPairs.has(pairKey)) {
-            lines.push(add(`       ${theme.fg("dim", `↳ depends_on: ${dep} (redundant)`)}`));
+            queueRows.push(add(`       ${theme.fg("dim", `↳ depends_on: ${dep} (redundant)`)}`));
           } else {
-            lines.push(add(`       ${theme.fg("dim", `↳ depends_on: ${dep}`)}`));
+            queueRows.push(add(`       ${theme.fg("dim", `↳ depends_on: ${dep}`)}`));
           }
         }
 
         // Missing deps
         for (const v of validation.violations.filter(v => v.milestone === item.id && v.type === 'missing_dep')) {
-          lines.push(add(`       ${theme.fg("error", `${GLYPH.statusWarning} depends_on: ${v.dependsOn} (does not exist)`)}`));
+          queueRows.push(add(`       ${theme.fg("error", `${GLYPH.statusWarning} depends_on: ${v.dependsOn} (does not exist)`)}`));
         }
       }
 
       // Removed deps feedback
+      const trailingLines: string[] = [];
       if (removedDeps.length > 0) {
-        push(ui.blank());
+        trailingLines.push(...ui.blank());
         for (const r of removedDeps) {
-          lines.push(add(`  ${theme.fg("success", `${GLYPH.statusDone} Removed: ${r.milestone} depends_on ${r.dep}`)}`));
+          trailingLines.push(add(`  ${theme.fg("success", `${GLYPH.statusDone} Removed: ${r.milestone} depends_on ${r.dep}`)}`));
         }
       }
 
       // Circular warning
       const circ = validation.violations.find(v => v.type === 'circular');
       if (circ) {
-        push(ui.blank());
-        lines.push(add(`  ${theme.fg("error", `${GLYPH.statusWarning} ${circ.message}`)}`));
+        trailingLines.push(...ui.blank());
+        trailingLines.push(add(`  ${theme.fg("error", `${GLYPH.statusWarning} ${circ.message}`)}`));
       }
 
-      push(ui.blank());
+      trailingLines.push(...ui.blank());
 
       // Hints — context-sensitive based on grab state
       const hints: string[] = [];
@@ -250,7 +256,19 @@ export async function showQueueReorder(
       }
       hints.push("esc");
 
-      push(ui.hints(hints), ui.bar());
+      trailingLines.push(...ui.hints(hints), ...ui.bar());
+
+      const maxOverlayRows = Math.max(10, process.stdout.rows ? Math.floor(process.stdout.rows * 0.8) : 24);
+      const availableQueueRows = Math.max(1, maxOverlayRows - lines.length - trailingLines.length);
+      const maxScroll = Math.max(0, queueRows.length - availableQueueRows);
+      if (cursorQueueRow < scrollOffset) {
+        scrollOffset = cursorQueueRow;
+      } else if (cursorQueueRow >= scrollOffset + availableQueueRows) {
+        scrollOffset = cursorQueueRow - availableQueueRows + 1;
+      }
+      scrollOffset = Math.min(Math.max(scrollOffset, 0), maxScroll);
+
+      lines.push(...queueRows.slice(scrollOffset, scrollOffset + availableQueueRows), ...trailingLines);
 
       cachedLines = lines;
       return lines;