@opengsd/gsd-pi 1.2.0-dev.0b870afa → 1.2.0-dev.23d85b63

package/src/resources/extensions/gsd/tests/engine-interfaces-contract.test.ts

@@ -1,10 +1,11 @@
 /**
- * engine-interfaces-contract.test.ts — Source-level contract tests for the
- * engine abstraction layer (S01).
+ * engine-interfaces-contract.test.ts — Runtime and type-level contract tests for
+ * the engine abstraction layer (S01).
  *
- * TypeScript interfaces are erased by --experimental-strip-types, so these
- * tests use source-level regex assertions on the .ts files to verify shapes.
- * Runtime assertions cover AutoSession.activeEngineId and resolveEngine().
+ * TypeScript interfaces are erased by --experimental-strip-types, so shape
+ * contracts are verified by constructing values that satisfy the types and
+ * asserting on their runtime fields. Type-level assertions guard compile-time
+ * contracts; pnpm run typecheck:extensions validates those.
  *
  * Follows the same conventions as auto-session-encapsulation.test.ts.
  */
@@ -15,15 +16,21 @@ import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import type {
+  EngineState,
+  EngineDispatchAction,
+  StepContract,
+  ReconcileResult,
+  RecoveryAction,
+  CloseoutResult,
+  DisplayMetadata,
+} from "../engine-types.js";
+import type { WorkflowEngine } from "../workflow-engine.js";
+import type { ExecutionPolicy } from "../execution-policy.js";
+import type { ResolvedEngine } from "../engine-resolver.js";
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ENGINE_TYPES_PATH = join(__dirname, "..", "engine-types.ts");
-const WORKFLOW_ENGINE_PATH = join(__dirname, "..", "workflow-engine.ts");
-const EXECUTION_POLICY_PATH = join(__dirname, "..", "execution-policy.ts");
-const ENGINE_RESOLVER_PATH = join(__dirname, "..", "engine-resolver.ts");
-
-function readSource(path: string): string {
-  return readFileSync(path, "utf-8");
-}
 
 // ── Import smoke tests ──────────────────────────────────────────────────────
 
@@ -55,9 +62,10 @@ describe("Import smoke tests", () => {
 
 // ── Leaf-node constraint ────────────────────────────────────────────────────
 
+// allow-source-grep: verifies engine-types.ts is a leaf node by design
 describe("Leaf-node constraint", () => {
   test("engine-types.ts has zero imports from GSD modules (only node: allowed)", () => {
-    const source = readSource(ENGINE_TYPES_PATH);
+    const source = readFileSync(ENGINE_TYPES_PATH, "utf-8");
     const lines = source.split("\n");
     const violations: string[] = [];
 
@@ -81,97 +89,111 @@ describe("Leaf-node constraint", () => {
 // ── EngineState shape ───────────────────────────────────────────────────────
 
 describe("EngineState shape", () => {
-  test("EngineState has all required fields with correct types", () => {
-    const source = readSource(ENGINE_TYPES_PATH);
-
-    const requiredFields = [
-      "phase",
-      "currentMilestoneId",
-      "activeSliceId",
-      "activeTaskId",
-      "isComplete",
-      "raw",
-    ];
-
-    for (const field of requiredFields) {
-      assert.ok(
-        source.includes(field),
-        `EngineState must contain field: ${field}`,
-      );
-    }
+  test("EngineState accepts all required fields with correct runtime types", () => {
+    const state: EngineState = {
+      phase: "research",
+      currentMilestoneId: "M001",
+      activeSliceId: "S01",
+      activeTaskId: "T01",
+      isComplete: false,
+      raw: { arbitrary: "engine-specific-state" },
+    };
+
+    assert.equal(state.phase, "research");
+    assert.equal(state.currentMilestoneId, "M001");
+    assert.equal(state.activeSliceId, "S01");
+    assert.equal(state.activeTaskId, "T01");
+    assert.equal(state.isComplete, false);
+    assert.deepEqual(state.raw, { arbitrary: "engine-specific-state" });
+  });
 
-    // raw must be typed unknown — not a GSD-specific type
-    assert.ok(
-      /raw:\s*unknown/.test(source),
-      "EngineState.raw must be typed 'unknown', not a GSD-specific type",
-    );
+  test("EngineState.raw accepts unknown opaque values", () => {
+    const state: EngineState = {
+      phase: "planning",
+      currentMilestoneId: null,
+      activeSliceId: null,
+      activeTaskId: null,
+      isComplete: true,
+      raw: null,
+    };
+
+    assert.equal(state.raw, null);
   });
 });
 
 // ── EngineDispatchAction shape ──────────────────────────────────────────────
 
 describe("EngineDispatchAction shape", () => {
-  test("EngineDispatchAction has dispatch, stop, and skip variants", () => {
-    const source = readSource(ENGINE_TYPES_PATH);
-
-    assert.ok(
-      /action:\s*"dispatch"/.test(source),
-      'EngineDispatchAction must have action: "dispatch" variant',
-    );
-    assert.ok(
-      /action:\s*"stop"/.test(source),
-      'EngineDispatchAction must have action: "stop" variant',
-    );
-    assert.ok(
-      /action:\s*"skip"/.test(source),
-      'EngineDispatchAction must have action: "skip" variant',
-    );
+  test("EngineDispatchAction supports dispatch, stop, and skip variants at runtime", () => {
+    const step: StepContract = {
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+      prompt: "execute the task",
+    };
+
+    const dispatchAction: EngineDispatchAction = { action: "dispatch", step };
+    assert.equal(dispatchAction.action, "dispatch");
+    assert.deepEqual(dispatchAction.step, step);
+
+    const stopAction: EngineDispatchAction = { action: "stop", reason: "blocked", level: "error" };
+    assert.equal(stopAction.action, "stop");
+    assert.equal(stopAction.reason, "blocked");
+    assert.equal(stopAction.level, "error");
+
+    const skipAction: EngineDispatchAction = { action: "skip" };
+    assert.equal(skipAction.action, "skip");
   });
 });
 
 // ── WorkflowEngine interface shape ──────────────────────────────────────────
 
 describe("WorkflowEngine interface shape", () => {
-  test("WorkflowEngine has engineId and all required methods", () => {
-    const source = readSource(WORKFLOW_ENGINE_PATH);
-
-    const requiredMembers = [
-      "engineId",
-      "deriveState",
-      "resolveDispatch",
-      "reconcile",
-      "getDisplayMetadata",
-    ];
-
-    for (const member of requiredMembers) {
-      assert.ok(
-        source.includes(member),
-        `WorkflowEngine must contain member: ${member}`,
-      );
-    }
+  test("WorkflowEngine accepts an object with engineId and all required methods", () => {
+    const engine: WorkflowEngine = {
+      engineId: "test-engine",
+      deriveState: async () => ({
+        phase: "test",
+        currentMilestoneId: null,
+        activeSliceId: null,
+        activeTaskId: null,
+        isComplete: false,
+        raw: null,
+      }),
+      resolveDispatch: async () => ({ action: "skip" }),
+      reconcile: async () => ({ outcome: "continue" }),
+      getDisplayMetadata: () => ({
+        engineLabel: "Test Engine",
+        currentPhase: "test",
+        progressSummary: "testing",
+        stepCount: null,
+      }),
+    };
+
+    assert.equal(engine.engineId, "test-engine");
+    assert.equal(typeof engine.deriveState, "function");
+    assert.equal(typeof engine.resolveDispatch, "function");
+    assert.equal(typeof engine.reconcile, "function");
+    assert.equal(typeof engine.getDisplayMetadata, "function");
   });
 });
 
 // ── ExecutionPolicy interface shape ─────────────────────────────────────────
 
 describe("ExecutionPolicy interface shape", () => {
-  test("ExecutionPolicy has all required methods", () => {
-    const source = readSource(EXECUTION_POLICY_PATH);
-
-    const requiredMethods = [
-      "prepareWorkspace",
-      "selectModel",
-      "verify",
-      "recover",
-      "closeout",
-    ];
-
-    for (const method of requiredMethods) {
-      assert.ok(
-        source.includes(method),
-        `ExecutionPolicy must contain method: ${method}`,
-      );
-    }
+  test("ExecutionPolicy accepts an object with all required methods", () => {
+    const policy: ExecutionPolicy = {
+      prepareWorkspace: async () => {},
+      selectModel: async () => null,
+      verify: async () => "continue",
+      recover: async () => ({ outcome: "retry" } as RecoveryAction),
+      closeout: async () => ({ committed: true, artifacts: [] } as CloseoutResult),
+    };
+
+    assert.equal(typeof policy.prepareWorkspace, "function");
+    assert.equal(typeof policy.selectModel, "function");
+    assert.equal(typeof policy.verify, "function");
+    assert.equal(typeof policy.recover, "function");
+    assert.equal(typeof policy.closeout, "function");
   });
 });
 
@@ -220,12 +242,16 @@ describe("Resolver stub behavior", () => {
     );
   });
 
-  test("ResolvedEngine type is exported (source check)", () => {
-    const source = readSource(ENGINE_RESOLVER_PATH);
-    assert.ok(
-      /export\s+(interface|type)\s+ResolvedEngine/.test(source),
-      "engine-resolver.ts must export ResolvedEngine type",
-    );
+  test("ResolvedEngine type is exported and has the expected shape", () => {
+    // Type-level assertion: ResolvedEngine must be { engine: WorkflowEngine; policy: ExecutionPolicy }.
+    // If the export or shape changes, the typecheck step fails.
+    type _AssertResolvedEngine = ResolvedEngine extends { engine: WorkflowEngine; policy: ExecutionPolicy }
+      ? true
+      : false;
+    const _assertResolvedEngine: true = {} as _AssertResolvedEngine;
+
+    // Runtime sanity check that the import path resolves.
+    assert.ok(_assertResolvedEngine === undefined || true);
   });
 });
 

package/src/resources/extensions/gsd/tests/ensure-db-open.test.ts

@@ -11,7 +11,10 @@ import * as path from 'node:path';
 import * as os from 'node:os';
 import * as fs from 'node:fs';
 import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { closeDatabase, isDbAvailable, getDecisionById, SCHEMA_VERSION, _getAdapter } from '../gsd-db.ts';
+import { formatWorkflowDatabaseOpenFailure } from '../bootstrap/dynamic-tools.ts';
 
 const _require = createRequire(import.meta.url);
 
@@ -288,6 +291,116 @@ function createLegacyV15Db(dbPath: string): void {
 // ═══════════════════════════════════════════════════════════════════════════
 
 describe('ensure-db-open', () => {
+  test('formatWorkflowDatabaseOpenFailure: open failure without provider gives actionable SQLite guidance', () => {
+    const message = formatWorkflowDatabaseOpenFailure(
+      {
+        ok: false,
+        reason: 'open-failed',
+        location: {
+          projectRoot: '/tmp/example',
+          projectGsd: '/tmp/example/.gsd',
+          projectDb: '/tmp/example/.gsd/gsd.db',
+        },
+      },
+      {
+        available: false,
+        provider: null,
+        attempted: true,
+        lastError: null,
+        lastPhase: null,
+      },
+      '22.15.0',
+    );
+
+    assert.match(message, /\/tmp\/example\/\.gsd\/gsd\.db/);
+    assert.match(message, /No SQLite provider available/);
+    assert.match(message, /node:sqlite/);
+    assert.match(message, /better-sqlite3/);
+  });
+
+  test('formatWorkflowDatabaseOpenFailure: old Node includes upgrade guidance', () => {
+    const message = formatWorkflowDatabaseOpenFailure(
+      {
+        ok: false,
+        reason: 'open-failed',
+        location: {
+          projectRoot: '/tmp/example',
+          projectGsd: '/tmp/example/.gsd',
+          projectDb: '/tmp/example/.gsd/gsd.db',
+        },
+      },
+      {
+        available: false,
+        provider: null,
+        attempted: true,
+        lastError: null,
+        lastPhase: null,
+      },
+      '20.11.1',
+    );
+
+    assert.match(message, />= 22\.0\.0/);
+    assert.match(message, /current: v20\.11\.1/);
+  });
+
+  test('ensureDbOpen: source-mode runtime without node:sqlite records actionable guidance', () => {
+    const loaderPath = fileURLToPath(new URL('./resolve-ts.mjs', import.meta.url));
+    const runningFromDistTest = fileURLToPath(import.meta.url).includes(`${path.sep}dist-test${path.sep}`);
+    const dynamicToolsImportUrl = pathToFileURL(
+      path.resolve(
+        runningFromDistTest
+          ? 'dist-test/src/resources/extensions/gsd/bootstrap/dynamic-tools.js'
+          : 'src/resources/extensions/gsd/bootstrap/dynamic-tools.ts',
+      ),
+    ).href;
+    const loggerImportUrl = pathToFileURL(
+      path.resolve(
+        runningFromDistTest
+          ? 'dist-test/src/resources/extensions/gsd/workflow-logger.ts'
+          : 'src/resources/extensions/gsd/workflow-logger.ts',
+      ),
+    ).href;
+    const script = `
+      const fs = require('node:fs');
+      const os = require('node:os');
+      const path = require('node:path');
+      (async () => {
+        const base = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-missing-sqlite-'));
+        try {
+          fs.mkdirSync(path.join(base, '.gsd'), { recursive: true });
+          const dynamicTools = await import(${JSON.stringify(dynamicToolsImportUrl)});
+          const logger = await import(${JSON.stringify(loggerImportUrl)});
+          await dynamicTools.ensureDbOpen(base);
+          const messages = logger.peekLogs().map((entry) => entry.message);
+          console.log(JSON.stringify(messages));
+        } finally {
+          fs.rmSync(base, { recursive: true, force: true });
+        }
+      })().catch((error) => {
+        console.error(error.stack || error.message || String(error));
+        process.exit(1);
+      });
+    `;
+    const result = spawnSync(
+      process.execPath,
+      [
+        '--no-experimental-sqlite',
+        '--import',
+        loaderPath,
+        '--experimental-strip-types',
+        '-e',
+        script,
+      ],
+      { cwd: process.cwd(), encoding: 'utf-8' },
+    );
+
+    assert.equal(result.status, 0, result.stderr);
+    const messages = JSON.parse(result.stdout.trim()) as string[];
+    assert.ok(messages.some((message) => /No SQLite provider available/.test(message)), result.stdout);
+    assert.ok(messages.some((message) => /node:sqlite/.test(message)), result.stdout);
+    assert.ok(messages.some((message) => /better-sqlite3/.test(message)), result.stdout);
+  });
+
   test('ensureDbOpen: creates empty DB without importing Markdown', async () => {
     const tmpDir = makeTmpDir();
     const gsdDir = path.join(tmpDir, '.gsd');

package/src/resources/extensions/gsd/tests/flat-rate-routing-guard.test.ts

@@ -51,6 +51,7 @@ describe("flat-rate provider routing guard (#3453)", () => {
         join(tempProject, ".gsd", "PREFERENCES.md"),
         [
           "---",
+          "token_profile: burn-max",
           "dynamic_routing:",
           "  enabled: true",
           "  tier_models:",
@@ -231,7 +232,7 @@ describe("flat-rate routing opt-in (#4386)", () => {
       mkdirSync(join(tempProject, ".gsd"), { recursive: true });
       writeFileSync(
         join(tempProject, ".gsd", "PREFERENCES.md"),
-        ["---", "version: 1", prefsYaml, "---"].join("\n"),
+        ["---", "version: 1", "token_profile: burn-max", prefsYaml, "---"].join("\n"),
         "utf-8",
       );
       process.env.GSD_HOME = tempGsdHome;

package/src/resources/extensions/gsd/tests/gsd-command-home.test.ts

@@ -3,7 +3,7 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
@@ -11,8 +11,18 @@ import { tmpdir } from "node:os";
 import { buildGsdHomeModel, showGsdHome } from "../gsd-command-home.ts";
 import { buildIdleMenuSummary, detectIdleMilestoneResidueHint } from "../closeout-wizard.ts";
 import { closeDatabase, insertMilestone, openDatabase } from "../gsd-db.ts";
+import { createWorktree } from "../worktree-manager.ts";
 import type { GSDState } from "../types.ts";
 
+function initGitRepo(base: string): void {
+  execFileSync("git", ["init", "-b", "main"], { cwd: base, stdio: "ignore" });
+  execFileSync("git", ["config", "user.name", "Test User"], { cwd: base, stdio: "ignore" });
+  execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: base, stdio: "ignore" });
+  writeFileSync(join(base, "README.md"), "# test\n", "utf-8");
+  execFileSync("git", ["add", "README.md"], { cwd: base, stdio: "ignore" });
+  execFileSync("git", ["commit", "-m", "init"], { cwd: base, stdio: "ignore" });
+}
+
 function baseState(overrides: Partial<GSDState> = {}): GSDState {
   return {
     activeMilestone: { id: "M001", title: "Menu Cleanup" },
@@ -160,13 +170,13 @@ test("detectIdleMilestoneResidueHint reports missing workflow database in a git
 test("detectIdleMilestoneResidueHint matches unique-format milestone ids (M###-abc123)", () => {
   const base = mkdtempSync(join(tmpdir(), "gsd-home-residue-unique-"));
   try {
-    execFileSync("git", ["init", "-b", "main"], { cwd: base, stdio: "ignore" });
-    mkdirSync(join(base, ".gsd-worktrees", "M042-abc123"), { recursive: true });
+    initGitRepo(base);
+    createWorktree(base, "M042-abc123");
     mkdirSync(join(base, ".gsd"), { recursive: true });
 
     openDatabase(join(base, ".gsd", "gsd.db"));
     try {
-      // Closed milestone with lingering worktree dir — classic residue.
+      // Closed milestone with a live git worktree still registered — classic residue.
       insertMilestone({ id: "M042-abc123", title: "Closed Unique", status: "complete" });
       const hint = detectIdleMilestoneResidueHint(base);
       assert.ok(hint, "unique-format closed milestone with worktree should be detected");
@@ -180,12 +190,35 @@ test("detectIdleMilestoneResidueHint matches unique-format milestone ids (M###-a
   }
 });
 
+test("detectIdleMilestoneResidueHint prunes bg-shell ghost dirs and does not warn", () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-home-residue-ghost-"));
+  try {
+    initGitRepo(base);
+    const ghostDir = join(base, ".gsd-worktrees", "M009");
+    mkdirSync(join(ghostDir, ".bg-shell"), { recursive: true });
+    writeFileSync(join(ghostDir, ".bg-shell", "manifest.json"), "[]\n", "utf-8");
+    mkdirSync(join(base, ".gsd"), { recursive: true });
+
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    try {
+      insertMilestone({ id: "M009", title: "Search Tasks", status: "complete" });
+      const hint = detectIdleMilestoneResidueHint(base);
+      assert.equal(hint, null, "bg-shell-only ghost worktree dir must not trigger residue hint");
+      assert.equal(existsSync(ghostDir), false, "ghost worktree dir should be auto-pruned");
+    } finally {
+      closeDatabase();
+    }
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
 test("detectIdleMilestoneResidueHint ignores in-flight milestones with worktree artifacts", () => {
   const base = mkdtempSync(join(tmpdir(), "gsd-home-residue-active-"));
   try {
-    execFileSync("git", ["init", "-b", "main"], { cwd: base, stdio: "ignore" });
-    mkdirSync(join(base, ".gsd-worktrees", "M001"), { recursive: true });
-    mkdirSync(join(base, ".gsd-worktrees", "M002-abc123"), { recursive: true });
+    initGitRepo(base);
+    createWorktree(base, "M001");
+    createWorktree(base, "M002-abc123");
     mkdirSync(join(base, ".gsd"), { recursive: true });
 
     openDatabase(join(base, ".gsd", "gsd.db"));

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

@@ -41,7 +41,9 @@ import {
   refreshOpenDatabaseFromDisk,
   tryCreateMemoriesFts,
   _isLikelyWslDrvFsPathForTest,
+  _shouldAttemptVacuumRecoveryForTest,
 } from '../gsd-db.ts';
+import { MigrationBackupError } from '../db-migration-backup.ts';
 import { _resetLogs, peekLogs, setStderrLoggingEnabled } from '../workflow-logger.ts';
 
 const _require = createRequire(import.meta.url);
@@ -539,6 +541,23 @@ describe('gsd-db', () => {
     cleanup(dbPath);
   });
 
+  test('gsd-db: migration backup errors bypass malformed-DB VACUUM recovery', () => {
+    assert.equal(
+      _shouldAttemptVacuumRecoveryForTest(
+        true,
+        new MigrationBackupError('database disk image is malformed during backup'),
+      ),
+      false,
+    );
+    assert.equal(
+      _shouldAttemptVacuumRecoveryForTest(
+        true,
+        new Error('database disk image is malformed'),
+      ),
+      true,
+    );
+  });
+
   test('gsd-db: pre-v18 DB with memory_sources missing scope opens without crash (issue #4607)', () => {
     // Regression: initSchema() ran CREATE INDEX on memories.scope and
     // memory_sources.scope unconditionally, before the v18 migration adds those

package/src/resources/extensions/gsd/tests/guided-dispatch-root.test.ts

@@ -11,6 +11,7 @@ import {
   _dispatchWorkflowForTest,
   resolveGuidedDispatchProjectRoot,
 } from "../guided-flow.ts";
+import { getRequiredWorkflowToolsForUnit } from "../unit-tool-contracts.ts";
 
 test("guided dispatch falls back to cwd only when no project root is supplied", () => {
   const cwd = process.cwd();
@@ -115,6 +116,7 @@ test("guided dispatch accepts workflow MCP tools absent from parent active tool
       getProviderAuthMode: () => "externalCli",
     },
     ui: {
+      setStatus: () => {},
       notify: (message: string) => {
         notifications.push(message);
       },
@@ -130,8 +132,22 @@ test("guided dispatch accepts workflow MCP tools absent from parent active tool
     "write",
   ];
 
+  // The workflow MCP server registers its tools out of band, so the unit's
+  // required workflow tools show up in the registered tool snapshot
+  // (getAllTools) under the MCP server prefix without ever entering the parent
+  // session's active tool surface (getActiveTools). This is exactly the shape
+  // the readiness gate must accept. Derive the surface from the unit contract
+  // so this test stays correct if discuss-milestone's required tools change.
+  const registeredTools = [
+    ...activeTools,
+    ...getRequiredWorkflowToolsForUnit("discuss-milestone").map(
+      (tool) => `mcp__gsd-workflow__${tool}`,
+    ),
+  ];
+
   const pi = {
     getActiveTools: () => [...activeTools],
+    getAllTools: () => registeredTools.map((name) => ({ name })),
     setActiveTools: (tools: string[]) => {
       activeTools = [...tools];
     },

package/src/resources/extensions/gsd/tests/integration/auto-worktree-milestone-merge.test.ts

@@ -23,6 +23,7 @@ import {
   createAutoWorktree,
   mergeMilestoneToMain,
   getAutoWorktreeOriginalBase,
+  _setRestoreEntryFnForTests,
 } from "../../auto-worktree.ts";
 import { getSliceBranchName } from "../../worktree.ts";
 import { nativeMergeSquash } from "../../native-git-bridge.ts";
@@ -1012,4 +1013,78 @@ describe("auto-worktree-milestone-merge", { timeout: 300_000 }, () => {
     assert.ok(!existsSync(join(repo, ".gsd", ".milestone-shelter")), "shelter removed on successful restore");
     assert.ok(result.commitMessage.length > 0, "merge completed");
   });
+
+  // #2505 log coverage: when the per-entry shelter restore throws (here via the
+  // _setRestoreEntryFnForTests seam — the only deterministic way to reach this
+  // path, since shelter + restore run synchronously in one merge call), the
+  // merge must log a `worktree` ERROR naming the entry (auto-worktree.ts:1809),
+  // emit a retention warning (:1816), and PRESERVE the shelter dir so the
+  // queued milestone files (whose on-disk sources were deleted during the
+  // shelter step) remain recoverable. The existing #2505 test only covered the
+  // success path; this pins the failure-path log + the data-loss guard.
+  test("#2505 logs: shelter restore failure logs a worktree error and retains the shelter", () => {
+    const repo = freshRepo();
+    const wtPath = createAutoWorktree(repo, "M210");
+
+    addSliceToMilestone(repo, wtPath, "M210", "S01", "Feature", [
+      { file: "feature.ts", content: "export const f = 1;\n", message: "add feature" },
+    ]);
+
+    // Seed a queued (non-target) milestone that will be sheltered then restored.
+    const queuedDir = join(repo, ".gsd", "milestones", "M211");
+    mkdirSync(queuedDir, { recursive: true });
+    writeFileSync(join(queuedDir, "CONTEXT.md"), "# queued\n");
+
+    const roadmap = makeRoadmap("M210", "Milestone w/ failing restore", [
+      { id: "S01", title: "Feature" },
+    ]);
+
+    // Inject a restore entry fn that always throws, forcing the best-effort
+    // failure path. restoreDefault() is invoked in finally so no other test in
+    // the process observes the injected behavior.
+    const restoreDefault = _setRestoreEntryFnForTests(() => {
+      throw new Error("forced restore failure");
+    });
+
+    const previousStderr = setStderrLoggingEnabled(false);
+    let logs: ReturnType<typeof drainLogs> = [];
+    try {
+      mergeMilestoneToMain(repo, "M210", roadmap);
+      logs = drainLogs();
+    } finally {
+      setStderrLoggingEnabled(previousStderr);
+      restoreDefault();
+    }
+
+    const worktreeLogs = logs.filter((e) => e.component === "worktree");
+
+    const restoreError = worktreeLogs.find(
+      (e) => e.severity === "error" && /shelter restore failed/u.test(e.message),
+    );
+    assert.ok(
+      restoreError,
+      "a worktree ERROR must be logged when the shelter restore fails (got: " +
+        worktreeLogs.map((e) => e.message).join(" | ") + ")",
+    );
+    assert.match(
+      restoreError!.message,
+      /shelter restore failed \(M211\)/u,
+      "the error must name the unrestored milestone entry",
+    );
+    assert.match(
+      restoreError!.message,
+      /forced restore failure/u,
+      "the error must carry the underlying restore failure detail",
+    );
+
+    // #2505 data-loss guard: the shelter must survive so files stay recoverable.
+    assert.ok(
+      worktreeLogs.some((e) => /shelter retained/u.test(e.message)),
+      "a retention warning must be logged when a restore entry fails",
+    );
+    assert.ok(
+      existsSync(join(repo, ".gsd", ".milestone-shelter")),
+      "the shelter dir must be retained when a restore entry fails",
+    );
+  });
 });