@opengsd/gsd-pi 1.5.0-dev.4fb2d460 → 1.5.0-dev.c4c8885f

package/src/resources/extensions/gsd/tests/reassess-handler.test.ts

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, existsSync, readFileSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, rmSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 
@@ -394,6 +394,54 @@ test('handleReassessRoadmap invalidates stale milestone-validation when roadmap
   }
 });
 
+test('handleReassessRoadmap deletes flat-phase compatibility validation files when roadmap changes (#2957)', async (t) => {
+  const base = makeTmpBase();
+  t.after(() => cleanup(base));
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  insertMilestone({ id: 'M001', title: 'Test Milestone', status: 'active' });
+  insertSlice({ id: 'S01', milestoneId: 'M001', title: 'Slice One', status: 'complete', demo: 'Demo' });
+
+  const legacyValidationPath = join(base, '.gsd', 'phases', '01-test', 'M001-VALIDATION.md');
+  const canonicalValidationPath = join(base, '.gsd', 'phases', '01-test', '01-VALIDATION.md');
+  const staleValidation = '---\nverdict: pass\n---\n\n# Stale validation\n';
+  writeFileSync(legacyValidationPath, staleValidation, 'utf-8');
+  writeFileSync(canonicalValidationPath, staleValidation, 'utf-8');
+  insertAssessment({
+    path: legacyValidationPath,
+    milestoneId: 'M001',
+    sliceId: null,
+    taskId: null,
+    status: 'pass',
+    scope: 'milestone-validation',
+    fullContent: staleValidation,
+  });
+
+  const result = await handleReassessRoadmap({
+    milestoneId: 'M001',
+    completedSliceId: 'S01',
+    verdict: 'confirmed',
+    assessment: 'S01 completed. Adding S02 changes roadmap structure.',
+    sliceChanges: {
+      modified: [],
+      added: [
+        {
+          sliceId: 'S02',
+          title: 'New Slice Two',
+          risk: 'low',
+          depends: ['S01'],
+          demo: 'Demo two.',
+        },
+      ],
+      removed: [],
+    },
+  }, base);
+
+  assert.ok(!('error' in result), `unexpected error: ${'error' in result ? result.error : ''}`);
+  assert.equal(existsSync(legacyValidationPath), false, 'stale compatibility validation artifact should be deleted');
+  assert.equal(existsSync(canonicalValidationPath), false, 'canonical validation artifact should not remain after reassess');
+});
+
 test('handleReassessRoadmap does NOT invalidate validation when no roadmap structural changes (#2957)', async () => {
   const base = makeTmpBase();
   openDatabase(join(base, '.gsd', 'gsd.db'));

package/src/resources/extensions/gsd/tests/rule-registry.test.ts

@@ -5,7 +5,7 @@
 
 import assert from 'node:assert/strict';
 import { test, describe, beforeEach } from "node:test";
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, realpathSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { emitJournalEvent } from "../journal.ts";
@@ -544,3 +544,97 @@ describe("RuleRegistry", () => {
     assert.deepStrictEqual(result.matchedRule, "<no-match>", "matchedRule is '<no-match>' on fallback");
   });
 });
+
+describe("resolveHookArtifactPath", () => {
+  test("resolves a phase-level artifact from the .gsd/phases layout", () => {
+    const originalGsdHome = process.env.GSD_HOME;
+    const projectRoot = mkdtempSync(join(tmpdir(), "gsd-hook-phase-"));
+    const tempGsdHome = mkdtempSync(join(tmpdir(), "gsd-hook-home-"));
+    try {
+      process.env.GSD_HOME = tempGsdHome;
+      const phaseDir = join(realpathSync(projectRoot), ".gsd", "phases", "50-some-phase");
+      mkdirSync(phaseDir, { recursive: true });
+      const artifactPath = join(phaseDir, "BROWSER-RUNTIME-EVIDENCE.md");
+      writeFileSync(artifactPath, "---\nverdict: advisory\n---\n", "utf-8");
+
+      const resolved = resolveHookArtifactPath(projectRoot, "M050/S02/T01", "BROWSER-RUNTIME-EVIDENCE.md");
+      assert.equal(resolved, artifactPath, "resolves the canonical phase-level artifact");
+    } finally {
+      if (originalGsdHome === undefined) delete process.env.GSD_HOME;
+      else process.env.GSD_HOME = originalGsdHome;
+      rmSync(projectRoot, { recursive: true, force: true });
+      rmSync(tempGsdHome, { recursive: true, force: true });
+    }
+  });
+
+  test("falls back to the legacy milestones/slices/tasks layout", () => {
+    const originalGsdHome = process.env.GSD_HOME;
+    const projectRoot = mkdtempSync(join(tmpdir(), "gsd-hook-legacy-"));
+    const tempGsdHome = mkdtempSync(join(tmpdir(), "gsd-hook-home-"));
+    try {
+      process.env.GSD_HOME = tempGsdHome;
+      const tasksDir = join(projectRoot, ".gsd", "milestones", "M050", "slices", "S02", "tasks");
+      mkdirSync(tasksDir, { recursive: true });
+      const artifactPath = join(tasksDir, "T01-REVIEW.md");
+      writeFileSync(artifactPath, "---\nverdict: pass\n---\n", "utf-8");
+
+      const resolved = resolveHookArtifactPath(projectRoot, "M050/S02/T01", "REVIEW.md");
+      assert.equal(resolved, artifactPath, "resolves the task-prefixed legacy artifact");
+    } finally {
+      if (originalGsdHome === undefined) delete process.env.GSD_HOME;
+      else process.env.GSD_HOME = originalGsdHome;
+      rmSync(projectRoot, { recursive: true, force: true });
+      rmSync(tempGsdHome, { recursive: true, force: true });
+    }
+  });
+
+  test("legacy: nested task artifact wins over a milestone-root file of the same name", () => {
+    const originalGsdHome = process.env.GSD_HOME;
+    const projectRoot = mkdtempSync(join(tmpdir(), "gsd-hook-legacy-root-"));
+    const tempGsdHome = mkdtempSync(join(tmpdir(), "gsd-hook-home-"));
+    try {
+      process.env.GSD_HOME = tempGsdHome;
+      const milestoneDir = join(projectRoot, ".gsd", "milestones", "M050");
+      const tasksDir = join(milestoneDir, "slices", "S02", "tasks");
+      mkdirSync(tasksDir, { recursive: true });
+      // The correct task-scoped artifact lives in the nested slices/tasks tree.
+      const nestedPath = join(tasksDir, "T01-REVIEW.md");
+      writeFileSync(nestedPath, "---\nverdict: pass\n---\n", "utf-8");
+      // A same-named decoy at the legacy milestone root must NOT win — before the
+      // fix, resolveMilestonePath returned the milestone root and it was probed
+      // ahead of the nested task path (#1264 Bugbot follow-up).
+      writeFileSync(join(milestoneDir, "REVIEW.md"), "---\nverdict: failed\n---\n", "utf-8");
+
+      const resolved = resolveHookArtifactPath(projectRoot, "M050/S02/T01", "REVIEW.md");
+      assert.equal(resolved, nestedPath, "task-scoped legacy path wins over the milestone-root file");
+    } finally {
+      if (originalGsdHome === undefined) delete process.env.GSD_HOME;
+      else process.env.GSD_HOME = originalGsdHome;
+      rmSync(projectRoot, { recursive: true, force: true });
+      rmSync(tempGsdHome, { recursive: true, force: true });
+    }
+  });
+
+  test("legacy: missing-artifact fallback points at the nested task path, not the milestone root", () => {
+    const originalGsdHome = process.env.GSD_HOME;
+    const projectRoot = mkdtempSync(join(tmpdir(), "gsd-hook-legacy-miss-"));
+    const tempGsdHome = mkdtempSync(join(tmpdir(), "gsd-hook-home-"));
+    try {
+      process.env.GSD_HOME = tempGsdHome;
+      const milestoneDir = join(projectRoot, ".gsd", "milestones", "M050");
+      mkdirSync(milestoneDir, { recursive: true });
+      // Content-bearing legacy milestone dir (a non-META file) so resolveMilestonePath
+      // returns it, but the requested gate artifact does not exist anywhere.
+      writeFileSync(join(milestoneDir, "M050-ROADMAP.md"), "# roadmap\n", "utf-8");
+
+      const resolved = resolveHookArtifactPath(projectRoot, "M050/S02/T01", "REVIEW.md");
+      const expected = join(milestoneDir, "slices", "S02", "tasks", "T01-REVIEW.md");
+      assert.equal(resolved, expected, "diagnostic fallback uses the nested task path for a legacy task-scoped unit");
+    } finally {
+      if (originalGsdHome === undefined) delete process.env.GSD_HOME;
+      else process.env.GSD_HOME = originalGsdHome;
+      rmSync(projectRoot, { recursive: true, force: true });
+      rmSync(tempGsdHome, { recursive: true, force: true });
+    }
+  });
+});

package/src/resources/extensions/gsd/tests/sibling-model-fallbacks.test.ts

@@ -0,0 +1,189 @@
+/**
+ * Sibling single-model fields honor `fallbacks[]` (#1229).
+ *
+ * `post_unit_hooks[].model`, `auto_supervisor.model`, and
+ * `reactive_execution.subagent_model` accept the same
+ * `{ model, provider?, fallbacks? }` object form as `models.<phase>` so a
+ * transient provider trip falls back to the next entry instead of hard-failing
+ * (and, for a blocking hook, pausing the whole auto-mode run).
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  normalizeModelFieldConfig,
+  resolveModelWithFallbacksForUnit,
+  resolveAutoSupervisorConfig,
+} from "../preferences-models.ts";
+import { validatePreferences } from "../preferences-validation.ts";
+
+function withPreferences<T>(frontmatter: string[], fn: () => T): T {
+  const oldHome = process.env.GSD_HOME;
+  const home = mkdtempSync(join(tmpdir(), "gsd-sibling-models-"));
+  try {
+    process.env.GSD_HOME = home;
+    writeFileSync(join(home, "preferences.md"), ["---", ...frontmatter, "---", ""].join("\n"));
+    return fn();
+  } finally {
+    if (oldHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = oldHome;
+    rmSync(home, { recursive: true, force: true });
+  }
+}
+
+// ─── normalizeModelFieldConfig ───────────────────────────────────────────────
+
+test("normalizeModelFieldConfig: bare string → primary with empty fallbacks", () => {
+  assert.deepEqual(normalizeModelFieldConfig("my-model"), { primary: "my-model", fallbacks: [] });
+});
+
+test("normalizeModelFieldConfig: object form carries fallbacks", () => {
+  assert.deepEqual(
+    normalizeModelFieldConfig({ model: "primary", fallbacks: ["fb-1", "fb-2"] }),
+    { primary: "primary", fallbacks: ["fb-1", "fb-2"] },
+  );
+});
+
+test("normalizeModelFieldConfig: provider prefix is prepended to bare model", () => {
+  assert.deepEqual(
+    normalizeModelFieldConfig({ model: "gpt-5.4", provider: "openai-codex" }),
+    { primary: "openai-codex/gpt-5.4", fallbacks: [] },
+  );
+});
+
+test("normalizeModelFieldConfig: unset / blank / model-less → undefined", () => {
+  assert.equal(normalizeModelFieldConfig(undefined), undefined);
+  assert.equal(normalizeModelFieldConfig("   "), undefined);
+  assert.equal(normalizeModelFieldConfig({ model: "" }), undefined);
+});
+
+// ─── post_unit_hooks[].model fallback resolution ─────────────────────────────
+
+test("hook/<name> resolves the hook's object-form model with fallbacks", () => {
+  withPreferences(
+    [
+      "post_unit_hooks:",
+      "  - name: plan-review",
+      "    after: [plan-slice]",
+      "    prompt: review the plan",
+      "    model:",
+      "      model: primary-model",
+      "      fallbacks:",
+      "        - fallback-a",
+      "        - fallback-b",
+    ],
+    () => {
+      const resolved = resolveModelWithFallbacksForUnit("hook/plan-review");
+      assert.deepEqual(resolved, { primary: "primary-model", fallbacks: ["fallback-a", "fallback-b"] });
+    },
+  );
+});
+
+test("hook/<name> still resolves the legacy bare-string model form", () => {
+  withPreferences(
+    [
+      "post_unit_hooks:",
+      "  - name: plan-review",
+      "    after: [plan-slice]",
+      "    prompt: review the plan",
+      "    model: solo-model",
+    ],
+    () => {
+      assert.deepEqual(
+        resolveModelWithFallbacksForUnit("hook/plan-review"),
+        { primary: "solo-model", fallbacks: [] },
+      );
+    },
+  );
+});
+
+test("hook/<name> resolves undefined when the hook has no model", () => {
+  withPreferences(
+    [
+      "post_unit_hooks:",
+      "  - name: plan-review",
+      "    after: [plan-slice]",
+      "    prompt: review the plan",
+    ],
+    () => {
+      assert.equal(resolveModelWithFallbacksForUnit("hook/plan-review"), undefined);
+      assert.equal(resolveModelWithFallbacksForUnit("hook/unknown-hook"), undefined);
+    },
+  );
+});
+
+// ─── auto_supervisor.model ───────────────────────────────────────────────────
+
+test("auto_supervisor.model object form resolves with fallbacks", () => {
+  withPreferences(
+    [
+      "auto_supervisor:",
+      "  model:",
+      "    model: supervisor-primary",
+      "    fallbacks: [supervisor-fb]",
+    ],
+    () => {
+      assert.deepEqual(resolveModelWithFallbacksForUnit("supervisor"), {
+        primary: "supervisor-primary",
+        fallbacks: ["supervisor-fb"],
+      });
+      const supervisor = resolveAutoSupervisorConfig();
+      assert.equal(supervisor.model, "supervisor-primary");
+      assert.deepEqual(supervisor.modelFallbacks, ["supervisor-fb"]);
+    },
+  );
+});
+
+// ─── validation accepts the object form ──────────────────────────────────────
+
+test("validatePreferences accepts object-form hook and subagent models", () => {
+  const { preferences: validated, errors } = validatePreferences({
+    post_unit_hooks: [
+      {
+        name: "plan-review",
+        after: ["plan-slice"],
+        prompt: "review",
+        model: { model: "primary", fallbacks: ["fb-1"] },
+      },
+    ],
+    reactive_execution: {
+      enabled: true,
+      subagent_model: { model: "sub-primary", fallbacks: ["sub-fb"] },
+    },
+  } as never);
+
+  assert.deepEqual(errors, []);
+  assert.deepEqual(validated.post_unit_hooks?.[0].model, { model: "primary", fallbacks: ["fb-1"] });
+  assert.deepEqual(validated.reactive_execution?.subagent_model, { model: "sub-primary", fallbacks: ["sub-fb"] });
+});
+
+test("validatePreferences rejects a model-less object form", () => {
+  const { errors } = validatePreferences({
+    post_unit_hooks: [
+      { name: "plan-review", after: ["plan-slice"], prompt: "review", model: { fallbacks: ["fb"] } },
+    ],
+  } as never);
+  assert.ok(errors.some((e) => e.includes('requires a non-empty "model"')));
+});
+
+test("validatePreferences accepts object-form auto_supervisor.model", () => {
+  const { preferences: validated, errors } = validatePreferences({
+    auto_supervisor: { model: { model: "sup-primary", fallbacks: ["sup-fb"] } },
+  } as never);
+  assert.deepEqual(errors, []);
+  assert.deepEqual(validated.auto_supervisor?.model, { model: "sup-primary", fallbacks: ["sup-fb"] });
+});
+
+test("validatePreferences rejects a model-less auto_supervisor.model object", () => {
+  const { errors } = validatePreferences({
+    auto_supervisor: { model: { fallbacks: ["sup-fb"] } },
+  } as never);
+  assert.ok(
+    errors.some((e) => e.includes("auto_supervisor.model") && e.includes('requires a non-empty "model"')),
+    `expected supervisor model error, got: ${JSON.stringify(errors)}`,
+  );
+});

package/src/resources/extensions/gsd/tests/single-field-model-thinking.test.ts

@@ -0,0 +1,156 @@
+/**
+ * Regression tests for #1269 — the object model form's `thinking` sub-field on
+ * the three single-model fields (`post_unit_hooks[].model`,
+ * `auto_supervisor.model`, and `reactive_execution.subagent_model`) was
+ * silently dropped after validation/normalization, so a configured
+ * hook/supervisor/subagent reasoning level never applied.
+ *
+ * These exercise the real preference pipeline through the exported runtime APIs:
+ *   sanitize   → validatePreferences
+ *   normalize  → normalizeModelFieldConfig
+ *   resolve    → resolveThinkingLevelForUnit  (supervisor + hook/* early path)
+ *
+ * The `supervisor` and `hook/*` unit types have no phase-bucket chain, so the
+ * pre-#1269 resolver walk never covered them and returned `undefined`.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { validatePreferences } from "../preferences-validation.ts";
+import { normalizeModelFieldConfig, resolveThinkingLevelForUnit } from "../preferences-models.ts";
+import { invalidateAllCaches } from "../cache.ts";
+
+/** Read the per-field `thinking` off a validated/normalized model config. */
+function thinkingOf(model: unknown): string | undefined {
+  return (model as { thinking?: string } | undefined)?.thinking;
+}
+
+/** Write a project-level `.gsd/PREFERENCES.md` and run `fn` with its basePath. */
+function withProjectPreferences<T>(frontmatter: string, fn: (basePath: string) => T): T {
+  const base = mkdtempSync(join(tmpdir(), "gsd-1269-thinking-"));
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  writeFileSync(join(base, ".gsd", "PREFERENCES.md"), `---\n${frontmatter}\n---\n`, "utf-8");
+  invalidateAllCaches();
+  try {
+    return fn(base);
+  } finally {
+    invalidateAllCaches();
+    rmSync(base, { recursive: true, force: true });
+  }
+}
+
+// ── sanitize: validatePreferences preserves a valid object-form thinking ──────
+
+test("validatePreferences preserves auto_supervisor.model object-form thinking", () => {
+  const { preferences, errors } = validatePreferences({
+    auto_supervisor: { model: { model: "supervisor-model", thinking: "high" } },
+  });
+  assert.equal(errors.length, 0);
+  assert.equal(thinkingOf(preferences.auto_supervisor?.model), "high");
+});
+
+test("validatePreferences preserves post_unit_hooks[].model object-form thinking", () => {
+  const { preferences, errors } = validatePreferences({
+    post_unit_hooks: [
+      {
+        name: "code-review",
+        after: ["execute-task"],
+        prompt: "Review the diff",
+        model: { model: "hook-model", thinking: "low" },
+      },
+    ],
+  });
+  assert.equal(errors.length, 0);
+  assert.equal(thinkingOf(preferences.post_unit_hooks?.[0]?.model), "low");
+});
+
+test("validatePreferences preserves reactive_execution.subagent_model object-form thinking", () => {
+  const { preferences, errors } = validatePreferences({
+    reactive_execution: {
+      enabled: true,
+      max_parallel: 2,
+      isolation_mode: "same-tree",
+      subagent_model: { model: "subagent-model", thinking: "medium" },
+    },
+  });
+  assert.equal(errors.length, 0);
+  assert.equal(thinkingOf(preferences.reactive_execution?.subagent_model), "medium");
+});
+
+// ── sanitize: an invalid thinking level is warned and stripped ────────────────
+
+test("validatePreferences warns and strips an invalid object-form thinking level", () => {
+  const { preferences, errors, warnings } = validatePreferences({
+    auto_supervisor: { model: { model: "supervisor-model", thinking: "ludicrous" } },
+  } as never);
+  // The model survives; only the bogus thinking is dropped, so a typo can never
+  // reach the resolver and masquerade as explicit configuration.
+  assert.equal(errors.length, 0);
+  assert.equal(thinkingOf(preferences.auto_supervisor?.model), undefined);
+  assert.ok(
+    warnings.some((w) => w.includes("auto_supervisor.model") && w.includes("thinking")),
+    `expected a thinking warning, got: ${JSON.stringify(warnings)}`,
+  );
+});
+
+// ── normalize: normalizeModelFieldConfig carries thinking through ─────────────
+
+test("normalizeModelFieldConfig carries object-form thinking through", () => {
+  const config = normalizeModelFieldConfig({ model: "hook-model", thinking: "xhigh" });
+  assert.equal(config?.primary, "hook-model");
+  assert.equal(config?.thinking, "xhigh");
+});
+
+test("normalizeModelFieldConfig leaves thinking absent when omitted", () => {
+  const fromObject = normalizeModelFieldConfig({ model: "hook-model" });
+  assert.equal(fromObject?.primary, "hook-model");
+  assert.equal(fromObject?.thinking, undefined);
+
+  const fromString = normalizeModelFieldConfig("hook-model");
+  assert.equal(fromString?.primary, "hook-model");
+  assert.equal(fromString?.thinking, undefined);
+});
+
+// ── resolve: the single-field unit types surface their per-field thinking ──────
+
+test("resolveThinkingLevelForUnit('supervisor') returns auto_supervisor.model thinking", () => {
+  withProjectPreferences(
+    ["auto_supervisor:", "  model:", "    model: supervisor-model", "    thinking: high"].join("\n"),
+    (base) => {
+      assert.equal(resolveThinkingLevelForUnit("supervisor", base), "high");
+    },
+  );
+});
+
+test("resolveThinkingLevelForUnit('hook/<name>') returns the matching hook model thinking", () => {
+  withProjectPreferences(
+    [
+      "post_unit_hooks:",
+      "  - name: code-review",
+      "    after:",
+      "      - execute-task",
+      "    prompt: Review the diff",
+      "    model:",
+      "      model: hook-model",
+      "      thinking: low",
+    ].join("\n"),
+    (base) => {
+      assert.equal(resolveThinkingLevelForUnit("hook/code-review", base), "low");
+    },
+  );
+});
+
+test("resolveThinkingLevelForUnit('supervisor') stays undefined when thinking is omitted", () => {
+  // Bare-string model form carries no thinking → dispatch falls back to the
+  // session/floor level, unchanged from pre-#1269 behavior.
+  withProjectPreferences(
+    ["auto_supervisor:", "  model: supervisor-model"].join("\n"),
+    (base) => {
+      assert.equal(resolveThinkingLevelForUnit("supervisor", base), undefined);
+    },
+  );
+});

package/src/resources/extensions/gsd/tests/skipped-validation-db-atomicity.test.ts

@@ -52,7 +52,12 @@ test("skipped validation dispatch persists the validation file and DB assessment
     const artifactPath = "milestones/M001/slices/S01/S01-ASSESSMENT.md";
     const assessmentPath = `.gsd/${artifactPath}`;
     assert.equal(getArtifact(artifactPath)?.artifact_type, "ASSESSMENT");
-    assert.equal(getAssessment(assessmentPath)?.scope, "run-uat");
+    // #1258: the per-slice ASSESSMENT fabricated by the pre-validation backfill
+    // is a placeholder (no UAT ever ran for this slice), so it is filed under the
+    // `backfill` scope — never `run-uat` — so `readUatGateVerdict` cannot mistake
+    // it for a genuine UAT sign-off. Its verdict body stays PASS to satisfy the
+    // MV02 artifact-existence requirement.
+    assert.equal(getAssessment(assessmentPath)?.scope, "backfill");
     assert.equal(getAssessment(assessmentPath)?.status, "pass");
     assert.equal(
       getLatestAssessmentByScope("M001", "milestone-validation")?.status,

package/src/resources/extensions/gsd/tests/start-auto-detached.test.ts

@@ -208,6 +208,38 @@ test("startAutoDetached reports failures asynchronously (#3733)", () => {
   );
 });
 
+test("failed auto-start always clears leaked s.active so later /gsd auto is not bricked (#1235)", () => {
+  const autoSrc = readGsdFile("auto.ts");
+
+  // 1. startAutoDetached is the single funnel for any exception thrown out of
+  //    startAuto — including a bootstrap throw that escapes before the loop's
+  //    try/finally could run cleanupAfterLoopExit. The failure handler must
+  //    clear leaked activation, or s.active + the on-disk auto lock persist and
+  //    the re-entry guard silently no-ops every later /gsd auto until restart.
+  const detachedIdx = autoSrc.indexOf("export function startAutoDetached");
+  assert.ok(detachedIdx > -1, "startAutoDetached should exist");
+  const detachedBody = autoSrc.slice(detachedIdx, autoSrc.indexOf("\n}", detachedIdx));
+  assert.ok(
+    detachedBody.includes("if (s.active)") &&
+      detachedBody.includes("cleanupAfterLoopExit(ctx)"),
+    "startAutoDetached failure handler must run cleanupAfterLoopExit when auto-mode is still active",
+  );
+
+  // 2. bootstrapAutoSession sets s.active = true before some bail-outs return
+  //    false (e.g. the SQLite-unavailable gate), so the fresh-start !ready path
+  //    must clear the leaked activation before returning.
+  const startAutoIdx = autoSrc.indexOf("export async function startAuto(");
+  assert.ok(startAutoIdx > -1, "startAuto should exist");
+  const startAutoBody = autoSrc.slice(startAutoIdx);
+  const notReadyIdx = startAutoBody.indexOf("if (!ready) {");
+  assert.ok(notReadyIdx > -1, "fresh start should guard on bootstrap readiness with a block body");
+  const notReadyBlock = startAutoBody.slice(notReadyIdx, notReadyIdx + 600);
+  assert.ok(
+    notReadyBlock.includes("if (s.active) await cleanupAfterLoopExit(ctx)"),
+    "fresh-start !ready bail-out must clear leaked auto activation before returning",
+  );
+});
+
 test("detached auto-start keeps a ref'ed handle until the run settles", async () => {
   const originalSetInterval = globalThis.setInterval;
   const originalClearInterval = globalThis.clearInterval;