gsd-pi 2.80.0-dev.cf9433f56 → 2.80.0-dev.d4fc28e6b

package/src/resources/extensions/gsd/tests/merge-conflict-stops-loop.test.ts

@@ -70,6 +70,7 @@ function makeDeps(
     getAutoWorktreePath: () => null,
     autoCommitCurrentBranch: () => undefined,
     getCurrentBranch: () => "worktree/M001",
+    checkoutBranch: () => undefined,
     autoWorktreeBranch: (mid: string) => `worktree/${mid}`,
     resolveMilestoneFile: () => null, // no roadmap → early return path
     readFileSync: () => "",

package/src/resources/extensions/gsd/tests/milestone-merge-stash-restore.test.ts

@@ -0,0 +1,242 @@
+// GSD-2 + src/resources/extensions/gsd/tests/milestone-merge-stash-restore.test.ts
+// Regression: postflight stash pop must run even when mergeAndExit throws.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { _runMilestoneMergeWithStashRestore } from "../auto/phases.js";
+import type { IterationContext } from "../auto/types.js";
+import { MergeConflictError } from "../git-service.js";
+import type {
+  PostflightResult,
+  PreflightResult,
+} from "../clean-root-preflight.js";
+
+interface CallLog {
+  preflightCalls: number;
+  mergeCalls: number;
+  postflightCalls: number;
+  stopAutoCalls: Array<string | undefined>;
+  notifyCalls: Array<{ message: string; level: string }>;
+  milestoneMergedInPhases: boolean;
+}
+
+function buildIc(opts: {
+  preflightResult: PreflightResult;
+  mergeBehavior: "succeed" | (() => never);
+  postflightResult: PostflightResult;
+}): { ic: IterationContext; log: CallLog } {
+  const log: CallLog = {
+    preflightCalls: 0,
+    mergeCalls: 0,
+    postflightCalls: 0,
+    stopAutoCalls: [],
+    notifyCalls: [],
+    milestoneMergedInPhases: false,
+  };
+
+  const session = {
+    basePath: "/tmp/proj",
+    originalBasePath: "/tmp/proj",
+    get milestoneMergedInPhases() {
+      return log.milestoneMergedInPhases;
+    },
+    set milestoneMergedInPhases(v: boolean) {
+      log.milestoneMergedInPhases = v;
+    },
+  };
+
+  const ctx = {
+    ui: {
+      notify: (message: string, level: string) => {
+        log.notifyCalls.push({ message, level });
+      },
+    },
+  };
+
+  const deps = {
+    preflightCleanRoot: () => {
+      log.preflightCalls += 1;
+      return opts.preflightResult;
+    },
+    postflightPopStash: () => {
+      log.postflightCalls += 1;
+      return opts.postflightResult;
+    },
+    resolver: {
+      mergeAndExit: () => {
+        log.mergeCalls += 1;
+        if (opts.mergeBehavior !== "succeed") {
+          opts.mergeBehavior();
+        }
+      },
+    },
+    stopAuto: async (_c?: unknown, _p?: unknown, reason?: string) => {
+      log.stopAutoCalls.push(reason);
+    },
+  };
+
+  const ic = {
+    ctx,
+    pi: {},
+    s: session,
+    deps,
+  } as unknown as IterationContext;
+
+  return { ic, log };
+}
+
+const STASH_PUSHED: PreflightResult = {
+  stashPushed: true,
+  stashMarker: "gsd-preflight-stash:M002:42:1700000000000:abc",
+  summary: "Stashed uncommitted changes before merge (milestone M002).",
+};
+
+const STASH_NOT_PUSHED: PreflightResult = {
+  stashPushed: false,
+  summary: "",
+};
+
+const POP_OK: PostflightResult = {
+  restored: true,
+  needsManualRecovery: false,
+  message: "Restored stashed changes after milestone M002 merge.",
+  stashRef: "stash@{0}",
+};
+
+const POP_NEEDS_RECOVERY: PostflightResult = {
+  restored: false,
+  needsManualRecovery: true,
+  message: "git stash pop stash@{0} failed: conflict in lib/models.ts",
+};
+
+test("happy path: merge succeeds and stash is popped", async () => {
+  const { ic, log } = buildIc({
+    preflightResult: STASH_PUSHED,
+    mergeBehavior: "succeed",
+    postflightResult: POP_OK,
+  });
+
+  const result = await _runMilestoneMergeWithStashRestore(ic, "M002");
+
+  assert.equal(result, null, "happy path returns null (loop continues)");
+  assert.equal(log.preflightCalls, 1);
+  assert.equal(log.mergeCalls, 1);
+  assert.equal(log.postflightCalls, 1, "postflight pop must run on success");
+  assert.equal(log.stopAutoCalls.length, 0, "no stopAuto on happy path");
+  assert.equal(log.milestoneMergedInPhases, true, "merge flag set");
+});
+
+test("regression #5538-followup: postflight pop runs even when mergeAndExit throws non-conflict error", async () => {
+  // The original bug: when mergeAndExit threw, the catch block called
+  // stopAuto + return break BEFORE postflight pop ran. The user's
+  // gsd-preflight-stash:M00x stash was orphaned. This test exercises that
+  // exact scenario and asserts the pop is now invoked.
+  const { ic, log } = buildIc({
+    preflightResult: STASH_PUSHED,
+    mergeBehavior: () => {
+      throw new Error("native git merge failed: index lock present");
+    },
+    postflightResult: POP_OK,
+  });
+
+  const result = await _runMilestoneMergeWithStashRestore(ic, "M002");
+
+  assert.deepEqual(result, { action: "break", reason: "merge-failed" });
+  assert.equal(log.mergeCalls, 1);
+  assert.equal(
+    log.postflightCalls,
+    1,
+    "postflight pop must run even on merge failure (was the bug)",
+  );
+  assert.equal(log.stopAutoCalls.length, 1);
+  assert.match(log.stopAutoCalls[0] ?? "", /Merge error on milestone M002/);
+  assert.equal(
+    log.milestoneMergedInPhases,
+    false,
+    "merge flag must NOT be set when merge throws",
+  );
+});
+
+test("regression #5538-followup: postflight pop runs even when mergeAndExit throws MergeConflictError", async () => {
+  const { ic, log } = buildIc({
+    preflightResult: STASH_PUSHED,
+    mergeBehavior: () => {
+      throw new MergeConflictError(
+        ["lib/models.ts", "app/page.tsx"],
+        "squash",
+        "milestone/M002",
+        "main",
+      );
+    },
+    postflightResult: POP_OK,
+  });
+
+  const result = await _runMilestoneMergeWithStashRestore(ic, "M002");
+
+  assert.deepEqual(result, { action: "break", reason: "merge-conflict" });
+  assert.equal(log.mergeCalls, 1);
+  assert.equal(
+    log.postflightCalls,
+    1,
+    "postflight pop must run on merge conflict (was the bug)",
+  );
+  assert.equal(log.stopAutoCalls.length, 1);
+  assert.match(log.stopAutoCalls[0] ?? "", /Merge conflict on milestone M002/);
+});
+
+test("clean tree: no stash to pop, merge succeeds, no pop attempted", async () => {
+  const { ic, log } = buildIc({
+    preflightResult: STASH_NOT_PUSHED,
+    mergeBehavior: "succeed",
+    postflightResult: POP_OK,
+  });
+
+  const result = await _runMilestoneMergeWithStashRestore(ic, "M002");
+
+  assert.equal(result, null);
+  assert.equal(log.postflightCalls, 0, "no pop when nothing was stashed");
+  assert.equal(log.milestoneMergedInPhases, true);
+});
+
+test("merge succeeds but stash pop needs manual recovery -> postflight-stash-restore-failed break", async () => {
+  const { ic, log } = buildIc({
+    preflightResult: STASH_PUSHED,
+    mergeBehavior: "succeed",
+    postflightResult: POP_NEEDS_RECOVERY,
+  });
+
+  const result = await _runMilestoneMergeWithStashRestore(ic, "M002");
+
+  assert.deepEqual(result, {
+    action: "break",
+    reason: "postflight-stash-restore-failed",
+  });
+  assert.equal(log.postflightCalls, 1);
+  assert.equal(log.stopAutoCalls.length, 1);
+  assert.match(
+    log.stopAutoCalls[0] ?? "",
+    /Post-merge stash restore failed for milestone M002/,
+  );
+});
+
+test("merge error is reported even when stash pop also failed (merge-error takes priority)", async () => {
+  const { ic, log } = buildIc({
+    preflightResult: STASH_PUSHED,
+    mergeBehavior: () => {
+      throw new Error("network unreachable during push");
+    },
+    postflightResult: POP_NEEDS_RECOVERY,
+  });
+
+  const result = await _runMilestoneMergeWithStashRestore(ic, "M002");
+
+  assert.deepEqual(result, { action: "break", reason: "merge-failed" });
+  assert.equal(log.postflightCalls, 1, "postflight pop still attempted");
+  assert.equal(log.stopAutoCalls.length, 1, "stopAuto called once, not twice");
+  assert.match(
+    log.stopAutoCalls[0] ?? "",
+    /Merge error/,
+    "stopAuto message reflects merge error, not stash failure",
+  );
+});

package/src/resources/extensions/gsd/tests/native-git-bridge-exec-fallback.test.ts

@@ -12,11 +12,18 @@
 
 import { describe, test, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { chmodSync, mkdtempSync, writeFileSync, readFileSync, rmSync } from "node:fs";
+import { chmodSync, existsSync, mkdtempSync, writeFileSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execFileSync } from "node:child_process";
-import { nativeIsRepo, nativeCommit, nativeResetHard, nativeBranchDelete } from "../native-git-bridge.js";
+import {
+  assertWorktreeMaterialized,
+  nativeBranchDelete,
+  nativeCommit,
+  nativeIsRepo,
+  nativeResetHard,
+  nativeWorktreeAdd,
+} from "../native-git-bridge.js";
 
 // Note: prior static-analysis tests that scanned native-git-bridge.ts for
 // the raw shell-spawn pattern were removed under #4827 — the integration
@@ -115,4 +122,29 @@ describe("native-git-bridge #4180: fallback runtime behaviour", () => {
       /GSD_GIT_ERROR|git branch -D does-not-exist failed/,
     );
   });
+
+  test("assertWorktreeMaterialized rejects directories without a .git file", (t) => {
+    const dir = mkdtempSync(join(tmpdir(), "ngb-worktree-missing-git-"));
+    t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+    assert.throws(
+      () => assertWorktreeMaterialized(dir),
+      /missing \.git file/,
+    );
+  });
+
+  test("nativeWorktreeAdd materializes a valid .git marker", (t) => {
+    const wtPath = join(repo, ".gsd", "worktrees", "M001");
+    t.after(() => {
+      try { git(["worktree", "remove", "--force", wtPath], repo); } catch { /* noop */ }
+    });
+
+    nativeWorktreeAdd(repo, wtPath, "milestone/M001", true, "HEAD");
+
+    assert.equal(
+      existsSync(join(wtPath, ".git")),
+      true,
+      "created worktree must have the .git file required by later health checks",
+    );
+  });
 });

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

@@ -110,6 +110,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] });

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

@@ -0,0 +1,133 @@
+// 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).
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { _mergeOrphanCompletedMilestone } from "../auto-start.js";
+import type { WorktreeResolver } from "../worktree-resolver.js";
+
+interface FakeResolverState {
+  mergeCalls: Array<{ milestoneId: string }>;
+  shouldThrow?: unknown;
+}
+
+function fakeResolver(state: FakeResolverState): WorktreeResolver {
+  return {
+    mergeAndExit: (milestoneId: string) => {
+      state.mergeCalls.push({ milestoneId });
+      if (state.shouldThrow) throw state.shouldThrow;
+    },
+  } as unknown as WorktreeResolver;
+}
+
+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 resolverState: FakeResolverState = { mergeCalls: [] };
+  const uiState: FakeUiState = { notifications: [] };
+  const result = _mergeOrphanCompletedMilestone(
+    fakeResolver(resolverState),
+    "M002",
+    fakeUi(uiState),
+  );
+
+  assert.deepEqual(result, { merged: true });
+  assert.deepEqual(resolverState.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: mergeAndExit throwing (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. If `_mergeOrphanCompletedMilestone`
+  // didn't catch the throw, bootstrap would surface an unhandled exception
+  // to the slash-command caller — the exact regression risk that motivated
+  // wrapping in try/catch.
+  const boom = new Error("dirty working tree blocks checkout");
+  const resolverState: FakeResolverState = { mergeCalls: [], shouldThrow: boom };
+  const uiState: FakeUiState = { notifications: [] };
+
+  const result = _mergeOrphanCompletedMilestone(
+    fakeResolver(resolverState),
+    "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 thrown values are still captured and notified", () => {
+  // Defensive: thrown strings, numbers, etc. must not crash the formatter.
+  const resolverState: FakeResolverState = {
+    mergeCalls: [],
+    // mimic a thrown non-Error value
+    shouldThrow: "git lock held",
+  };
+  const uiState: FakeUiState = { notifications: [] };
+
+  const result = _mergeOrphanCompletedMilestone(
+    fakeResolver(resolverState),
+    "M002",
+    fakeUi(uiState),
+  );
+
+  assert.equal(result.merged, false);
+  assert.equal(result.error, resolverState.shouldThrow);
+  assert.equal(uiState.notifications[1].level, "warning");
+  assert.match(uiState.notifications[1].message, /git lock held/);
+});
+
+test("the mergeAndExit call receives a notify-bound NotifyCtx the resolver can invoke", () => {
+  // The resolver's NotifyCtx must be wired to ui.notify so user-facing
+  // messages from inside mergeAndExit (e.g. "Milestone Mxxx merged") still
+  // reach the UI. Verify by having the fake resolver invoke the ctx.notify.
+  const uiState: FakeUiState = { notifications: [] };
+  const ui = fakeUi(uiState);
+
+  const resolver = {
+    mergeAndExit: (_milestoneId: string, ctx: { notify: (msg: string, level?: "info" | "warning" | "error" | "success") => void }) => {
+      ctx.notify("inner success message", "success");
+    },
+  } as unknown as WorktreeResolver;
+
+  const result = _mergeOrphanCompletedMilestone(resolver, "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);
+});