gsd-pi 2.74.0 → 2.75.0-dev.fd2382b9f

package/src/resources/extensions/gsd/tests/provider-errors.test.ts

@@ -32,6 +32,19 @@ test("classifyError detects rate limit from message", () => {
   assert.equal(result.kind, "rate-limit");
 });
 
+test("classifyError treats Anthropic quota-window phrasing as transient rate-limit (#4373)", () => {
+  const result = classifyError("You've hit your limit · resets soon");
+  assert.ok(isTransient(result));
+  assert.equal(result.kind, "rate-limit");
+  assert.ok("retryAfterMs" in result && result.retryAfterMs === 60_000);
+});
+
+test("classifyError treats usage-limit phrasing as transient rate-limit (#4373)", () => {
+  const result = classifyError("usage limit reached for this workspace");
+  assert.ok(isTransient(result));
+  assert.equal(result.kind, "rate-limit");
+});
+
 test("classifyError treats OpenRouter affordability errors as transient rate-limit class", () => {
   const result = classifyError(
     "402 This request requires more credits, or fewer max_tokens. You requested up to 32000 tokens, but can only afford 329.",
@@ -202,6 +215,10 @@ test("isTransientNetworkError detects DNS errors", () => {
   assert.ok(isTransientNetworkError("dns resolution failed"));
 });
 
+test("isTransientNetworkError detects unexpected EOF", () => {
+  assert.ok(isTransientNetworkError("unexpected EOF"));
+});
+
 test("isTransientNetworkError rejects auth errors", () => {
   assert.ok(!isTransientNetworkError("unauthorized: invalid API key"));
 });
@@ -455,6 +472,22 @@ test("agent-end-recovery.ts resumes transient provider pauses through startAuto
   );
 });
 
+test("agent-end-recovery.ts does not defer rate-limit errors to core retry handler before fallback (#4373)", () => {
+  const src = readFileSync(join(__dirname, "..", "bootstrap", "agent-end-recovery.ts"), "utf-8");
+  assert.ok(
+    src.includes('if (isTransient(cls) && cls.kind !== "rate-limit")'),
+    "rate-limit errors must bypass transient core-retry deferral so fallback can execute (#4373)",
+  );
+});
+
+test("agent-end-recovery.ts updates dashboard dispatched model after fallback switch", () => {
+  const src = readFileSync(join(__dirname, "..", "bootstrap", "agent-end-recovery.ts"), "utf-8");
+  assert.ok(
+    src.includes("setCurrentDispatchedModelId"),
+    "agent-end-recovery.ts should update currentDispatchedModelId when recovery switches model",
+  );
+});
+
 // ── Codex error extraction (#1166) ──────────────────────────────────────────
 
 test("openai-codex-responses.ts extracts nested error fields", () => {
@@ -497,6 +530,16 @@ test("provider-error-resume.ts calls resetTransientRetryState before startAuto",
     resetIdx !== -1 && startIdx !== -1 && resetIdx < startIdx,
     "resetTransientRetryState() must be called before deps.startAuto()",
   );
+  // Session timeout counter must also be reset before startAuto
+  assert.ok(
+    src.includes("resetSessionTimeoutState"),
+    "provider-error-resume.ts must import and call resetSessionTimeoutState",
+  );
+  const sessionResetIdx = src.indexOf("resetSessionTimeoutState()");
+  assert.ok(
+    sessionResetIdx !== -1 && startIdx !== -1 && sessionResetIdx < startIdx,
+    "resetSessionTimeoutState() must be called before deps.startAuto()",
+  );
 });
 
 // ── Fix 2: Session creation timeout treated as transient in phases.ts ───────
@@ -509,9 +552,9 @@ test("phases.ts handles timeout session-creation failures with pause instead of
     src.includes('category === "timeout"'),
     "phases.ts must check category === 'timeout' on transient cancelled unitResults",
   );
-  // Must call pauseAuto (not stopAuto) for timeout cancellations
+  // Must call pauseAuto or pauseAutoForProviderError (not stopAuto) for timeout cancellations
   assert.ok(
-    /category === "timeout"[\s\S]{0,300}pauseAuto/.test(src),
+    /category === "timeout"[\s\S]{0,1200}pauseAuto/.test(src),
     "phases.ts must call pauseAuto for session-timeout failures (not stopAuto or continue)",
   );
   // Must NOT use action: "continue" for transient cancellations (causes infinite loops)
@@ -521,6 +564,51 @@ test("phases.ts handles timeout session-creation failures with pause instead of
   );
 });
 
+// ── Fix 2b: Session creation timeout schedules auto-resume timer ─────────────
+
+test("phases.ts schedules auto-resume timer for session creation timeouts", () => {
+  const src = readFileSync(join(__dirname, "..", "auto", "phases.ts"), "utf-8");
+
+  // Must use pauseAutoForProviderError (not bare pauseAuto) for session-timeout
+  assert.ok(
+    src.includes("pauseAutoForProviderError"),
+    "phases.ts must use pauseAutoForProviderError for session-timeout auto-resume",
+  );
+  // Must schedule resume via resumeAutoAfterProviderDelay
+  assert.ok(
+    src.includes("resumeAutoAfterProviderDelay"),
+    "phases.ts must schedule resume via resumeAutoAfterProviderDelay",
+  );
+  // Must track consecutive session timeouts
+  assert.ok(
+    src.includes("consecutiveSessionTimeouts"),
+    "phases.ts must track consecutive session timeouts for escalating backoff",
+  );
+  // Must cap session timeout auto-resumes
+  assert.ok(
+    /MAX_SESSION_TIMEOUT_AUTO_RESUMES\s*=\s*\d+/.test(src),
+    "phases.ts must cap session timeout auto-resumes",
+  );
+});
+
+test("phases.ts differentiates session creation timeout from unit hard timeout", () => {
+  const src = readFileSync(join(__dirname, "..", "auto", "phases.ts"), "utf-8");
+  assert.ok(
+    src.includes("Session creation timed out"),
+    "phases.ts must check for 'Session creation timed out' message to differentiate from unit hard timeout",
+  );
+});
+
+test("phases.ts resets session timeout counter on successful unit completion", () => {
+  const src = readFileSync(join(__dirname, "..", "auto", "phases.ts"), "utf-8");
+  const resetIdx = src.indexOf("consecutiveSessionTimeouts = 0");
+  const closeoutIdx = src.indexOf("closeoutUnit");
+  assert.ok(
+    resetIdx !== -1 && closeoutIdx !== -1 && resetIdx < closeoutIdx,
+    "consecutiveSessionTimeouts must reset before closeoutUnit (on success path)",
+  );
+});
+
 // ── Fix 3: MAX_TRANSIENT_AUTO_RESUMES raised to 8 ───────────────────────────
 
 test("MAX_TRANSIENT_AUTO_RESUMES is at least 8 for sustained overload resilience", () => {

package/src/resources/extensions/gsd/tests/register-hooks-depth-verification.test.ts

@@ -10,6 +10,7 @@ import {
   resetWriteGateState,
   shouldBlockContextArtifactSave,
 } from "../bootstrap/write-gate.ts";
+import { toRoundResultResponse } from "../../remote-questions/manager.ts";
 
 function makeTempDir(prefix: string): string {
   const dir = join(
@@ -41,7 +42,7 @@ test("register-hooks unlocks milestone depth verification from question id witho
     },
   } as any;
 
-  registerHooks(pi);
+  registerHooks(pi, []);
 
   const questionId = "depth_verification_M001_confirm";
   const questions = [
@@ -95,3 +96,69 @@ test("register-hooks unlocks milestone depth verification from question id witho
     "question-id milestone inference should unlock the matching milestone context write",
   );
 });
+
+test("register-hooks clears depth gate when remote (Telegram/Slack/Discord) answer is normalized (#4406)", async (t) => {
+  const dir = makeTempDir("remote");
+  const originalCwd = process.cwd();
+  process.chdir(dir);
+  resetWriteGateState();
+
+  t.after(() => {
+    resetWriteGateState();
+    process.chdir(originalCwd);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  const handlers = new Map<string, Array<(event: any, ctx?: any) => Promise<void> | void>>();
+  const pi = {
+    on(event: string, handler: (event: any, ctx?: any) => Promise<void> | void) {
+      const existing = handlers.get(event) ?? [];
+      existing.push(handler);
+      handlers.set(event, existing);
+    },
+  } as any;
+
+  registerHooks(pi, []);
+
+  const questionId = "depth_verification_M002_confirm";
+  const questions = [
+    {
+      id: questionId,
+      question: "Do you agree?",
+      options: [
+        { label: "Yes, you got it (Recommended)" },
+        { label: "Needs adjustment" },
+      ],
+    },
+  ];
+
+  for (const handler of handlers.get("tool_call") ?? []) {
+    await handler({ toolName: "ask_user_questions", input: { questions } });
+  }
+  assert.equal(getPendingGate(), questionId);
+
+  // Simulate the normalized response the remote manager now emits:
+  // a Telegram button press returns a RemoteAnswer that is fed through
+  // toRoundResultResponse before reaching details.response.
+  const remoteAnswer = {
+    answers: {
+      [questionId]: { answers: ["Yes, you got it (Recommended)"] },
+    },
+  };
+  const normalized = toRoundResultResponse(remoteAnswer);
+
+  for (const handler of handlers.get("tool_result") ?? []) {
+    await handler({
+      toolName: "ask_user_questions",
+      input: { questions },
+      details: { response: normalized },
+    });
+  }
+
+  assert.equal(getPendingGate(), null, "normalized remote answer must clear the gate");
+  assert.equal(
+    shouldBlockContextArtifactSave("CONTEXT", "M002").block,
+    false,
+    "remote confirmation must unlock the matching milestone context write",
+  );
+});

package/src/resources/extensions/gsd/tests/remote-notification-from-desktop.test.ts

@@ -0,0 +1,107 @@
+/**
+ * remote-notification-from-desktop.test.ts
+ *
+ * Regression guard: sendDesktopNotification must fire sendRemoteNotification
+ * as a fire-and-forget side-effect so that Telegram/Slack/Discord channels
+ * receive the same events as native desktop notifications.
+ *
+ * Testing strategy (structural analysis):
+ *   node:test does not support mock.module without --experimental-test-module-mocks,
+ *   so we use the same source-code structural approach established in this codebase
+ *   (see session-start-footer.test.ts). We read notifications.ts and assert that:
+ *     1. It imports sendRemoteNotification from the remote-questions/notify module.
+ *     2. The sendDesktopNotification function body calls sendRemoteNotification
+ *        with title and message as arguments.
+ *     3. The call uses the void fire-and-forget pattern with a .catch(() => {})
+ *        suppressor so that async failures never break the synchronous caller.
+ *
+ * Relates to #4341.
+ */
+
+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";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SOURCE = readFileSync(join(__dirname, "..", "notifications.ts"), "utf-8");
+
+test("notifications.ts imports sendRemoteNotification from remote-questions/notify", () => {
+  const hasImport =
+    SOURCE.includes('from "../remote-questions/notify.js"') ||
+    SOURCE.includes("from '../remote-questions/notify.js'");
+  assert.ok(
+    hasImport,
+    "notifications.ts must import from '../remote-questions/notify.js'",
+  );
+
+  const importLine = SOURCE.split("\n").find(
+    (line) =>
+      line.includes("sendRemoteNotification") &&
+      (line.includes("remote-questions/notify") || line.includes("remote-questions/notify.js")),
+  );
+  assert.ok(
+    importLine,
+    "The import statement must include sendRemoteNotification from the remote-questions/notify module",
+  );
+});
+
+test("sendDesktopNotification calls sendRemoteNotification(title, message)", () => {
+  // Extract the body of sendDesktopNotification — from its opening brace to the
+  // closing brace at the same indentation level.
+  const fnStart = SOURCE.indexOf("export function sendDesktopNotification(");
+  assert.ok(fnStart > -1, "sendDesktopNotification must be present in notifications.ts");
+
+  // Find the next exported function/const after sendDesktopNotification to bound the search.
+  const nextExportIdx = SOURCE.indexOf("\nexport ", fnStart + 1);
+  const fnBody = nextExportIdx > -1 ? SOURCE.slice(fnStart, nextExportIdx) : SOURCE.slice(fnStart);
+
+  assert.ok(
+    fnBody.includes("sendRemoteNotification"),
+    "sendDesktopNotification must call sendRemoteNotification",
+  );
+
+  assert.ok(
+    fnBody.includes("sendRemoteNotification(title") || fnBody.includes("sendRemoteNotification(title,"),
+    "sendRemoteNotification must be called with title as first argument",
+  );
+});
+
+test("sendRemoteNotification is invoked as void fire-and-forget with .catch(() => {})", () => {
+  const fnStart = SOURCE.indexOf("export function sendDesktopNotification(");
+  const nextExportIdx = SOURCE.indexOf("\nexport ", fnStart + 1);
+  const fnBody = nextExportIdx > -1 ? SOURCE.slice(fnStart, nextExportIdx) : SOURCE.slice(fnStart);
+
+  assert.ok(
+    fnBody.includes("void sendRemoteNotification("),
+    "sendRemoteNotification must be called with void (fire-and-forget)",
+  );
+
+  assert.ok(
+    fnBody.includes(".catch("),
+    "sendRemoteNotification call must be followed by .catch() to suppress unhandled-rejection warnings",
+  );
+});
+
+test("sendRemoteNotification call appears before shouldSendDesktopNotification guard", () => {
+  // Regression guard for the HIGH-severity bug where remote notifications were
+  // gated behind the desktop-notification preference check. Users who disable
+  // desktop notifications must still receive Telegram/Slack/Discord messages.
+  const fnStart = SOURCE.indexOf("export function sendDesktopNotification(");
+  assert.ok(fnStart > -1, "sendDesktopNotification must be present in notifications.ts");
+
+  const nextExportIdx = SOURCE.indexOf("\nexport ", fnStart + 1);
+  const fnBody = nextExportIdx > -1 ? SOURCE.slice(fnStart, nextExportIdx) : SOURCE.slice(fnStart);
+
+  const remoteCallIdx = fnBody.indexOf("sendRemoteNotification(");
+  const guardIdx = fnBody.indexOf("shouldSendDesktopNotification(");
+
+  assert.ok(remoteCallIdx > -1, "sendRemoteNotification must be called inside sendDesktopNotification");
+  assert.ok(guardIdx > -1, "shouldSendDesktopNotification guard must be present inside sendDesktopNotification");
+
+  assert.ok(
+    remoteCallIdx < guardIdx,
+    `sendRemoteNotification (pos ${remoteCallIdx}) must appear BEFORE the shouldSendDesktopNotification guard (pos ${guardIdx}) so that remote channels fire even when desktop notifications are disabled`,
+  );
+});

package/src/resources/extensions/gsd/tests/requirements.test.ts

@@ -95,6 +95,15 @@ describe('requirements', () => {
     assert.ok(report.issues.some(issue => issue.code === "active_requirement_missing_owner"), "doctor flags missing owner");
   });
 
+  // #4414: active_requirement_missing_owner is a planning-hygiene signal,
+  // not a correctness blocker — severity must be warning, not error.
+  test('#4414: active_requirement_missing_owner is a warning, not an error', async () => {
+    const report = await runGSDDoctor(base);
+    const issue = report.issues.find(i => i.code === "active_requirement_missing_owner");
+    assert.ok(issue, "issue is present");
+    assert.equal(issue!.severity, "warning", "severity downgraded so doctor report.ok is not flipped to false");
+  });
+
   after(() => {
     rmSync(base, { recursive: true, force: true });
   });

package/src/resources/extensions/gsd/tests/session-start-footer.test.ts

@@ -0,0 +1,153 @@
+/**
+ * session-start-footer.test.ts
+ *
+ * Verifies that register-hooks.ts suppresses the built-in footer by calling
+ * ctx.ui.setFooter(hideFooter) in both session_start and session_switch when
+ * isAutoActive() is true.
+ *
+ * Testing strategy:
+ *   Two layers:
+ *   1. Source-code regression guard: ensures the guard and setFooter call are
+ *      structurally present in register-hooks.ts for both event handlers.
+ *      (node:test does not support mock.module without --experimental-test-module-mocks,
+ *       so structural analysis is the correct approach here.)
+ *   2. Behavioral integration test: fires the live session_start handler with a
+ *      fake ctx when isAutoActive() is false (its default at test time) and
+ *      confirms setFooter is NOT called — verifying the guard is conditional.
+ *
+ * Relates to #4314.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, readFileSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+import { registerHooks } from "../bootstrap/register-hooks.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const HOOKS_SOURCE = readFileSync(
+  join(__dirname, "..", "bootstrap", "register-hooks.ts"),
+  "utf-8",
+);
+
+// ─── Source-code regression guards ──────────────────────────────────────────
+
+test("register-hooks.ts imports hideFooter from auto-dashboard", () => {
+  assert.ok(
+    HOOKS_SOURCE.includes('import { hideFooter } from "../auto-dashboard.js"') ||
+    HOOKS_SOURCE.includes("import { hideFooter } from '../auto-dashboard.js'"),
+    "register-hooks.ts must import hideFooter from auto-dashboard.js",
+  );
+});
+
+test("session_start handler calls ctx.ui.setFooter(hideFooter) when isAutoActive()", () => {
+  // Locate the session_start handler body (up to the next pi.on call)
+  const sessionStartIdx = HOOKS_SOURCE.indexOf('"session_start"');
+  assert.ok(sessionStartIdx > -1, "session_start handler must exist");
+
+  const sessionSwitchIdx = HOOKS_SOURCE.indexOf('"session_switch"');
+  assert.ok(sessionSwitchIdx > sessionStartIdx, "session_switch handler must follow session_start");
+
+  const sessionStartBody = HOOKS_SOURCE.slice(sessionStartIdx, sessionSwitchIdx);
+
+  assert.ok(
+    sessionStartBody.includes("isAutoActive()"),
+    "session_start handler must call isAutoActive()",
+  );
+  assert.ok(
+    sessionStartBody.includes("ctx.ui.setFooter(hideFooter)"),
+    "session_start handler must call ctx.ui.setFooter(hideFooter)",
+  );
+
+  // Guard must wrap the setFooter call
+  const guardIdx = sessionStartBody.indexOf("isAutoActive()");
+  const setFooterIdx = sessionStartBody.indexOf("ctx.ui.setFooter(hideFooter)");
+  assert.ok(
+    guardIdx < setFooterIdx,
+    "isAutoActive() guard must appear before ctx.ui.setFooter(hideFooter) in session_start",
+  );
+});
+
+test("session_switch handler calls ctx.ui.setFooter(hideFooter) when isAutoActive()", () => {
+  const sessionSwitchIdx = HOOKS_SOURCE.indexOf('"session_switch"');
+  assert.ok(sessionSwitchIdx > -1, "session_switch handler must exist");
+
+  const beforeAgentStartIdx = HOOKS_SOURCE.indexOf('"before_agent_start"');
+  assert.ok(beforeAgentStartIdx > sessionSwitchIdx, "before_agent_start handler must follow session_switch");
+
+  const sessionSwitchBody = HOOKS_SOURCE.slice(sessionSwitchIdx, beforeAgentStartIdx);
+
+  assert.ok(
+    sessionSwitchBody.includes("isAutoActive()"),
+    "session_switch handler must call isAutoActive()",
+  );
+  assert.ok(
+    sessionSwitchBody.includes("ctx.ui.setFooter(hideFooter)"),
+    "session_switch handler must call ctx.ui.setFooter(hideFooter)",
+  );
+
+  const guardIdx = sessionSwitchBody.indexOf("isAutoActive()");
+  const setFooterIdx = sessionSwitchBody.indexOf("ctx.ui.setFooter(hideFooter)");
+  assert.ok(
+    guardIdx < setFooterIdx,
+    "isAutoActive() guard must appear before ctx.ui.setFooter(hideFooter) in session_switch",
+  );
+});
+
+// ─── Behavioral test: setFooter NOT called when auto-mode is inactive ────────
+
+test("session_start does NOT call setFooter when isAutoActive() is false (default)", async (t) => {
+  const dir = join(
+    tmpdir(),
+    `gsd-footer-test-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+  );
+  mkdirSync(dir, { recursive: true });
+
+  const originalCwd = process.cwd();
+  process.chdir(dir);
+  t.after(() => {
+    process.chdir(originalCwd);
+    try { rmSync(dir, { recursive: true, force: true }); } catch { /* best-effort */ }
+  });
+
+  let setFooterCallCount = 0;
+
+  const handlers = new Map<string, (event: unknown, ctx: any) => Promise<void> | void>();
+  const pi = {
+    on(event: string, handler: (event: unknown, ctx: any) => Promise<void> | void) {
+      handlers.set(event, handler);
+    },
+  } as any;
+
+  registerHooks(pi, []);
+
+  const sessionStart = handlers.get("session_start");
+  assert.ok(sessionStart, "session_start handler must be registered");
+
+  await sessionStart!({}, {
+    hasUI: true,
+    ui: {
+      notify: () => {},
+      setStatus: () => {},
+      setFooter: (_footer: unknown) => {
+        setFooterCallCount++;
+      },
+      setWorkingMessage: () => {},
+      onTerminalInput: () => () => {},
+      setWidget: () => {},
+    },
+    sessionManager: { getSessionId: () => null },
+    model: null,
+  } as any);
+
+  // isAutoActive() is false at test time (no auto session started),
+  // so setFooter must not be called.
+  assert.equal(
+    setFooterCallCount,
+    0,
+    "setFooter must NOT be called when isAutoActive() returns false",
+  );
+});

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

@@ -0,0 +1,180 @@
+// Structural invariant: gsd-db.ts is the single writer for .gsd/gsd.db.
+//
+// No file under src/resources/extensions/gsd/ may issue raw write SQL
+// (INSERT/UPDATE/DELETE/REPLACE) or raw transaction control (BEGIN/COMMIT/
+// ROLLBACK via `.exec(...)`) against the engine database. Every bypass must
+// route through a typed wrapper exported from gsd-db.ts.
+//
+// Allowlist:
+// - gsd-db.ts itself — the single writer
+// - unit-ownership.ts — manages a separate .gsd/unit-claims.db for
+//   cross-worktree claim races; intentionally outside this invariant
+// - tests/** — fixtures and direct DB inspection are fair game
+//
+// When this test fails, do not add a new suppression. Instead:
+// 1. Add a typed wrapper to gsd-db.ts that captures the SQL
+// 2. Switch the flagged site to call the wrapper
+//
+// See `.claude/plans/joyful-doodling-pony.md` for the full rationale.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const gsdDir = join(process.cwd(), "src/resources/extensions/gsd");
+
+const ALLOWLIST = new Set([
+  "gsd-db.ts",
+  "unit-ownership.ts",
+]);
+
+/** Walk the gsd extension dir and return all .ts files outside tests/. */
+function walkTsFiles(root: string): string[] {
+  const out: string[] = [];
+  const stack: string[] = [root];
+
+  while (stack.length > 0) {
+    const dir = stack.pop()!;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const ent of entries) {
+      const full = join(dir, ent.name);
+      if (ent.isDirectory()) {
+        // Skip tests/ — fixtures and direct DB inspection are expected there
+        if (ent.name === "tests") continue;
+        stack.push(full);
+        continue;
+      }
+      if (!ent.isFile()) continue;
+      if (!ent.name.endsWith(".ts")) continue;
+      // Skip dotfiles and backup/generated files
+      if (ent.name.startsWith(".")) continue;
+      out.push(full);
+    }
+  }
+
+  return out;
+}
+
+interface Violation {
+  file: string;
+  line: number;
+  snippet: string;
+  kind: string;
+}
+
+// Match .prepare("... INSERT|UPDATE|DELETE|REPLACE ...") in any quoting style.
+const PREPARE_WRITE_RE = /\.prepare\s*\(\s*[`'"][^`'"]*\b(INSERT|UPDATE|DELETE|REPLACE)\b/i;
+
+// Match .exec("... INSERT|UPDATE|DELETE|REPLACE ...") or raw BEGIN/COMMIT/ROLLBACK.
+const EXEC_WRITE_RE = /\.exec\s*\(\s*[`'"][^`'"]*\b(INSERT|UPDATE|DELETE|REPLACE|BEGIN|COMMIT|ROLLBACK)\b/i;
+
+test("no module outside gsd-db.ts issues raw write SQL against the engine DB", () => {
+  const files = walkTsFiles(gsdDir);
+  assert.ok(files.length >= 20, `Expected at least 20 .ts files under gsd/, found ${files.length}`);
+
+  const violations: Violation[] = [];
+
+  for (const abs of files) {
+    const rel = relative(gsdDir, abs);
+    const base = rel.split("/").pop()!;
+    if (ALLOWLIST.has(base)) continue;
+
+    let content: string;
+    try {
+      content = readFileSync(abs, "utf-8");
+    } catch {
+      continue;
+    }
+
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      const prepareMatch = PREPARE_WRITE_RE.exec(line);
+      if (prepareMatch) {
+        violations.push({
+          file: rel,
+          line: i + 1,
+          snippet: line.trim(),
+          kind: `prepare(${prepareMatch[1].toUpperCase()})`,
+        });
+      }
+
+      const execMatch = EXEC_WRITE_RE.exec(line);
+      if (execMatch) {
+        violations.push({
+          file: rel,
+          line: i + 1,
+          snippet: line.trim(),
+          kind: `exec(${execMatch[1].toUpperCase()})`,
+        });
+      }
+    }
+  }
+
+  if (violations.length > 0) {
+    const lines = violations.map(
+      (v) => `  ${v.file}:${v.line} [${v.kind}] — ${v.snippet}`,
+    );
+    assert.fail(
+      `Found ${violations.length} raw write SQL bypass(es) outside gsd-db.ts:\n` +
+        lines.join("\n") +
+        "\n\nEach of these must be replaced with a typed wrapper exported from gsd-db.ts.",
+    );
+  }
+});
+
+test("gsd-db.ts exports the expected single-writer wrappers", async () => {
+  // Positive assertion — fail loudly if the module layout changes so this
+  // structural test can't silently become a no-op.
+  const db = await import("../gsd-db.js");
+
+  const expected = [
+    "deleteDecisionById",
+    "deleteRequirementById",
+    "deleteArtifactByPath",
+    "clearEngineHierarchy",
+    "insertOrIgnoreSlice",
+    "insertOrIgnoreTask",
+    "setSliceReplanTriggeredAt",
+    "upsertQualityGate",
+    "restoreManifest",
+    "bulkInsertLegacyHierarchy",
+    "readTransaction",
+    "insertMemoryRow",
+    "rewriteMemoryId",
+    "updateMemoryContentRow",
+    "incrementMemoryHitCount",
+    "supersedeMemoryRow",
+    "markMemoryUnitProcessed",
+    "decayMemoriesBefore",
+    "supersedeLowestRankedMemories",
+  ];
+
+  for (const name of expected) {
+    assert.ok(
+      typeof (db as Record<string, unknown>)[name] === "function",
+      `gsd-db.ts must export ${name} as a function`,
+    );
+  }
+});
+
+test("the invariant test touches every .ts module under gsd/ (sanity check)", () => {
+  const files = walkTsFiles(gsdDir);
+  // Rough sanity: ensure we're not accidentally walking an empty tree
+  assert.ok(files.length >= 30, `Expected to scan at least 30 .ts files, scanned ${files.length}`);
+
+  // Spot-check a couple of known files that must be included
+  const rels = files.map((f) => relative(gsdDir, f));
+  assert.ok(rels.includes("gsd-db.ts"), "walker must include gsd-db.ts");
+  assert.ok(rels.includes("memory-store.ts"), "walker must include memory-store.ts");
+  assert.ok(rels.includes("workflow-manifest.ts"), "walker must include workflow-manifest.ts");
+});
+