@opengsd/gsd-pi 1.0.2-dev.867e002 → 1.0.2-dev.88c4dc5

package/src/resources/extensions/gsd/tests/orphaned-worktree-audit.test.ts

@@ -48,20 +48,27 @@ describe("auditOrphanedMilestoneBranches", () => {
     const result = auditOrphanedMilestoneBranches(dir, "worktree");
     assert.deepStrictEqual(result.recovered, []);
     assert.deepStrictEqual(result.warnings, []);
+    assert.deepStrictEqual(result.actions, []);
+    assert.equal(result.blockingStrandedWork, null);
   });
 
-  test("skips in none isolation mode", () => {
-    // Create a milestone branch that would otherwise be detected
+  test("runs in none isolation mode and cleans safe completed residue", () => {
     run("git branch milestone/M001", dir);
     insertMilestone({ id: "M001", title: "Test", status: "complete" });
 
     const result = auditOrphanedMilestoneBranches(dir, "none");
-    assert.deepStrictEqual(result.recovered, []);
+    assert.ok(
+      result.recovered.some((r) => r.includes("Deleted merged branch milestone/M001")),
+      `should clean merged completed residue even in none mode; got: ${JSON.stringify(result.recovered)}`,
+    );
     assert.deepStrictEqual(result.warnings, []);
+    assert.ok(
+      result.actions.some((action) => action.kind === "complete-merged-branch"),
+      "should record structured cleanup action",
+    );
 
-    // Branch should still exist
     const branches = run("git branch --list milestone/M001", dir);
-    assert.ok(branches.includes("milestone/M001"), "branch should be preserved in none mode");
+    assert.equal(branches, "", "safe completed branch should be cleaned in none mode");
   });
 
   test("deletes merged branch for completed milestone", () => {
@@ -149,9 +156,12 @@ describe("auditOrphanedMilestoneBranches", () => {
     // Must surface a warning so the user knows the worktree holds uncollapsed work
     assert.ok(result.warnings.length > 0, "should warn about in-progress orphan");
     assert.ok(
-      result.warnings.some(w => w.includes("milestone/M001") && w.includes("in-progress")),
-      `warning should mention milestone/M001 and in-progress state; got: ${JSON.stringify(result.warnings)}`,
+      result.warnings.some(w => w.includes("Stranded work") && w.includes("milestone/M001") && w.includes("in-progress")),
+      `warning should mention stranded milestone/M001 and in-progress state; got: ${JSON.stringify(result.warnings)}`,
     );
+    assert.equal(result.blockingStrandedWork?.milestoneId, "M001");
+    assert.equal(result.blockingStrandedWork?.recoveryMode, "branch");
+    assert.equal(result.blockingStrandedWork?.commitsAhead, 1);
 
     // Branch must still exist
     const branches = run("git branch --list milestone/M001", dir);
@@ -184,6 +194,53 @@ describe("auditOrphanedMilestoneBranches", () => {
       result.warnings.some(w => w.includes(".gsd/worktrees/M001") || w.includes("worktree")),
       `warning should reference the worktree location; got: ${JSON.stringify(result.warnings)}`,
     );
+    assert.equal(result.blockingStrandedWork?.recoveryMode, "worktree");
+  });
+
+  test("detects dirty in-progress worktree even when branch has no commits ahead", () => {
+    run("git branch milestone/M001", dir);
+
+    const wtDir = join(dir, ".gsd", "worktrees", "M001");
+    mkdirSync(wtDir, { recursive: true });
+    writeFileSync(join(wtDir, ".git"), `gitdir: ${join(dir, ".git", "worktrees", "M001")}\n`);
+    writeFileSync(join(wtDir, "dirty.txt"), "uncommitted work\n");
+
+    insertMilestone({ id: "M001", title: "Test", status: "active" });
+
+    const result = auditOrphanedMilestoneBranches(dir, "worktree", {
+      hasChanges: (basePath) => basePath === wtDir,
+    });
+
+    assert.deepStrictEqual(result.recovered, []);
+    assert.ok(
+      result.warnings.some((w) => w.includes("uncommitted changes")),
+      `dirty worktree should be treated as stranded work; got: ${JSON.stringify(result.warnings)}`,
+    );
+    assert.equal(result.blockingStrandedWork?.milestoneId, "M001");
+    assert.equal(result.blockingStrandedWork?.dirtyWorktree, true);
+    assert.equal(result.blockingStrandedWork?.recoveryMode, "worktree");
+  });
+
+  test("detects dirty in-progress worktree even when milestone branch is absent", () => {
+    const wtDir = join(dir, ".gsd", "worktrees", "M001");
+    mkdirSync(wtDir, { recursive: true });
+    writeFileSync(join(wtDir, ".git"), `gitdir: ${join(dir, ".git", "worktrees", "M001")}\n`);
+    writeFileSync(join(wtDir, "dirty.txt"), "branchless work\n");
+
+    insertMilestone({ id: "M001", title: "Test", status: "active" });
+
+    const result = auditOrphanedMilestoneBranches(dir, "none", {
+      hasChanges: (basePath) => basePath === wtDir,
+    });
+
+    assert.deepStrictEqual(result.recovered, []);
+    assert.ok(
+      result.warnings.some((w) => w.includes("Stranded work") && w.includes("M001")),
+      `branchless dirty worktree should block; got: ${JSON.stringify(result.warnings)}`,
+    );
+    assert.equal(result.blockingStrandedWork?.branch, undefined);
+    assert.equal(result.blockingStrandedWork?.dirtyWorktree, true);
+    assert.equal(result.blockingStrandedWork?.recoveryMode, "worktree");
   });
 
   test("cleans up orphaned worktree directory for merged milestone", () => {
@@ -359,7 +416,7 @@ describe("auditOrphanedMilestoneBranches", () => {
     assert.ok(existsSync(wtDir), "active milestone worktree dir must be preserved");
   });
 
-  test("#5879 — skips branch-less orphan in 'none' isolation mode", () => {
+  test("#5879 — cleans branch-less complete orphan in 'none' isolation mode", () => {
     insertMilestone({ id: "M001", title: "Test", status: "complete" });
 
     const wtDir = join(dir, ".gsd", "worktrees", "M001");
@@ -368,7 +425,10 @@ describe("auditOrphanedMilestoneBranches", () => {
 
     const result = auditOrphanedMilestoneBranches(dir, "none");
 
-    assert.deepStrictEqual(result.recovered, []);
-    assert.ok(existsSync(wtDir), "'none' mode must not touch worktree dirs");
+    assert.ok(
+      result.recovered.some((r) => r.includes("M001") && r.includes("branch already deleted")),
+      `none mode should still clean safe completed residue; got: ${JSON.stringify(result.recovered)}`,
+    );
+    assert.ok(!existsSync(wtDir), "completed orphan worktree dir should be cleaned in none mode");
   });
 });

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

@@ -5,6 +5,7 @@ import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 
 import { visibleWidth } from "@gsd/pi-tui";
+import { assertFullOuterBorder } from "./tui-border-assertions.ts";
 
 function assertLinesFit(lines: string[], width: number): void {
   for (const line of lines) {
@@ -51,6 +52,9 @@ describe("parallel-monitor-overlay", () => {
     const joined = lines.join("\n");
     assert.ok(joined.includes("Parallel Monitor"), "should include title");
     assert.ok(joined.includes("No parallel workers found"), "should show empty state");
+    assertFullOuterBorder(lines, 80);
+    assert.match(lines[0] ?? "", /^╭─ GSD Parallel Monitor /);
+    assert.match(lines.at(-1) ?? "", /^╰─+╯$/);
 
     // Dispose should not throw
     overlay.dispose();
@@ -105,7 +109,9 @@ describe("parallel-monitor-overlay", () => {
     );
 
     for (const width of [40, 80, 120]) {
-      assertLinesFit(overlay.render(width), width);
+      const lines = overlay.render(width);
+      assertLinesFit(lines, width);
+      assertFullOuterBorder(lines, width);
       overlay.invalidate();
     }
 

package/src/resources/extensions/gsd/tests/post-unit-retry-on-orchestrator-bridge.test.ts

@@ -0,0 +1,93 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { mock } from "node:test";
+
+import { postUnitPostVerification, type PostUnitContext } from "../auto-post-unit.ts";
+import { AutoSession } from "../auto/session.ts";
+import { checkPostUnitHooks, resetHookState, resolveHookArtifactPath } from "../post-unit-hooks.ts";
+import { _clearGsdRootCache } from "../paths.ts";
+import { invalidateAllCaches } from "../cache.ts";
+
+function writePreferences(basePath: string): void {
+  const content = `---
+post_unit_hooks:
+  - name: review-arbiter
+    after:
+      - execute-task
+    prompt: Review {taskId}
+    agent: arbiter
+    artifact: REVIEW-DEBATE.md
+    retry_on: NEEDS-REWORK.md
+    max_cycles: 3
+    enabled: true
+---
+`;
+  writeFileSync(join(basePath, ".gsd", "PREFERENCES.md"), content, "utf-8");
+}
+
+test("post-unit retry_on marks trigger unit as retry in orchestrator before redispatch", async () => {
+  const originalCwd = process.cwd();
+  const base = mkdtempSync(join(tmpdir(), "gsd-post-unit-retry-"));
+  const taskDir = join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks");
+  mkdirSync(taskDir, { recursive: true });
+
+  try {
+    process.chdir(base);
+    _clearGsdRootCache();
+    invalidateAllCaches();
+    resetHookState();
+    writePreferences(base);
+
+    const hookDispatch = checkPostUnitHooks("execute-task", "M001/S01/T01", base);
+    assert.ok(hookDispatch, "hook should dispatch for execute-task");
+
+    const retryPath = resolveHookArtifactPath(base, "M001/S01/T01", "NEEDS-REWORK.md");
+    writeFileSync(retryPath, "rework requested", "utf-8");
+
+    const retryActiveUnit = mock.fn(async (_unit: { unitType: string; unitId: string }) => {});
+    const s = new AutoSession();
+    s.basePath = base;
+    s.active = true;
+    s.currentUnit = { type: "hook/review-arbiter", id: "M001/S01/T01", startedAt: Date.now() };
+    s.orchestration = {
+      start: async () => ({ kind: "started" }),
+      advance: async () => ({ kind: "stopped", reason: "unused" }),
+      completeActiveUnit: async () => {},
+      retryActiveUnit,
+      resume: async () => ({ kind: "resumed" }),
+      stop: async (reason: string) => ({ kind: "stopped", reason }),
+      getStatus: () => ({ phase: "running", transitionCount: 0 }),
+    };
+
+    const pctx: PostUnitContext = {
+      s,
+      ctx: {
+        ui: { notify: () => {}, setStatus: () => {}, setWidget: () => {}, setFooter: () => {} },
+        model: { id: "test-model" },
+      } as any,
+      pi: { sendMessage: async () => {}, setModel: async () => true } as any,
+      buildSnapshotOpts: () => ({}),
+      lockBase: () => base,
+      stopAuto: async () => {},
+      pauseAuto: async () => {},
+      updateProgressWidget: () => {},
+    };
+
+    const result = await postUnitPostVerification(pctx);
+    assert.equal(result, "continue");
+    assert.equal(retryActiveUnit.mock.callCount(), 1);
+    assert.deepEqual(retryActiveUnit.mock.calls[0]?.arguments[0], {
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+    });
+  } finally {
+    process.chdir(originalCwd);
+    resetHookState();
+    invalidateAllCaches();
+    _clearGsdRootCache();
+    rmSync(base, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/queue-reorder-ui.test.ts

@@ -2,6 +2,7 @@ import { describe, test } from "node:test";
 import assert from "node:assert/strict";
 
 import { showQueueReorder } from "../queue-reorder-ui.ts";
+import { assertFullOuterBorder } from "./tui-border-assertions.ts";
 
 const fakeTheme = {
   fg: (_color: string, text: string) => text,
@@ -43,6 +44,51 @@ describe("queue-reorder-ui", () => {
       const joined = lastRender.join("\n");
       assert.ok(joined.includes("M016"), "selected item should stay visible after scrolling");
       assert.ok(lastRender.length <= 16, `overlay should fit terminal max-height, got ${lastRender.length}`);
+      assertFullOuterBorder(lastRender, 100);
+      assert.match(lastRender[0] ?? "", /^╭─ Queue Reorder /);
+      assert.match(lastRender.at(-1) ?? "", /^╰─+╯$/);
+    } finally {
+      if (originalRowsDescriptor) {
+        Object.defineProperty(process.stdout, "rows", originalRowsDescriptor);
+      } else {
+        delete (process.stdout as { rows?: number }).rows;
+      }
+    }
+  });
+
+  test("draws queue scroll thumb beside queue rows when completed rows are shown", async () => {
+    const originalRowsDescriptor = Object.getOwnPropertyDescriptor(process.stdout, "rows");
+    Object.defineProperty(process.stdout, "rows", { value: 12, configurable: true });
+
+    try {
+      const completed = [
+        { id: "M000", title: "Already done" },
+      ];
+      const pending = Array.from({ length: 8 }, (_, idx) => ({
+        id: `M${String(idx + 1).padStart(3, "0")}`,
+        title: `Milestone ${idx + 1}`,
+      }));
+      let rendered: string[] = [];
+
+      const ctx = {
+        hasUI: true,
+        ui: {
+          custom: async (factory: any) => {
+            const component = factory({ requestRender() {} }, fakeTheme, null, () => {});
+            rendered = component.render(80);
+            return null;
+          },
+        },
+      } as any;
+
+      await showQueueReorder(ctx, completed, pending);
+
+      const completedHeader = rendered.find(line => line.includes("Completed:"));
+      const firstQueueRow = rendered.find(line => line.includes("M001"));
+      assert.ok(completedHeader, "completed header should be rendered before queue rows");
+      assert.ok(firstQueueRow, "first queue row should be rendered");
+      assert.match(completedHeader, /│$/);
+      assert.match(firstQueueRow, /┃$/);
     } finally {
       if (originalRowsDescriptor) {
         Object.defineProperty(process.stdout, "rows", originalRowsDescriptor);

package/src/resources/extensions/gsd/tests/register-extension-guard.test.ts

@@ -134,6 +134,72 @@ test("handleRecoverableExtensionProcessError swallows EPIPE without writing a cr
   }
 });
 
+test("handleRecoverableExtensionProcessError tolerates stderr.write throwing EPIPE (re-entry guard)", () => {
+  // process.stderr.write itself can EPIPE; safeStderr() must swallow it so the
+  // handler doesn't re-enter the EPIPE branch and loop forever.
+  const originalWrite = process.stderr.write.bind(process.stderr);
+  process.stderr.write = (() => {
+    throw Object.assign(new Error("stderr broken pipe"), {
+      code: "EPIPE",
+      syscall: "write",
+    });
+  }) as typeof process.stderr.write;
+
+  try {
+    const handled = handleRecoverableExtensionProcessError(
+      Object.assign(new Error("broken pipe"), {
+        code: "EPIPE",
+        syscall: "write",
+      }),
+    );
+    assert.equal(handled, true);
+  } finally {
+    process.stderr.write = originalWrite;
+  }
+});
+
+// #181: Windows surfaces a closed pipe mid-write as `Error: write EOF` (or
+// `read EOF`) with no `code` set. Both are the same logical condition as POSIX
+// EPIPE and must be swallowed, else they escape to the uncaught-exception path
+// and crash auto-mode workers. These non-storm cases run before the storm test
+// below so the shared storm counter stays under threshold. ECONNRESET is
+// intentionally NOT in this set — see the dedicated "leaves ECONNRESET network
+// errors unhandled" test above.
+test("handleRecoverableExtensionProcessError swallows Windows 'write EOF' (no code)", () => {
+  let stderr = "";
+  const originalWrite = process.stderr.write.bind(process.stderr);
+  process.stderr.write = ((chunk: string | Uint8Array) => {
+    stderr += String(chunk);
+    return true;
+  }) as typeof process.stderr.write;
+
+  try {
+    // Mirror the real Windows error: message "write EOF", no `code`, no `syscall`.
+    const handled = handleRecoverableExtensionProcessError(new Error("write EOF"));
+    assert.equal(handled, true);
+    assert.match(stderr, /swallowed write EOF/);
+  } finally {
+    process.stderr.write = originalWrite;
+  }
+});
+
+test("handleRecoverableExtensionProcessError swallows 'read EOF' (no code)", () => {
+  let stderr = "";
+  const originalWrite = process.stderr.write.bind(process.stderr);
+  process.stderr.write = ((chunk: string | Uint8Array) => {
+    stderr += String(chunk);
+    return true;
+  }) as typeof process.stderr.write;
+
+  try {
+    const handled = handleRecoverableExtensionProcessError(new Error("read EOF"));
+    assert.equal(handled, true);
+    assert.match(stderr, /swallowed read EOF/);
+  } finally {
+    process.stderr.write = originalWrite;
+  }
+});
+
 test("handleRecoverableExtensionProcessError swallows dead transport control write errors", () => {
   let stderr = "";
   const originalWrite = process.stderr.write.bind(process.stderr);
@@ -153,7 +219,16 @@ test("handleRecoverableExtensionProcessError swallows dead transport control wri
   }
 });
 
-test("handleRecoverableExtensionProcessError swallows write EOF without code", () => {
+test("handleRecoverableExtensionProcessError leaves a plain EOF-substring error unhandled", () => {
+  // Guard against over-matching: only the exact "write EOF"/"read EOF" messages
+  // are the Windows pipe-closed signature; an unrelated error must not be eaten.
+  const handled = handleRecoverableExtensionProcessError(new Error("could not write EOF marker to log"));
+  assert.equal(handled, false);
+});
+
+test("handleRecoverableExtensionProcessError exits on EPIPE storm (>100 within 10s)", () => {
+  // After the storm threshold, the pipe is gone for good — handler must exit
+  // cleanly instead of swallowing forever in a tight CPU loop.
   let stderr = "";
   const originalWrite = process.stderr.write.bind(process.stderr);
   process.stderr.write = ((chunk: string | Uint8Array) => {
@@ -161,18 +236,38 @@ test("handleRecoverableExtensionProcessError swallows write EOF without code", (
     return true;
   }) as typeof process.stderr.write;
 
+  const originalExit = process.exit;
+  const exitCalls: Array<number | undefined> = [];
+  process.exit = ((code?: number) => {
+    exitCalls.push(code);
+    // Don't actually exit; just record the call.
+    return undefined as never;
+  }) as typeof process.exit;
+
   try {
-    const handled = handleRecoverableExtensionProcessError(
-      new Error("write EOF"),
+    const err = Object.assign(new Error("broken pipe"), {
+      code: "EPIPE",
+      syscall: "write",
+    });
+    // Fire well above the 100-event threshold inside the 10s window.
+    for (let i = 0; i < 150; i++) {
+      handleRecoverableExtensionProcessError(err);
+    }
+    assert.ok(
+      exitCalls.length > 0,
+      `expected process.exit to be called during EPIPE storm, got ${exitCalls.length} calls`,
     );
-    assert.equal(handled, true);
-    assert.match(stderr, /swallowed write EOF/);
+    assert.equal(exitCalls[0], 0);
+    assert.match(stderr, /EPIPE storm/);
   } finally {
     process.stderr.write = originalWrite;
+    process.exit = originalExit;
   }
 });
 
-test("handleRecoverableExtensionProcessError swallows read EOF without code", () => {
+test("handleRecoverableExtensionProcessError exits on a Windows 'write EOF' storm too (#181)", () => {
+  // The storm counter is shared across all pipe-closed encodings, so a runaway
+  // Windows `write EOF` loop must trip the same clean-exit guard as EPIPE.
   let stderr = "";
   const originalWrite = process.stderr.write.bind(process.stderr);
   process.stderr.write = ((chunk: string | Uint8Array) => {
@@ -180,13 +275,23 @@ test("handleRecoverableExtensionProcessError swallows read EOF without code", ()
     return true;
   }) as typeof process.stderr.write;
 
+  const originalExit = process.exit;
+  const exitCalls: Array<number | undefined> = [];
+  process.exit = ((code?: number) => {
+    exitCalls.push(code);
+    return undefined as never;
+  }) as typeof process.exit;
+
   try {
-    const handled = handleRecoverableExtensionProcessError(
-      new Error("read EOF"),
-    );
-    assert.equal(handled, true);
-    assert.match(stderr, /swallowed read EOF/);
+    const err = new Error("write EOF");
+    for (let i = 0; i < 150; i++) {
+      handleRecoverableExtensionProcessError(err);
+    }
+    assert.ok(exitCalls.length > 0, "expected process.exit during write EOF storm");
+    assert.equal(exitCalls[0], 0);
+    assert.match(stderr, /write EOF storm/);
   } finally {
     process.stderr.write = originalWrite;
+    process.exit = originalExit;
   }
 });

package/src/resources/extensions/gsd/tests/repository-registry.test.ts

@@ -2,9 +2,10 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { execFileSync } from "node:child_process";
 import { createRepositoryRegistryFromPreferences, defaultRepositoryTargets } from "../repository-registry.ts";
 
 test("repository registry includes implicit project root and declared child repos", (t) => {
@@ -99,3 +100,31 @@ test("defaultRepositoryTargets returns [project] for a parent-mode registry", (t
 
   assert.deepEqual(defaultRepositoryTargets(registry), ["project"]);
 });
+
+test("repository registry keeps project root anchored to .gsd project in monorepo subdirectory", (t) => {
+  const monorepo = mkdtempSync(join(tmpdir(), "gsd-repo-registry-mono-"));
+  t.after(() => rmSync(monorepo, { recursive: true, force: true }));
+  execFileSync("git", ["init"], { cwd: monorepo, stdio: "ignore" });
+
+  const subproject = join(monorepo, "fieldkit-tools");
+  mkdirSync(join(subproject, ".gsd"), { recursive: true });
+  writeFileSync(join(subproject, ".gsd", "PREFERENCES.md"), "---\nversion: 1\n---\n");
+
+  const registry = createRepositoryRegistryFromPreferences(subproject, undefined);
+
+  assert.equal(registry.projectRoot, subproject);
+  assert.equal(registry.byId.get("project")?.root, subproject);
+});
+
+test("repository registry uses external-state worktree checkout as project root", (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-repo-registry-external-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+  const worktree = join(base, ".gsd", "projects", "abc123", "worktrees", "M001");
+  mkdirSync(worktree, { recursive: true });
+  execFileSync("git", ["init"], { cwd: worktree, stdio: "ignore" });
+
+  const registry = createRepositoryRegistryFromPreferences(worktree, undefined);
+
+  assert.equal(registry.projectRoot, worktree);
+  assert.equal(registry.byId.get("project")?.root, worktree);
+});

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

@@ -7,6 +7,7 @@ import assert from "node:assert/strict";
 
 import { GSDConfigOverlay, formatConfigText } from "../config-overlay.ts";
 import { handleCoreCommand } from "../commands/handlers/core.ts";
+import { assertFullOuterBorder } from "./tui-border-assertions.ts";
 
 const theme = {
   bold: (s: string) => s,
@@ -24,6 +25,9 @@ test("GSDConfigOverlay renders and responds to input", () => {
 
   const lines = overlay.render(60);
   assert.ok(lines.some((line) => line.includes("GSD Configuration")));
+  assertFullOuterBorder(lines, 60);
+  assert.match(lines[0] ?? "", /^╭─ GSD Configuration /);
+  assert.match(lines.at(-1) ?? "", /^╰─+╯$/);
 
   overlay.handleInput("j");
   assert.equal(renderRequests, 1);

package/src/resources/extensions/gsd/tests/skill-discovery.test.ts

@@ -0,0 +1,111 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  appendDiscoveredSkillsFallback,
+  clearSkillSnapshot,
+  detectNewSkills,
+  refreshCatalogForNewSkills,
+  snapshotSkills,
+} from "../skill-discovery.js";
+
+function makeTempHome(): string {
+  return mkdtempSync(join(tmpdir(), "gsd-skill-discovery-"));
+}
+
+async function withTempSkillHome<T>(fn: (home: string) => T | Promise<T>): Promise<T> {
+  const previousHome = process.env.HOME;
+  const previousGsdHome = process.env.GSD_HOME;
+  const home = makeTempHome();
+  process.env.HOME = home;
+  process.env.GSD_HOME = join(home, ".gsd");
+  try {
+    return await fn(home);
+  } finally {
+    clearSkillSnapshot();
+    if (previousHome === undefined) {
+      delete process.env.HOME;
+    } else {
+      process.env.HOME = previousHome;
+    }
+    if (previousGsdHome === undefined) {
+      delete process.env.GSD_HOME;
+    } else {
+      process.env.GSD_HOME = previousGsdHome;
+    }
+    rmSync(home, { recursive: true, force: true });
+  }
+}
+
+function writeDiskSkill(root: string, name: string, description = `Use for ${name}.`): void {
+  const dir = join(root, name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "SKILL.md"), `---\nname: ${name}\ndescription: ${description}\n---\n\n# ${name}\n`);
+}
+
+test("detectNewSkills detects skills added on disk after the baseline snapshot", async () => {
+  await withTempSkillHome((home) => {
+    const skillsRoot = join(home, ".agents", "skills");
+    writeDiskSkill(skillsRoot, "existing-skill");
+    snapshotSkills();
+
+    writeDiskSkill(skillsRoot, "new-disk-skill", "New disk skill.");
+    const detected = detectNewSkills();
+
+    assert.deepEqual(detected.map(skill => skill.name), ["new-disk-skill"]);
+    assert.equal(detected[0].description, "New disk skill.");
+    assert.equal(detected[0].location, join(skillsRoot, "new-disk-skill", "SKILL.md"));
+  });
+});
+
+test("refreshCatalogForNewSkills retries discovery after reload failure", async () => {
+  await withTempSkillHome(async (home) => {
+    const skillsRoot = join(home, ".agents", "skills");
+    snapshotSkills();
+    writeDiskSkill(skillsRoot, "reload-retry-skill");
+
+    const messages: Array<{ message: string; level: "info" | "warning" }> = [];
+    const failed = await refreshCatalogForNewSkills({
+      reload: async () => { throw new Error("reload failed"); },
+      notify: (message, level) => messages.push({ message, level }),
+    });
+
+    assert.deepEqual(failed.map(skill => skill.name), ["reload-retry-skill"]);
+    assert.deepEqual(detectNewSkills().map(skill => skill.name), ["reload-retry-skill"]);
+    assert.equal(messages[0]?.level, "warning");
+
+    const loaded = await refreshCatalogForNewSkills({
+      reload: async () => {},
+      notify: (message, level) => messages.push({ message, level }),
+    });
+
+    assert.deepEqual(loaded.map(skill => skill.name), ["reload-retry-skill"]);
+    assert.deepEqual(detectNewSkills(), []);
+    assert.ok(messages.some(({ level, message }) => level === "info" && message.includes("reload-retry-skill")));
+  });
+});
+
+test("appendDiscoveredSkillsFallback exposes newly detected skills missing from the prompt", () => {
+  const prompt = appendDiscoveredSkillsFallback("base system prompt", [{
+    name: "fallback-skill",
+    description: "Use when reload fails & skill is needed.",
+    location: "/tmp/fallback-skill/SKILL.md",
+  }]);
+
+  assert.match(prompt, /<newly_discovered_skills>/);
+  assert.match(prompt, /fallback-skill/);
+  assert.match(prompt, /Use when reload fails &amp; skill is needed\./);
+  assert.match(prompt, /\/tmp\/fallback-skill\/SKILL.md/);
+});
+
+test("appendDiscoveredSkillsFallback does not duplicate skills already in the prompt", () => {
+  const prompt = "base system prompt\n/tmp/already-loaded/SKILL.md";
+
+  assert.equal(appendDiscoveredSkillsFallback(prompt, [{
+    name: "already-loaded",
+    description: "Already present.",
+    location: "/tmp/already-loaded/SKILL.md",
+  }]), prompt);
+});