@opengsd/gsd-pi 1.8.0 → 1.8.1-dev.897b3c90

package/src/resources/extensions/gsd/prompts/refine-slice.md

@@ -66,12 +66,12 @@ Then:
    **Web apps:** when inlined Web App UAT guidance is present, follow it for Playwright scaffolding and browser-capable verification commands.
 4. For non-trivial slices, plan observability / proof level / integration closure, threat surface, and requirement impact. Omit entirely for simple slices.
 5. Decompose the slice into tasks that fit one context window each. Every task passed to `gsd_plan_slice` must use the exact keys `taskId`, `title`, `description`, `estimate`, `files`, `verify`, `inputs`, `expectedOutput`, and optional `observabilityImpact`. Put Why / Do / Done-when detail in `description`. `files`, `inputs`, and `expectedOutput` must be JSON arrays of strings, even for one path (for example, `"expectedOutput": ["src/index.ts"]`, never `"expectedOutput": "src/index.ts"`). `expectedOutput` is path-only: list only files the task creates or overwrites, and use `[]` for pure verification tasks. Never list GSD planning artifacts — anything under `.gsd/`, `.planning/`, or `.audits/`, or artifact names like `M001-CONTEXT.md` / `S01-PLAN.md` — in `inputs`, `files`, or `expectedOutput`: their content is preloaded as context, and they are written by workflow tools, not by tasks.
-6. **Persist planning state through `gsd_plan_slice`.** Call it with the full payload. The tool writes to the DB and renders `{{outputPath}}` and `{{slicePath}}/tasks/T##-PLAN.md` automatically. Do NOT rely on direct `PLAN.md` writes.
+6. **Persist planning state through `gsd_plan_slice`.** Call it with the full payload. The tool writes to the DB and renders `{{outputPath}}` with embedded task planning automatically. Do NOT rely on direct `PLAN.md` writes.
 7. **Self-audit the plan.** If every task were completed exactly as written, the slice goal/demo should be true. Every must-have maps to a task. Inputs and Expected Output are backtick-wrapped file paths.
 8. If refinement produced structural decisions that diverge from the sketch, call `gsd_decision_save` for each; the tool persists the decision and regenerates `.gsd/DECISIONS.md`.
 9. {{commitInstruction}}
 
-The slice directory and tasks/ subdirectory already exist. Do NOT mkdir.
+The slice plan path already exists. Do NOT mkdir.
 
 **Autonomous execution:** Do not call `ask_user_questions` or `secure_env_collect`. Document assumptions in the plan.
 

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

@@ -232,7 +232,7 @@ export function recordToolCall(toolCallId: string, toolName: string, input: Reco
       toolCallId,
       // gsd_exec / gsd_uat_exec carry the script body in `script` (or `code`);
       // bash-style tools use `command`/`cmd`; gsd_exec_search uses `query`.
-      command: String(input.command ?? input.script ?? input.cmd ?? input.code ?? input.query ?? ""),
+      command: formatExecutionEvidenceCommand(toolName, input),
       exitCode: -1,
       outputSnippet: "",
       timestamp: Date.now(),
@@ -254,6 +254,33 @@ export function recordToolCall(toolCallId: string, toolName: string, input: Reco
   }
 }
 
+function pickString(input: Record<string, unknown>, ...keys: string[]): string {
+  for (const key of keys) {
+    const value = input[key];
+    if (typeof value === "string" && value.trim().length > 0) return value.trim();
+  }
+  return "";
+}
+
+function canonicalExecutionToolLabel(toolName: string): string {
+  const normalized = toolName.trim().toLowerCase();
+  const mcpMatch = normalized.match(/^mcp__.+__(gsd_(?:uat_)?exec(?:_search)?)$/);
+  return mcpMatch?.[1] ?? normalized;
+}
+
+function formatExecutionEvidenceCommand(toolName: string, input: Record<string, unknown>): string {
+  const body = pickString(input, "command", "script", "cmd", "code", "query");
+  const tool = canonicalExecutionToolLabel(toolName);
+  const purpose = pickString(input, "purpose");
+  const runtime = pickString(input, "runtime").toLowerCase();
+  const label = purpose && (tool === "gsd_exec" || tool === "gsd_uat_exec")
+    ? `${tool}${runtime ? ` ${runtime}` : ""}: ${purpose}`
+    : "";
+
+  if (label && body) return `${label}\n${body}`;
+  return body || label;
+}
+
 /**
  * Record a tool execution result. Matches the entry by toolCallId (assigned
  * at dispatch time) and fills in exit code + output. Prior versions matched

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

@@ -161,9 +161,18 @@ function findMatches(
 ): BashEvidence[] {
   const normalized = claimedCommand.trim();
 
-  // Exact matches first
-  const exact = bashCalls.filter(b => b.command.trim() === normalized);
-  if (exact.length > 0) return exact;
+  const exact = bashCalls.filter((b) => b.command.trim() === normalized);
+
+  // When an exact run exists, also consider wrapper-equivalent reruns (e.g.
+  // `cd ... && <command>`) so a newer pass is not shadowed by a stale exact
+  // failure. Do not merge arbitrary containing scripts: their exit code may
+  // belong to later work, not to the claimed verification command.
+  const scriptWrapped = bashCalls.filter((b) => {
+    const command = b.command.trim();
+    if (command.length === 0 || command === normalized) return false;
+    return isWrapperEquivalentCommand(command, normalized);
+  });
+  if (exact.length > 0) return [...exact, ...scriptWrapped];
 
   // Substring match: claimed is contained in actual or actual in claimed.
   // A claimed verification command typically appears verbatim inside a
@@ -171,7 +180,7 @@ function findMatches(
   // script-containing-claim is the common direction. Blank-command entries
   // must be excluded — `"x".includes("")` is true, so they'd match anything.
   const substring = bashCalls.filter(
-    b => b.command.trim().length > 0 &&
+    (b) => b.command.trim().length > 0 &&
       (b.command.includes(normalized) || normalized.includes(b.command)),
   );
   if (substring.length > 0) return substring;
@@ -199,6 +208,23 @@ function findMatches(
 
 function latestMatch(matches: readonly BashEvidence[]): BashEvidence {
   return matches.reduce((latest, match) => (
-    match.timestamp > latest.timestamp ? match : latest
+    match.timestamp >= latest.timestamp ? match : latest
   ));
 }
+
+/** True when `actual` is the same command with only shell wrapper noise. */
+function isWrapperEquivalentCommand(actual: string, claimed: string): boolean {
+  const claimIndex = actual.lastIndexOf(claimed);
+  if (claimIndex < 0) return false;
+
+  const prefix = actual.slice(0, claimIndex).trim();
+  if (prefix.length > 0 && !/^cd\s+.+\s+&&$/.test(prefix)) return false;
+
+  const suffix = actual.slice(claimIndex + claimed.length).trim();
+  return suffix.length === 0 || isBenignWrapperSuffix(suffix);
+}
+
+function isBenignWrapperSuffix(suffix: string): boolean {
+  if (/^;\s*echo\s+["']?[A-Z_]*EXIT=\$\?["']?$/.test(suffix)) return true;
+  return /^(?:(?:\d?>>?|&>)\s*\S+|\d?>&\d)(?:\s+(?:(?:\d?>>?|&>)\s*\S+|\d?>&\d))*$/.test(suffix);
+}

package/src/resources/extensions/gsd/state-reconciliation/drift/external-markdown-edit.ts

@@ -3,9 +3,10 @@
 //
 // gsd-pi's DB is canonical, but .gsd/*.md is the inter-tool contract. When
 // gsd-core edits a projection file, this handler detects the sha drift vs the
-// recorded baseline in .gsd/.compat.json and re-imports the affected entities
-// into the DB. The next renderAllFromDb pass re-projects; the write-time
-// invalidation hook then refreshes the marker entry, closing the loop.
+// recorded baseline in .gsd/.compat.json and re-imports from markdown with
+// status authority scoped to the affected milestone ids. The next
+// renderAllFromDb pass re-projects; the write-time invalidation hook then
+// refreshes the marker entry, closing the loop.
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -59,10 +60,11 @@ function detectExternalMarkdownEdit(
 }
 
 /**
- * Idempotent repair: re-import hierarchy for the affected entities from
- * markdown into the DB, then update the marker entry so the next detect pass
- * sees the file as expected. migrateHierarchyToDb is itself idempotent
- * (upsert), so re-running this repair after a successful one is a no-op.
+ * Idempotent repair: re-import the hierarchy from markdown while allowing
+ * markdown status authority only for milestones named by the drifted file's
+ * marker entities, then update the marker entry so the next detect pass sees
+ * the file as expected. migrateHierarchyToDb is itself idempotent (upsert), so
+ * re-running this repair after a successful one is a no-op.
  */
 async function repairExternalMarkdownEdit(
   record: ExternalMarkdownEditDrift,
@@ -72,13 +74,28 @@ async function repairExternalMarkdownEdit(
     // Dynamic imports break a module-init cycle: this handler ← registry ←
     // state.ts ← guided-flow.ts ← md-importer.ts ← (this handler's old static
     // import). Deferring to repair time keeps module load cycle-free.
-    const { migrateHierarchyToDb } = await import("../../md-importer.js");
+    const { migrateHierarchyToDb, milestoneIdsFromEntities } = await import("../../md-importer.js");
     const { invalidateStateCache } = await import("../../state.js");
-    // Scoped re-import. migrateHierarchyToDb walks the whole tree but is a
-    // cheap upsert; per-entity scoping would require decomposing it, which is
-    // out of scope for v1. The cost is bounded by tree size and runs at most
-    // once per reconcile pass (MAX_PASSES=2).
-    migrateHierarchyToDb(ctx.basePath);
+    // #027: migrateHierarchyToDb walks the whole tree (a cheap upsert), so
+    // without scoping every projection rides along with markdown *status*
+    // authority. That lets an unrelated file that is stale from gsd-pi's own
+    // miss silently revert a reopened slice/milestone. Scope status authority to
+    // exactly the milestone(s) this drifted file projects.
+    //
+    // Step 1: the marker's `entities` are DB ids (`M001`, `M001/S01`,
+    // `M001/S01/T01`), so the milestone id is always the first `/`-segment —
+    // layout-independent (legacy `milestones/<MID>/…` and flat `phases/NN-slug/…`
+    // both resolve the same way), no projectionPath parsing needed. An empty set
+    // (no resolvable entities) preserves DB status everywhere: fail toward
+    // protecting the DB, not toward markdown authority.
+    const statusAuthoritativeMilestones = milestoneIdsFromEntities(record.entities);
+    if (statusAuthoritativeMilestones.size === 0) {
+      logWarning(
+        "reconcile",
+        `external-markdown-edit: no milestone scope resolved for ${record.projectionPath}; preserving DB status for all milestones`,
+      );
+    }
+    migrateHierarchyToDb(ctx.basePath, { statusAuthoritativeMilestones });
     invalidateStateCache();
   } catch (err) {
     logWarning(

package/src/resources/extensions/gsd/state-reconciliation/drift/external-planning-edit.ts

@@ -3,7 +3,8 @@
 // Parallel to external-markdown-edit.ts. Detects sha drift between the compat
 // marker's planning.projections/passthrough and current .planning/ files.
 //
-// Modeled files (projections): re-imported via parsePlanningDirectory → DB.
+// Modeled files (projections): re-imported via parsePlanningDirectory → DB,
+// with markdown status authority scoped to their marker entity milestone ids.
 // Passthrough files (un-modeled docs): sha refreshed, content untouched.
 
 import { existsSync, readFileSync } from "node:fs";
@@ -148,13 +149,25 @@ async function repairExternalPlanningEdit(
     const { parsePlanningDirectory } = await import("../../migrate/parser.js");
     const { transformToGSD } = await import("../../migrate/transformer.js");
     const { writeGSDDirectory } = await import("../../migrate/writer.js");
-    const { migrateHierarchyToDb } = await import("../../md-importer.js");
+    const { migrateHierarchyToDb, milestoneIdsFromEntities } = await import("../../md-importer.js");
     const { invalidateStateCache } = await import("../../state.js");
 
     const parsed = await parsePlanningDirectory(join(ctx.basePath, ".planning"));
     const gsdProject = transformToGSD(parsed);
     await writeGSDDirectory(gsdProject, ctx.basePath);
-    migrateHierarchyToDb(ctx.basePath);
+    // #027: scope status authority to the milestone(s) this drifted .planning/
+    // file projects (first `/`-segment of its DB entity ids), so a stale
+    // checkbox in an unrelated projection can't revert a reopened slice/milestone
+    // in the DB. Unseeded files carry no entities → empty set → preserve DB
+    // status everywhere (fail toward the DB, log the breadcrumb).
+    const statusAuthoritativeMilestones = milestoneIdsFromEntities(record.entities);
+    if (statusAuthoritativeMilestones.size === 0) {
+      logWarning(
+        "reconcile",
+        `external-planning-edit: no milestone scope resolved for ${record.projectionPath}; preserving DB status for all milestones`,
+      );
+    }
+    migrateHierarchyToDb(ctx.basePath, { statusAuthoritativeMilestones });
     invalidateStateCache();
   } catch (err) {
     logWarning(

package/src/resources/extensions/gsd/state-reconciliation/drift/project-md.ts

@@ -7,8 +7,8 @@
 
 import { existsSync } from "node:fs";
 
-import { getMilestone, isDbAvailable } from "../../gsd-db.js";
-import { findMilestoneIds } from "../../milestone-ids.js";
+import { getAllMilestones, getMilestone, isDbAvailable } from "../../gsd-db.js";
+import { findMilestoneIds, parseMilestoneId } from "../../milestone-ids.js";
 import { resolveMilestoneFile, resolveMilestonePath } from "../../paths.js";
 import type { GSDState } from "../../types.js";
 import type { DriftContext, DriftHandler, DriftRecord } from "../types.js";
@@ -29,6 +29,26 @@ function milestoneHasContent(basePath: string, milestoneId: string): boolean {
   );
 }
 
+/**
+ * A directory extracted to a bare `M{NNN}` id is not unregistered when the
+ * milestone is actually registered under a `unique_milestone_ids` suffixed id
+ * (`M{NNN}-<suffix>`) for the same sequence number. The flat-phase extractor in
+ * `milestone-ids` cannot recover the suffix from a descriptive slug (e.g.
+ * `07-v40fmq-m007-...-footer-system`), so it falls through to the bare `M007`.
+ * Probing the DB for a suffixed row on that sequence resolves the directory to
+ * its registered identity instead of firing a false-positive drift (issue
+ * #1281).
+ */
+function hasRegisteredSuffixedVariant(milestoneId: string): boolean {
+  const { suffix, num } = parseMilestoneId(milestoneId);
+  // Only bare, well-formed `M{NNN}` ids can be ambiguous with a suffixed row.
+  if (suffix || num === 0) return false;
+  return getAllMilestones().some((m) => {
+    const parsed = parseMilestoneId(m.id);
+    return parsed.num === num && parsed.suffix !== undefined;
+  });
+}
+
 export function detectUnregisteredMilestoneDrift(
   _state: GSDState,
   ctx: DriftContext,
@@ -38,6 +58,7 @@ export function detectUnregisteredMilestoneDrift(
   const drifts: UnregisteredMilestoneDrift[] = [];
   for (const milestoneId of findMilestoneIds(ctx.basePath)) {
     if (getMilestone(milestoneId)) continue;
+    if (hasRegisteredSuffixedVariant(milestoneId)) continue;
     if (!milestoneHasContent(ctx.basePath, milestoneId)) continue;
     drifts.push({ kind: "unregistered-milestone", milestoneId });
   }
@@ -45,35 +66,61 @@ export function detectUnregisteredMilestoneDrift(
 }
 
 /**
- * Repair intentionally fails closed. The project-root DB is authoritative at
- * runtime; markdown-only milestones must be reconciled through an explicit,
- * operator-controlled action so operators opt into changing canonical state.
- *
- * The hint deliberately leads with the *targeted*, non-destructive options. The
- * common cause of this drift is a directory left under an old ID after a
- * `unique_milestone_ids` rename, where the right fix is to rename (move) the
- * directory — not a full DB reimport. `/gsd recover --confirm` is a destructive
- * clear-and-reimport of the entire DB and is offered only as a last resort, so
- * users do not reach for it expecting a targeted repair (see issue #826).
+ * The recovery hint deliberately leads with the *targeted*, non-destructive
+ * options. The common cause of this drift is a directory left under an old ID
+ * after a `unique_milestone_ids` rename, where the right fix is to rename (move)
+ * the directory — not a full DB reimport. `/gsd recover --confirm` is a
+ * destructive clear-and-reimport of the entire DB and is offered only as a last
+ * resort, so users do not reach for it expecting a targeted repair (see issue
+ * #826).
  */
-export function repairUnregisteredMilestone(
+function unregisteredMilestoneGuidance(
   record: UnregisteredMilestoneDrift,
   ctx: DriftContext,
-): void {
+): string {
   const dir = resolveMilestonePath(ctx.basePath, record.milestoneId);
   const dirHint = dir ?? `the .gsd directory for ${record.milestoneId}`;
-  throw new Error(
+  return (
     `Milestone ${record.milestoneId} exists only as markdown projection ` +
-      "(on-disk ROADMAP/CONTEXT/SUMMARY with no authoritative DB row). " +
-      "Runtime reconciliation will not import markdown into the DB. Choose one:\n" +
-      `  • Rename: if this directory is the same milestone under an old ID (e.g. a unique_milestone_ids rename), move \`${dirHint}\` to the current ID's directory and re-run.\n` +
-      `  • Discard: if this milestone is no longer relevant, delete \`${dirHint}\` and re-run.\n` +
-      "  • Last resort: `/gsd recover --confirm` performs a destructive full DB clear-and-reimport — it does NOT do a targeted import and can replace or duplicate existing DB milestones.",
+    "(on-disk ROADMAP/CONTEXT/SUMMARY with no authoritative DB row). " +
+    "Runtime reconciliation will not import markdown into the DB. Choose one:\n" +
+    `  • Rename: if this directory is the same milestone under an old ID (e.g. a unique_milestone_ids rename), move \`${dirHint}\` to the current ID's directory and re-run.\n` +
+    `  • Discard: if this milestone is no longer relevant, delete \`${dirHint}\` and re-run.\n` +
+    "  • Last resort: `/gsd recover --confirm` performs a destructive full DB clear-and-reimport — it does NOT do a targeted import and can replace or duplicate existing DB milestones."
   );
 }
 
+/**
+ * Terminal blocker for an unregistered milestone. The project-root DB is
+ * authoritative at runtime; markdown-only milestones must be reconciled through
+ * an explicit, operator-controlled action so operators opt into changing
+ * canonical state. Exposing this as a `blocker` (matching the `artifact-db`
+ * convention) surfaces the drift as a pause-with-hint that gates dispatch,
+ * instead of a guaranteed repair throw that escalates auto-mode health to red
+ * (see issue #1281).
+ */
+export function describeUnregisteredMilestoneBlocker(
+  record: UnregisteredMilestoneDrift,
+  ctx: DriftContext,
+): string {
+  return unregisteredMilestoneGuidance(record, ctx);
+}
+
+/**
+ * Repair intentionally fails closed. Retained as a defensive fallback for the
+ * reconciliation engine; in practice `blocker` short-circuits this drift into a
+ * non-fatal pause before repair is ever attempted.
+ */
+export function repairUnregisteredMilestone(
+  record: UnregisteredMilestoneDrift,
+  ctx: DriftContext,
+): void {
+  throw new Error(unregisteredMilestoneGuidance(record, ctx));
+}
+
 export const unregisteredMilestoneHandler: DriftHandler<UnregisteredMilestoneDrift> = {
   kind: "unregistered-milestone",
   detect: detectUnregisteredMilestoneDrift,
+  blocker: describeUnregisteredMilestoneBlocker,
   repair: repairUnregisteredMilestone,
 };

package/src/resources/extensions/gsd/state-reconciliation/drift/sketch-flag.ts

@@ -8,13 +8,14 @@
 //      sketch slices to plan-slice, which writes PLAN.md but leaves
 //      is_sketch=1 — the next reconciliation pass clears it.
 
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 
 import {
   getSketchedSliceIds,
   isDbAvailable,
   setSliceSketchFlag,
 } from "../../gsd-db.js";
+import { parsePlan } from "../../parsers-legacy.js";
 import { resolveSliceFile } from "../../paths.js";
 import type { GSDState } from "../../types.js";
 import type { DriftContext, DriftHandler, DriftRecord } from "../types.js";
@@ -31,13 +32,54 @@ export function detectStaleSketchFlags(
 
   const sliceIds = getSketchedSliceIds(mid);
   return sliceIds
-    .filter((sid) => {
-      const planPath = resolveSliceFile(ctx.basePath, mid, sid, "PLAN");
-      return planPath !== null && existsSync(planPath);
-    })
+    .filter((sid) => sketchIsPlanned(ctx.basePath, mid, sid))
     .map((sid) => ({ kind: "stale-sketch-flag" as const, mid, sid }));
 }
 
+/**
+ * True when a task title is a synthetic placeholder emitted by a projection
+ * round-trip rather than a real, refined task. `migrate/transformer.buildTaskTitle`
+ * produces two shapes when a plan was never decomposed:
+ *   - `Plan NN`            (fallback when phase/plan frontmatter is absent)
+ *   - `${phase} ${plan}`   (e.g. `00 01`, `00 03b`, `29-auth-system 01`)
+ * Neither carries genuine planning intent, so both must be treated as stubs.
+ */
+function isPlaceholderTaskTitle(title: string): boolean {
+  const t = title.trim();
+  if (/^Plan\s+\d+[a-z]*$/i.test(t)) return true;
+  // buildTaskTitle returns `${phase} ${plan}` when frontmatter has both fields.
+  // Phase slugs are digit-led (e.g. `00`, `29-auth-system`); require that so
+  // legitimate titles like `Step 1` are not misclassified as stubs.
+  return /^\d[\w-]*\s+\d+[a-z]*$/i.test(t);
+}
+
+/**
+ * A sketch slice counts as "planned" (so its is_sketch flag may be cleared)
+ * only when it has a *real* plan on disk — not merely any PLAN file.
+ *
+ * File existence alone (#1287) is too weak: a stub/placeholder PLAN, a
+ * crash-leftover, or a projection round-trip that emits synthetic placeholder
+ * task titles (migrate/transformer.buildTaskTitle) all satisfy existsSync yet
+ * were never actually refined. Clearing the flag for one strips the `refining`
+ * guard in phase derivation and lets a phantom task drive dispatch.
+ *
+ * A legitimate plan-slice always decomposes into >= 1 genuine task, so require
+ * at least one non-placeholder task. This is strictly stricter than the old
+ * existence check — the documented crash-recovery scenarios (a real plan-slice
+ * that wrote its tasks) still clear, a bare stub no longer does.
+ */
+function sketchIsPlanned(basePath: string, mid: string, sid: string): boolean {
+  const planPath = resolveSliceFile(basePath, mid, sid, "PLAN");
+  if (planPath === null || !existsSync(planPath)) return false;
+  try {
+    const plan = parsePlan(readFileSync(planPath, "utf-8"));
+    return plan.tasks.some((t) => !isPlaceholderTaskTitle(t.title));
+  } catch {
+    // A PLAN we cannot parse is not a trustworthy "planning done" signal.
+    return false;
+  }
+}
+
 export function repairStaleSketchFlag(record: SketchFlagDrift): void {
   setSliceSketchFlag(record.mid, record.sid, false);
 }

package/src/resources/extensions/gsd/state-reconciliation/types.ts

@@ -49,14 +49,14 @@ export type DriftRecord =
       projectionPath: string;       // relative to basePath, e.g. "m1/plan.md"
       expectedSha: string;          // sha recorded in .compat.json
       actualSha: string;            // freshly computed from disk
-      entities: string[];           // DB entity ids to re-import
+      entities: string[];           // DB entity ids used to scope status authority
     }
   | {
       kind: "external-planning-edit";
       projectionPath: string;       // relative to .planning/, e.g. "phases/01-foo/01-01-PLAN.md"
       expectedSha: string;
       actualSha: string;
-      entities: string[];
+      entities: string[];           // DB entity ids used to scope status authority
       passthrough: boolean;         // true = content-only, no re-import, just refresh sha
     };
 

package/src/resources/extensions/gsd/stop-notice.ts

@@ -66,10 +66,27 @@ export function isNonBlockingPauseNotice(message: string): boolean {
   return message.includes("idempotent advance: unit already active");
 }
 
+/**
+ * A picker / next-action menu that could not render in a non-interactive
+ * (headless / RPC) session. Both wordings originate from the menu-unavailable
+ * helpers (`notifyCommandMenuUnavailable` and `notifyPickerCommandNeedsInteractiveMenu`
+ * in next-action-ui.ts / command-feedback.ts). Headless `auto`/`next` cannot
+ * answer such a menu, so the run has dead-ended and needs operator intervention.
+ * Classify it as blocked so the headless host exits 10 instead of idling
+ * forever waiting for a completion signal that never comes. (#1294)
+ */
+export function isInteractiveMenuUnavailableNotice(message: string): boolean {
+  return (
+    message.includes("menu could not be shown in this session") ||
+    message.includes("did not start:")
+  );
+}
+
 export function isBlockedNoticeMessage(message: string): boolean {
   return (
     message.includes("blocked:") ||
     (isPauseNotice(message) && !isNonBlockingPauseNotice(message)) ||
-    isManualResolutionNotice(message)
+    isManualResolutionNotice(message) ||
+    isInteractiveMenuUnavailableNotice(message)
   );
 }

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

@@ -9,8 +9,10 @@ import { dirname, join } from "node:path";
 const STALE_THRESHOLD_MS = 60_000; // 60 seconds
 const DEFAULT_TIMEOUT_MS = 0;      // fail fast; sync waits block the JS event loop
 
-function lockFilePath(basePath: string): string {
-  return join(basePath, ".gsd", "sync.lock");
+const DEFAULT_LOCK_NAME = "sync.lock";
+
+function lockFilePath(basePath: string, lockName: string = DEFAULT_LOCK_NAME): string {
+  return join(basePath, ".gsd", lockName);
 }
 
 /** True if the given PID is alive in the current process namespace. */
@@ -74,8 +76,9 @@ function tryCreateLockFile(lp: string, payload: string): boolean {
 export function acquireSyncLock(
   basePath: string,
   _timeoutMs: number = DEFAULT_TIMEOUT_MS,
+  lockName: string = DEFAULT_LOCK_NAME,
 ): { acquired: boolean } {
-  const lp = lockFilePath(basePath);
+  const lp = lockFilePath(basePath, lockName);
   const lockData = JSON.stringify(
     { pid: process.pid, acquired_at: new Date().toISOString() },
     null,
@@ -89,7 +92,12 @@ export function acquireSyncLock(
         return { acquired: true };
       }
     } catch {
-      /* unexpected — fall through to retry */
+      // tryCreateLockFile only throws for non-EEXIST errors — a persistently
+      // uncreatable lock path (dangling-symlink parent, ENOTDIR, read-only FS).
+      // Retrying would spin the loop forever with no progress condition,
+      // blocking the JS event loop. Fail open like a contended lock so callers
+      // proceed (racy but functional) instead of hanging.
+      return { acquired: false };
     }
 
     // File exists. Decide whether to steal (stale + owner dead) or skip.
@@ -131,8 +139,8 @@ export function acquireSyncLock(
 /**
  * Release the advisory sync lock. No-op if lock file does not exist.
  */
-export function releaseSyncLock(basePath: string): void {
-  const lp = lockFilePath(basePath);
+export function releaseSyncLock(basePath: string, lockName: string = DEFAULT_LOCK_NAME): void {
+  const lp = lockFilePath(basePath, lockName);
   try {
     if (existsSync(lp)) {
       unlinkSync(lp);

package/src/resources/extensions/gsd/tests/closeout-git-deferral.test.ts

@@ -3,8 +3,14 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
 
-import { shouldDeferCloseoutGitAction } from "../auto-post-unit.ts";
+import { postUnitPreVerification, shouldDeferCloseoutGitAction, type PostUnitContext } from "../auto-post-unit.ts";
+import { AutoSession } from "../auto/session.ts";
+import { closeDatabase, insertMilestone, insertSlice, insertTask, insertVerificationEvidence, openDatabase } from "../gsd-db.ts";
+import { recordToolCall, recordToolResult, resetEvidence } from "../safety/evidence-collector.ts";
+import { cleanup, git, makeTempRepo } from "./test-utils.ts";
 
 test("execute-task defers closeout git action until verification passes", () => {
   assert.equal(shouldDeferCloseoutGitAction("execute-task"), true);
@@ -14,3 +20,92 @@ test("non execute-task units keep pre-verification closeout git action", () => {
   assert.equal(shouldDeferCloseoutGitAction("plan-slice"), false);
   assert.equal(shouldDeferCloseoutGitAction("complete-slice"), false);
 });
+
+test("blocking evidence-xref commits deferred execute-task work before pausing", async () => {
+  const base = makeTempRepo("gsd-evidence-xref-commit-before-pause-");
+
+  try {
+    writeFileSync(join(base, ".gitignore"), ".gsd/\n");
+    git(base, "add", ".gitignore");
+    git(base, "commit", "-m", "chore: ignore gsd runtime");
+
+    openDatabase(":memory:");
+    insertMilestone({ id: "M001", title: "Milestone", status: "active" });
+    insertSlice({ id: "S01", milestoneId: "M001", title: "Slice", status: "active" });
+    insertTask({
+      id: "T01",
+      sliceId: "S01",
+      milestoneId: "M001",
+      title: "Add app entrypoint",
+      status: "complete",
+      oneLiner: "Added app entrypoint",
+      keyFiles: ["app.js"],
+      planning: {
+        description: "Create app entrypoint",
+        estimate: "small",
+        files: ["app.js"],
+        verify: "npm test",
+        inputs: [],
+        expectedOutput: ["app.js"],
+        observabilityImpact: "none",
+      },
+    });
+    insertVerificationEvidence({
+      taskId: "T01",
+      sliceId: "S01",
+      milestoneId: "M001",
+      command: "npm test",
+      exitCode: 0,
+      verdict: "passed",
+      durationMs: 10,
+    });
+
+    writeFileSync(join(base, "app.js"), "console.log('ready');\n");
+    resetEvidence();
+    recordToolCall("call-1", "bash", { command: "npm test" });
+    recordToolResult("call-1", "bash", "Command exited with code 1\nfailed\n", true);
+
+    const s = new AutoSession();
+    s.active = true;
+    s.basePath = base;
+    s.currentUnit = { type: "execute-task", id: "M001/S01/T01", startedAt: Date.now() };
+
+    let pauseCalled = false;
+    const notifications: string[] = [];
+    const pctx: PostUnitContext = {
+      s,
+      ctx: {
+        ui: { notify: (message: string) => notifications.push(message) },
+      } as unknown as PostUnitContext["ctx"],
+      pi: {} as PostUnitContext["pi"],
+      buildSnapshotOpts: () => ({}),
+      lockBase: () => base,
+      stopAuto: async () => {},
+      pauseAuto: async () => {
+        pauseCalled = true;
+        assert.equal(git(base, "status", "--short"), "", "task work must be committed before pauseAuto runs");
+      },
+      updateProgressWidget: () => {},
+    };
+
+    const result = await postUnitPreVerification(pctx, {
+      skipSettleDelay: true,
+      skipWorktreeSync: true,
+    });
+
+    assert.equal(result, "dispatched");
+    assert.equal(pauseCalled, true);
+    assert.ok(
+      notifications.some((message) => message.includes("claimed passing verification")),
+      `expected evidence-xref notification, got: ${notifications.join("\n")}`,
+    );
+
+    const commitMessage = git(base, "log", "-1", "--pretty=%B");
+    assert.match(commitMessage, /^feat: Added app entrypoint/m);
+    assert.match(commitMessage, /GSD-Task: S01\/T01/);
+  } finally {
+    resetEvidence();
+    closeDatabase();
+    cleanup(base);
+  }
+});