gsd-pi 2.80.0 → 2.81.0

package/src/resources/extensions/gsd/tests/note-captures-executed.test.ts

@@ -6,41 +6,45 @@
  * adds a filter for classification === "note" and calls markCaptureExecuted
  * for each matching capture.
  *
- * Structural verification test — reads source to confirm the note filter
- * and markCaptureExecuted call exist.
+ * Behavior test — resolved note captures should be marked executed without
+ * dispatching inject/replan work.
  */
 
 import { describe, test } from 'node:test';
 import assert from 'node:assert/strict';
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-const source = readFileSync(join(__dirname, '..', 'triage-resolution.ts'), 'utf-8');
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { loadAllCaptures } from '../captures.ts';
+import { executeTriageResolutions } from '../triage-resolution.ts';
 
 describe('note captures executed in triage resolution (#3578)', () => {
-  test('markCaptureExecuted is imported', () => {
-    assert.match(source, /markCaptureExecuted/,
-      'markCaptureExecuted should be imported');
-  });
+  test('resolved note captures are stamped executed', () => {
+    const base = mkdtempSync(join(tmpdir(), 'gsd-note-capture-'));
+    try {
+      mkdirSync(join(base, '.gsd'), { recursive: true });
+      writeFileSync(join(base, '.gsd', 'CAPTURES.md'), [
+        '# Captures',
+        '',
+        '### cap-note',
+        '**Text:** Remember this',
+        '**Captured:** 2026-01-01T00:00:00.000Z',
+        '**Status:** resolved',
+        '**Classification:** note',
+        '**Resolution:** informational only',
+        '**Resolved:** 2026-01-01T00:01:00.000Z',
+        '',
+      ].join('\n'));
 
-  test('note classification filter exists', () => {
-    assert.match(source, /classification\s*===\s*"note"/,
-      'filter should check classification === "note"');
-  });
-
-  test('note filter checks resolved status and not-executed', () => {
-    assert.match(source, /status\s*===\s*"resolved"\s*&&\s*!c\.executed\s*&&\s*c\.classification\s*===\s*"note"/,
-      'filter should check resolved + not-executed + note classification');
-  });
+      const result = executeTriageResolutions(base, 'M001', 'S01');
+      const [capture] = loadAllCaptures(base);
 
-  test('markCaptureExecuted is called for note captures', () => {
-    // The source should call markCaptureExecuted for note captures
-    const noteSection = source.slice(source.indexOf('classification === "note"'));
-    assert.match(noteSection, /markCaptureExecuted\(basePath,\s*cap\.id\)/,
-      'markCaptureExecuted should be called for note captures');
+      assert.equal(result.injected, 0);
+      assert.equal(result.replanned, 0);
+      assert.ok(result.actions.some((action) => action.includes('Note acknowledged: cap-note')));
+      assert.equal(capture?.executed, true);
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
   });
 });

package/src/resources/extensions/gsd/tests/notification-store.test.ts

@@ -19,6 +19,7 @@ import {
   onNotificationStoreChange,
   _resetNotificationStore,
 } from "../notification-store.js";
+import { resolveNotificationStoreBasePath } from "../bootstrap/register-hooks.js";
 
 describe("notification-store", () => {
   let tmp: string;
@@ -243,6 +244,13 @@ describe("notification-store", () => {
     rmSync(tmp2, { recursive: true, force: true });
   });
 
+  test("session notification base resolves auto-worktree paths to project root", () => {
+    const worktreePath = join(tmp, ".gsd", "worktrees", "M001");
+    mkdirSync(worktreePath, { recursive: true });
+
+    assert.equal(resolveNotificationStoreBasePath(worktreePath), tmp);
+  });
+
   test("counters resync from disk after markAllRead", () => {
     initNotificationStore(tmp);
     appendNotification("msg1", "info");

package/src/resources/extensions/gsd/tests/notification-widget.test.ts

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 
 import { initNotificationStore, appendNotification, _resetNotificationStore } from "../notification-store.js";
-import { buildNotificationWidgetLines } from "../notification-widget.js";
+import { buildNotificationWidgetLines, initNotificationWidget, _resetNotificationWidgetForTests } from "../notification-widget.js";
 
 test("buildNotificationWidgetLines shows unread count with shortcut pair", () => {
   const tmp = mkdtempSync(join(tmpdir(), "gsd-notification-widget-"));
@@ -27,3 +27,42 @@ test("buildNotificationWidgetLines shows unread count with shortcut pair", () =>
     rmSync(tmp, { recursive: true, force: true });
   }
 });
+
+test("initNotificationWidget replaces prior interval and store subscription", () => {
+  const tmp = mkdtempSync(join(tmpdir(), "gsd-notification-widget-"));
+  const firstStatuses: Array<string | undefined> = [];
+  const secondStatuses: Array<string | undefined> = [];
+  try {
+    mkdirSync(join(tmp, ".gsd"), { recursive: true });
+    _resetNotificationStore();
+    _resetNotificationWidgetForTests();
+    initNotificationStore(tmp);
+    appendNotification("Need attention", "warning");
+
+    const firstCleanup = initNotificationWidget({
+      hasUI: true,
+      ui: { setStatus: (_key: string, value: string | undefined) => firstStatuses.push(value) },
+    } as any);
+    initNotificationWidget({
+      hasUI: true,
+      ui: { setStatus: (_key: string, value: string | undefined) => secondStatuses.push(value) },
+    } as any);
+
+    const firstCountAfterReplace = firstStatuses.length;
+    firstCleanup();
+    assert.equal(firstStatuses.length, firstCountAfterReplace, "stale cleanup must not clear the replaced status chip");
+
+    appendNotification("Need follow-up", "warning");
+
+    assert.equal(
+      firstStatuses.length,
+      firstCountAfterReplace,
+      "replaced widget must not receive store-change refreshes",
+    );
+    assert.match(secondStatuses.at(-1) ?? "", /2 unread/);
+  } finally {
+    _resetNotificationWidgetForTests();
+    _resetNotificationStore();
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/originalbase-path-comparison.test.ts

@@ -34,12 +34,43 @@ import {
 } from "../auto-worktree.ts";
 import { normalizeWorktreePathForCompare } from "../worktree-root.ts";
 import {
-  WorktreeResolver,
-  type WorktreeResolverDeps,
+  WorktreeLifecycle,
+  type WorktreeLifecycleDeps,
   type NotifyCtx,
-} from "../worktree-resolver.ts";
+} from "../worktree-lifecycle.ts";
+import { WorktreeStateProjection } from "../worktree-state-projection.ts";
+import { resolveWorktreeProjectRoot } from "../worktree-root.ts";
 import { AutoSession } from "../auto/session.ts";
 
+// Test-local: LegacyTestDeps had three fields Lifecycle does not need
+// (shouldUseWorktreeIsolation, syncWorktreeStateBack, captureIntegrationBranch).
+// Permit them in test fixtures so existing override patterns keep working —
+// Lifecycle ignores the extras via structural typing.
+type LegacyTestDeps = WorktreeLifecycleDeps & {
+  shouldUseWorktreeIsolation?: () => boolean;
+  syncWorktreeStateBack?: (
+    mainBasePath: string,
+    worktreePath: string,
+    milestoneId: string,
+  ) => { synced: string[] };
+  captureIntegrationBranch?: (basePath: string, mid: string | undefined) => void;
+};
+
+/** Shim factory preserving the legacy WorktreeResolver throw shape for tests. */
+function makeResolver(s: AutoSession, deps: LegacyTestDeps) {
+  const lifecycle = new WorktreeLifecycle(s, deps);
+  return {
+    get workPath(): string { return s.basePath; },
+    get projectRoot(): string {
+      return resolveWorktreeProjectRoot(s.basePath, s.originalBasePath);
+    },
+    mergeAndExit: (mid: string, ctx: NotifyCtx) => {
+      const r = lifecycle.exitMilestone(mid, { merge: true }, ctx);
+      if (!r.ok && r.cause instanceof Error) throw r.cause;
+    },
+  };
+}
+
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
 function git(args: string[], cwd: string): void {
@@ -69,10 +100,10 @@ function makeSession(overrides?: Partial<{ basePath: string; originalBasePath: s
 
 interface CallLog { fn: string; args: unknown[] }
 
-function makeDeps(overrides?: Partial<WorktreeResolverDeps>): WorktreeResolverDeps & { calls: CallLog[] } {
+function makeDeps(overrides?: Partial<LegacyTestDeps>): LegacyTestDeps & { calls: CallLog[] } {
   const calls: CallLog[] = [];
 
-  const deps: WorktreeResolverDeps & { calls: CallLog[] } = {
+  const deps: LegacyTestDeps & { calls: CallLog[] } = {
     calls,
     isInAutoWorktree: (basePath: string) => {
       calls.push({ fn: "isInAutoWorktree", args: [basePath] });
@@ -110,6 +141,9 @@ function makeDeps(overrides?: Partial<WorktreeResolverDeps>): WorktreeResolverDe
       calls.push({ fn: "getCurrentBranch", args: [basePath] });
       return "main";
     },
+    checkoutBranch: (basePath: string, branch: string) => {
+      calls.push({ fn: "checkoutBranch", args: [basePath, branch] });
+    },
     autoWorktreeBranch: (milestoneId: string) => `milestone/${milestoneId}`,
     resolveMilestoneFile: (basePath: string, milestoneId: string, fileType: string) => {
       calls.push({ fn: "resolveMilestoneFile", args: [basePath, milestoneId, fileType] });
@@ -121,11 +155,12 @@ function makeDeps(overrides?: Partial<WorktreeResolverDeps>): WorktreeResolverDe
     },
     GitServiceImpl: class {
       constructor(_basePath: string, _gitConfig: unknown) {}
-    } as unknown as WorktreeResolverDeps["GitServiceImpl"],
+    } as unknown as LegacyTestDeps["GitServiceImpl"],
     loadEffectiveGSDPreferences: () => ({ preferences: { git: {} } }),
     invalidateAllCaches: () => { calls.push({ fn: "invalidateAllCaches", args: [] }); },
-    captureIntegrationBranch: (_basePath: string, _mid: string) => {},
+    captureIntegrationBranch: (_basePath: string, _mid: string | undefined) => {},
     enterBranchModeForMilestone: (_basePath: string, _milestoneId: string) => {},
+    worktreeProjection: new WorktreeStateProjection(),
     ...overrides,
   };
 
@@ -270,7 +305,7 @@ describe("WorktreeResolver: roadmap-fallback skipped when basePath is same physi
     // Override calls ref so we can inspect it directly
     (deps as unknown as { calls: CallLog[] }).calls = calls;
 
-    const resolver = new WorktreeResolver(s, deps);
+    const resolver = makeResolver(s, deps);
     const ctx = makeNotifyCtx();
 
     // mergeAndExit → _mergeWorktreeMode
@@ -316,7 +351,7 @@ describe("WorktreeResolver: roadmap-fallback skipped when basePath is same physi
     });
     (deps as unknown as { calls: CallLog[] }).calls = calls;
 
-    const resolver = new WorktreeResolver(s, deps);
+    const resolver = makeResolver(s, deps);
     const ctx = makeNotifyCtx();
 
     resolver.mergeAndExit("M002", ctx);

package/src/resources/extensions/gsd/tests/orphan-merge-bootstrap.test.ts

@@ -0,0 +1,144 @@
+// GSD-2 + src/resources/extensions/gsd/tests/orphan-merge-bootstrap.test.ts
+// Regression: bootstrap must actively merge orphan completed-but-unmerged
+// milestones, not just seed `s.currentMilestoneId` (the seed approach was
+// silently overwritten at auto-start.ts:948 — caught in audit of PR #5549).
+//
+// After ADR-016 / slice 7 step E, _mergeOrphanCompletedMilestone takes a
+// WorktreeLifecycle and inspects the typed ExitResult instead of catching
+// a throw — the fakeLifecycle below returns {ok:false, cause} to model the
+// previous throw shape.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { _mergeOrphanCompletedMilestone } from "../auto-start.js";
+import type { WorktreeLifecycle } from "../worktree-lifecycle.js";
+
+interface FakeLifecycleState {
+  mergeCalls: Array<{ milestoneId: string }>;
+  causeOnFail?: unknown;
+}
+
+function fakeLifecycle(state: FakeLifecycleState): WorktreeLifecycle {
+  return {
+    exitMilestone: (milestoneId: string) => {
+      state.mergeCalls.push({ milestoneId });
+      if (state.causeOnFail !== undefined) {
+        return { ok: false, reason: "teardown-failed", cause: state.causeOnFail };
+      }
+      return { ok: true, merged: true, codeFilesChanged: false };
+    },
+  } as unknown as WorktreeLifecycle;
+}
+
+interface FakeUiState {
+  notifications: Array<{ message: string; level: string }>;
+}
+
+function fakeUi(state: FakeUiState): {
+  notify: (msg: string, level?: "info" | "warning" | "error" | "success") => void;
+} {
+  return {
+    notify: (message: string, level?: "info" | "warning" | "error" | "success") => {
+      state.notifications.push({ message, level: level ?? "info" });
+    },
+  };
+}
+
+test("happy path: orphan merge runs, returns merged:true, emits info notify", () => {
+  const lcState: FakeLifecycleState = { mergeCalls: [] };
+  const uiState: FakeUiState = { notifications: [] };
+  const result = _mergeOrphanCompletedMilestone(
+    fakeLifecycle(lcState),
+    "M002",
+    fakeUi(uiState),
+  );
+
+  assert.deepEqual(result, { merged: true });
+  assert.deepEqual(lcState.mergeCalls, [{ milestoneId: "M002" }]);
+  assert.equal(uiState.notifications.length, 1);
+  assert.deepEqual(uiState.notifications[0], {
+    message: "Detected unmerged completed milestone M002. Merging now.",
+    level: "info",
+  });
+});
+
+test("regression: failure from exitMilestone (e.g. wrong-branch from PR #5549 commit 5) does not bubble out", () => {
+  // Commit 5 (68ef58a3c) made `_mergeBranchMode` throw on wrong branch
+  // instead of silently returning false. Lifecycle now wraps the throw in
+  // {ok:false, cause}; _mergeOrphanCompletedMilestone must surface that as
+  // a notify, never re-throwing into the slash-command caller.
+  const boom = new Error("dirty working tree blocks checkout");
+  const lcState: FakeLifecycleState = { mergeCalls: [], causeOnFail: boom };
+  const uiState: FakeUiState = { notifications: [] };
+
+  const result = _mergeOrphanCompletedMilestone(
+    fakeLifecycle(lcState),
+    "M002",
+    fakeUi(uiState),
+  );
+
+  assert.equal(result.merged, false);
+  assert.equal(result.error, boom);
+
+  // First notify announces the merge attempt; second notify reports the failure.
+  assert.equal(uiState.notifications.length, 2);
+  assert.equal(uiState.notifications[0].level, "info");
+  assert.equal(uiState.notifications[1].level, "warning");
+  assert.match(
+    uiState.notifications[1].message,
+    /Could not merge orphan milestone M002/,
+  );
+  assert.match(uiState.notifications[1].message, /dirty working tree blocks checkout/);
+  assert.match(uiState.notifications[1].message, /Resolve manually/);
+});
+
+test("non-Error failure causes are still captured and notified", () => {
+  // Defensive: non-Error causes (strings, numbers) must not crash the formatter.
+  const lcState: FakeLifecycleState = {
+    mergeCalls: [],
+    // mimic a non-Error cause
+    causeOnFail: "git lock held",
+  };
+  const uiState: FakeUiState = { notifications: [] };
+
+  const result = _mergeOrphanCompletedMilestone(
+    fakeLifecycle(lcState),
+    "M002",
+    fakeUi(uiState),
+  );
+
+  assert.equal(result.merged, false);
+  assert.equal(uiState.notifications[1].level, "warning");
+  assert.match(uiState.notifications[1].message, /git lock held/);
+});
+
+test("the exitMilestone call receives a notify-bound NotifyCtx the lifecycle can invoke", () => {
+  // The lifecycle's NotifyCtx must be wired to ui.notify so user-facing
+  // messages from inside exitMilestone (e.g. "Milestone Mxxx merged") still
+  // reach the UI. Verify by having the fake invoke ctx.notify.
+  const uiState: FakeUiState = { notifications: [] };
+  const ui = fakeUi(uiState);
+
+  const lifecycle = {
+    exitMilestone: (
+      _milestoneId: string,
+      _opts: { merge: boolean },
+      ctx: { notify: (msg: string, level?: "info" | "warning" | "error" | "success") => void },
+    ) => {
+      ctx.notify("inner success message", "success");
+      return { ok: true, merged: true, codeFilesChanged: false };
+    },
+  } as unknown as WorktreeLifecycle;
+
+  const result = _mergeOrphanCompletedMilestone(lifecycle, "M002", ui);
+
+  assert.equal(result.merged, true);
+  // 1: outer "Detected unmerged completed milestone..."
+  // 2: inner "inner success message" emitted via the bound ctx.notify
+  assert.equal(uiState.notifications.length, 2);
+  assert.deepEqual(uiState.notifications[1], {
+    message: "inner success message",
+    level: "success",
+  });
+});

package/src/resources/extensions/gsd/tests/orphan-stash-audit.test.ts

@@ -0,0 +1,201 @@
+// GSD-2 + src/resources/extensions/gsd/tests/orphan-stash-audit.test.ts
+// Regression: orphaned gsd-preflight-stash entries from completed milestones
+// must be auto-applied at startup so the user's pre-merge work returns.
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  auditOrphanedPreflightStashes,
+  _isAlreadyRestoredApplyError,
+} from "../orphan-stash-audit.js";
+
+function git(cwd: string, ...args: string[]): string {
+  return execFileSync("git", args, {
+    cwd,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+    env: {
+      ...process.env,
+      GIT_TERMINAL_PROMPT: "0",
+      GIT_AUTHOR_NAME: "test",
+      GIT_AUTHOR_EMAIL: "test@example.com",
+      GIT_COMMITTER_NAME: "test",
+      GIT_COMMITTER_EMAIL: "test@example.com",
+    },
+  });
+}
+
+function pushPreflightStash(repo: string, milestoneId: string, fileName: string, content: string): string {
+  writeFileSync(join(repo, fileName), content);
+  const marker = `gsd-preflight-stash:${milestoneId}:42:1700000000000:abcd`;
+  git(repo, "stash", "push", "--include-untracked", "-m", `gsd-preflight-stash [${marker}]`);
+  return marker;
+}
+
+describe("auditOrphanedPreflightStashes", () => {
+  let repo: string;
+
+  beforeEach(() => {
+    repo = mkdtempSync(join(tmpdir(), "orphan-stash-audit-"));
+    git(repo, "init", "-q");
+    git(repo, "config", "user.email", "test@example.com");
+    git(repo, "config", "user.name", "test");
+    writeFileSync(join(repo, "seed.txt"), "seed\n");
+    git(repo, "add", "seed.txt");
+    git(repo, "commit", "-q", "-m", "initial");
+  });
+
+  afterEach(() => {
+    if (repo && existsSync(repo)) {
+      rmSync(repo, { recursive: true, force: true });
+    }
+  });
+
+  test("returns empty result when there are no stashes", () => {
+    const result = auditOrphanedPreflightStashes(repo, () => true);
+    assert.deepEqual(result, { applied: [], warnings: [] });
+  });
+
+  test("applies an orphan preflight stash when its milestone is complete", () => {
+    pushPreflightStash(repo, "M002", "leftover.txt", "lost work\n");
+
+    // Verify the file is gone (stashed away) before the audit runs.
+    assert.equal(existsSync(join(repo, "leftover.txt")), false, "stash push must remove the file");
+
+    const result = auditOrphanedPreflightStashes(repo, (id) => id === "M002");
+
+    assert.equal(result.applied.length, 1, "expected exactly one stash applied");
+    assert.equal(result.applied[0].milestoneId, "M002");
+    assert.match(result.applied[0].stashRef, /^stash@\{\d+\}$/);
+    assert.equal(result.warnings.length, 0);
+
+    // The user's pre-merge content must be back in the working tree.
+    assert.equal(existsSync(join(repo, "leftover.txt")), true);
+    assert.equal(readFileSync(join(repo, "leftover.txt"), "utf-8"), "lost work\n");
+
+    // The stash entry must remain (apply, not pop) so the user has a backup.
+    const list = git(repo, "stash", "list");
+    assert.match(list, /gsd-preflight-stash:M002:/);
+  });
+
+  test("ignores stashes whose milestone is not complete", () => {
+    pushPreflightStash(repo, "M003", "wip.txt", "still-working\n");
+
+    const result = auditOrphanedPreflightStashes(repo, () => false);
+
+    assert.deepEqual(result, { applied: [], warnings: [] });
+    // File stays stashed.
+    assert.equal(existsSync(join(repo, "wip.txt")), false);
+  });
+
+  test("ignores non-gsd stash entries", () => {
+    writeFileSync(join(repo, "manual.txt"), "manual\n");
+    git(repo, "stash", "push", "--include-untracked", "-m", "user manual stash");
+
+    const result = auditOrphanedPreflightStashes(repo, () => true);
+
+    assert.deepEqual(result, { applied: [], warnings: [] });
+  });
+
+  test("collects a warning when the completion callback throws", () => {
+    pushPreflightStash(repo, "M004", "danger.txt", "boom\n");
+
+    const result = auditOrphanedPreflightStashes(repo, () => {
+      throw new Error("db unavailable");
+    });
+
+    assert.equal(result.applied.length, 0);
+    assert.equal(result.warnings.length, 1);
+    assert.match(result.warnings[0], /Could not determine completion status for M004/);
+    assert.match(result.warnings[0], /db unavailable/);
+  });
+
+  test("collects a warning when stash apply fails (conflicting working tree)", () => {
+    // Push a stash containing a change to seed.txt; then dirty seed.txt with
+    // a conflicting modification before the audit runs so apply fails.
+    writeFileSync(join(repo, "seed.txt"), "stashed\n");
+    const marker = `gsd-preflight-stash:M005:42:1700:zz`;
+    git(repo, "stash", "push", "-m", `gsd-preflight-stash [${marker}]`);
+
+    // Dirty the working tree so apply will conflict.
+    writeFileSync(join(repo, "seed.txt"), "conflicting modification\n");
+
+    const result = auditOrphanedPreflightStashes(repo, () => true);
+
+    assert.equal(result.applied.length, 0);
+    assert.equal(result.warnings.length, 1);
+    assert.match(result.warnings[0], /Could not apply orphaned preflight stash/);
+    assert.match(result.warnings[0], /M005/);
+    assert.match(result.warnings[0], /git stash apply/);
+
+    const list = git(repo, "stash", "list");
+    assert.match(list, /gsd-preflight-stash:M005:/);
+  });
+
+  test("returns empty result when basePath is not a git repo", () => {
+    const nonRepo = mkdtempSync(join(tmpdir(), "orphan-stash-not-repo-"));
+    try {
+      const result = auditOrphanedPreflightStashes(nonRepo, () => true);
+      assert.deepEqual(result, { applied: [], warnings: [] });
+    } finally {
+      rmSync(nonRepo, { recursive: true, force: true });
+    }
+  });
+
+  test("repeat run is a silent no-op when files were already restored (peer-review regression)", () => {
+    // Codex peer review caught: the first audit applies the stash and the
+    // file appears in the working tree. The stash entry stays in `git stash
+    // list` (apply, not pop). On the next audit, `git stash apply` exits
+    // non-zero with "already exists, no checkout" because the untracked file
+    // already exists. The original code surfaced that as a warning every
+    // startup. The fix detects that error and treats it as the idempotent
+    // steady state.
+    pushPreflightStash(repo, "M002", "leftover.txt", "lost work\n");
+
+    const first = auditOrphanedPreflightStashes(repo, () => true);
+    assert.equal(first.applied.length, 1, "first run applies");
+    assert.equal(first.warnings.length, 0);
+
+    const second = auditOrphanedPreflightStashes(repo, () => true);
+    assert.equal(second.applied.length, 0, "second run skips silently");
+    assert.equal(
+      second.warnings.length,
+      0,
+      "second run must NOT warn — files are already restored from first run",
+    );
+  });
+});
+
+test("_isAlreadyRestoredApplyError detects the git stash apply already-exists error", () => {
+  // Real-world stderr produced by git when an --include-untracked stash is
+  // applied while the file already exists in the working tree.
+  const realError: { stderr: string } = {
+    stderr: "leftover.txt already exists, no checkout\nCould not restore untracked files from stash entry\n",
+  };
+  assert.equal(_isAlreadyRestoredApplyError(realError), true);
+
+  // Buffer-form stderr (when encoding is not set explicitly).
+  const bufErr = { stderr: Buffer.from("foo.ts already exists, no checkout\n") };
+  assert.equal(_isAlreadyRestoredApplyError(bufErr), true);
+
+  // Some Node versions surface the message in err.message.
+  const messageOnly = new Error("Command failed: git stash apply\nfoo.ts already exists, no checkout");
+  assert.equal(_isAlreadyRestoredApplyError(messageOnly), true);
+
+  // Unrelated errors must NOT be classified as already-restored.
+  const realConflict: { stderr: string } = {
+    stderr: "CONFLICT (content): Merge conflict in lib/models.ts\n",
+  };
+  assert.equal(_isAlreadyRestoredApplyError(realConflict), false);
+
+  // Defensive null/undefined handling.
+  assert.equal(_isAlreadyRestoredApplyError(null), false);
+  assert.equal(_isAlreadyRestoredApplyError(undefined), false);
+  assert.equal(_isAlreadyRestoredApplyError("not an error"), false);
+  assert.equal(_isAlreadyRestoredApplyError({}), false);
+});