@opengsd/gsd-pi 1.6.0 → 1.7.0-dev.30c4ec2f

package/src/resources/extensions/gsd/tests/migration-auto-check.test.ts

@@ -420,6 +420,59 @@ test("migration auto-check still reports real drift with scratch dirs excluded f
   }
 });
 
+test("migration auto-check excludes sketch slice stub tasks from the markdown scan (#1286)", () => {
+  const base = makeBase();
+  try {
+    // S01 is a sketch (`[sketch]` badge): its PLAN is a stub carrying a
+    // placeholder <tasks> block until refinement. migrateHierarchyToDb skips
+    // seeding those stub tasks, so the markdown scan must skip them too — else
+    // the stub inflates the markdown count and reports false drift against a DB
+    // that (correctly) holds zero tasks for the sketch slice.
+    const roadmap = `# M001: Test Milestone
+
+**Vision:** Sketch slices must not inflate markdown task counts.
+
+## Slices
+
+- [ ] **S01: Sketch Slice** \`[sketch]\` \`risk:low\` \`depends:[]\`
+  > After this: Sketch decomposed.
+
+- [ ] **S02: Real Slice** \`risk:low\` \`depends:[]\`
+  > After this: Real work done.
+`;
+    const sketchPlan = `# S01: Sketch Slice
+
+**Goal:** Placeholder.
+
+## Tasks
+
+- [ ] **T01: Plan 01**
+  Stub placeholder task.
+`;
+    const realPlan = `# S02: Real Slice
+
+**Goal:** Real work.
+
+## Tasks
+
+- [ ] **T01: Real Task**
+  Real work.
+`;
+    const milestoneDir = join(base, ".gsd", "milestones", "M001");
+    mkdirSync(join(milestoneDir, "slices", "S01"), { recursive: true });
+    mkdirSync(join(milestoneDir, "slices", "S02"), { recursive: true });
+    writeFileSync(join(milestoneDir, "M001-ROADMAP.md"), roadmap);
+    writeFileSync(join(milestoneDir, "slices", "S01", "S01-PLAN.md"), sketchPlan);
+    writeFileSync(join(milestoneDir, "slices", "S02", "S02-PLAN.md"), realPlan);
+
+    // Both slices count, but only the refined slice contributes a task; the
+    // sketch stub task is excluded, matching migrateHierarchyToDb.
+    assert.deepEqual(countMarkdownHierarchy(base), { milestones: 1, slices: 2, tasks: 1 });
+  } finally {
+    cleanup(base);
+  }
+});
+
 test("migration auto-check still compares a roadmapless milestone that HAS a DB row", async () => {
   const base = makeBase();
   try {

package/src/resources/extensions/gsd/tests/parsers-legacy-importers.test.ts

@@ -47,6 +47,9 @@ const ALLOWED_IMPORTERS = new Set([
   "gsd/migration-auto-check.ts",
   // drift detection: compares markdown projection against DB by design
   "gsd/state-reconciliation/drift/roadmap.ts",
+  // drift detection: reads PLAN.md tasks to distinguish a real plan from a
+  // stub before clearing a stale is_sketch flag (#1287)
+  "gsd/state-reconciliation/drift/sketch-flag.ts",
   // stale-render detection + render verification helpers over rendered output
   "gsd/markdown-renderer.ts",
   // pre-migration fallback: deriveState must work before the DB exists
@@ -58,6 +61,7 @@ const ALLOWED_IMPORTERS = new Set([
   "gsd/artifact-verification.ts",
   // diagnostics-only surfaces: report on projections, make no dispatch decisions
   "gsd/doctor.ts",
+  "gsd/doctor-state-checks.ts",
   // diagnostics-only: compares PLAN.md task checkboxes against DB status
   "gsd/doctor-engine-checks.ts",
   // display/telemetry-only surfaces

package/src/resources/extensions/gsd/tests/planning-writer.test.ts

@@ -8,7 +8,7 @@ import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 
 import { writePlanningDirectory } from "../migrate/planning-writer.ts";
-import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask } from "../gsd-db.ts";
+import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask, updateTaskStatus } from "../gsd-db.ts";
 
 const tmpDirs: string[] = [];
 function makeTmp(): string {
@@ -65,6 +65,23 @@ test("writePlanningDirectory emits phase plan file with XML structure", async ()
   assert.match(plan, /<tasks>/);
 });
 
+test("writePlanningDirectory renders completed task checkboxes as [x] (#1276)", async () => {
+  const base = makeTmp();
+  updateTaskStatus("M001", "S01", "T01", "complete");
+  await writePlanningDirectory(base, "flat-phases");
+
+  const phaseDir = readdirSync(join(base, ".planning", "phases"), { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name)[0]!;
+  const planFile = readdirSync(join(base, ".planning", "phases", phaseDir))
+    .filter((f) => f.endsWith("PLAN.md"))[0]!;
+  const plan = readFileSync(join(base, ".planning", "phases", phaseDir, planFile), "utf-8");
+  assert.match(plan, /- \[x\] \*\*T01\*\*/, "completed task should project as [x], not [ ]");
+
+  const roadmap = readFileSync(join(base, ".planning", "ROADMAP.md"), "utf-8");
+  assert.match(roadmap, /- \[x\] 01 —/, "phase with all tasks complete should be [x] in ROADMAP");
+});
+
 test("writePlanningDirectory is idempotent: writing twice produces stable content", async () => {
   const base = makeTmp();
   await writePlanningDirectory(base, "flat-phases");

package/src/resources/extensions/gsd/tests/progressive-planning.test.ts

@@ -76,6 +76,21 @@ function writeS01Artifacts(base: string): void {
   writeFileSync(join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-SUMMARY.md"), "# S01 Summary\n");
 }
 
+// A *real* decomposed PLAN (>= 1 genuine task). #1287: the stale-sketch-flag
+// detector requires a real plan — not a bare stub — before clearing is_sketch.
+function realPlanContent(sliceId: string): string {
+  return [
+    `# ${sliceId}: Feature`,
+    "",
+    "**Goal:** Ship the feature",
+    "",
+    "## Tasks",
+    "",
+    "- [ ] **T01: Build the feature** `est:1h`",
+    "",
+  ].join("\n");
+}
+
 function cleanup(base: string, originalCwd: string): void {
   try { closeDatabase(); } catch { /* noop */ }
   process.chdir(originalCwd);
@@ -185,7 +200,7 @@ test("ADR-011: existing PLAN + stale sketch flag heals via reconcileBeforeDispat
   writePreferences(base, "phases:\n  progressive_planning: true");
   writeFileSync(
     join(base, ".gsd", "milestones", "M001", "slices", "S02", "S02-PLAN.md"),
-    "# S02 Plan\n",
+    realPlanContent("S02"),
   );
   process.chdir(base);
 
@@ -252,7 +267,7 @@ test("ADR-011: reconcileBeforeDispatch auto-heals stale sketch flag when PLAN ex
   // Simulate plan-slice completion where PLAN exists but is_sketch was not flipped.
   writeFileSync(
     join(base, ".gsd", "milestones", "M001", "slices", "S02", "S02-PLAN.md"),
-    "# S02 Plan\n",
+    realPlanContent("S02"),
   );
   process.chdir(base);
 
@@ -282,7 +297,7 @@ test("ADR-011: deriveState stays pure across worktree/canonical-root; healing be
   writePreferences(base, "phases:\n  skip_research: false");
   writeFileSync(
     join(base, ".gsd", "milestones", "M001", "slices", "S02", "S02-PLAN.md"),
-    "# S02 Plan\n",
+    realPlanContent("S02"),
   );
   const worktreePath = join(base, "worker");
   mkdirSync(worktreePath, { recursive: true });

package/src/resources/extensions/gsd/tests/reopen-reason.test.ts

@@ -0,0 +1,117 @@
+// GSD — reopen-reason injection tests (#1272)
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+} from '../gsd-db.ts';
+import { handleReopenTask } from '../tools/reopen-task.ts';
+import {
+  reopenReasonArtifactPath,
+  writeReopenReason,
+  claimReopenReasonForInjection,
+} from '../reopen-reason.ts';
+
+function makeTmpBase(): string {
+  const base = mkdtempSync(join(tmpdir(), 'gsd-reopen-reason-'));
+  mkdirSync(join(base, '.gsd', 'milestones', 'M001', 'slices', 'S01', 'tasks'), { recursive: true });
+  return base;
+}
+
+function cleanup(base: string): void {
+  try { closeDatabase(); } catch { /* noop */ }
+  try { rmSync(base, { recursive: true, force: true }); } catch { /* noop */ }
+}
+
+function seedCompleteTask(): void {
+  insertMilestone({ id: 'M001', title: 'Test Milestone', status: 'active' });
+  insertSlice({ id: 'S01', milestoneId: 'M001', title: 'Test Slice', status: 'in_progress' });
+  insertTask({ id: 'T01', sliceId: 'S01', milestoneId: 'M001', title: 'Task One', status: 'complete' });
+}
+
+test('writeReopenReason then claim: injects the reason, then is one-shot', () => {
+  const base = makeTmpBase();
+  try {
+    const reason = 'T01 shifted the descendants count to 12. Fix: update the assertion to 12.';
+    writeReopenReason(base, 'M001', 'S01', 'T01', reason);
+
+    const path = reopenReasonArtifactPath(base, 'M001', 'S01', 'T01')!;
+    assert.ok(existsSync(path), 'artifact should be written');
+
+    const claimed = claimReopenReasonForInjection(base, 'M001', 'S01', 'T01');
+    assert.ok(claimed, 'first claim should return an injection block');
+    assert.match(claimed!.injectionBlock, /Reopened — Reason/);
+    assert.match(claimed!.injectionBlock, /descendants count to 12/);
+    assert.ok(!existsSync(path), 'artifact should be deleted after claim (one-shot)');
+
+    const second = claimReopenReasonForInjection(base, 'M001', 'S01', 'T01');
+    assert.equal(second, null, 'second claim should return null');
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('claimReopenReasonForInjection: returns null when nothing pending', () => {
+  const base = makeTmpBase();
+  try {
+    assert.equal(claimReopenReasonForInjection(base, 'M001', 'S01', 'T01'), null);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('writeReopenReason: empty/whitespace reason is a no-op', () => {
+  const base = makeTmpBase();
+  try {
+    writeReopenReason(base, 'M001', 'S01', 'T01', '   ');
+    const path = reopenReasonArtifactPath(base, 'M001', 'S01', 'T01')!;
+    assert.ok(!existsSync(path), 'no artifact should be written for an empty reason');
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handleReopenTask: persists a claimable reopen reason when reason is provided', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+  try {
+    seedCompleteTask();
+
+    const result = await handleReopenTask({
+      milestoneId: 'M001',
+      sliceId: 'S01',
+      taskId: 'T01',
+      reason: 'Full suite caught NavNodeTest regression — update count assertion to 12.',
+    }, base);
+    assert.ok(!('error' in result), `unexpected error: ${'error' in result ? result.error : ''}`);
+
+    const claimed = claimReopenReasonForInjection(base, 'M001', 'S01', 'T01');
+    assert.ok(claimed, 'reopen reason should be claimable after handleReopenTask');
+    assert.match(claimed!.injectionBlock, /NavNodeTest regression/);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handleReopenTask: no reason provided leaves nothing to claim', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+  try {
+    seedCompleteTask();
+
+    await handleReopenTask({ milestoneId: 'M001', sliceId: 'S01', taskId: 'T01' }, base);
+
+    assert.equal(claimReopenReasonForInjection(base, 'M001', 'S01', 'T01'), null);
+  } finally {
+    cleanup(base);
+  }
+});

package/src/resources/extensions/gsd/tests/state-reconciliation-drift.test.ts

@@ -107,11 +107,11 @@ test("ADR-017 (#5700): sketch-flag drift detected and repaired end-to-end", asyn
     sketchScope: "limited",
   });
 
-  // Simulate the post-crash scenario: PLAN.md exists on disk but the
-  // is_sketch flag is still 1.
+  // Simulate the post-crash scenario: a *real* PLAN.md (a decomposed task)
+  // exists on disk but the is_sketch flag is still 1.
   writeFileSync(
     join(base, ".gsd", "phases", "01-test", "01-02-PLAN.md"),
-    "# S02 Plan\n",
+    makeStalePlanContent("S02", [{ id: "T01", title: "Build the feature", done: false }]),
   );
   assert.equal(getSlice("M001", "S02")?.is_sketch, 1, "pre: flagged as sketch");
 
@@ -131,6 +131,120 @@ test("ADR-017 (#5700): sketch-flag drift detected and repaired end-to-end", asyn
   }
 });
 
+test("#1287: stub/placeholder PLAN does NOT clear the sketch flag", async (t) => {
+  const base = makeFixtureBase();
+  t.after(() => cleanup(base));
+
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Test", status: "active" });
+  insertSlice({
+    id: "S02",
+    milestoneId: "M001",
+    title: "Feature",
+    status: "pending",
+    risk: "medium",
+    depends: [],
+    demo: "S02 demo.",
+    sequence: 1,
+    isSketch: true,
+    sketchScope: "limited",
+  });
+
+  const planPath = join(base, ".gsd", "phases", "01-test", "01-02-PLAN.md");
+
+  // A bare stub PLAN (no decomposed tasks) must not clear the flag.
+  writeFileSync(planPath, "# S02 Plan\n");
+  clearRendererCaches();
+  let state = makeState({ activeMilestone: { id: "M001", title: "Test" } });
+  let result = await reconcileBeforeDispatch(base, {
+    invalidateStateCache: () => {},
+    deriveState: async () => state,
+  });
+  assert.equal(result.ok, true);
+  assert.equal(getSlice("M001", "S02")?.is_sketch, 1, "stub PLAN: flag stays set");
+  assert.equal(result.repaired.length, 0, "stub PLAN: no repair");
+
+  // A projection round-trip stub whose only task is a synthetic "Plan NN"
+  // placeholder (migrate/transformer.buildTaskTitle) must also not clear it.
+  writeFileSync(
+    planPath,
+    makeStalePlanContent("S02", [{ id: "T01", title: "Plan 01", done: false }]),
+  );
+  clearRendererCaches();
+  state = makeState({ activeMilestone: { id: "M001", title: "Test" } });
+  result = await reconcileBeforeDispatch(base, {
+    invalidateStateCache: () => {},
+    deriveState: async () => state,
+  });
+  assert.equal(result.ok, true);
+  assert.equal(getSlice("M001", "S02")?.is_sketch, 1, "placeholder task: flag stays set");
+  assert.equal(result.repaired.length, 0, "placeholder task: no repair");
+
+  // buildTaskTitle also emits `${phase} ${plan}` (e.g. "00 01") when the plan
+  // frontmatter carries phase/plan. This projected placeholder must not clear
+  // the flag either.
+  writeFileSync(
+    planPath,
+    makeStalePlanContent("S02", [{ id: "T01", title: "00 01", done: false }]),
+  );
+  clearRendererCaches();
+  state = makeState({ activeMilestone: { id: "M001", title: "Test" } });
+  result = await reconcileBeforeDispatch(base, {
+    invalidateStateCache: () => {},
+    deriveState: async () => state,
+  });
+  assert.equal(result.ok, true);
+  assert.equal(
+    getSlice("M001", "S02")?.is_sketch,
+    1,
+    "phase/plan placeholder task: flag stays set",
+  );
+  assert.equal(result.repaired.length, 0, "phase/plan placeholder task: no repair");
+});
+
+test("#1288: real tasks shaped like `word + number` still clear the sketch flag", async (t) => {
+  const base = makeFixtureBase();
+  t.after(() => cleanup(base));
+
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Test", status: "active" });
+  insertSlice({
+    id: "S02",
+    milestoneId: "M001",
+    title: "Feature",
+    status: "pending",
+    risk: "medium",
+    depends: [],
+    demo: "S02 demo.",
+    sequence: 1,
+    isSketch: true,
+    sketchScope: "limited",
+  });
+
+  const planPath = join(base, ".gsd", "phases", "01-test", "01-02-PLAN.md");
+
+  // `Step 1` / `RFC 1234` match the loose `word + number` shape but are genuine
+  // decomposed tasks. buildTaskTitle only emits `${phase} ${plan}` with a
+  // digit-led phase, so these must NOT be read as placeholders (#1288): a real
+  // plan-slice like this must still clear the stale is_sketch flag.
+  writeFileSync(
+    planPath,
+    makeStalePlanContent("S02", [
+      { id: "T01", title: "Step 1", done: false },
+      { id: "T02", title: "RFC 1234", done: false },
+    ]),
+  );
+  clearRendererCaches();
+  const state = makeState({ activeMilestone: { id: "M001", title: "Test" } });
+  const result = await reconcileBeforeDispatch(base, {
+    invalidateStateCache: () => {},
+    deriveState: async () => state,
+  });
+  assert.equal(result.ok, true);
+  assert.equal(getSlice("M001", "S02")?.is_sketch, 0, "real task titles: flag cleared");
+  assert.equal(result.repaired.length, 1, "real task titles: repaired once");
+});
+
 test("ADR-017 (#5700): repair failure throws ReconciliationFailedError with shape", async () => {
   const seenDrift: DriftRecord = { kind: "stale-sketch-flag", mid: "M001", sid: "S02" };
   const handler: DriftHandler = {
@@ -1032,7 +1146,7 @@ test("ADR-017 (#5703): live worker lock is not cleared", async (t) => {
 
 // ─── #5704: unregistered-milestone drift ────────────────────────────────────
 
-test("ADR-017 (#5704): unregistered-milestone drift fails closed without importing markdown", async (t) => {
+test("ADR-017 (#5704/#1281): unregistered-milestone drift pauses with a hint instead of hard-escalating", async (t) => {
   const base = mkdtempSync(join(tmpdir(), "gsd-adr017-projmd-"));
   const milestoneDir = join(base, ".gsd", "phases", "42-test");
   mkdirSync(milestoneDir, { recursive: true });
@@ -1059,29 +1173,67 @@ test("ADR-017 (#5704): unregistered-milestone drift fails closed without importi
   // Pre-condition: filesystem has the milestone, DB does NOT.
   assert.equal(getMilestone("M042"), null, "pre: DB has no row for M042");
 
-  await assert.rejects(
-    reconcileBeforeDispatch(base, {
-      invalidateStateCache: () => {},
-      deriveState: async () => makeState(),
-    }),
-    (err: unknown) => {
-      assert.ok(err instanceof ReconciliationFailedError);
-      assert.match(String(err.message), /unregistered-milestone/);
-      assert.equal(err.failures[0]?.drift.kind, "unregistered-milestone");
-      assert.match(String(err.failures[0]?.cause), /M042/);
-      assert.match(String(err.failures[0]?.cause), /markdown projection/);
-      // Hint leads with targeted, non-destructive actions (rename/discard)...
-      assert.match(String(err.failures[0]?.cause), /Rename/);
-      assert.match(String(err.failures[0]?.cause), /Discard/);
-      // ...and reframes recover as a destructive last resort, not the fix (#826).
-      assert.match(String(err.failures[0]?.cause), /\/gsd recover/);
-      assert.match(String(err.failures[0]?.cause), /last resort/i);
-      return true;
-    },
-  );
+  // #1281: the handler exposes a `blocker`, so reconciliation returns a
+  // non-fatal pause-with-hint (ok:true + blocker) rather than throwing.
+  const result = await reconcileBeforeDispatch(base, {
+    invalidateStateCache: () => {},
+    deriveState: async () => makeState(),
+  });
+  assert.equal(result.ok, true);
+  const blocker = result.blockers.find((b) => /M042/.test(b));
+  assert.ok(blocker, "expected an M042 unregistered-milestone blocker");
+  assert.match(blocker!, /markdown projection/);
+  // Hint leads with targeted, non-destructive actions (rename/discard)...
+  assert.match(blocker!, /Rename/);
+  assert.match(blocker!, /Discard/);
+  // ...and reframes recover as a destructive last resort, not the fix (#826).
+  assert.match(blocker!, /\/gsd recover/);
+  assert.match(blocker!, /last resort/i);
+  // Runtime never imports markdown into the DB.
   assert.equal(getMilestone("M042"), null, "post: DB still has no row for M042");
 });
 
+test("#1281: descriptive flat-phase dir registered under a suffixed id → no false-positive drift", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-1281-suffix-"));
+  // Descriptive slug the flat-phase extractor cannot recover the suffix from →
+  // it derives the bare `M007`, which has no DB row.
+  const milestoneDir = join(base, ".gsd", "phases", "07-v40fmq-m007-v40fmq-navigation-footer-system");
+  mkdirSync(milestoneDir, { recursive: true });
+  writeFileSync(
+    join(milestoneDir, "M007-v40fmq-ROADMAP.md"),
+    [
+      "# M007: Navigation Footer System",
+      "",
+      "**Vision:** Verify no false-positive unregistered-milestone drift",
+      "",
+      "## Slices",
+      "",
+      "- [ ] **S01: Foundation** `risk:medium` `depends:[]`",
+      "",
+    ].join("\n"),
+  );
+  t.after(() => {
+    try { closeDatabase(); } catch { /* noop */ }
+    rmSync(base, { recursive: true, force: true });
+  });
+
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  // The milestone IS registered — under the unique_milestone_ids suffixed id.
+  insertMilestone({ id: "M007-v40fmq", title: "Navigation Footer System", status: "complete" });
+
+  const result = await reconcileBeforeDispatch(base, {
+    invalidateStateCache: () => {},
+    deriveState: async () => makeState(),
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(
+    result.blockers.some((b) => /unregistered/i.test(b) || /M007/.test(b)),
+    false,
+    "bare M007 derived from the slug must resolve to the registered M007-v40fmq row",
+  );
+});
+
 test("ADR-017 (#5704): registered milestone (DB row present) → no drift", async (t) => {
   const base = mkdtempSync(join(tmpdir(), "gsd-adr017-projmd-clean-"));
   const milestoneDir = join(base, ".gsd", "phases", "01-test");
@@ -1977,7 +2129,7 @@ test("deriveState is pure: stale sketch healed only via reconcileBeforeDispatch"
   });
   writeFileSync(
     join(base, ".gsd", "phases", "01-test", "01-02-PLAN.md"),
-    "# S02 Plan\n",
+    makeStalePlanContent("S02", [{ id: "T01", title: "Build the feature", done: false }]),
   );
 
   const { deriveState } = await import("../state.ts");

package/src/resources/extensions/gsd/tests/worker-resume-wait.test.ts

@@ -0,0 +1,73 @@
+/**
+ * Tests: awaitWorkerResume — headless worker pause survives without a resumer.
+ *
+ * Regression for #1273: a worker `pause` used to call a terminal pauseAuto()
+ * that exited the process with BLOCKED (10). On the headless path there is no
+ * resumer to send the matching `resume`, so the worker was stranded after its
+ * first unit. awaitWorkerResume lets the worker wait for the coordinator to lift
+ * the pause and, when no resumer responds, report "timeout" so the caller can
+ * degrade to in-process serialization instead of halting forever.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { awaitWorkerResume, sendSignal } from "../session-status-io.ts";
+
+function makeBase(): { base: string; cleanup: () => void } {
+  const base = mkdtempSync(join(tmpdir(), "gsd-worker-resume-"));
+  mkdirSync(join(base, ".gsd", "parallel"), { recursive: true });
+  return { base, cleanup: () => rmSync(base, { recursive: true, force: true }) };
+}
+
+describe("awaitWorkerResume", () => {
+  it("returns 'resume' when the coordinator sends resume", async () => {
+    const { base, cleanup } = makeBase();
+    try {
+      sendSignal(base, "M001", "resume");
+      const outcome = await awaitWorkerResume(base, "M001", { timeoutMs: 500, pollMs: 20 });
+      assert.equal(outcome, "resume");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("returns 'stop' when the coordinator sends stop", async () => {
+    const { base, cleanup } = makeBase();
+    try {
+      sendSignal(base, "M001", "stop");
+      const outcome = await awaitWorkerResume(base, "M001", { timeoutMs: 500, pollMs: 20 });
+      assert.equal(outcome, "stop");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("returns 'timeout' when no resumer lifts the pause (headless, #1273)", async () => {
+    const { base, cleanup } = makeBase();
+    try {
+      const outcome = await awaitWorkerResume(base, "M001", { timeoutMs: 100, pollMs: 20 });
+      assert.equal(outcome, "timeout");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("ignores a repeated pause and still resumes when resume arrives", async () => {
+    const { base, cleanup } = makeBase();
+    try {
+      // A duplicate pause must not be treated as a resume, nor reset the wait.
+      sendSignal(base, "M001", "pause");
+      const waiting = awaitWorkerResume(base, "M001", { timeoutMs: 1000, pollMs: 20 });
+      // Deliver the resume shortly after the pause is consumed and ignored.
+      setTimeout(() => sendSignal(base, "M001", "resume"), 60);
+      const outcome = await waiting;
+      assert.equal(outcome, "resume");
+    } finally {
+      cleanup();
+    }
+  });
+});

package/src/resources/extensions/gsd/tools/reopen-task.ts

@@ -23,6 +23,7 @@ import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
+import { writeReopenReason } from "../reopen-reason.js";
 import { existsSync, unlinkSync } from "node:fs";
 import { join, basename, dirname } from "node:path";
 import { resolveTasksDir, resolveSlicePath, clearPathCache } from "../paths.js";
@@ -125,6 +126,20 @@ export async function handleReopenTask(
   }
   clearPathCache();
 
+  // ── Persist the reopen reason for the next execute-task dispatch (#1272) ──
+  // Without this, the re-dispatched executor receives the original task plan
+  // and verify command with zero signal that it was reopened — it re-runs the
+  // (still-green) scoped verify and re-completes the task, never touching the
+  // regression the gate actually caught. buildExecuteTaskPrompt claims this
+  // artifact and prepends the diagnosis to the next dispatch.
+  if (params.reason && params.reason.trim() !== "") {
+    try {
+      writeReopenReason(basePath, params.milestoneId, params.sliceId, params.taskId, params.reason);
+    } catch (reasonErr) {
+      logWarning("tool", `reopen-task reason persistence warning: ${(reasonErr as Error).message}`);
+    }
+  }
+
   // ── Post-mutation hook ───────────────────────────────────────────────────
   try {
     await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });