gsd-pi 2.73.1-dev.47ed32a → 2.73.1-dev.49397e5

package/src/resources/extensions/gsd/tests/completed-at-reconcile.test.ts

@@ -0,0 +1,42 @@
+/**
+ * Regression test for #4129: tasks.completed_at stays NULL when status is
+ * reconciled to 'complete' via the file-existence path in state.ts.
+ *
+ * Root cause: reconcileSliceTasks called
+ *   updateTaskStatus(milestoneId, sliceId, t.id, "complete")
+ * without a completedAt timestamp, so the column stays NULL.
+ *
+ * Fix: pass new Date().toISOString() as the 5th argument.
+ */
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const stateSource = readFileSync(join(__dirname, "..", "state.ts"), "utf-8");
+
+describe("completed-at reconcile (#4129)", () => {
+  test("reconcileSliceTasks passes a completedAt timestamp when setting status to complete", () => {
+    // Before the fix, state.ts had:
+    //   updateTaskStatus(milestoneId, sliceId, t.id, "complete")
+    // which leaves completed_at NULL in the DB.
+    // After the fix, a timestamp must be passed as the 5th argument.
+    assert.doesNotMatch(
+      stateSource,
+      /updateTaskStatus\(\s*milestoneId\s*,\s*sliceId\s*,\s*t\.id\s*,\s*["']complete["']\s*\)/,
+      "updateTaskStatus must not be called without a completedAt timestamp when reconciling tasks to 'complete' (#4129)",
+    );
+  });
+
+  test("reconcileSliceTasks passes new Date().toISOString() as the completedAt argument", () => {
+    // Positive assertion: the fixed call must include a timestamp.
+    assert.match(
+      stateSource,
+      /updateTaskStatus\(\s*milestoneId\s*,\s*sliceId\s*,\s*t\.id\s*,\s*["']complete["']\s*,\s*new Date\(\)\.toISOString\(\)\s*\)/,
+      "reconcileSliceTasks must pass new Date().toISOString() as completedAt when setting task status to 'complete' (#4129)",
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/derive-state-crossval.test.ts

@@ -351,8 +351,9 @@ skills_used: []
       const dbState = await deriveStateFromDb(base);
 
       assertStatesEqual(dbState, fileState, 'E-blocked');
-      assert.deepStrictEqual(dbState.phase, 'blocked', 'E-blocked: phase is blocked');
-      assert.ok(dbState.blockers.length > 0, 'E-blocked: has blockers');
+      // With partial-dep fallback, circular deps no longer block — fallback picks first eligible slice
+      assert.deepStrictEqual(dbState.phase, 'planning', 'E-blocked: phase is planning (fallback picks a slice)');
+      assert.ok(dbState.activeSlice !== null, 'E-blocked: activeSlice is set via fallback');
 
       closeDatabase();
     } finally {

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

@@ -616,9 +616,10 @@ describe('derive-state-db', async () => {
       invalidateStateCache();
       const dbState = await deriveStateFromDb(base);
 
-      assert.deepStrictEqual(dbState.phase, 'blocked', 'blocked-db: phase is blocked');
+      // With partial-dep fallback, circular deps no longer block — fallback picks first eligible slice
+      assert.deepStrictEqual(dbState.phase, 'planning', 'blocked-db: phase is planning (fallback picks a slice)');
       assert.deepStrictEqual(dbState.phase, fileState.phase, 'blocked-db: phase matches filesystem');
-      assert.ok(dbState.blockers.length > 0, 'blocked-db: has blockers');
+      assert.ok(dbState.activeSlice !== null, 'blocked-db: activeSlice is set via fallback');
 
       closeDatabase();
     } finally {

package/src/resources/extensions/gsd/tests/derive-state-helpers.test.ts

@@ -307,27 +307,87 @@ describe('derive-state-helpers', () => {
     }
   });
 
-  // ─── buildCompletenessSet: SUMMARY-on-disk marks complete ───────────
-  test('buildCompletenessSet: milestone with SUMMARY on disk treated as complete', async () => {
+  // ─── buildCompletenessSet: DB status is authoritative ──────────────
+  test('buildCompletenessSet: DB status=complete marks milestone complete', async () => {
     const base = createFixtureBase();
     try {
-      // M001 has summary on disk but DB status is still 'active'
       writeFile(base, 'milestones/M001/M001-ROADMAP.md', ROADMAP_CONTENT);
       writeFile(base, 'milestones/M001/M001-SUMMARY.md', '# M001 Summary\n\nDone.');
-      // M002 is the real active milestone
       writeFile(base, 'milestones/M002/M002-CONTEXT.md', '# M002\n\nActive.');
 
       openDatabase(':memory:');
-      insertMilestone({ id: 'M001', title: 'First', status: 'active' });
+      insertMilestone({ id: 'M001', title: 'First', status: 'complete' });
       insertMilestone({ id: 'M002', title: 'Second', status: 'active' });
 
       invalidateStateCache();
       const state = await deriveStateFromDb(base);
 
-      // M001 should be complete (summary on disk), M002 should be active
       const m1 = state.registry.find(e => e.id === 'M001');
-      assert.equal(m1?.status, 'complete', 'summary-disk: M001 marked complete via disk SUMMARY');
-      assert.equal(state.activeMilestone?.id, 'M002', 'summary-disk: M002 is active');
+      assert.equal(m1?.status, 'complete', 'DB status=complete → registry entry complete');
+      assert.equal(state.activeMilestone?.id, 'M002', 'M002 is the active milestone');
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  // ─── Regression #4179: orphan SUMMARY must NOT flip DB-active milestone ───
+  // A crashed complete-milestone turn (or stale/manual SUMMARY.md) can leave
+  // a milestone SUMMARY on disk while the DB row still reads 'active'. The
+  // read-side of state derivation must NOT treat the orphan SUMMARY as a
+  // completion signal, or the auto-loop advances and merges work that was
+  // never actually finished (same failure class as #4175, read-side twin).
+  test('buildCompletenessSet (#4179): orphan SUMMARY on disk does not mark DB-active milestone complete', async () => {
+    const base = createFixtureBase();
+    try {
+      writeFile(base, 'milestones/M001/M001-ROADMAP.md', ROADMAP_CONTENT);
+      writeFile(base, 'milestones/M001/M001-SUMMARY.md', '# M001 Orphan Summary\n\nLeft over from crashed turn.');
+
+      openDatabase(':memory:');
+      insertMilestone({ id: 'M001', title: 'First', status: 'active' });
+      // Slice still in-flight — auto should resume, not merge.
+      insertSlice({ id: 'S01', milestoneId: 'M001', title: 'First', status: 'active', risk: 'low', depends: [] });
+      insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Second', status: 'pending', risk: 'low', depends: ['S01'] });
+      insertTask({ id: 'T01', sliceId: 'S01', milestoneId: 'M001', title: 'In-flight', status: 'pending' });
+
+      invalidateStateCache();
+      const state = await deriveStateFromDb(base);
+
+      const m1 = state.registry.find(e => e.id === 'M001');
+      assert.notEqual(m1?.status, 'complete', 'orphan SUMMARY must not mark milestone complete');
+      assert.equal(m1?.status, 'active', 'M001 remains active — DB is authoritative');
+      assert.equal(state.activeMilestone?.id, 'M001', 'M001 is still the active milestone');
+      assert.notEqual(state.phase, 'completing-milestone', 'must not short-circuit into completion');
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  // Regression #4179 (companion): DB-active milestone with all slices done +
+  // validation terminal + orphan SUMMARY must still flow through completing-milestone
+  // (re-runs complete-milestone), not be reported as already-complete.
+  test('buildRegistryAndFindActive (#4179): orphan SUMMARY with validation-terminal falls through to completing-milestone', async () => {
+    const base = createFixtureBase();
+    try {
+      writeFile(base, 'milestones/M001/M001-ROADMAP.md', ROADMAP_CONTENT);
+      writeFile(base, 'milestones/M001/slices/S01/S01-PLAN.md', PLAN_CONTENT);
+      writeFile(base, 'milestones/M001/slices/S02/S02-PLAN.md', PLAN_CONTENT);
+      writeFile(base, 'milestones/M001/M001-VALIDATION.md', '---\nverdict: passed\n---\n# Validation\nAll good.');
+      writeFile(base, 'milestones/M001/M001-SUMMARY.md', '# M001 Orphan Summary\n\nLeft over.');
+
+      openDatabase(':memory:');
+      insertMilestone({ id: 'M001', title: 'First', status: 'active' });
+      insertSlice({ id: 'S01', milestoneId: 'M001', title: 'First', status: 'complete', risk: 'low', depends: [] });
+      insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Second', status: 'complete', risk: 'low', depends: ['S01'] });
+
+      invalidateStateCache();
+      const state = await deriveStateFromDb(base);
+
+      const m1 = state.registry.find(e => e.id === 'M001');
+      assert.equal(m1?.status, 'active', 'M001 stays active despite orphan SUMMARY + validation-terminal');
+      assert.equal(state.activeMilestone?.id, 'M001', 'M001 is still the active milestone');
+      assert.equal(state.phase, 'completing-milestone', 'phase flows through completing-milestone (re-run)');
     } finally {
       closeDatabase();
       cleanup(base);

package/src/resources/extensions/gsd/tests/derive-state.test.ts

@@ -446,9 +446,9 @@ Continue from step 2.
 
       const state2 = await deriveState(base2);
 
-      assert.deepStrictEqual(state2.phase, 'blocked', 'blocked-B: phase is blocked');
-      assert.deepStrictEqual(state2.activeSlice, null, 'blocked-B: activeSlice is null');
-      assert.ok(state2.blockers.length > 0, 'blocked-B: blockers array is non-empty');
+      // With partial-dep fallback, S01 is picked despite unmet dep on S99
+      assert.deepStrictEqual(state2.phase, 'planning', 'blocked-B: phase is planning (fallback picks S01)');
+      assert.deepStrictEqual(state2.activeSlice?.id, 'S01', 'blocked-B: activeSlice is S01 via fallback');
     } finally {
       cleanup(base2);
     }

package/src/resources/extensions/gsd/tests/extension-bootstrap-isolation.test.ts

@@ -0,0 +1,154 @@
+// Structural contracts for GSD extension bootstrap isolation.
+//
+// The /gsd command must survive failures in the full extension bootstrap
+// (register-extension.ts). This guards against the regression where a
+// Windows-specific import failure in register-shortcuts.ts silently
+// prevented /gsd from being registered at all (#4168, #4172).
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const indexSrc = readFileSync(join(__dirname, "../index.ts"), "utf-8");
+const registerExtSrc = readFileSync(
+  join(__dirname, "../bootstrap/register-extension.ts"),
+  "utf-8",
+);
+
+// ─── index.ts: core /gsd command must be registered before full bootstrap ─────
+
+describe("index.ts bootstrap isolation", () => {
+  test("imports registerGSDCommand from commands/index.js separately", () => {
+    assert.ok(
+      indexSrc.includes('./commands/index.js"') || indexSrc.includes("./commands/index.js'"),
+      "index.ts must import registerGSDCommand from ./commands/index.js",
+    );
+  });
+
+  test("calls registerGSDCommand before importing register-extension.js", () => {
+    const gsdCommandCallPos = indexSrc.indexOf("registerGSDCommand(pi)");
+    const bootstrapImportPos = indexSrc.indexOf(
+      './bootstrap/register-extension.js"',
+    );
+
+    assert.ok(gsdCommandCallPos >= 0, "must call registerGSDCommand(pi)");
+    assert.ok(bootstrapImportPos >= 0, "must import register-extension.js");
+    assert.ok(
+      gsdCommandCallPos < bootstrapImportPos,
+      "registerGSDCommand(pi) must be called BEFORE importing register-extension.js",
+    );
+  });
+
+  test("wraps register-extension.js import in try-catch", () => {
+    // The dynamic import of register-extension.js must be inside a try block
+    const tryPos = indexSrc.indexOf("try {");
+    const bootstrapImportPos = indexSrc.indexOf(
+      './bootstrap/register-extension.js"',
+    );
+    const catchPos = indexSrc.indexOf("catch (err)");
+
+    assert.ok(tryPos >= 0, "must have try block");
+    assert.ok(catchPos >= 0, "must have catch block");
+    assert.ok(
+      tryPos < bootstrapImportPos && bootstrapImportPos < catchPos,
+      "register-extension.js import must be wrapped in try-catch",
+    );
+  });
+
+  test("logs warning on bootstrap failure via workflow-logger", () => {
+    assert.ok(
+      indexSrc.includes("logWarning"),
+      "must use logWarning when bootstrap fails",
+    );
+    assert.ok(
+      indexSrc.includes("Extension setup partially failed"),
+      "warning message must indicate partial failure with /gsd still available",
+    );
+  });
+});
+
+// ─── register-extension.ts: no double-registration + defensive wrapping ───────
+
+describe("register-extension.ts defensive registration", () => {
+  test("does NOT import or call registerGSDCommand (avoids double-registration)", () => {
+    // registerGSDCommand is now called by index.ts, not register-extension.ts
+    assert.ok(
+      !registerExtSrc.includes("import { registerGSDCommand }"),
+      "register-extension.ts must NOT import registerGSDCommand",
+    );
+
+    // Check the function body of registerGsdExtension doesn't call it
+    const funcBodyStart = registerExtSrc.indexOf(
+      "export function registerGsdExtension",
+    );
+    const funcBody = registerExtSrc.slice(funcBodyStart);
+    assert.ok(
+      !funcBody.includes("registerGSDCommand(pi)"),
+      "registerGsdExtension must NOT call registerGSDCommand(pi)",
+    );
+  });
+
+  test("still registers worktree, exit, and kill commands", () => {
+    const funcBodyStart = registerExtSrc.indexOf(
+      "export function registerGsdExtension",
+    );
+    const funcBody = registerExtSrc.slice(funcBodyStart);
+
+    assert.ok(
+      funcBody.includes("registerWorktreeCommand(pi)"),
+      "must register worktree command",
+    );
+    assert.ok(
+      funcBody.includes("registerExitCommand(pi)"),
+      "must register exit command",
+    );
+    assert.ok(
+      funcBody.includes('"kill"'),
+      "must register kill command",
+    );
+  });
+
+  test("wraps non-critical registrations in individual try-catch blocks", () => {
+    const funcBodyStart = registerExtSrc.indexOf(
+      "export function registerGsdExtension",
+    );
+    const funcBody = registerExtSrc.slice(funcBodyStart);
+
+    // Each non-critical registration should be wrapped with error handling
+    const registrationNames = [
+      "dynamic-tools",
+      "db-tools",
+      "journal-tools",
+      "query-tools",
+      "shortcuts",
+      "hooks",
+    ];
+
+    for (const name of registrationNames) {
+      assert.ok(
+        funcBody.includes(`"${name}"`),
+        `non-critical registration "${name}" must be present`,
+      );
+    }
+
+    // Must have try-catch inside the registration loop
+    assert.ok(
+      funcBody.includes("try {") && funcBody.includes("catch (err)"),
+      "must have try-catch for non-critical registrations",
+    );
+  });
+
+  test("logs warning when a non-critical registration fails", () => {
+    assert.ok(
+      registerExtSrc.includes("Failed to register"),
+      "must log descriptive warning for individual registration failures",
+    );
+    assert.ok(
+      registerExtSrc.includes("logWarning"),
+      "must use logWarning from workflow-logger",
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/integration/state-machine-edge-cases.test.ts

@@ -691,7 +691,7 @@ describe("transition boundary failures", () => {
     );
   });
 
-  test("blocked state: all slices have unmet deps → blocked phase", async () => {
+  test("blocked state: all slices have unmet deps → fallback picks slice", async () => {
     base = makeTempDir();
     const mDir = join(base, ".gsd", "milestones", "M001");
     mkdirSync(join(mDir, "slices", "S01", "tasks"), { recursive: true });
@@ -736,7 +736,9 @@ describe("transition boundary failures", () => {
 
     invalidateAllCaches();
     const state = await deriveStateFromDb(base);
-    assert.equal(state.phase, "blocked", "circular deps should produce blocked phase");
+    // With partial-dep fallback, circular deps no longer block — fallback picks first eligible slice
+    assert.equal(state.phase, "planning", "circular deps: fallback picks a slice instead of blocking");
+    assert.ok(state.activeSlice !== null, "activeSlice set via fallback");
   });
 });
 

package/src/resources/extensions/gsd/tests/journal-integration.test.ts

@@ -92,6 +92,7 @@ function makeMockDeps(
     getPriorSliceCompletionBlocker: () => null,
     getMainBranch: () => "main",
     closeoutUnit: async () => {},
+    autoCommitUnit: async () => null,
     recordOutcome: () => {},
     writeLock: () => {},
     captureAvailableSkills: () => {},
@@ -567,7 +568,15 @@ test("unit-end event contains errorContext when unit is cancelled with structure
   const { resolveAgentEndCancelled, _resetPendingResolve } = await import("../auto-loop.js");
   _resetPendingResolve();
 
-  const deps = makeMockDeps(capture);
+  let pauseCalls = 0;
+  let commitCalls = 0;
+  const deps = makeMockDeps(capture, {
+    pauseAuto: async () => { pauseCalls++; },
+    autoCommitUnit: async () => {
+      commitCalls++;
+      return "commit";
+    },
+  });
   const ic = makeIC(deps);
   const iterData: IterationData = {
     unitType: "execute-task",
@@ -593,10 +602,68 @@ test("unit-end event contains errorContext when unit is cancelled with structure
   // Transient timeout cancellations pause (recoverable) instead of hard-stopping
   assert.equal(result.action, "break");
   assert.equal((result as any).reason, "session-timeout");
+  assert.equal(pauseCalls, 1, "timeout cancellations should pause auto-mode exactly once");
+  assert.equal(commitCalls, 1, "timeout cancellations should flush a unit auto-commit once");
 
   // Verify error classification used structured errorContext on the window entry
   const entry = loopState.recentUnits[loopState.recentUnits.length - 1];
   assert.ok(entry.error, "window entry must have error set");
   assert.ok(entry.error!.startsWith("timeout:"), "error must start with category from errorContext");
   assert.ok(entry.error!.includes("Hard timeout error"), "error must include the errorContext message");
+
+  const endEvents = capture.events.filter(e => e.eventType === "unit-end");
+  assert.equal(endEvents.length, 1, "timeout cancellations should still emit unit-end");
+  assert.equal((endEvents[0].data as any).status, "cancelled");
+  assert.equal((endEvents[0].data as any).artifactVerified, false);
+  assert.equal((endEvents[0].data as any).errorContext.category, "timeout");
+});
+
+test("session-failed cancellations close out and emit unit-end before hard stop", async () => {
+  const capture = createEventCapture();
+  const { resolveAgentEndCancelled, _resetPendingResolve } = await import("../auto-loop.js");
+  _resetPendingResolve();
+
+  let closeoutCalls = 0;
+  let commitCalls = 0;
+  let stopCalls = 0;
+  const deps = makeMockDeps(capture, {
+    closeoutUnit: async () => { closeoutCalls++; },
+    autoCommitUnit: async () => {
+      commitCalls++;
+      return "commit";
+    },
+    stopAuto: async () => { stopCalls++; },
+  });
+  const ic = makeIC(deps);
+  const iterData: IterationData = {
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    prompt: "do stuff",
+    finalPrompt: "do stuff",
+    pauseAfterUatDispatch: false,
+    state: { phase: "executing", activeMilestone: { id: "M001" }, activeSlice: { id: "S01" }, registry: [], blockers: [] } as any,
+    mid: "M001",
+    midTitle: "Test",
+    isRetry: false,
+    previousTier: undefined,
+  };
+  const loopState: LoopState = { recentUnits: [{ key: "execute-task/M001/S01/T01" }], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 };
+
+  const unitPromise = runUnitPhase(ic, iterData, loopState);
+  await new Promise(r => setTimeout(r, 50));
+
+  resolveAgentEndCancelled({ message: "session bootstrap exploded", category: "session-failed", isTransient: false });
+
+  const result = await unitPromise;
+  assert.equal(result.action, "break");
+  assert.equal((result as any).reason, "session-failed");
+  assert.equal(closeoutCalls, 1, "session-failed cancellations should close out the unit before stopping");
+  assert.equal(commitCalls, 1, "session-failed cancellations should try one auto-commit flush");
+  assert.equal(stopCalls, 1, "session-failed cancellations should hard-stop auto-mode");
+
+  const endEvents = capture.events.filter(e => e.eventType === "unit-end");
+  assert.equal(endEvents.length, 1, "session-failed cancellations should emit unit-end");
+  assert.equal((endEvents[0].data as any).status, "cancelled");
+  assert.equal((endEvents[0].data as any).artifactVerified, false);
+  assert.equal((endEvents[0].data as any).errorContext.category, "session-failed");
 });

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

@@ -0,0 +1,140 @@
+// native-git-bridge-exec-fallback.test.ts — regression for #4180
+//
+// nativeCommit, nativeIsRepo, and nativeResetHard used execSync() (string
+// command) in their fallback paths. On Windows, execSync spawns cmd.exe which
+// cannot resolve git when Git for Windows is installed via MSYS2/bash but not
+// in cmd.exe's PATH. All other fallback paths in this file use execFileSync()
+// which invokes the binary directly — these three must do the same.
+//
+// Static-analysis tests fail before the fix (source still has execSync calls)
+// and pass after (replaced with execFileSync). Integration tests verify the
+// fallback functions behave correctly on all platforms.
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { 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 } from "../native-git-bridge.js";
+
+// ─── Static analysis ──────────────────────────────────────────────────────
+// Verify the fallback paths of the three affected functions do not call the
+// raw execSync() string-command variant. Replacing all execFileSync( tokens
+// first ensures we match only the bare execSync( form.
+
+const SRC_PATH = join(import.meta.dirname, "..", "native-git-bridge.ts");
+
+function extractFunctionBody(src: string, fnName: string): string {
+  const idx = src.indexOf(`export function ${fnName}`);
+  if (idx === -1) throw new Error(`${fnName} not found in source`);
+  return src.slice(idx, idx + 1500);
+}
+
+function hasRawExecSync(body: string): boolean {
+  const withoutFileSync = body.replace(/execFileSync\(/g, "__FILESYNC__");
+  return withoutFileSync.includes("execSync(");
+}
+
+describe("native-git-bridge #4180: fallback paths use execFileSync not execSync", () => {
+  const src = readFileSync(SRC_PATH, "utf-8");
+
+  test("nativeIsRepo fallback does not use raw execSync", () => {
+    const body = extractFunctionBody(src, "nativeIsRepo");
+    assert.equal(
+      hasRawExecSync(body),
+      false,
+      "nativeIsRepo fallback must use execFileSync to avoid cmd.exe PATH failures on Windows",
+    );
+  });
+
+  test("nativeCommit fallback does not use raw execSync", () => {
+    const body = extractFunctionBody(src, "nativeCommit");
+    assert.equal(
+      hasRawExecSync(body),
+      false,
+      "nativeCommit fallback must use execFileSync to avoid cmd.exe PATH failures on Windows",
+    );
+  });
+
+  test("nativeResetHard fallback does not use raw execSync", () => {
+    const body = extractFunctionBody(src, "nativeResetHard");
+    assert.equal(
+      hasRawExecSync(body),
+      false,
+      "nativeResetHard fallback must use execFileSync to avoid cmd.exe PATH failures on Windows",
+    );
+  });
+});
+
+// ─── Integration tests ────────────────────────────────────────────────────
+// Verify correct runtime behaviour through the fallback path (native module
+// is disabled by default in tests — GSD_ENABLE_NATIVE_GSD_GIT is not set).
+
+function git(args: string[], cwd: string): string {
+  return execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
+}
+
+describe("native-git-bridge #4180: fallback runtime behaviour", () => {
+  let repo: string;
+
+  beforeEach(() => {
+    repo = mkdtempSync(join(tmpdir(), "ngb4180-"));
+    git(["init"], repo);
+    git(["config", "user.email", "test@test.com"], repo);
+    git(["config", "user.name", "Test"], repo);
+    writeFileSync(join(repo, "file.txt"), "initial\n");
+    git(["add", "."], repo);
+    git(["commit", "-m", "init"], repo);
+  });
+
+  afterEach(() => {
+    rmSync(repo, { recursive: true, force: true });
+  });
+
+  test("nativeIsRepo returns true for a valid git repository", () => {
+    assert.equal(nativeIsRepo(repo), true);
+  });
+
+  test("nativeIsRepo returns false for a plain directory", (t) => {
+    const dir = mkdtempSync(join(tmpdir(), "ngb4180-notrepo-"));
+    t.after(() => rmSync(dir, { recursive: true, force: true }));
+    assert.equal(nativeIsRepo(dir), false);
+  });
+
+  test("nativeCommit commits staged changes and returns non-null output", () => {
+    writeFileSync(join(repo, "file.txt"), "modified\n");
+    git(["add", "."], repo);
+
+    const result = nativeCommit(repo, "test: regression commit #4180");
+    assert.ok(result !== null, "should return output string for a successful commit");
+
+    const subject = git(["log", "-1", "--format=%s"], repo);
+    assert.equal(subject, "test: regression commit #4180");
+  });
+
+  test("nativeCommit returns null when nothing is staged", () => {
+    const result = nativeCommit(repo, "test: nothing staged");
+    assert.equal(result, null);
+  });
+
+  test("nativeCommit respects the allowEmpty option", () => {
+    const result = nativeCommit(repo, "test: empty commit #4180", { allowEmpty: true });
+    assert.ok(result !== null, "allow-empty commit should return output");
+
+    const subject = git(["log", "-1", "--format=%s"], repo);
+    assert.equal(subject, "test: empty commit #4180");
+  });
+
+  test("nativeResetHard discards unstaged working tree changes", () => {
+    writeFileSync(join(repo, "file.txt"), "dirty content\n");
+
+    const statusBefore = git(["status", "--short"], repo);
+    assert.ok(statusBefore.length > 0, "repo should be dirty before reset");
+
+    nativeResetHard(repo);
+
+    const content = readFileSync(join(repo, "file.txt"), "utf-8");
+    assert.equal(content, "initial\n", "file should be restored to HEAD content after hard reset");
+  });
+});