@opengsd/gsd-pi 1.3.0-dev.65546769 → 1.3.0-dev.738160b9

package/src/resources/extensions/gsd/tests/commands-context.test.ts

@@ -101,6 +101,32 @@ test("analyzeSessionContext buckets injections, tool results, and loaded skills"
   assert.equal(result.subagentSpawns, 1);
 });
 
+test("analyzeSessionContext bounds large assistant tool-call arguments", () => {
+  const result = analyzeSessionContext(sessionEntries({
+    role: "assistant",
+    content: [
+      {
+        type: "toolCall",
+        id: "tc-save",
+        name: "gsd_summary_save",
+        arguments: {
+          path: ".gsd/milestones/M001/M001-SUMMARY.md",
+          artifact_type: "SUMMARY",
+          content: "x".repeat(20_000),
+        },
+      },
+    ],
+    timestamp: TS,
+  }), PROVIDER);
+
+  const assistant = result.conversationSections.find((section) => section.label === "Assistant responses");
+  assert.ok(assistant);
+  assert.ok(
+    assistant.tokens < 200,
+    `assistant tool-call arguments should be redacted before token counting, got ${assistant.tokens} tokens`,
+  );
+});
+
 test("formatContextReport lists skills and subagents", () => {
   const report = buildContextBreakdown({
     modelLabel: "claude-code/claude-sonnet-4-6",

package/src/resources/extensions/gsd/tests/commands-gsd-core.test.ts

@@ -460,6 +460,7 @@ describe("Batch 3 prompt templates resolve", () => {
     const out = loadPrompt("code-review", { scope: "s", depth: "deep", fixMode: "off", reviewId: "001" });
     assert.match(out, /deep/);
     assert.match(out, /001/);
+    assert.match(out, /diff-first/i, "code-review prompt should require diff-first context gathering");
   });
   test("review.md loads with target + reviewers", () => {
     const out = loadPrompt("review", { target: "t", reviewers: "claude, codex" });

package/src/resources/extensions/gsd/tests/commands-worktree-clean.test.ts

@@ -1,10 +1,22 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 
 import {
   formatCleanKeepReason,
+  handleWorktree,
   type WorktreeStatus,
 } from "../commands-worktree.ts";
+import { withCommandCwd } from "../commands/context.ts";
+import { createWorktree } from "../worktree-manager.ts";
+import {
+  disableDebug,
+  enableDebug,
+  getDebugCounters,
+} from "../debug-logger.ts";
 
 function mkStatus(over: Partial<WorktreeStatus>): WorktreeStatus {
   const name = over.name ?? "feat-x";
@@ -22,6 +34,45 @@ function mkStatus(over: Partial<WorktreeStatus>): WorktreeStatus {
   };
 }
 
+function git(cwd: string, args: string[]): string {
+  return execFileSync("git", args, {
+    cwd,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+  }).trim();
+}
+
+function makeRepo(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-worktree-command-"));
+  git(base, ["init", "-b", "main"]);
+  git(base, ["config", "user.name", "Test User"]);
+  git(base, ["config", "user.email", "test@example.com"]);
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  writeFileSync(join(base, "README.md"), "# Test\n", "utf-8");
+  git(base, ["add", "."]);
+  git(base, ["commit", "-m", "chore: init"]);
+  return base;
+}
+
+function createCommittedWorktree(base: string, name: string): void {
+  const wt = createWorktree(base, name);
+  writeFileSync(join(wt.path, `${name}.txt`), `${name}\n`, "utf-8");
+  git(wt.path, ["add", "."]);
+  git(wt.path, ["commit", "-m", `feat: ${name}`]);
+}
+
+function createMockCtx() {
+  const notifications: { message: string; level: string }[] = [];
+  return {
+    notifications,
+    ui: {
+      notify(message: string, level: string) {
+        notifications.push({ message, level });
+      },
+    },
+  };
+}
+
 test("clean keep reason shows uncommitted-only worktrees clearly", () => {
   const reason = formatCleanKeepReason(mkStatus({ uncommitted: true }));
   assert.equal(reason, "uncommitted changes");
@@ -46,3 +97,32 @@ test("clean keep reason uses singular form for a single changed file", () => {
   const reason = formatCleanKeepReason(mkStatus({ filesChanged: 1, uncommitted: false }));
   assert.equal(reason, "1 changed file");
 });
+
+test("worktree list detects main branch once for the command", async (t) => {
+  if (process.env.GSD_ENABLE_NATIVE_GSD_GIT === "1") {
+    t.skip("git invocation regression is specific to the CLI fallback path");
+    return;
+  }
+
+  const base = makeRepo();
+  try {
+    createCommittedWorktree(base, "feature-a");
+    createCommittedWorktree(base, "feature-b");
+
+    const ctx = createMockCtx();
+    enableDebug(base);
+    try {
+      await withCommandCwd(base, async () => {
+        await handleWorktree("list", ctx as any);
+      });
+
+      assert.equal(ctx.notifications.length, 1);
+      assert.match(ctx.notifications[0].message, /Worktrees — 2/);
+      assert.equal(getDebugCounters().gitInvocations, 12);
+    } finally {
+      disableDebug();
+    }
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/complete-milestone.test.ts

@@ -312,6 +312,34 @@ console.log('\n=== complete-milestone: incomplete slices block closeout ===');
   cleanup(dbPath);
 }
 
+// ═══════════════════════════════════════════════════════════════════════════
+// complete-milestone: deferred slices are inactive for closeout
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== complete-milestone: deferred slices do not block closeout ===');
+{
+  const dbPath = tempDbPath();
+  openDatabase(dbPath);
+  const { basePath } = createTempProject();
+  seedCompletedMilestone({ basePath, validationVerdict: 'pass' });
+  insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Deferred Slice', status: 'deferred' });
+  insertTask({
+    id: 'T02',
+    sliceId: 'S02',
+    milestoneId: 'M001',
+    status: 'pending',
+    title: 'Deferred Slice Task',
+  });
+
+  const result = await handleCompleteMilestone(makeValidParams(), basePath);
+
+  assertTrue(!('error' in result), 'deferred slice should not block milestone completion');
+  assertEq(getMilestone('M001')!.status, 'complete', 'milestone should complete with deferred inactive slice');
+
+  cleanupDir(basePath);
+  cleanup(dbPath);
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // complete-milestone: deep task check (slice closed, task not)
 // ═══════════════════════════════════════════════════════════════════════════

package/src/resources/extensions/gsd/tests/complete-slice-reopen-handoff.test.ts

@@ -7,6 +7,10 @@ import { join } from "node:path";
 
 import { postUnitPreVerification } from "../auto-post-unit.ts";
 import { AutoSession } from "../auto/session.ts";
+import {
+  decideVerificationRetry,
+  hashVerificationFailureContext,
+} from "../auto/verification-retry-policy.ts";
 import { cleanup, makeTempRepo } from "./test-utils.ts";
 
 function makePostUnitContext(base: string, s: AutoSession, notifications: string[]) {
@@ -227,3 +231,68 @@ test("complete-slice with gsd_replan_slice but no REPLAN artifact retries", asyn
     cleanup(base);
   }
 });
+
+test("artifact retry context stays stable across attempts while notifications show attempt count", async () => {
+  const base = makeTempRepo("gsd-artifact-retry-stable-context-");
+  try {
+    mkdirSync(join(base, ".gsd", "milestones", "M001", "slices", "S01"), { recursive: true });
+
+    const s = new AutoSession();
+    s.active = true;
+    s.basePath = base;
+    s.currentUnit = { type: "complete-slice", id: "M001/S01", startedAt: Date.now() };
+
+    const notifications: string[] = [];
+    const pctx = makePostUnitContext(base, s, notifications);
+    const opts = {
+      skipSettleDelay: true,
+      skipWorktreeSync: true,
+      agentEndMessages: [
+        {
+          role: "toolResult",
+          toolName: "gsd_replan_slice",
+          isError: false,
+          content: "Slice replanned with reopened task T02.",
+        },
+      ],
+    };
+
+    assert.equal(await postUnitPreVerification(pctx, opts), "retry");
+    const firstRetry = s.pendingVerificationRetry;
+    assert.ok(firstRetry);
+    assert.equal(firstRetry.attempt, 1);
+    assert.doesNotMatch(firstRetry.failureContext, /\(attempt \d\/3\)\.$/);
+    const firstFailureHash = hashVerificationFailureContext(firstRetry.failureContext);
+
+    assert.equal(await postUnitPreVerification(pctx, opts), "retry");
+    const secondRetry = s.pendingVerificationRetry;
+    assert.ok(secondRetry);
+    assert.equal(secondRetry.attempt, 2);
+    assert.equal(secondRetry.failureContext, firstRetry.failureContext);
+    assert.equal(hashVerificationFailureContext(secondRetry.failureContext), firstFailureHash);
+    assert.deepEqual(
+      decideVerificationRetry({
+        unitType: s.currentUnit.type,
+        retryInfo: secondRetry,
+        previousFailureHash: firstFailureHash,
+        random: () => 0.5,
+      }),
+      {
+        action: "pause",
+        reason: "duplicate-failure-context",
+        key: "complete-slice:M001/S01",
+        failureHash: firstFailureHash,
+      },
+    );
+    assert.ok(
+      notifications.some((message) => message.includes("Retrying (attempt 1/3).")),
+      `expected first attempt notification, got: ${notifications.join("\n")}`,
+    );
+    assert.ok(
+      notifications.some((message) => message.includes("Retrying (attempt 2/3).")),
+      `expected second attempt notification, got: ${notifications.join("\n")}`,
+    );
+  } finally {
+    cleanup(base);
+  }
+});

package/src/resources/extensions/gsd/tests/complete-slice.test.ts

@@ -203,6 +203,10 @@ console.log('\n=== complete-slice: handler happy path ===');
   insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Second Slice', risk: 'low', depends: ['S01'], demo: 'advanced stuff', sequence: 2 });
   insertTask({ id: 'T01', sliceId: 'S01', milestoneId: 'M001', status: 'complete', title: 'Task 1' });
   insertTask({ id: 'T02', sliceId: 'S01', milestoneId: 'M001', status: 'complete', title: 'Task 2' });
+  insertTask({ id: 'T99', sliceId: 'S02', milestoneId: 'M001', status: 'complete', title: 'Sibling Task' });
+  const siblingSummaryPath = path.join(path.dirname(roadmapPath), 'T99-SUMMARY.md');
+  const siblingSummaryBefore = '# Existing sibling task summary\n\nDo not rewrite this file.\n';
+  fs.writeFileSync(siblingSummaryPath, siblingSummaryBefore);
 
   const params = makeValidSliceParams();
   const result = await handleCompleteSlice(params, basePath);
@@ -267,6 +271,13 @@ console.log('\n=== complete-slice: handler happy path ===');
     // (e) Verify slice status is complete in DB
     assertEq(sliceAfter!.status, 'complete', 'slice status should be complete in DB');
     assertTrue(sliceAfter!.completed_at !== null, 'completed_at should be set in DB');
+
+    // (f) Verify unrelated completed task summaries are not re-rendered during slice completion
+    assertEq(
+      fs.readFileSync(siblingSummaryPath, 'utf-8'),
+      siblingSummaryBefore,
+      'complete-slice should not re-render sibling completed task summaries',
+    );
   }
 
   cleanupDir(basePath);

package/src/resources/extensions/gsd/tests/complete-task-rollback-evidence.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, rmSync, writeFileSync, promises as fsPromises } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
@@ -41,7 +41,7 @@ const VALID_PARAMS = {
   ],
 };
 
-describe("complete-task projection failures keep DB completion committed", () => {
+describe("complete-task projection failures roll back DB completion", () => {
   let base: string;
 
   afterEach(() => {
@@ -75,7 +75,44 @@ describe("complete-task projection failures keep DB completion committed", () =>
     assert.equal(rows.length, 2, "should have 2 evidence rows after success");
   });
 
-  it("keeps task completion and verification_evidence when disk projection write fails", async () => {
+  it("reopens the workflow DB when it disappears between SUMMARY.md write and plan render", async (t) => {
+    base = makeTmpBase();
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    insertMilestone({ id: "M001" });
+    insertSlice({ id: "S01", milestoneId: "M001" });
+
+    const planPath = join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLAN.md");
+    writeFileSync(
+      planPath,
+      "# S01 Plan\n\n## Tasks\n\n- [ ] **T01: Test task**\n",
+    );
+
+    const originalRename = fsPromises.rename.bind(fsPromises);
+    let closedAfterSummaryWrite = false;
+    t.mock.method(fsPromises, "rename", async (...args: Parameters<typeof fsPromises.rename>) => {
+      await originalRename(...args);
+      const target = String(args[1]);
+      if (!closedAfterSummaryWrite && target.endsWith("T01-SUMMARY.md")) {
+        closedAfterSummaryWrite = true;
+        closeDatabase();
+      }
+    });
+
+    const result = await handleCompleteTask(VALID_PARAMS, base);
+    assert.ok(closedAfterSummaryWrite, "test fixture should close DB after SUMMARY.md atomic rename");
+    assert.ok(!("error" in result), `unexpected error: ${"error" in result ? result.error : ""}`);
+
+    const content = readFileSync(planPath, "utf-8");
+    assert.match(content, /\[x\][^\n]*\*\*T01\*\*/, "PLAN.md checkbox should be rendered after DB reopen");
+
+    const adapter = _getAdapter()!;
+    const task = adapter.prepare(
+      `SELECT status FROM tasks WHERE milestone_id = 'M001' AND slice_id = 'S01' AND id = 'T01'`,
+    ).get() as { status: string } | undefined;
+    assert.equal(task?.status, "complete", "task should remain complete after successful projection");
+  });
+
+  it("rolls back DB completion and clears verification_evidence when disk projection write fails", async () => {
     base = makeTmpBase();
     openDatabase(join(base, ".gsd", "gsd.db"));
     insertMilestone({ id: "M001" });
@@ -87,19 +124,22 @@ describe("complete-task projection failures keep DB completion committed", () =>
     writeFileSync(tasksDir, "not-a-directory");
 
     const result = await handleCompleteTask(VALID_PARAMS, base);
-    assert.ok(!("error" in result), `unexpected error: ${"error" in result ? result.error : ""}`);
-    assert.equal(result.stale, true, "result should report stale projection");
+    assert.ok("error" in result, "expected rollback error when projection write fails");
+    assert.ok(
+      (result as { error: string }).error.includes("rolled completion back to pending"),
+      `error should mention rollback; got: ${"error" in result ? result.error : ""}`,
+    );
 
     const adapter = _getAdapter()!;
     const task = adapter.prepare(
       `SELECT status FROM tasks WHERE milestone_id = 'M001' AND slice_id = 'S01' AND id = 'T01'`,
     ).get() as { status: string } | undefined;
-    assert.ok(task, "task row should still exist");
-    assert.equal(task!.status, "complete", "task status should remain complete");
+    assert.ok(task, "task row should still exist after rollback");
+    assert.equal(task!.status, "pending", "task status should be rolled back to pending");
 
     const evidenceRows = adapter.prepare(
       `SELECT * FROM verification_evidence WHERE task_id = 'T01' AND slice_id = 'S01' AND milestone_id = 'M001'`,
     ).all();
-    assert.equal(evidenceRows.length, 2, "verification_evidence should remain committed");
+    assert.equal(evidenceRows.length, 0, "verification_evidence should be deleted after rollback");
   });
 });

package/src/resources/extensions/gsd/tests/complete-task.test.ts

@@ -380,6 +380,81 @@ console.log('\n=== complete-task: handler happy path ===');
   cleanup(dbPath);
 }
 
+// ═══════════════════════════════════════════════════════════════════════════
+// complete-task: Projection failure rolls DB completion back
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== complete-task: projection failure rolls DB completion back ===');
+{
+  const dbPath = tempDbPath();
+  openDatabase(dbPath);
+
+  const { basePath, planPath } = createTempProject();
+
+  insertMilestone({ id: 'M001', title: 'Test Milestone' });
+  insertSlice({ id: 'S01', milestoneId: 'M001', title: 'Test Slice' });
+
+  fs.unlinkSync(planPath);
+  fs.mkdirSync(planPath, { recursive: true });
+
+  const result = await handleCompleteTask(makeValidParams(), basePath);
+
+  assertTrue('error' in result, 'projection failure should return an error');
+  if ('error' in result) {
+    assertMatch(result.error, /projection write failed/, 'error should mention projection write failure');
+  }
+
+  const task = getTask('M001', 'S01', 'T01');
+  assertTrue(task !== null, 'task row should remain for retry');
+  assertEq(task!.status, 'pending', 'task status should be rolled back to pending');
+  assertEq(task!.completed_at, null, 'rolled back task should not keep completed_at');
+
+  const adapter = _getAdapter()!;
+  const evRows = adapter.prepare(
+    "SELECT * FROM verification_evidence WHERE task_id = 'T01' AND slice_id = 'S01' AND milestone_id = 'M001'"
+  ).all();
+  assertEq(evRows.length, 0, 'verification evidence should be deleted when projection rollback runs');
+
+  const summaryPath = path.join(path.dirname(planPath), 'T01-SUMMARY.md');
+  assertTrue(!fs.existsSync(summaryPath), 'SUMMARY.md should be removed so disk state stays pending');
+
+  cleanupDir(basePath);
+  cleanup(dbPath);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// complete-task: Handler does not re-render completed sibling summaries
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== complete-task: handler leaves completed sibling summaries untouched ===');
+{
+  const dbPath = tempDbPath();
+  openDatabase(dbPath);
+
+  const { basePath, planPath } = createTempProject();
+
+  insertMilestone({ id: 'M001', title: 'Test Milestone' });
+  insertSlice({ id: 'S01', milestoneId: 'M001', title: 'Test Slice', risk: 'high', depends: [], demo: 'basic functionality works', sequence: 1 });
+  insertTask({ id: 'T00', sliceId: 'S01', milestoneId: 'M001', status: 'complete', title: 'Already complete task', oneLiner: 'Previously completed' });
+  insertTask({ id: 'T02', sliceId: 'S01', milestoneId: 'M001', status: 'pending', title: 'Second task' });
+
+  const siblingSummaryPath = path.join(path.dirname(planPath), 'T00-SUMMARY.md');
+  const siblingSummaryContent = 'existing sibling summary marker\n';
+  fs.writeFileSync(siblingSummaryPath, siblingSummaryContent);
+
+  const result = await handleCompleteTask(makeValidParams(), basePath);
+
+  assertTrue(!('error' in result), 'handler should succeed without error');
+  assertEq(
+    fs.readFileSync(siblingSummaryPath, 'utf-8'),
+    siblingSummaryContent,
+    'complete-task should not re-render summaries for already-completed sibling tasks',
+  );
+
+  cleanupDir(basePath);
+  cleanup(dbPath);
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // complete-task: hard-blocker escalation with mid-execution escalation disabled
 // ═══════════════════════════════════════════════════════════════════════════

package/src/resources/extensions/gsd/tests/dashboard-overlay.test.ts

@@ -4,9 +4,10 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdirSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import { chmodSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { delimiter, join } from "node:path";
 import { tmpdir } from "node:os";
+import { performance } from "node:perf_hooks";
 
 import { GSDDashboardOverlay } from "../dashboard-overlay.ts";
 import type { UnitMetrics } from "../metrics.ts";
@@ -85,6 +86,58 @@ test("GSDDashboardOverlay non-identity refresh avoids reparsing preferences", as
   );
 });
 
+test("GSDDashboardOverlay render and scroll do not run environment doctor subprocesses", (t) => {
+  const basePath = join(
+    tmpdir(),
+    `gsd-dashboard-overlay-env-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+  );
+  const shimDir = join(
+    tmpdir(),
+    `gsd-dashboard-overlay-shim-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+  );
+  mkdirSync(basePath, { recursive: true });
+  mkdirSync(shimDir, { recursive: true });
+  writeFileSync(join(basePath, "package.json"), JSON.stringify({ engines: { node: ">=22.0.0" } }));
+
+  const posixNodeShim = join(shimDir, "node");
+  writeFileSync(posixNodeShim, "#!/bin/sh\nsleep 1\nexit 1\n");
+  chmodSync(posixNodeShim, 0o755);
+  writeFileSync(join(shimDir, "node.cmd"), "@echo off\r\nping -n 2 127.0.0.1 > nul\r\nexit /b 1\r\n");
+
+  const originalPath = process.env.PATH;
+  const overlay = new GSDDashboardOverlay({ requestRender() {} }, fakeTheme as any, () => {});
+  overlay.dispose();
+
+  t.after(() => {
+    if (originalPath === undefined) {
+      delete process.env.PATH;
+    } else {
+      process.env.PATH = originalPath;
+    }
+    rmSync(basePath, { recursive: true, force: true });
+    rmSync(shimDir, { recursive: true, force: true });
+  });
+
+  (overlay as any).loading = false;
+  (overlay as any).milestoneData = null;
+  (overlay as any).dashData = {
+    ...(overlay as any).dashData,
+    basePath,
+  };
+
+  process.env.PATH = `${shimDir}${delimiter}${originalPath ?? ""}`;
+  const start = performance.now();
+  overlay.render(100);
+  overlay.handleInput("j");
+  overlay.render(100);
+  const elapsed = performance.now() - start;
+
+  assert.ok(
+    elapsed < 500,
+    `rendering and scrolling should not wait for environment subprocesses, took ${Math.round(elapsed)}ms`,
+  );
+});
+
 function makeUnit(id: string, cost: number): UnitMetrics {
   return {
     type: "execute-task",

package/src/resources/extensions/gsd/tests/db-memory-fts-schema.test.ts

@@ -3,11 +3,16 @@
 
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
+import { createRequire } from "node:module";
 import {
+  MEMORIES_FTS_REBUILT_KEY,
   isMemoriesFtsAvailableSchema,
+  rebuildMemoriesFtsSchemaOnce,
   tryCreateMemoriesFtsSchema,
 } from "../db-memory-fts-schema.ts";
-import type { DbAdapter, DbStatement } from "../db-adapter.ts";
+import { createDbAdapter, type DbAdapter, type DbStatement } from "../db-adapter.ts";
+
+const _require = createRequire(import.meta.url);
 
 class FakeStatement implements DbStatement {
   private readonly row: Record<string, unknown> | undefined;
@@ -32,6 +37,7 @@ class FakeStatement implements DbStatement {
 class FakeAdapter implements DbAdapter {
   readonly execCalls: string[] = [];
   hasFts = false;
+  hasRebuildMarker = false;
   failExec = false;
 
   exec(sql: string): void {
@@ -39,13 +45,26 @@ class FakeAdapter implements DbAdapter {
     if (this.failExec) throw new Error("fts unavailable");
   }
 
-  prepare(): DbStatement {
-    return new FakeStatement(this.hasFts ? { name: "memories_fts" } : undefined);
+  prepare(sql: string): DbStatement {
+    if (sql.includes("sqlite_master")) {
+      return new FakeStatement(this.hasFts ? { name: "memories_fts" } : undefined);
+    }
+    if (sql.includes("runtime_kv")) {
+      return new FakeStatement(this.hasRebuildMarker ? { present: 1 } : undefined);
+    }
+    return new FakeStatement(undefined);
   }
 
   close(): void {}
 }
 
+function openMemoryAdapter(): { db: DbAdapter; close: () => void } {
+  const sqlite = _require("node:sqlite") as { DatabaseSync: new (path: string) => unknown };
+  const raw = new sqlite.DatabaseSync(":memory:");
+  const db = createDbAdapter(raw);
+  return { db, close: () => db.close() };
+}
+
 describe("db-memory-fts-schema", () => {
   test("creates memories_fts and insert/delete/update triggers", () => {
     const db = new FakeAdapter();
@@ -83,4 +102,40 @@ describe("db-memory-fts-schema", () => {
     db.hasFts = true;
     assert.equal(isMemoriesFtsAvailableSchema(db), true);
   });
+
+  test("rebuilds the external-content index once and records a marker", () => {
+    const { db, close } = openMemoryAdapter();
+    try {
+      db.exec("CREATE TABLE memories (seq INTEGER PRIMARY KEY AUTOINCREMENT, content TEXT NOT NULL)");
+      db.exec("INSERT INTO memories (content) VALUES ('pre FTS auth memory must be searchable')");
+
+      const ok = tryCreateMemoriesFtsSchema(db);
+      if (!ok) return;
+
+      const before = db.prepare("SELECT rowid FROM memories_fts WHERE memories_fts MATCH 'auth'").all();
+      assert.equal(before.length, 0, "external-content FTS starts empty for existing rows");
+
+      rebuildMemoriesFtsSchemaOnce(db);
+
+      const after = db.prepare("SELECT rowid FROM memories_fts WHERE memories_fts MATCH 'auth'").all();
+      assert.deepEqual(after.map((row) => row["rowid"]), [1]);
+      const marker = db.prepare(
+        "SELECT value_json FROM runtime_kv WHERE scope = 'global' AND scope_id = '' AND key = :key",
+      ).get({ ":key": MEMORIES_FTS_REBUILT_KEY });
+      assert.ok(marker, "rebuild marker should be stored");
+    } finally {
+      close();
+    }
+  });
+
+  test("skips rebuild when marker already exists", () => {
+    const db = new FakeAdapter();
+    db.hasFts = true;
+    db.hasRebuildMarker = true;
+
+    rebuildMemoriesFtsSchemaOnce(db);
+
+    assert.ok(db.execCalls.some((sql) => sql.includes("CREATE TABLE IF NOT EXISTS runtime_kv")));
+    assert.ok(!db.execCalls.some((sql) => sql.includes("VALUES('rebuild')")));
+  });
 });