@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

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

@@ -10,8 +10,8 @@
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
-import { isAbsolute, join, relative } from "node:path";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
 import { QUICK_BRANCH_RE } from "./branch-patterns.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
@@ -31,6 +31,7 @@ interface QuickReturnState {
 }
 
 let pendingQuickReturn: QuickReturnState | null = null;
+const pendingQuickReturnMisses = new Map<string, string>();
 
 // ─── Quick Task Helpers ───────────────────────────────────────────────────────
 
@@ -189,12 +190,35 @@ export function buildQuickCommitInstruction(basePath: string, root: string): str
   ].join("\n");
 }
 
+function readHeadBranchName(basePath: string): string | null {
+  try {
+    const gitPath = join(basePath, ".git");
+    if (!existsSync(gitPath)) return null;
+
+    let headPath: string;
+    if (lstatSync(gitPath).isDirectory()) {
+      headPath = join(gitPath, "HEAD");
+    } else {
+      const gitFile = readFileSync(gitPath, "utf-8").trim();
+      if (!gitFile.startsWith("gitdir: ")) return null;
+      headPath = join(resolve(basePath, gitFile.slice("gitdir: ".length)), "HEAD");
+    }
+
+    const head = readFileSync(headPath, "utf-8").trim();
+    if (!head.startsWith("ref: refs/heads/")) return null;
+    return head.slice("ref: refs/heads/".length);
+  } catch {
+    return null;
+  }
+}
+
 function quickReturnStatePath(basePath: string): string {
   return join(gsdRoot(basePath), "runtime", "quick-return.json");
 }
 
 function persistPendingReturn(state: QuickReturnState): void {
   pendingQuickReturn = state;
+  pendingQuickReturnMisses.delete(state.basePath);
   mkdirSync(join(gsdRoot(state.basePath), "runtime"), { recursive: true });
   writeFileSync(quickReturnStatePath(state.basePath), JSON.stringify(state) + "\n", "utf-8");
 }
@@ -203,6 +227,13 @@ function readPendingReturn(basePath: string): QuickReturnState | null {
   if (pendingQuickReturn && pendingQuickReturn.basePath === basePath) {
     return pendingQuickReturn;
   }
+  if (pendingQuickReturnMisses.has(basePath)) {
+    const statePath = quickReturnStatePath(basePath);
+    if (!existsSync(statePath) && readHeadBranchName(basePath) === pendingQuickReturnMisses.get(basePath)) {
+      return null;
+    }
+    pendingQuickReturnMisses.delete(basePath);
+  }
 
   try {
     const raw = readFileSync(quickReturnStatePath(basePath), "utf-8");
@@ -216,6 +247,7 @@ function readPendingReturn(basePath: string): QuickReturnState | null {
       && typeof parsed.description === "string"
     ) {
       pendingQuickReturn = parsed as QuickReturnState;
+      pendingQuickReturnMisses.delete(basePath);
       return pendingQuickReturn;
     }
   } catch {
@@ -225,9 +257,14 @@ function readPendingReturn(basePath: string): QuickReturnState | null {
   const inferred = inferQuickReturnFromBranch(basePath);
   if (inferred) {
     pendingQuickReturn = inferred;
+    pendingQuickReturnMisses.delete(basePath);
     return inferred;
   }
 
+  const branchAtMiss = readHeadBranchName(basePath);
+  if (branchAtMiss) {
+    pendingQuickReturnMisses.set(basePath, branchAtMiss);
+  }
   return null;
 }
 
@@ -235,6 +272,10 @@ function clearPendingReturn(basePath: string): void {
   if (pendingQuickReturn?.basePath === basePath) {
     pendingQuickReturn = null;
   }
+  const branchAtMiss = readHeadBranchName(basePath);
+  if (branchAtMiss) {
+    pendingQuickReturnMisses.set(basePath, branchAtMiss);
+  }
   rmSync(quickReturnStatePath(basePath), { force: true });
 }
 

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

@@ -4,6 +4,7 @@
 import { isToolUnavailableError } from "./auto-tool-tracking.js";
 import { classifyError, isTransient, type ErrorClass } from "./error-classifier.js";
 import { recoveryRemediation } from "./guidance.js";
+import { isTerminalToolSurfaceError } from "./tool-surface-readiness.js";
 import { ReconciliationFailedError } from "./state-reconciliation.js";
 import { IllegalPhaseTransitionError } from "./state-transition-matrix.js";
 
@@ -94,6 +95,12 @@ const FAILURE_TAXONOMY: Record<
 };
 
 function inferFailureKind(message: string): RecoveryFailureKind {
+  // A terminal tool-surface failure (workflow MCP server in failed/needs-auth/
+  // disabled) will not self-heal, so it must escalate rather than retry the
+  // same model into the per-unit cost cap. Checked before the generic
+  // tool-unavailable branch, which matches the same readiness prefix and
+  // would otherwise route it to retry. See #783.
+  if (isTerminalToolSurfaceError(message)) return "runtime-unknown";
   if (isToolUnavailableError(message)) return "tool-unavailable";
   if (/tool contract|auto-unit tool scope|phase-boundary gate|not permitted.*own/i.test(message)) return "tool-contract";
   if (/lifecycle progression|required artifact|missing .*assessment|missing .*closeout|cannot legally (?:advance|progress)/i.test(message)) return "lifecycle-progression";

package/src/resources/extensions/gsd/redact-secrets.ts

@@ -0,0 +1,40 @@
+// redact-secrets.ts
+// Best-effort redaction of secret-shaped substrings before persisting free text
+// (exec-sandbox output, activity-log session entries) to disk under .gsd/, which
+// the secret scanner skips. Patterns mirror scripts/secret-scan.mjs.
+
+const PLACEHOLDER = "«redacted»";
+
+// Each secret shape. Global flag so replace() catches every occurrence in a line.
+// Order is not significant — matches are replaced independently.
+const PATTERNS: RegExp[] = [
+  /AKIA[0-9A-Z]{16}/g, // AWS access key id
+  /(api[_-]?key|apikey|api[_-]?secret)[ \t]*[:=][ \t]*['"][0-9a-zA-Z_./-]{20,}['"]/gi,
+  /(secret|token|password|passwd|pwd|credential)[ \t]*[:=][ \t]*['"][^\s'"]{8,}['"]/gi,
+  /(authorization|bearer)[ \t]*[:=][ \t]*['"][^\s'"]{8,}['"]/gi,
+  /Bearer[ \t]+[0-9a-zA-Z._-]{8,}/g, // Authorization: Bearer <token> (unquoted)
+  /-----BEGIN\s+(RSA|DSA|EC|OPENSSH|PGP)\s+PRIVATE\s+KEY-----[\s\S]*?-----END\s+(RSA|DSA|EC|OPENSSH|PGP)\s+PRIVATE\s+KEY-----/g,
+  /(mysql|postgres|postgresql|mongodb|redis|amqp|mssql):\/\/[^\s'"]{8,}/gi,
+  /gh[pousr]_[0-9a-zA-Z]{36,}/g, // GitHub token
+  /glpat-[0-9a-zA-Z-]{20,}/g, // GitLab token
+  /xox[baprs]-[0-9a-zA-Z-]{10,}/g, // Slack token
+  /hooks\.slack\.com\/services\/T[0-9A-Z]{8,}\/B[0-9A-Z]{8,}\/[0-9a-zA-Z]{20,}/g,
+  /AIza[0-9A-Za-z_-]{35}/g, // Google API key
+  /[sr]k_(live|test)_[0-9a-zA-Z]{20,}/g, // Stripe key
+  /sk-(ant-)?[0-9a-zA-Z_-]{20,}/g, // OpenAI / Anthropic style key
+  /npm_[0-9a-zA-Z]{36,}/g, // npm token
+  /(secret|key|token|password)[ \t]*[:=][ \t]*['"]?[0-9a-f]{32,}['"]?/gi, // hex secret
+];
+
+/**
+ * Replace secret-shaped substrings in `text` with a placeholder, preserving the
+ * surrounding content. Pure and safe to call per log line. The placeholder
+ * contains no quote/brace/backslash, so redacting a JSON string keeps it valid.
+ */
+export function redactSecrets(text: string): string {
+  let out = text;
+  for (const pattern of PATTERNS) {
+    out = out.replace(pattern, PLACEHOLDER);
+  }
+  return out;
+}

package/src/resources/extensions/gsd/repo-identity.ts

@@ -355,6 +355,23 @@ export function externalProjectsRoot(): string {
   return join(base, "projects");
 }
 
+/**
+ * Check whether this project already has authoritative external state.
+ *
+ * Used by legacy `.gsd/` migration to avoid re-copying a re-materialized local
+ * directory over newer state when an already-migrated symlink was replaced.
+ */
+export function externalStateAlreadyExistsForProject(basePath: string): boolean {
+  const base = process.env.GSD_STATE_DIR || gsdHome();
+  const computedPath = join(base, "projects", repoIdentity(basePath));
+  if (hasProjectState(computedPath)) return true;
+
+  const markerId = readGsdIdMarker(resolveGitRoot(basePath));
+  if (!markerId) return false;
+
+  return hasProjectState(join(base, "projects", markerId));
+}
+
 // ─── Numbered Variant Cleanup ────────────────────────────────────────────────
 
 /**

package/src/resources/extensions/gsd/repository-registry.ts

@@ -23,6 +23,12 @@ export interface RepositoryRegistry {
 }
 
 export function defaultRepositoryTargets(registry: RepositoryRegistry): string[] {
+  // In parent mode, default to the declared child repositories so work is
+  // attributed to the repo it touches — not silently to the root "project".
+  if (registry.mode === "parent") {
+    return registry.repositories.filter((repo) => repo.id !== "project").map((repo) => repo.id);
+  }
+
   const project = registry.byId.get("project");
   if (project) return [project.id];
   const first = registry.repositories[0];
@@ -78,7 +84,7 @@ export function createRepositoryRegistry(
 ): RepositoryRegistry {
   const contract = resolveGsdPathContract(basePath);
   const projectRoot = contract.isWorktree
-    ? resolveGitWorkingTreeRoot(contract.workRoot) ?? contract.projectRoot
+    ? resolveGitWorkingTreeRoot(contract.workRoot) ?? contract.workRoot
     : contract.projectRoot;
   const mode = workspacePrefs?.mode ?? "project";
   const repoMap = new Map<string, RegisteredRepository>();

package/src/resources/extensions/gsd/roadmap-slices.ts

@@ -201,7 +201,7 @@ export function parseRoadmapSlices(content: string): RoadmapSliceEntry[] {
   let currentSlice: RoadmapSliceEntry | null = null;
 
   for (const line of checkboxItems) {
-    const cbMatch = line.match(/^\s*-\s+\[([ xX])\]\s+\*\*([\w.]+):\s+(.+?)\*\*\s*(.*)/);
+    const cbMatch = line.match(/^\s*-\s+\[([ xX])\]\s+\*\*([\w.-]+):\s+(.+?)\*\*\s*(.*)/);
     if (cbMatch) {
       if (currentSlice) slices.push(currentSlice);
 

package/src/resources/extensions/gsd/root-write-leak-guard.ts

@@ -5,8 +5,18 @@ import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { GSD_RUNTIME_PATTERNS } from "./gitignore.js";
 
 const MAX_SYNC_FINGERPRINT_BYTES = 1_500_000_000;
+const ROOT_RUNTIME_PATH_PREFIXES = Array.from(
+  new Set(
+    GSD_RUNTIME_PATTERNS.map((pattern) => {
+      const path = pattern.replace(/\/+$/, "");
+      const slash = path.indexOf("/");
+      return slash === -1 ? path : path.slice(0, slash);
+    }),
+  ),
+);
 
 export interface RootDirtyEntry {
   path: string;
@@ -25,7 +35,9 @@ export interface RootWriteLeak {
 export type RootDirtySnapshot = Map<string, RootDirtyEntry>;
 
 function isRootRuntimePath(path: string): boolean {
-  return path === ".gsd" || path.startsWith(".gsd/");
+  return ROOT_RUNTIME_PATH_PREFIXES.some(
+    (prefix) => path === prefix || path.startsWith(`${prefix}/`),
+  );
 }
 
 function fileFingerprint(rootPath: string, relPath: string): string {
@@ -53,11 +65,12 @@ export function captureRootDirtySnapshot(rootPath: string): RootDirtySnapshot {
   for (const line of status.split("\n")) {
     if (!line.trim()) continue;
     const code = line.slice(0, 2);
+    if (code !== "??") continue;
     const path = line.slice(3).replace(/^"|"$/g, "");
     if (!path || isRootRuntimePath(path)) continue;
     snapshot.set(path, {
       path,
-      status: code.trim() || code,
+      status: code,
       fingerprint: fileFingerprint(rootPath, path),
     });
   }
@@ -75,7 +88,7 @@ export function detectRootWriteLeak(input: {
   const leaked: RootDirtyEntry[] = [];
   for (const entry of after.values()) {
     const prior = input.before?.get(entry.path);
-    if (!prior || prior.status !== entry.status || prior.fingerprint !== entry.fingerprint) {
+    if (!prior || prior.fingerprint !== entry.fingerprint) {
       leaked.push(entry);
     }
   }

package/src/resources/extensions/gsd/safe-fs.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, cpSync, type CopySyncOptions } from "node:fs"
+import { existsSync, mkdirSync, cpSync, statSync, type CopySyncOptions } from "node:fs"
 import { dirname } from "node:path"
 import { logWarning } from "./workflow-logger.js"
 
@@ -39,7 +39,27 @@ export function safeCopyRecursive(src: string, dst: string, opts?: Omit<CopySync
   if (!existsSync(src)) return false
   try {
     mkdirSync(dirname(dst), { recursive: true })
-    cpSync(src, dst, { ...opts, recursive: true })
+    const userFilter = opts?.filter
+    cpSync(src, dst, {
+      ...opts,
+      recursive: true,
+      filter: (srcPath, dstPath) => {
+        if (existsSync(dstPath)) {
+          try {
+            const srcStat = statSync(srcPath)
+            const dstStat = statSync(dstPath)
+            if (srcStat.isDirectory() !== dstStat.isDirectory()) {
+              logWarning("fs", `recursive copy skipped type collision: ${srcPath} → ${dstPath}`)
+              return false
+            }
+          } catch (err) {
+            logWarning("fs", `recursive copy skipped unreadable path: ${srcPath} → ${dstPath}: ${(err as Error).message}`)
+            return false
+          }
+        }
+        return userFilter ? userFilter(srcPath, dstPath) : true
+      },
+    })
     return true
   } catch (err) {
     logWarning("fs", `recursive copy failed: ${src} → ${dst}: ${(err as Error).message}`)

package/src/resources/extensions/gsd/safety/content-validator.ts

@@ -46,7 +46,8 @@ export function validateContent(
 
 type ContentValidatorFn = (content: string) => ContentViolation[];
 
-const TASK_MARKER_RE = /^\s*(?:-\s+\[[ xX]\]\s+\*\*T\d+:|#{2,4}\s+T\d+\b)/gm;
+// Matches both legacy "**T01: title**" and flat-phase "**T01**: title" checkbox formats.
+const TASK_MARKER_RE = /^\s*(?:-\s+\[[ xX]\]\s+\*\*T\d+(?:\*\*)?:|#{2,4}\s+T\d+\b)/gm;
 const SLICE_MARKER_RE = /^\s*(?:-\s+\[[ xX]\]\s+\*\*S\d+:|#{2,4}\s+S\d+\b)/gm;
 
 const VALIDATORS: Record<string, ContentValidatorFn> = {

package/src/resources/extensions/gsd/safety/destructive-guard.ts

@@ -29,6 +29,13 @@ const DESTRUCTIVE_PATTERNS: readonly DestructivePattern[] = [
   { pattern: /\bkubectl\s+(delete|apply)\b/i, label: "kubectl mutation" },
 ];
 
+function stripQuotedAndComments(command: string): string {
+  return command
+    .replace(/"(?:[^"\\]|\\.)*"/g, '""')
+    .replace(/'(?:[^'\\]|\\.)*'/g, "''")
+    .replace(/(^|\s)#.*$/g, "$1");
+}
+
 // ─── Public API ─────────────────────────────────────────────────────────────
 
 export interface CommandClassification {
@@ -41,9 +48,10 @@ export interface CommandClassification {
  * Returns the list of matched destructive pattern labels.
  */
 export function classifyCommand(command: string): CommandClassification {
+  const commandToClassify = stripQuotedAndComments(command);
   const labels: string[] = [];
   for (const { pattern, label } of DESTRUCTIVE_PATTERNS) {
-    if (pattern.test(command)) {
+    if (pattern.test(commandToClassify)) {
       // Deduplicate labels (e.g., two force-push patterns)
       if (!labels.includes(label)) labels.push(label);
     }

package/src/resources/extensions/gsd/safety/evidence-collector.ts

@@ -65,12 +65,16 @@ const MCP_EXECUTION_TOOL_RE = /^mcp__.+__gsd_(?:uat_)?exec(?:_search)?$/;
 // ─── Module State ───────────────────────────────────────────────────────────
 
 let unitEvidence: EvidenceEntry[] = [];
+let lastWritePath: string | null = null;
+let lastWriteSig: string | null = null;
 
 // ─── Public API ─────────────────────────────────────────────────────────────
 
 /** Reset all evidence for a new unit. Call at unit start. */
 export function resetEvidence(): void {
   unitEvidence = [];
+  lastWritePath = null;
+  lastWriteSig = null;
 }
 
 /** Get a read-only view of all evidence collected for the current unit. */
@@ -145,10 +149,15 @@ export function saveEvidenceToDisk(
 ): void {
   try {
     const path = evidencePath(basePath, milestoneId, sliceId, taskId);
+    const body = JSON.stringify(unitEvidence, null, 2) + "\n";
+    if (path === lastWritePath && body === lastWriteSig) return;
+
     mkdirSync(dirname(path), { recursive: true });
     const tmp = `${path}.tmp.${randomBytes(4).toString("hex")}`;
-    writeFileSync(tmp, JSON.stringify(unitEvidence, null, 2) + "\n", "utf-8");
+    writeFileSync(tmp, body, "utf-8");
     renameSync(tmp, path);
+    lastWritePath = path;
+    lastWriteSig = body;
   } catch {
     // Non-fatal — don't let persistence failures break unit execution
   }
@@ -167,6 +176,8 @@ export function loadEvidenceFromDisk(
   taskId: string,
 ): void {
   try {
+    lastWritePath = null;
+    lastWriteSig = null;
     const path = evidencePath(basePath, milestoneId, sliceId, taskId);
     if (!existsSync(path)) return;
     const raw = readFileSync(path, "utf-8");
@@ -195,6 +206,10 @@ export function clearEvidenceFromDisk(
     if (existsSync(path)) {
       unlinkSync(path);
     }
+    if (path === lastWritePath) {
+      lastWritePath = null;
+      lastWriteSig = null;
+    }
   } catch {
     // Non-fatal
   }

package/src/resources/extensions/gsd/safety/evidence-cross-ref.ts

@@ -66,8 +66,28 @@ export function crossReferenceEvidence(
       continue;
     }
 
+    // A shell-spawn/infra failure means the command never ran (e.g. on Windows
+    // `gsd_exec runtime=bash` resolves to a WSL with no /bin/bash). The LLM
+    // typically recovers by re-running via another runtime, and that genuine
+    // run may not even be in the match set. Such a failure is inconclusive, not
+    // a falsified pass — exclude it before judging the exit code.
+    const commandRuns = matches.filter((m) => !isInfraSpawnFailure(m));
+    if (commandRuns.length === 0) {
+      if (claimed.exitCode === 0) {
+        mismatches.push({
+          severity: "warning",
+          claimed,
+          actual: latestMatch(matches),
+          reason:
+            `Matched execution failed to spawn (infrastructure error, not a command failure); ` +
+            `treating as inconclusive`,
+        });
+      }
+      continue;
+    }
+
     // Exit code mismatch: LLM claims success but actual command failed
-    const match = latestMatch(matches);
+    const match = latestMatch(commandRuns);
     if (claimed.exitCode === 0 && match.exitCode !== 0) {
       mismatches.push({
         severity: "error",
@@ -81,6 +101,30 @@ export function crossReferenceEvidence(
   return mismatches;
 }
 
+/**
+ * Runtime-spawn / shell-infra failure signatures. When a bash-runtime call
+ * fails to *spawn* (rather than the command running and exiting non-zero), the
+ * recorded exitCode is an ordinary non-zero but the output carries one of these
+ * markers. Such a call is not evidence that a verification failed.
+ */
+const INFRA_SPAWN_FAILURE_SIGNATURES: readonly RegExp[] = [
+  /execvpe\([^)]*\)\s+failed/i,   // WSL: execvpe(/bin/bash) failed: No such file or directory
+  /WSL \(.*\) ERROR/i,            // WSL relay error banner
+  /command not found:\s*(?:bash|sh|zsh|dash|fish|ash|ksh|wsl)\b/i, // missing shell interpreter only
+];
+
+/**
+ * True when a non-zero bash call looks like a shell-spawn/infra failure (the
+ * command never started) rather than a real command failure. A successful run
+ * (exitCode 0) is never an infra failure.
+ */
+function isInfraSpawnFailure(call: BashEvidence): boolean {
+  if (call.exitCode === 0) return false;
+  const snippet = call.outputSnippet ?? "";
+  if (snippet.length === 0) return false;
+  return INFRA_SPAWN_FAILURE_SIGNATURES.some((re) => re.test(snippet));
+}
+
 // ─── Internals ──────────────────────────────────────────────────────────────
 
 /**

package/src/resources/extensions/gsd/safety/file-change-validator.ts

@@ -76,8 +76,14 @@ export function validateFileChanges(
   const actualFiles = getChangedFilesFromLastCommit(basePath);
   if (!actualFiles) return null;
 
-  // Filter out .gsd/ internal files — only validate project source files
-  const projectFiles = actualFiles.filter(f => !f.startsWith(".gsd/") && !f.startsWith(".gsd\\"));
+  // Filter out GSD-internal paths — only validate project source files.
+  const projectFiles = actualFiles.filter(
+    (f) =>
+      !f.startsWith(".gsd/") &&
+      !f.startsWith(".gsd\\") &&
+      !f.startsWith(".gsd-backups/") &&
+      !f.startsWith(".gsd-backups\\"),
+  );
 
   // Normalize expected paths (strip leading ./ or /)
   const normalizedExpected = new Set(

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

@@ -13,6 +13,7 @@ import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import { existsSync, readFileSync } from "node:fs";
 import { saveFile } from "./files.js";
 import {
+  clearGSDPreferencesCache,
   getGlobalGSDPreferencesPath,
   loadEffectiveGSDPreferences,
   loadGlobalGSDPreferences,
@@ -153,6 +154,7 @@ async function writeGlobalServiceTier(
   }
 
   await saveFile(path, `---\n${frontmatter}---${body}`);
+  clearGSDPreferencesCache();
   await ctx.waitForIdle();
   await ctx.reload();
 }

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

@@ -223,11 +223,21 @@ export function extractTrace(entries: unknown[]): ExecutionTrace {
 
   // Flush any pending tool calls that never got results (crash mid-tool)
   for (const [, pending] of pendingTools) {
+    const missingResultError = `Tool call ${pending.name} started but no toolResult was recorded`;
     toolCalls.push({
       name: pending.name,
       input: redactInput(pending.name, pending.input),
-      isError: false,
+      result: "missing tool result (stream/tool-call abort before execution)",
+      isError: true,
     });
+    errors.push(missingResultError);
+
+    // Mark the matching commandsRun entry as failed so it is consistent with
+    // the isError: true on the tool call above (bash/bg_shell only).
+    if (pending.name === "bash" || pending.name === "bg_shell") {
+      const lastCmd = findLast(commandsRun, c => c.command === String(pending.input.command));
+      if (lastCmd) lastCmd.failed = true;
+    }
   }
 
   return {

package/src/resources/extensions/gsd/session-lock.ts

@@ -698,6 +698,12 @@ export interface RetryOptions {
   delayMs?: number;
 }
 
+const _retrySleepView = new Int32Array(new SharedArrayBuffer(4));
+function sleepSync(ms: number): void {
+  if (!(ms > 0)) return;
+  Atomics.wait(_retrySleepView, 0, 0, ms);
+}
+
 export function readExistingLockDataWithRetry(
   lp: string,
   options?: RetryOptions,
@@ -709,12 +715,7 @@ export function readExistingLockDataWithRetry(
     const data = readExistingLockData(lp);
     if (data !== null) return data;
     if (attempt < maxAttempts) {
-      // Synchronous busy-wait — onCompromised runs in a sync callback context
-      // and the delays are short (200ms default).
-      const start = Date.now();
-      while (Date.now() - start < delayMs) {
-        // busy-wait
-      }
+      sleepSync(delayMs);
     }
   }
   return null;

package/src/resources/extensions/gsd/skills/gsd-headless/SKILL.md

@@ -211,17 +211,15 @@ All state lives in `.gsd/` as markdown files (version-controllable):
 
 ```
 .gsd/
-  milestones/M001/
-    M001-CONTEXT.md      # Requirements, scope, decisions
-    M001-ROADMAP.md      # Slices with tasks, dependencies, checkboxes
-    M001-SUMMARY.md      # Completion summary
-    slices/S01/
-      S01-PLAN.md        # Task list
-      S01-SUMMARY.md     # Slice summary with frontmatter
-      tasks/T01-PLAN.md  # Individual task spec
+  phases/01-foundation/
+    01-CONTEXT.md        # Requirements, scope, decisions
+    01-ROADMAP.md        # Slices with tasks, dependencies, checkboxes
+    01-SUMMARY.md        # Completion summary
+    01-01-PLAN.md        # First slice task list
+    01-01-SUMMARY.md     # First slice summary with frontmatter
 ```
 
-State is derived from files on disk — checkboxes in ROADMAP.md are the source of truth for completion.
+Runtime state is stored in the project-root database; markdown files are reviewable projections written under `.gsd/phases/`. Legacy projects may still resolve to `.gsd/milestones/<MID>/` until migrated.
 
 ## All Headless Commands
 
@@ -240,3 +238,6 @@ Quick reference — see [references/commands.md](references/commands.md) for the
 | `skip` / `undo` | Unit control |
 | `doctor` | Health check + auto-fix |
 | `steer <desc>` | Hard-steer plan mid-execution |
+| `explore` / `spike` / `sketch` | Prompt-driven ideation and experiment workflows |
+| `map-codebase` / `docs-update` / `graphify` | Codebase documentation and knowledge workflows |
+| `code-review` / `review` / `audit-*` / `verify-work` | Review, audit, and UAT workflows |

package/src/resources/extensions/gsd/skills/gsd-headless/references/commands.md

@@ -22,6 +22,7 @@ All commands can be run via `gsd headless [command]`.
 | `status` | Progress dashboard (TUI overlay — useful interactively, not for parsing) |
 | `visualize` | Workflow visualizer (deps, metrics, timeline) |
 | `history` | Execution history (supports --cost, --phase, --model, limit) |
+| `codebase` | Manage `.gsd/CODEBASE.md`; parent workspaces include declared child repositories under repo-labeled sections |
 
 ## Unit Control
 
@@ -50,6 +51,57 @@ All commands can be run via `gsd headless [command]`.
 | `inspect` | Show SQLite DB diagnostics (schema, row counts) |
 | `forensics` | Post-mortem investigation of auto-mode failures |
 
+## Additional Prompt-Driven Workflows
+
+These commands dispatch native GSD prompts adapted to the milestone, slice, and `.gsd/` model. Use them as `gsd headless <command> [args...]`.
+
+| Command | Description |
+|---------|-------------|
+| `explore` | Socratic ideation before committing an idea |
+| `spike` | Focused throwaway experiment (`--quick`, `--text`, or frontier mode) |
+| `sketch` | UI/design exploration with throwaway HTML mockups |
+| `map-codebase` | Generate structured codebase docs under `.gsd/codebase/` |
+| `docs-update` | Generate, update, or verify docs against live code |
+| `graphify` | Build, query, inspect, or diff `.gsd/knowledge/` |
+| `stats` | Show project statistics, milestone state, git metrics, and timeline |
+| `progress` | Summarize recent work; can route `--next` or `--do "..."` |
+| `health` | Check `.gsd/` integrity (`--repair`, `--context`) |
+| `surface` | Manage surfaced skills and extensions |
+| `code-review` | Review changed source diff-first for bugs, security, and quality |
+| `review` | Peer-review recent work across reviewer perspectives |
+| `audit-milestone` | Verify a milestone met its definition of done |
+| `audit-uat` | Audit outstanding UAT/verification items |
+| `audit-fix` | Classify and remediate audit findings |
+| `ui-review` | Run a six-pillar frontend visual audit |
+| `secure-phase` | Verify threat mitigations |
+| `validate-phase` | Fill validation and test coverage gaps |
+| `verify-work` | Run conversational UAT |
+| `plan-review-convergence` | Iterate a plan through review cycles |
+| `discuss-phase` | Gather milestone or slice context through questions |
+| `plan-phase` | Create a detailed slice plan |
+| `execute-phase` | Execute slice tasks with wave support |
+| `spec-phase` | Clarify what a milestone delivers |
+| `mvp-phase` | Plan a vertical MVP milestone |
+| `ui-phase` | Produce a `UI-SPEC` |
+| `ai-integration-phase` | Produce an `AI-SPEC` |
+| `ultraplan-phase` | Run extended planning and review |
+| `autonomous` | Run remaining lifecycle work continuously |
+| `pause-work` | Create a pause handoff |
+| `resume-work` | Resume work with restored context |
+| `manager` | Manage multiple milestones from a command-center workflow |
+| `phase` | Manage milestone queue ordering |
+| `thread` | Manage persistent context threads |
+| `workstreams` | Route workstream actions through `parallel` |
+| `workspace` | Route workspace actions through `worktree` |
+| `milestone-summary` | Generate a project or milestone summary |
+| `review-backlog` | Review and promote backlog items |
+| `inbox` | Triage GitHub issues and PRs |
+| `import` | Ingest external plans with conflict detection |
+| `ingest-docs` | Bootstrap or merge `.gsd/` state from docs |
+| `profile-user` | Generate and persist a developer profile |
+| `settings` | Configure workflow toggles and model profile |
+| `ns-context`, `ns-ideate`, `ns-manage`, `ns-project`, `ns-review`, `ns-workflow` | Namespace-grouping names that redirect to `help` |
+
 ## Phases
 
 GSD workflows progress through these phases: