gsd-pi 2.81.0 → 2.82.0

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

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Tests for the GSD health widget state and footer hint rendering.
+
 import test from "node:test";
 import assert from "node:assert/strict";
 import { mkdirSync, rmSync, writeFileSync } from "node:fs";
@@ -9,6 +12,7 @@ import {
   formatRelativeTime,
   type HealthWidgetData,
 } from "../health-widget-core.ts";
+import { HEALTH_WIDGET_ACTIVE_HINTS } from "../health-widget.ts";
 import { registerHooks } from "../bootstrap/register-hooks.ts";
 
 function makeTempDir(prefix: string): string {
@@ -75,13 +79,11 @@ test("buildHealthLines: none state shows single onboarding line pointing at /gsd
   assert.match(lines[0]!, /\/gsd/);
 });
 
-test("buildHealthLines: initialized state shows single setup line pointing at /gsd", (t) => {
+test("buildHealthLines: initialized state shows concise initialized line", (t) => {
   const lines = buildHealthLines(activeData({ projectState: "initialized" }));
   assert.equal(lines.length, 1, "renders exactly one line");
   assert.ok(!/System OK|Budget|Last commit/.test(lines[0]!), "no active-project chrome");
-  // Distinct from "none" — must mention initialized/setup language and /gsd.
-  assert.match(lines[0]!, /\/gsd/);
-  assert.match(lines[0]!, /initiali[sz]ed|setup/i);
+  assert.equal(lines[0], "  GSD  Project Initialized");
 });
 
 test("buildHealthLines: active state with ledger-driven spend shows spent summary", (t) => {
@@ -91,6 +93,14 @@ test("buildHealthLines: active state with ledger-driven spend shows spent summar
   assert.match(lines[0]!, /Spent: 42\.0¢/);
 });
 
+test("health widget active hints include visualization and notifications", () => {
+  assert.match(HEALTH_WIDGET_ACTIVE_HINTS, /\/gsd auto to run/);
+  assert.match(HEALTH_WIDGET_ACTIVE_HINTS, /\/gsd status for overview/);
+  assert.match(HEALTH_WIDGET_ACTIVE_HINTS, /\/gsd visualize to inspect/);
+  assert.match(HEALTH_WIDGET_ACTIVE_HINTS, /\/gsd notifications for history/);
+  assert.match(HEALTH_WIDGET_ACTIVE_HINTS, /\/gsd help/);
+});
+
 test("buildHealthLines: active state with budget ceiling shows percent summary", (t) => {
   const lines = buildHealthLines(activeData({ budgetSpent: 2.5, budgetCeiling: 10 }));
   assert.equal(lines.length, 1);

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

@@ -608,6 +608,32 @@ describe('git-service', async () => {
     rmSync(repo, { recursive: true, force: true });
   });
 
+  test('GitServiceImpl: task context keyFiles ignores gitignored build outputs', () => {
+    const repo = initTempRepo();
+    const svc = new GitServiceImpl(repo);
+
+    createFile(repo, ".gitignore", "dist/\n");
+    runGit(repo, ["add", ".gitignore"]);
+    runGit(repo, ["commit", "-F", "-"], { input: "ignore dist" });
+
+    createFile(repo, "src/task.ts", "export const task = true;");
+    createFile(repo, "dist/task.js", "export const task = true;");
+
+    const msg = svc.autoCommit("execute-task", "M001/S01/T01", [], {
+      taskId: "S01/T01",
+      taskTitle: "implement scoped task",
+      oneLiner: "Added scoped task implementation",
+      keyFiles: ["src/task.ts", "dist/task.js"],
+    });
+    assert.ok(msg !== null, "autoCommit should commit non-ignored key files");
+
+    const committed = run("git show --name-only --format= HEAD", repo);
+    assert.ok(committed.includes("src/task.ts"), "non-ignored key file is committed");
+    assert.ok(!committed.includes("dist/task.js"), "ignored build output is not committed");
+
+    rmSync(repo, { recursive: true, force: true });
+  });
+
   // ─── GitServiceImpl: empty-after-staging guard ─────────────────────────
 
   test('GitServiceImpl: empty-after-staging guard', () => {

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

@@ -62,8 +62,8 @@ import {
   renderRoadmapCheckboxes,
   renderAllFromDb,
   detectStaleRenders,
-  repairStaleRenders,
 } from "../../markdown-renderer.ts";
+import { repairStaleRenders } from "../../state-reconciliation/drift/stale-render.ts";
 
 // ── State derivation ──────────────────────────────────────────────────────
 import {

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

@@ -85,7 +85,49 @@ function cleanup(dir: string): void {
   try { rmSync(dir, { recursive: true, force: true }); } catch { /* */ }
 }
 
-/** Set up a milestone roadmap file in .gsd/milestones/<MID>/ */
+/**
+ * Write `.gsd/preferences.md` with `git.isolation: branch` so the merge
+ * routes through the standalone Lifecycle merge body in branch mode rather
+ * than falling through `getIsolationMode === "none"` to a skipped result.
+ *
+ * Parallel-merge in production runs with `git.isolation: worktree` and a
+ * real auto-worktree on disk; these integration tests use branch mode as a
+ * simpler equivalent that exercises the same merge path without requiring
+ * `git worktree add` setup. ADR-016 phase 2 / A2 routes parallel-merge
+ * through the Module, which performs mode detection — branch mode keeps
+ * the test simple while still going through the Module.
+ */
+function setupBranchIsolation(repo: string): void {
+  mkdirSync(join(repo, ".gsd"), { recursive: true });
+  writeFileSync(
+    join(repo, ".gsd", "preferences.md"),
+    "## Git\n- isolation: branch\n",
+  );
+  // Commit on main so subsequent `git checkout main` restores the file.
+  // Without this commit, `createMilestoneBranch`'s checkout dance carries
+  // the uncommitted file onto the milestone branch and back-checking-out
+  // main loses the preference file before `mergeMilestoneStandalone`
+  // reads it (ADR-016 phase 2 / A2).
+  try {
+    run("git add .gsd/preferences.md", repo);
+    run('git commit -m "test: add branch-isolation preferences"', repo);
+  } catch { /* file may already be committed */ }
+}
+
+/**
+ * Set up a milestone roadmap file in .gsd/milestones/<MID>/ AND commit it on
+ * the current branch.
+ *
+ * The commit is required after ADR-016 phase 2 / A2 because the standalone
+ * Module-level merge (now used by parallel-merge) reads the roadmap _after_
+ * its branch checkout. Uncommitted roadmaps on `main` survive a checkout
+ * for the first milestone but get committed onto the milestone branch by
+ * `autoCommitDirtyState`, which then doesn't reproduce them on the next
+ * milestone branch's checkout.
+ *
+ * Real production runs commit roadmap files on each milestone branch as
+ * part of the unit's normal output; tests should mirror that.
+ */
 function setupRoadmap(repo: string, mid: string, title: string, slices: string[]): void {
   const dir = join(repo, ".gsd", "milestones", mid);
   mkdirSync(dir, { recursive: true });
@@ -94,6 +136,10 @@ function setupRoadmap(repo: string, mid: string, title: string, slices: string[]
     join(dir, `${mid}-ROADMAP.md`),
     `# ${mid}: ${title}\n\n## Slices\n${sliceLines}\n`,
   );
+  try {
+    run(`git add .gsd/milestones/${mid}/${mid}-ROADMAP.md`, repo);
+    run(`git commit -m "test: add roadmap for ${mid}"`, repo);
+  } catch { /* file may already be committed; not a git repo; etc. */ }
 }
 
 /** Create a milestone branch with file changes, then return to main. */
@@ -234,15 +280,36 @@ test("formatMergeResults — mixed results", () => {
 // ═══════════════════════════════════════════════════════════════════════════════
 
 test("mergeCompletedMilestone — missing roadmap returns error result", async () => {
-  const base = join(tmpdir(), `parallel-merge-noroadmap-${Date.now()}`);
-  mkdirSync(join(base, ".gsd"), { recursive: true });
+  const savedCwd = process.cwd();
+  // Use a real git repo so the standalone's branch-mode merge body can
+  // call `getCurrentBranch` without throwing. The roadmap is intentionally
+  // omitted so the merge ends in the "no-roadmap" branch.
+  const repo = createTempRepo();
   try {
-    const result = await mergeCompletedMilestone(base, "M999");
+    setupBranchIsolation(repo);
+    // Create a milestone branch but no roadmap file — this is the
+    // condition under test.
+    run("git checkout -b milestone/M999", repo);
+    writeFileSync(join(repo, "feature.ts"), "export {};\n");
+    run("git add .", repo);
+    run('git commit -m "M999 feature"', repo);
+    run("git checkout main", repo);
+
+    process.chdir(repo);
+    const result = await mergeCompletedMilestone(repo, "M999");
+
     assert.equal(result.success, false);
-    assert.ok(result.error?.includes("No roadmap found") || result.error?.includes("Could not read"));
+    // A2 widens the error surface vs. the legacy bypass: the standalone
+    // routes through the Module, so the no-roadmap path teardowns the
+    // (non-existent) worktree branch and surfaces a typed failure.
+    // What matters is `success: false`; the exact wording can shift as
+    // the standalone evolves.
+    assert.ok(result.error, "should report a non-empty error");
     assert.equal(result.milestoneId, "M999");
   } finally {
-    cleanup(base);
+    process.chdir(savedCwd);
+    try { run("git reset --hard HEAD", repo); } catch { /* */ }
+    cleanup(repo);
   }
 });
 
@@ -251,14 +318,24 @@ test("mergeCompletedMilestone — clean merge, session status cleaned up", async
   const repo = createTempRepo();
 
   try {
+    // Route the merge through the Module's branch-mode path. With default
+    // `isolation: none`, the standalone returns `{ mode: "skipped" }`
+    // (ADR-016 phase 2 / A2). Branch mode exercises the same Module-level
+    // merge body without requiring an on-disk auto-worktree.
+    setupBranchIsolation(repo);
+
+    // Set up roadmap on main BEFORE the milestone branch is created so the
+    // roadmap is in the milestone branch's history. After A2, the standalone
+    // reads the roadmap _inside_ the merge body (after the branch checkout)
+    // — the file must therefore exist in the milestone branch's tree, not
+    // just as an uncommitted file on main.
+    setupRoadmap(repo, "M010", "Auth System", ["S01: JWT module"]);
+
     // Create milestone branch with a new file
     createMilestoneBranch(repo, "M010", [
       { name: "auth.ts", content: "export const auth = true;\n" },
     ]);
 
-    // Set up roadmap
-    setupRoadmap(repo, "M010", "Auth System", ["S01: JWT module"]);
-
     // Write session status to verify cleanup
     writeSessionStatus(repo, {
       milestoneId: "M010",
@@ -309,6 +386,11 @@ test("mergeCompletedMilestone — conflict returns structured error with file li
   const repo = createTempRepo();
 
   try {
+    setupBranchIsolation(repo);
+
+    // Roadmap committed on main BEFORE branching — see "clean merge" test.
+    setupRoadmap(repo, "M020", "Conflict Test", ["S01: Conflict scenario"]);
+
     // Create milestone branch that modifies README.md
     run("git checkout -b milestone/M020", repo);
     writeFileSync(join(repo, "README.md"), "# M020 version\n");
@@ -321,9 +403,6 @@ test("mergeCompletedMilestone — conflict returns structured error with file li
     run("git add .", repo);
     run('git commit -m "main changes README"', repo);
 
-    // Set up roadmap
-    setupRoadmap(repo, "M020", "Conflict Test", ["S01: Conflict scenario"]);
-
     process.chdir(repo);
     const result = await mergeCompletedMilestone(repo, "M020");
 
@@ -350,6 +429,12 @@ test("mergeAllCompleted — merges in sequential order", async () => {
   const repo = createTempRepo();
 
   try {
+    setupBranchIsolation(repo);
+
+    // Roadmaps committed on main BEFORE branching — see "clean merge" test.
+    setupRoadmap(repo, "M001", "Auth", ["S01: Auth module"]);
+    setupRoadmap(repo, "M002", "Dashboard", ["S01: Dashboard module"]);
+
     // M001: adds auth.ts
     createMilestoneBranch(repo, "M001", [
       { name: "auth.ts", content: "export const auth = true;\n" },
@@ -359,9 +444,6 @@ test("mergeAllCompleted — merges in sequential order", async () => {
       { name: "dashboard.ts", content: "export const dash = true;\n" },
     ]);
 
-    setupRoadmap(repo, "M001", "Auth", ["S01: Auth module"]);
-    setupRoadmap(repo, "M002", "Dashboard", ["S01: Dashboard module"]);
-
     const workers = [
       makeWorker({ milestoneId: "M002", startedAt: 100 }),
       makeWorker({ milestoneId: "M001", startedAt: 200 }),
@@ -373,9 +455,9 @@ test("mergeAllCompleted — merges in sequential order", async () => {
     // Both should succeed
     assert.equal(results.length, 2, "should have two results");
     assert.equal(results[0]!.milestoneId, "M001", "M001 merged first (sequential)");
-    assert.equal(results[0]!.success, true, "M001 should succeed");
+    assert.equal(results[0]!.success, true, `M001 should succeed: ${results[0]!.error}`);
     assert.equal(results[1]!.milestoneId, "M002", "M002 merged second");
-    assert.equal(results[1]!.success, true, "M002 should succeed");
+    assert.equal(results[1]!.success, true, `M002 should succeed: ${results[1]!.error}`);
 
     // Both files on main
     assert.ok(existsSync(join(repo, "auth.ts")), "auth.ts on main");
@@ -391,6 +473,12 @@ test("mergeAllCompleted — stops on first conflict, skips later milestones", as
   const repo = createTempRepo();
 
   try {
+    setupBranchIsolation(repo);
+
+    // Roadmaps committed on main BEFORE branching — see "clean merge" test.
+    setupRoadmap(repo, "M001", "Conflict milestone", ["S01: Conflict test"]);
+    setupRoadmap(repo, "M002", "Clean milestone", ["S01: Clean test"]);
+
     // M001: modifies README.md (will conflict with main)
     run("git checkout -b milestone/M001", repo);
     writeFileSync(join(repo, "README.md"), "# M001 version\n");
@@ -408,9 +496,6 @@ test("mergeAllCompleted — stops on first conflict, skips later milestones", as
     run("git add .", repo);
     run('git commit -m "main diverges README"', repo);
 
-    setupRoadmap(repo, "M001", "Conflict milestone", ["S01: Conflict test"]);
-    setupRoadmap(repo, "M002", "Clean milestone", ["S01: Clean test"]);
-
     const workers = [
       makeWorker({ milestoneId: "M001" }),
       makeWorker({ milestoneId: "M002" }),
@@ -442,6 +527,12 @@ test("mergeAllCompleted — by-completion order respects startedAt", async () =>
   const repo = createTempRepo();
 
   try {
+    setupBranchIsolation(repo);
+
+    // Roadmaps committed on main BEFORE branching — see "clean merge" test.
+    setupRoadmap(repo, "M001", "Auth", ["S01: Auth module"]);
+    setupRoadmap(repo, "M002", "Feature", ["S01: Feature module"]);
+
     // M001: adds auth.ts (started later)
     createMilestoneBranch(repo, "M001", [
       { name: "auth.ts", content: "export const auth = true;\n" },
@@ -451,9 +542,6 @@ test("mergeAllCompleted — by-completion order respects startedAt", async () =>
       { name: "feature.ts", content: "export const feature = true;\n" },
     ]);
 
-    setupRoadmap(repo, "M001", "Auth", ["S01: Auth module"]);
-    setupRoadmap(repo, "M002", "Feature", ["S01: Feature module"]);
-
     const workers = [
       makeWorker({ milestoneId: "M001", startedAt: 2000 }),
       makeWorker({ milestoneId: "M002", startedAt: 1000 }),
@@ -549,11 +637,15 @@ test("mergeAllCompleted — discovers DB-complete milestones when workers show e
   const repo = createTempRepo();
 
   try {
+    setupBranchIsolation(repo);
+
+    // Roadmap committed on main BEFORE branching — see "clean merge" test.
+    setupRoadmap(repo, "M011", "Feature System", ["S01: Feature module"]);
+
     // Create milestone branch with a file
     createMilestoneBranch(repo, "M011", [
       { name: "feature.ts", content: "export const feature = true;\n" },
     ]);
-    setupRoadmap(repo, "M011", "Feature System", ["S01: Feature module"]);
 
     // Set up canonical DB showing M011 is complete
     setupCanonicalDbWithWorktree(repo, "M011");

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

@@ -75,7 +75,6 @@ function makeMockDeps(
     pruneQueueOrder: () => {},
     isInAutoWorktree: () => false,
     shouldUseWorktreeIsolation: () => false,
-    mergeMilestoneToMain: () => ({ pushed: false, codeFilesChanged: false }),
     teardownAutoWorktree: () => {},
     createAutoWorktree: () => "/tmp/wt",
     captureIntegrationBranch: () => {},

package/src/resources/extensions/gsd/tests/markdown-renderer.test.ts

@@ -24,8 +24,8 @@ import {
   renderPlanFromDb,
   renderTaskPlanFromDb,
   detectStaleRenders,
-  repairStaleRenders,
 } from '../markdown-renderer.ts';
+import { repairStaleRenders } from '../state-reconciliation/drift/stale-render.ts';
 import {
   parseRoadmap,
   parsePlan,

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

@@ -29,20 +29,25 @@
 
 import { describe, test, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, rmSync, mkdirSync } from "node:fs";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
-import { WorktreeLifecycle, type WorktreeLifecycleDeps } from "../worktree-lifecycle.ts";
+import {
+  WorktreeLifecycle,
+  type WorktreeLifecycleDeps,
+  type WorktreeLifecycleTestOverrides,
+} from "../worktree-lifecycle.ts";
 import { WorktreeStateProjection } from "../worktree-state-projection.ts";
 import { MergeConflictError } from "../git-service.ts";
 import type { 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 & {
+// Test-local: extras the WorktreeResolver-era fixture passed but Lifecycle
+// does not need (shouldUseWorktreeIsolation, syncWorktreeStateBack,
+// captureIntegrationBranch). Lifecycle ignores them via structural typing.
+// The C1-C4-inlined primitive overrides come from
+// `WorktreeLifecycleTestOverrides`, the test seam exported by the Module.
+type LegacyTestDeps = WorktreeLifecycleDeps & WorktreeLifecycleTestOverrides & {
   shouldUseWorktreeIsolation?: () => boolean;
   syncWorktreeStateBack?: (
     mainBasePath: string,
@@ -50,6 +55,7 @@ type LegacyTestDeps = WorktreeLifecycleDeps & {
     milestoneId: string,
   ) => { synced: string[] };
   captureIntegrationBranch?: (basePath: string, mid: string | undefined) => void;
+  GitServiceImpl?: new (basePath: string, gitConfig: unknown) => unknown;
 };
 
 /**
@@ -96,7 +102,12 @@ function makeDeps(
     enterAutoWorktree: () => "",
     enterBranchModeForMilestone: () => undefined,
     getAutoWorktreePath: () => null,
-    autoCommitCurrentBranch: () => undefined,
+    autoCommitCurrentBranch: (
+      _basePath: string,
+      _unitType: string,
+      _unitId: string,
+      _taskContext?: unknown,
+    ) => null,
     getCurrentBranch: () => "worktree/M001",
     checkoutBranch: () => undefined,
     autoWorktreeBranch: (mid: string) => `worktree/${mid}`,
@@ -109,6 +120,8 @@ function makeDeps(
     invalidateAllCaches: () => undefined,
     captureIntegrationBranch: () => undefined,
     worktreeProjection: new WorktreeStateProjection(),
+    // ADR-016 phase 2 / C4 (#5627): GitServiceImpl constructor → factory.
+    gitServiceFactory: () => ({}) as never,
     ...overrides,
   };
 }
@@ -128,14 +141,36 @@ function makeNotifyCtx(): {
 
 describe("WorktreeResolver.mergeAndExit re-throws MergeConflictError (#2330)", () => {
   let baseDir: string;
+  const savedCwd = process.cwd();
 
   beforeEach(() => {
     baseDir = mkdtempSync(join(tmpdir(), "merge-conflict-stops-loop-"));
     // Fake out a milestone directory so mergeAndExit reaches mergeMilestoneToMain.
     mkdirSync(join(baseDir, ".gsd", "milestones", "M001"), { recursive: true });
+    // ADR-016 phase 2 / C1 (#5624): worktree-lifecycle.ts now calls
+    // node:fs.readFileSync directly (the dep was retired), so the roadmap
+    // file must exist on disk for the test to reach mergeMilestoneToMain.
+    writeFileSync(
+      join(baseDir, ".gsd", "milestones", "M001", "M001-ROADMAP.md"),
+      "# M001\n",
+    );
+    // ADR-016 phase 2 / C3 (#5626): `getIsolationMode` is also inlined.
+    // Without explicit isolation preferences the mode defaults to "none"
+    // and the merge short-circuits before the test's mocked
+    // `mergeMilestoneToMain` is reached. Write a preferences file so the
+    // standalone routes through worktree-mode merge.
+    writeFileSync(
+      join(baseDir, ".gsd", "preferences.md"),
+      "## Git\n- isolation: worktree\n",
+    );
   });
 
   afterEach(() => {
+    // ADR-016 phase 2 / C2 (#5625): the inlined `mergeMilestoneStandalone`
+    // chdirs into the project root before the merge body runs. Restore
+    // cwd before deleting `baseDir` so the next test's `process.cwd()`
+    // doesn't fail with ENOENT.
+    try { process.chdir(savedCwd); } catch { /* best-effort */ }
     try {
       rmSync(baseDir, { recursive: true, force: true });
     } catch {
@@ -147,7 +182,7 @@ describe("WorktreeResolver.mergeAndExit re-throws MergeConflictError (#2330)", (
     const conflicted = ["src/feature.ts", "README.md"];
     const roadmapPath = join(baseDir, ".gsd", "milestones", "M001", "M001-ROADMAP.md");
     const deps = makeDeps({
-      resolveMilestoneFile: (_base, _mid, type) =>
+      resolveMilestoneFile: (_base: string, _mid: string, type: string) =>
         type === "ROADMAP" ? roadmapPath : null,
       readFileSync: () => "# M001\n",
       mergeMilestoneToMain: () => {
@@ -178,7 +213,7 @@ describe("WorktreeResolver.mergeAndExit re-throws MergeConflictError (#2330)", (
     const roadmapPath = join(baseDir, ".gsd", "milestones", "M001", "M001-ROADMAP.md");
     class FakePermError extends Error {}
     const deps = makeDeps({
-      resolveMilestoneFile: (_base, _mid, type) =>
+      resolveMilestoneFile: (_base: string, _mid: string, type: string) =>
         type === "ROADMAP" ? roadmapPath : null,
       readFileSync: () => "# M001\n",
       mergeMilestoneToMain: () => {
@@ -204,7 +239,7 @@ describe("WorktreeResolver.mergeAndExit re-throws MergeConflictError (#2330)", (
   test("successful merge does not throw", () => {
     const roadmapPath = join(baseDir, ".gsd", "milestones", "M001", "M001-ROADMAP.md");
     const deps = makeDeps({
-      resolveMilestoneFile: (_base, _mid, type) =>
+      resolveMilestoneFile: (_base: string, _mid: string, type: string) =>
         type === "ROADMAP" ? roadmapPath : null,
       readFileSync: () => "# M001\n",
       mergeMilestoneToMain: () => ({ pushed: false, codeFilesChanged: true }),

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

@@ -1,55 +1,53 @@
-// GSD Extension — Notification Overlay Tests
-// Tests for message wrapping in the notification panel.
-// Mirrors the private wrapText from notification-overlay.ts so its contract
-// can be exercised without exporting internals.
+// Project/App: GSD-2
+// File Purpose: Regression tests for notification overlay wrapping and width-safe rendering.
 
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 
-import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@gsd/pi-tui";
+import { visibleWidth } from "@gsd/pi-tui";
+import { appendNotification, initNotificationStore, _resetNotificationStore } from "../notification-store.ts";
+import { GSDNotificationOverlay, notificationOverlayOptions } from "../notification-overlay.ts";
+import { wrapVisibleText } from "../tui/render-kit.ts";
 
-// ── wrapText logic (mirrors the private function in notification-overlay.ts) ──
+const fakeTheme = {
+  fg: (_color: string, text: string) => text,
+  bold: (text: string) => text,
+};
 
-function wrapText(text: string, maxWidth: number): string[] {
-  if (maxWidth <= 0) return [text];
-  const lines = wrapTextWithAnsi(text, maxWidth);
-  return lines.map((l) =>
-    visibleWidth(l) > maxWidth ? truncateToWidth(l, maxWidth, "…") : l,
-  );
+function assertLinesFit(lines: string[], width: number): void {
+  for (const line of lines) {
+    assert.ok(
+      visibleWidth(line) <= width,
+      `line exceeds maxWidth: visibleWidth=${visibleWidth(line)} max=${width}: "${line}"`,
+    );
+  }
 }
 
 describe("notification overlay — wrapText", () => {
   test("short text returns single line", () => {
-    const result = wrapText("hello world", 80);
+    const result = wrapVisibleText("hello world", 80);
     assert.deepStrictEqual(result, ["hello world"]);
   });
 
   test("long text wraps at word boundaries without exceeding maxWidth", () => {
     const text = "This is a long notification message that should wrap across multiple lines";
-    const result = wrapText(text, 40);
+    const result = wrapVisibleText(text, 40);
     assert.ok(result.length > 1, `expected multiple lines, got ${result.length}`);
-    for (const line of result) {
-      assert.ok(
-        visibleWidth(line) <= 40,
-        `line exceeds maxWidth: "${line}" (${visibleWidth(line)})`,
-      );
-    }
+    assertLinesFit(result, 40);
   });
 
   test("single word exceeding maxWidth is broken to fit column budget", () => {
-    const result = wrapText("superlongwordthatexceedsmaxwidth", 10);
-    for (const line of result) {
-      assert.ok(
-        visibleWidth(line) <= 10,
-        `line exceeds maxWidth: "${line}" (${visibleWidth(line)})`,
-      );
-    }
+    const result = wrapVisibleText("superlongwordthatexceedsmaxwidth", 10);
+    assertLinesFit(result, 10);
   });
 
   test("preserves all words across wrapped lines", () => {
     const words = ["alpha", "bravo", "charlie", "delta", "echo", "foxtrot"];
     const text = words.join(" ");
-    const result = wrapText(text, 15);
+    const result = wrapVisibleText(text, 15);
     const rejoined = result.join(" ");
     for (const w of words) {
       assert.ok(rejoined.includes(w), `missing word: ${w}`);
@@ -70,23 +68,62 @@ describe("notification overlay — wrapText", () => {
       "(expired — will auto-refresh) ✗ google — not configured " +
       "(aistudio.google.com/apikey) ✗ groq — not configured";
     const maxWidth = 118;
-    const result = wrapText(msg, maxWidth);
-    for (const line of result) {
-      assert.ok(
-        visibleWidth(line) <= maxWidth,
-        `line exceeds column budget: visibleWidth=${visibleWidth(line)} max=${maxWidth}: "${line}"`,
-      );
-    }
+    const result = wrapVisibleText(msg, maxWidth);
+    assertLinesFit(result, maxWidth);
   });
 
   test("unbreakable long token (URL) is clamped to maxWidth", () => {
     const url = "https://example.com/" + "a".repeat(200);
-    const result = wrapText(url, 40);
-    for (const line of result) {
-      assert.ok(
-        visibleWidth(line) <= 40,
-        `line exceeds maxWidth: visibleWidth=${visibleWidth(line)} line="${line}"`,
-      );
+    const result = wrapVisibleText(url, 40);
+    assertLinesFit(result, 40);
+  });
+
+  test("real overlay render fits common terminal widths", (t) => {
+    const dir = mkdtempSync(join(tmpdir(), "gsd-notification-overlay-"));
+    t.after(() => {
+      _resetNotificationStore();
+      rmSync(dir, { recursive: true, force: true });
+    });
+
+    initNotificationStore(dir);
+    appendNotification("A long notification with " + "x".repeat(180), "warning");
+
+    const overlay = new GSDNotificationOverlay({ requestRender() {} }, fakeTheme as any, () => {});
+    t.after(() => overlay.dispose());
+
+    for (const width of [40, 80, 120]) {
+      assertLinesFit(overlay.render(width), width);
+      overlay.invalidate();
     }
   });
+
+  test("rendered height stays within the configured overlay max height", (t) => {
+    const dir = mkdtempSync(join(tmpdir(), "gsd-notification-overlay-height-"));
+    const originalRowsDescriptor = Object.getOwnPropertyDescriptor(process.stdout, "rows");
+    Object.defineProperty(process.stdout, "rows", { value: 40, configurable: true });
+
+    t.after(() => {
+      if (originalRowsDescriptor) {
+        Object.defineProperty(process.stdout, "rows", originalRowsDescriptor);
+      } else {
+        delete (process.stdout as { rows?: number }).rows;
+      }
+      _resetNotificationStore();
+      rmSync(dir, { recursive: true, force: true });
+    });
+
+    initNotificationStore(dir);
+    for (let i = 0; i < 80; i++) {
+      appendNotification(`notification-${i + 1} with enough text to exercise clipping`, "warning");
+    }
+
+    const overlay = new GSDNotificationOverlay({ requestRender() {} }, fakeTheme as any, () => {});
+    t.after(() => overlay.dispose());
+
+    const rendered = overlay.render(100);
+    const maxHeight = Math.floor((40 * 52) / 100);
+    assert.ok(rendered.length <= maxHeight, `expected ${rendered.length} lines to fit maxHeight ${maxHeight}`);
+    assert.ok(rendered.at(-1)?.includes("╯"), "bottom border should remain visible");
+    assert.equal(notificationOverlayOptions().maxHeight, "52%");
+  });
 });