gsd-pi 2.78.1-dev.84a383f51 → 2.78.1

package/src/resources/extensions/gsd/tests/discuss-queued-milestones.test.ts

@@ -16,9 +16,11 @@
 
 import { describe, test, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { dirname } from "node:path";
 
 import { deriveState } from "../state.ts";
 import { invalidateAllCaches } from "../cache.ts";
@@ -55,6 +57,12 @@ function writeRoadmap(base: string, mid: string, content: string): void {
   writeFileSync(join(base, ".gsd", "milestones", mid, `${mid}-ROADMAP.md`), content);
 }
 
+function readGuidedFlowSource(): string {
+  const thisFile = fileURLToPath(import.meta.url);
+  const thisDir = dirname(thisFile);
+  return readFileSync(join(thisDir, "..", "guided-flow.ts"), "utf-8");
+}
+
 // ─── Tests ────────────────────────────────────────────────────────────────────
 
 describe("discuss-queued-milestones (#2307)", () => {
@@ -161,10 +169,113 @@ describe("discuss-queued-milestones (#2307)", () => {
     }
   });
 
-  // The earlier tests 6-13 source-grepped guided-flow.ts for identifier
-  // names (showDiscussQueuedMilestone, dispatchDiscussForMilestone),
-  // UI-copy strings ("[queued]", "Discuss a queued milestone"), and
-  // regex-on-function-body assertions for the #3150 routing — all
-  // structural rather than behavioural (Refs #4826). They were dropped
-  // when this file was tightened against handler-level assertions.
+  test("6. guided-flow no longer hard-exits when no active milestone but pending exist", () => {
+    const source = readGuidedFlowSource();
+
+    // The old guard was a simple early-exit:
+    //   if (!state.activeMilestone) {
+    //     ctx.ui.notify("No active milestone. Run /gsd to create one first.", "warning");
+    //     return;
+    //   }
+    //
+    // The new guard should check for pending milestones and route instead.
+    const oldGuardPattern = /if\s*\(!state\.activeMilestone\)\s*\{\s*ctx\.ui\.notify\("No active milestone/;
+    assert.ok(
+      !oldGuardPattern.test(source),
+      "guided-flow must not unconditionally exit when activeMilestone is null",
+    );
+  });
+
+  test("7. showDiscussQueuedMilestone helper exists in guided-flow", () => {
+    const source = readGuidedFlowSource();
+    assert.ok(
+      source.includes("showDiscussQueuedMilestone"),
+      "guided-flow must export showDiscussQueuedMilestone helper",
+    );
+  });
+
+  test("8. dispatchDiscussForMilestone helper exists in guided-flow", () => {
+    const source = readGuidedFlowSource();
+    assert.ok(
+      source.includes("dispatchDiscussForMilestone"),
+      "guided-flow must export dispatchDiscussForMilestone helper",
+    );
+  });
+
+  test("9. dispatchDiscussForMilestone does not set pendingAutoStart", () => {
+    const source = readGuidedFlowSource();
+
+    // Extract the dispatchDiscussForMilestone function body
+    const fnMatch = source.match(
+      /async function dispatchDiscussForMilestone\s*\([^)]*\)[^{]*\{([\s\S]*?)\n\}/,
+    );
+    assert.ok(!!fnMatch, "dispatchDiscussForMilestone function body must be present");
+
+    if (fnMatch) {
+      assert.ok(
+        !fnMatch[1].includes("pendingAutoStart"),
+        "dispatchDiscussForMilestone must NOT set pendingAutoStart — discussing a queued milestone must not activate it",
+      );
+    }
+  });
+
+  test("10. slice picker includes queued milestone option when pending milestones exist", () => {
+    const source = readGuidedFlowSource();
+    assert.ok(
+      source.includes("discuss_queued_milestone"),
+      "slice picker must include a 'discuss_queued_milestone' action id for queued milestones",
+    );
+    assert.ok(
+      source.includes("Discuss a queued milestone"),
+      "slice picker must label the queued milestone action clearly",
+    );
+  });
+
+  test("11. queued milestone picker labels entries with [queued]", () => {
+    const source = readGuidedFlowSource();
+    assert.ok(
+      source.includes("[queued]"),
+      "queued milestone picker must label entries with [queued] to distinguish from active",
+    );
+  });
+
+  // ─── #3150: allDiscussed early-return must not block queued milestone discussion ──
+
+  test("12. allDiscussed path checks for pending milestones before returning (#3150)", () => {
+    const source = readGuidedFlowSource();
+
+    // Extract the allDiscussed block — the if (allDiscussed) { ... } body
+    const allDiscussedMatch = source.match(
+      /const allDiscussed = pendingSlices\.every\([\s\S]*?\n    if \(allDiscussed\) \{([\s\S]*?)\n    \}/,
+    );
+    assert.ok(!!allDiscussedMatch, "allDiscussed guard block must exist in showDiscuss()");
+
+    if (allDiscussedMatch) {
+      const body = allDiscussedMatch[1];
+      // The fix must check for pending milestones and route to showDiscussQueuedMilestone
+      assert.ok(
+        body.includes("pending") && body.includes("showDiscussQueuedMilestone"),
+        "allDiscussed block must check for pending milestones and call showDiscussQueuedMilestone before returning (#3150)",
+      );
+    }
+  });
+
+  test("13. pendingSlices.length===0 path checks for pending milestones before returning (#3150)", () => {
+    const source = readGuidedFlowSource();
+
+    // Find the pendingSlices.length === 0 guard block
+    const zeroSlicesMatch = source.match(
+      /if \(pendingSlices\.length === 0\) \{([\s\S]*?)\n  \}/,
+    );
+    assert.ok(!!zeroSlicesMatch, "pendingSlices.length === 0 guard block must exist in showDiscuss()");
+
+    if (zeroSlicesMatch) {
+      const body = zeroSlicesMatch[1];
+      // The fix must check for pending milestones and route to showDiscussQueuedMilestone
+      assert.ok(
+        body.includes("pending") && body.includes("showDiscussQueuedMilestone"),
+        "pendingSlices.length===0 block must check for pending milestones and call showDiscussQueuedMilestone before returning (#3150)",
+      );
+    }
+  });
 });

package/src/resources/extensions/gsd/tests/discuss-slice-structured-questions.test.ts

@@ -0,0 +1,47 @@
+/**
+ * Regression test for discuss-slice structured questions availability
+ *
+ * The guided-discuss-slice.md template must use the structuredQuestionsAvailable
+ * template variable to conditionally switch between ask_user_questions tool
+ * calls and plain-text questions, so the prompt works correctly when the
+ * structured questions tool is not available.
+ */
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { extractSourceRegion } from "./test-helpers.ts";
+
+const template = readFileSync(
+  resolve(process.cwd(), 'src', 'resources', 'extensions', 'gsd', 'prompts', 'guided-discuss-slice.md'),
+  'utf-8',
+)
+
+describe('discuss-slice structuredQuestionsAvailable template variable', () => {
+  it('template references structuredQuestionsAvailable variable', () => {
+    assert.ok(
+      template.includes('{{structuredQuestionsAvailable}}'),
+      'guided-discuss-slice.md must use {{structuredQuestionsAvailable}} template variable',
+    )
+  })
+
+  it('template handles both true and false cases', () => {
+    const trueCase = template.includes('`{{structuredQuestionsAvailable}}` is `true`')
+    const falseCase = template.includes('`{{structuredQuestionsAvailable}}` is `false`')
+
+    assert.ok(trueCase, 'template must have a branch for structuredQuestionsAvailable=true')
+    assert.ok(falseCase, 'template must have a branch for structuredQuestionsAvailable=false')
+  })
+
+  it('false case instructs plain text questions', () => {
+    const falseIdx = template.indexOf('`{{structuredQuestionsAvailable}}` is `false`')
+    assert.ok(falseIdx !== -1)
+
+    const afterFalse = extractSourceRegion(template, '`{{structuredQuestionsAvailable}}` is `false`')
+    assert.ok(
+      afterFalse.includes('plain text'),
+      'when structuredQuestionsAvailable is false, questions should be in plain text',
+    )
+  })
+})

package/src/resources/extensions/gsd/tests/discuss-tool-scope-leak.test.ts

@@ -1,35 +1,77 @@
-// GSD-2 — Behavioural regression test for #3616.
-//
-// Bug: After a discuss session narrows the active tool set via setActiveTools,
-// the narrowed list persisted into the next auto-mode session because newSession()
-// did not restore extension tools when cwd was unchanged. This caused
-// gsd_plan_slice and other DB tools to be missing from plan-slice subagent
-// sessions.
-//
-// The behavioural invariant we can pin without grepping source: gsd_plan_slice
-// (a heavy planning tool) is NOT inside the discuss allowlist. The remaining
-// guarantees (newSession including all extension tools in both branches) are
-// covered by agent-session.test.ts inside packages/pi-coding-agent.
-//
-// Refs #4826 (rewrite from source-grep on guided-flow.ts / agent-session.ts).
+// GSD-2 — Regression test for #3616: discuss tool scoping must not leak into subsequent sessions
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+/**
+ * Bug #3616: After a discuss session narrows the active tool set via
+ * setActiveTools(), the narrowed list persisted into the next auto-mode
+ * session because newSession() did not restore extension tools when cwd
+ * was unchanged. This caused gsd_plan_slice and other DB tools to be
+ * missing from plan-slice subagent sessions.
+ *
+ * This test verifies the structural properties that prevent the leak:
+ *   1. guided-flow.ts narrows tools ONLY for discuss-* unit types
+ *   2. The narrowed set explicitly excludes gsd_plan_slice (a HEAVY_TOOL)
+ *   3. agent-session.ts:newSession() has an else-branch that restores
+ *      all extension tools even when cwd hasn't changed
+ */
 
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { DISCUSS_TOOLS_ALLOWLIST } from "../constants.ts";
+import { extractSourceRegion } from "./test-helpers.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const guidedFlowSource = readFileSync(join(__dirname, "..", "guided-flow.ts"), "utf-8");
 
 describe("#3616 — discuss tool scoping must not leak across sessions", () => {
 	test("gsd_plan_slice is NOT in DISCUSS_TOOLS_ALLOWLIST", () => {
 		assert.ok(
 			!DISCUSS_TOOLS_ALLOWLIST.includes("gsd_plan_slice"),
-			`gsd_plan_slice (a heavy planning tool) must be excluded from the discuss scope; allowlist=${JSON.stringify(DISCUSS_TOOLS_ALLOWLIST)}`,
+			"gsd_plan_slice should be excluded from discuss scope (it's a heavy planning tool)",
+		);
+	});
+
+	test("tool scoping only activates for discuss-* unit types", () => {
+		// The guard must be: if (unitType?.startsWith("discuss-"))
+		assert.ok(
+			guidedFlowSource.includes('unitType?.startsWith("discuss-")'),
+			"tool scoping should only trigger for discuss-* unit types",
 		);
 	});
 
-	test("DISCUSS_TOOLS_ALLOWLIST is non-empty (sanity)", () => {
+	test("discuss tool scoping uses setActiveTools (not setTools) for reversibility", () => {
+		// setActiveTools changes the active subset but doesn't remove tools from
+		// the registry. newSession()'s _refreshToolRegistry can restore them.
+		assert.ok(
+			guidedFlowSource.includes("pi.setActiveTools(scopedTools)"),
+			"should use pi.setActiveTools to narrow tools (preserving registry)",
+		);
+	});
+
+	test("newSession() in agent-session.ts has defense against tool narrowing persistence", () => {
+		const agentSessionSource = readFileSync(
+			join(process.cwd(), "packages/pi-coding-agent/src/core/agent-session.ts"),
+			"utf-8",
+		);
+		const newSessionStart = agentSessionSource.indexOf("async newSession(options?:");
+		assert.ok(newSessionStart >= 0, "should find newSession");
+		const body = extractSourceRegion(agentSessionSource, "async newSession(options?:");
+
+		// Both branches (cwd-changed and cwd-unchanged) must include extension tools
+		assert.ok(
+			body.includes("includeAllExtensionTools: true"),
+			"newSession() must include all extension tools in both branches",
+		);
+
+		// Count occurrences — should be at least 2 (one per branch)
+		const matches = body.match(/includeAllExtensionTools:\s*true/g);
 		assert.ok(
-			DISCUSS_TOOLS_ALLOWLIST.length > 0,
-			"discuss scope should include at least one tool — empty allowlist would break /gsd discuss",
+			matches && matches.length >= 2,
+			`expected >=2 includeAllExtensionTools:true in newSession(), got ${matches?.length ?? 0}`,
 		);
 	});
 });

package/src/resources/extensions/gsd/tests/double-merge-guard.test.ts

@@ -1,20 +1,82 @@
-/**
- * Behavioural regression test for #2645 — double mergeAndExit guard.
- *
- * AutoSession.milestoneMergedInPhases is the producer-side flag set by the
- * "complete" / "all-milestones-complete" branches in phases.ts after they
- * call mergeAndExit. stopAuto reads it to skip the redundant Step-4 merge
- * (which previously failed because the branch was already deleted).
- *
- * Refs #4829 (rewrite from positional source-grep on phases.ts/auto.ts).
- */
-
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { AutoSession } from "../auto/session.ts";
+import { extractSourceRegion } from "./test-helpers.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+describe("double mergeAndExit guard (#2645)", () => {
+  test("phases.ts sets milestoneMergedInPhases after mergeAndExit in milestone-complete path", () => {
+    // Source audit: the "complete" phase path must set the guard flag
+    // after calling mergeAndExit so that stopAuto skips the second merge.
+    const phasesSrc = readFileSync(
+      join(__dirname, "..", "auto", "phases.ts"),
+      "utf-8",
+    );
+
+    // Find the "complete" phase block
+    const completeIdx = phasesSrc.indexOf('state.phase === "complete"');
+    assert.ok(completeIdx > 0, "phases.ts should have a 'complete' phase check");
+
+    const afterComplete = extractSourceRegion(phasesSrc, 'state.phase === "complete"');
+    const mergeIdx = afterComplete.indexOf("deps.resolver.mergeAndExit");
+    const flagIdx = afterComplete.indexOf("s.milestoneMergedInPhases = true");
+
+    assert.ok(mergeIdx > 0, "complete path should call mergeAndExit");
+    assert.ok(flagIdx > 0, "complete path should set milestoneMergedInPhases");
+    assert.ok(
+      flagIdx > mergeIdx,
+      "milestoneMergedInPhases must be set AFTER mergeAndExit (not before)",
+    );
+  });
+
+  test("phases.ts sets milestoneMergedInPhases after mergeAndExit in all-milestones-complete path", () => {
+    const phasesSrc = readFileSync(
+      join(__dirname, "..", "auto", "phases.ts"),
+      "utf-8",
+    );
+
+    // The "all milestones complete" block checks incomplete.length === 0
+    const allCompleteIdx = phasesSrc.indexOf("incomplete.length === 0");
+    assert.ok(allCompleteIdx > 0, "phases.ts should have an all-milestones-complete check");
+
+    const afterAllComplete = extractSourceRegion(phasesSrc, "incomplete.length === 0");
+    const mergeIdx = afterAllComplete.indexOf("deps.resolver.mergeAndExit");
+    const flagIdx = afterAllComplete.indexOf("s.milestoneMergedInPhases = true");
+
+    assert.ok(mergeIdx > 0, "all-complete path should call mergeAndExit");
+    assert.ok(flagIdx > 0, "all-complete path should set milestoneMergedInPhases");
+    assert.ok(
+      flagIdx > mergeIdx,
+      "milestoneMergedInPhases must be set AFTER mergeAndExit (not before)",
+    );
+  });
+
+  test("stopAuto checks milestoneMergedInPhases before calling mergeAndExit", () => {
+    const autoSrc = readFileSync(
+      join(__dirname, "..", "auto.ts"),
+      "utf-8",
+    );
+
+    // The Step 4 worktree exit block must check the guard flag
+    const step4Idx = autoSrc.indexOf("Step 4: Auto-worktree exit");
+    assert.ok(step4Idx > 0, "auto.ts should have Step 4 worktree exit");
+
+    const step4Block = extractSourceRegion(autoSrc, "Step 4: Auto-worktree exit");
+    assert.ok(
+      step4Block.includes("milestoneMergedInPhases"),
+      "stopAuto Step 4 must check milestoneMergedInPhases before merging",
+    );
+    assert.ok(
+      step4Block.includes("!s.milestoneMergedInPhases"),
+      "stopAuto should skip merge when milestoneMergedInPhases is true",
+    );
+  });
 
-describe("AutoSession.milestoneMergedInPhases (#2645)", () => {
-  test("defaults to false on a fresh session", () => {
+  test("AutoSession.milestoneMergedInPhases defaults to false", () => {
     const session = new AutoSession();
     assert.equal(
       session.milestoneMergedInPhases,
@@ -23,7 +85,7 @@ describe("AutoSession.milestoneMergedInPhases (#2645)", () => {
     );
   });
 
-  test("reset() clears the flag back to false", () => {
+  test("AutoSession.reset() clears milestoneMergedInPhases", () => {
     const session = new AutoSession();
     session.milestoneMergedInPhases = true;
     session.reset();

package/src/resources/extensions/gsd/tests/empty-content-abort-loop.test.ts

@@ -0,0 +1,75 @@
+/**
+ * empty-content-abort-loop.test.ts — Regression test for #2695.
+ *
+ * When the LLM sends an assistant message with empty `content: []` and
+ * `stopReason: "aborted"`, this is NOT a fatal abort — it is a non-fatal
+ * end-of-turn. The abort handler in agent-end-recovery.ts must distinguish
+ * this case and NOT pause auto-mode, allowing the loop to continue via
+ * resolveAgentEnd instead of entering a stuck re-dispatch loop.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { extractSourceRegion } from "./test-helpers.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const RECOVERY_PATH = join(__dirname, "..", "bootstrap", "agent-end-recovery.ts");
+
+function getRecoverySource(): string {
+  return readFileSync(RECOVERY_PATH, "utf-8");
+}
+
+test("agent-end-recovery.ts does not pause on aborted messages with empty content (#2695)", () => {
+  const source = getRecoverySource();
+
+  // The abort handler at `stopReason === "aborted"` must check for empty content
+  // before deciding to pause. An empty content array is a non-fatal agent stop.
+  const abortIdx = source.indexOf('stopReason === "aborted"');
+  assert.ok(abortIdx > -1, "abort handler must exist in agent-end-recovery.ts");
+
+  // Extract the region around the abort handler (enough to see the guard logic)
+  const abortRegion = extractSourceRegion(source, 'stopReason === "aborted"', { fromIdx: abortIdx });
+
+  // Must check for empty content before pausing
+  assert.ok(
+    abortRegion.includes("content") && (abortRegion.includes("length") || abortRegion.includes("?.length")),
+    "abort handler must inspect content array length to distinguish empty-content aborts from fatal aborts (#2695)",
+  );
+});
+
+test("agent-end-recovery.ts routes empty-content aborted messages to resolveAgentEnd (#2695)", () => {
+  const source = getRecoverySource();
+
+  // The abort block must have a path that calls resolveAgentEnd for empty-content messages
+  // instead of unconditionally calling pauseAuto
+  const abortIdx = source.indexOf('stopReason === "aborted"');
+  assert.ok(abortIdx > -1, "abort handler must exist");
+
+  // Get the full abort handling block (from the if to the next stopReason check or success path)
+  const afterAbort = extractSourceRegion(source, 'stopReason === "aborted"');
+
+  // The abort block must have a code path that calls resolveAgentEnd (for empty-content case)
+  assert.ok(
+    afterAbort.includes("resolveAgentEnd"),
+    "abort handler must route empty-content aborted messages to resolveAgentEnd instead of always pausing (#2695)",
+  );
+});
+
+test("agent-end-recovery.ts checks for errorMessage presence in abort handler (#2695)", () => {
+  const source = getRecoverySource();
+
+  const abortIdx = source.indexOf('stopReason === "aborted"');
+  assert.ok(abortIdx > -1, "abort handler must exist");
+
+  const abortRegion = extractSourceRegion(source, 'stopReason === "aborted"');
+
+  // Fatal aborts should have error context (errorMessage field).
+  // The handler should check for this to distinguish fatal from non-fatal aborts.
+  assert.ok(
+    abortRegion.includes("errorMessage"),
+    "abort handler must check for errorMessage to distinguish fatal aborts from empty-content non-fatal stops (#2695)",
+  );
+});

package/src/resources/extensions/gsd/tests/false-degraded-mode-warning.test.ts

@@ -1,43 +1,104 @@
 /**
- * Behavioural regression tests for #3922.
+ * false-degraded-mode-warning.test.ts — Regression tests for #3922.
  *
- * Before this fix, deriveState() logged "DB unavailable — degraded mode"
- * even when the DB had not been opened yet (e.g. during
- * before_agent_start context injection). The fix introduced
- * wasDbOpenAttempted() so the warning fires only after a real open attempt.
+ * Before this fix, deriveState() logged a "DB unavailable — degraded mode"
+ * warning even when the DB simply hadn't been opened yet (e.g. during
+ * before_agent_start context injection). The fix introduces wasDbOpenAttempted()
+ * to distinguish "not yet initialized" from "genuinely unavailable."
  *
- * The earlier tests source-grepped state.ts for the warning string and the
- * preceding line (POSITIONAL/SOURCE_GREP per #4826/#4829). They are
- * replaced here with direct calls to the wasDbOpenAttempted flag.
+ * Two aspects:
+ * 1. gsd-db: wasDbOpenAttempted() tracks whether openDatabase() was ever called.
+ * 2. state: the degraded-mode warning is gated behind wasDbOpenAttempted().
  */
 
-import { describe, test, beforeEach, afterEach } from "node:test";
+import { describe, test } from "node:test";
 import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import {
   openDatabase,
   closeDatabase,
+  isDbAvailable,
   wasDbOpenAttempted,
 } from "../gsd-db.ts";
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const stateSource = readFileSync(join(__dirname, "..", "state.ts"), "utf-8");
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 1. gsd-db: wasDbOpenAttempted flag
+// ═══════════════════════════════════════════════════════════════════════════
+
 describe("wasDbOpenAttempted (#3922)", () => {
-  beforeEach(() => { closeDatabase(); });
-  afterEach(() => { closeDatabase(); });
 
-  test("returns true after a successful openDatabase call", () => {
+  test("wasDbOpenAttempted returns true after openDatabase is called", () => {
+    // By this point in the test suite, openDatabase may or may not have been
+    // called by other tests. So we call it explicitly and verify it returns true.
     openDatabase(":memory:");
-    assert.strictEqual(
-      wasDbOpenAttempted(),
-      true,
-      "wasDbOpenAttempted should report true after openDatabase succeeds",
-    );
+    assert.strictEqual(wasDbOpenAttempted(), true,
+      "wasDbOpenAttempted should be true after openDatabase call");
+    closeDatabase();
   });
 
-  test("remains true after a failed open attempt — the attempt is what matters", () => {
+  test("openDatabase sets the flag even if it fails on invalid path", () => {
+    // openDatabase with an unreachable path may fail, but the flag should
+    // still be set because the attempt was made.
     try { openDatabase("/nonexistent/path/that/will/fail.db"); } catch { /* expected */ }
-    assert.strictEqual(
-      wasDbOpenAttempted(),
-      true,
-      "wasDbOpenAttempted should be true even when openDatabase throws — the warning gate keys on the attempt, not the outcome",
+    assert.strictEqual(wasDbOpenAttempted(), true,
+      "wasDbOpenAttempted should be true even after a failed open attempt");
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 2. state.ts: degraded-mode warning is gated behind wasDbOpenAttempted
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("degraded-mode warning guard (#3922)", () => {
+
+  test("state.ts imports wasDbOpenAttempted from gsd-db", () => {
+    assert.ok(
+      stateSource.includes("wasDbOpenAttempted"),
+      "state.ts must import wasDbOpenAttempted to gate the degraded-mode warning",
     );
   });
+
+  test("degraded-mode warning is inside a wasDbOpenAttempted() guard", () => {
+    // Find the degraded-mode warning string
+    const warningStr = 'DB unavailable — using filesystem state derivation (degraded mode)';
+    const warningIdx = stateSource.indexOf(warningStr);
+    assert.ok(warningIdx > 0, "degraded-mode warning string must exist in state.ts");
+
+    // The wasDbOpenAttempted() check must appear BEFORE the warning,
+    // within the same else-branch (i.e. within a reasonable distance).
+    // Look backwards from the warning for the guard.
+    const searchWindow = stateSource.slice(Math.max(0, warningIdx - 300), warningIdx);
+    assert.ok(
+      searchWindow.includes("wasDbOpenAttempted()"),
+      "wasDbOpenAttempted() guard must appear shortly before the degraded-mode warning " +
+      "to prevent false warnings when DB has not been initialized yet",
+    );
+  });
+
+  test("warning is NOT emitted unconditionally in the else branch", () => {
+    // The old code had `logWarning(...)` directly in the else branch.
+    // The fix wraps it in `if (wasDbOpenAttempted())`.
+    // Verify the logWarning call is inside a conditional, not bare.
+    const lines = stateSource.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      if (lines[i]!.includes("DB unavailable") && lines[i]!.includes("degraded mode")) {
+        // This line has the warning. Check that the preceding non-empty line
+        // contains an if-condition (wasDbOpenAttempted), not a bare else.
+        let prev = i - 1;
+        while (prev >= 0 && lines[prev]!.trim() === "") prev--;
+        const prevLine = lines[prev]!.trim();
+        assert.ok(
+          prevLine.includes("wasDbOpenAttempted"),
+          `Line ${i + 1} emits degraded-mode warning — preceding line ${prev + 1} must ` +
+          `contain wasDbOpenAttempted guard, but found: "${prevLine}"`,
+        );
+        break;
+      }
+    }
+  });
 });