gsd-pi 2.80.0 → 2.81.0

package/src/resources/extensions/gsd/tests/run-uat-replay-cap.test.ts

@@ -1,51 +1,67 @@
 /**
- * Regression test for #3624 — cap run-uat dispatch attempts
- *
- * When verification commands fail before writing a verdict, the run-uat
- * dispatch rule fires repeatedly in an infinite loop. The fix adds a
- * MAX_UAT_ATTEMPTS constant and calls incrementUatCount before dispatch
- * to cap the number of attempts.
- *
- * Structural verification test — reads source to confirm MAX_UAT_ATTEMPTS
- * and incrementUatCount exist.
+ * Regression test for #3624 — cap run-uat dispatch attempts.
  */
 
-import { describe, test } from 'node:test';
-import assert from 'node:assert/strict';
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
+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";
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+import { DISPATCH_RULES, getUatCount } from "../auto-dispatch.ts";
 
-const source = readFileSync(join(__dirname, '..', 'auto-dispatch.ts'), 'utf-8');
+function makeUatProject(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-uat-cap-"));
+  const milestone = join(base, ".gsd", "milestones", "M001");
+  mkdirSync(join(milestone, "slices", "S01"), { recursive: true });
+  mkdirSync(join(milestone, "slices", "S02"), { recursive: true });
+  writeFileSync(
+    join(milestone, "M001-ROADMAP.md"),
+    [
+      "# M001: UAT Cap",
+      "",
+      "## Slices",
+      "- [x] **S01: Completed slice** `risk:low`",
+      "  Demo: done.",
+      "- [ ] **S02: Remaining slice** `risk:low`",
+      "  Demo: pending.",
+    ].join("\n"),
+    "utf-8",
+  );
+  writeFileSync(
+    join(milestone, "slices", "S01", "S01-UAT.md"),
+    "# UAT\n\nRun the checks. No verdict has been written yet.\n",
+    "utf-8",
+  );
+  return base;
+}
 
-describe('run-uat replay cap (#3624)', () => {
-  test('MAX_UAT_ATTEMPTS constant is defined', () => {
-    assert.match(source, /const MAX_UAT_ATTEMPTS\s*=\s*\d+/,
-      'MAX_UAT_ATTEMPTS constant should be defined');
-  });
+test("run-uat dispatch stops after three attempts without a verdict", async () => {
+  const basePath = makeUatProject();
+  const rule = DISPATCH_RULES.find((r) => r.name === "run-uat (post-completion)");
+  assert.ok(rule, "run-uat dispatch rule is registered");
 
-  test('incrementUatCount function is exported', () => {
-    assert.match(source, /export function incrementUatCount\(/,
-      'incrementUatCount should be an exported function');
-  });
+  const ctx = {
+    state: { phase: "planning", activeSlice: null },
+    mid: "M001",
+    midTitle: "UAT Cap",
+    basePath,
+    prefs: { uat_dispatch: true },
+  };
 
-  test('getUatCount function is exported', () => {
-    assert.match(source, /export function getUatCount\(/,
-      'getUatCount should be an exported function');
-  });
+  try {
+    for (let i = 1; i <= 3; i++) {
+      const action = await rule.match(ctx as any);
+      assert.equal(action?.action, "dispatch");
+      assert.equal(action?.unitType, "run-uat");
+      assert.equal(getUatCount(basePath, "M001", "S01"), i);
+    }
 
-  test('incrementUatCount is called before dispatch in rule', () => {
-    // incrementUatCount should be called before the dispatch return
-    const ruleSection = source.slice(source.indexOf('checkNeedsRunUat'));
-    assert.match(ruleSection, /incrementUatCount\(/,
-      'incrementUatCount should be called in the dispatch rule');
-  });
-
-  test('attempts are compared against MAX_UAT_ATTEMPTS', () => {
-    assert.match(source, /attempts\s*>\s*MAX_UAT_ATTEMPTS/,
-      'dispatch should check attempts > MAX_UAT_ATTEMPTS');
-  });
+    const capped = await rule.match(ctx as any);
+    assert.equal(capped?.action, "stop");
+    assert.match(capped?.reason ?? "", /dispatched 3 times/);
+    assert.equal(getUatCount(basePath, "M001", "S01"), 4);
+  } finally {
+    rmSync(basePath, { recursive: true, force: true });
+  }
 });

package/src/resources/extensions/gsd/tests/runtime-invariant-modules.test.ts

@@ -0,0 +1,91 @@
+// Project/App: GSD-2
+// File Purpose: ADR-015 runtime invariant module contract tests.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { classifyFailure } from "../recovery-classification.js";
+import { reconcileBeforeDispatch } from "../state-reconciliation.js";
+import { compileUnitToolContract } from "../tool-contract.js";
+import type { GSDState } from "../types.js";
+
+function makeState(overrides: Partial<GSDState> = {}): GSDState {
+  return {
+    activeMilestone: { id: "M001", title: "Milestone" },
+    activeSlice: null,
+    activeTask: null,
+    phase: "planning",
+    recentDecisions: [],
+    blockers: [],
+    nextAction: "Plan milestone",
+    registry: [],
+    requirements: { active: 0, validated: 0, deferred: 0, outOfScope: 0, blocked: 0, total: 0 },
+    progress: { milestones: { done: 0, total: 1 } },
+    ...overrides,
+  };
+}
+
+test("State Reconciliation invalidates cache and returns reconciled state", async () => {
+  const calls: string[] = [];
+  const state = makeState();
+
+  const result = await reconcileBeforeDispatch("/project", {
+    invalidateStateCache() { calls.push("invalidate"); },
+    async deriveState(basePath) {
+      calls.push(`derive:${basePath}`);
+      return state;
+    },
+  });
+
+  assert.equal(result.ok, true);
+  assert.deepEqual(calls, ["invalidate", "derive:/project"]);
+  assert.equal(result.ok && result.stateSnapshot, state);
+});
+
+test("State Reconciliation blocks when derived state carries blockers", async () => {
+  const result = await reconcileBeforeDispatch("/project", {
+    invalidateStateCache() {},
+    async deriveState() {
+      return makeState({ phase: "blocked", blockers: ["slice lock missing"] });
+    },
+  });
+
+  assert.equal(result.ok, false);
+  assert.equal(!result.ok && result.reason, "slice lock missing");
+});
+
+test("Tool Contract compiles known Unit prompt and tool policy", () => {
+  const result = compileUnitToolContract("execute-task");
+
+  assert.equal(result.ok, true);
+  assert.equal(result.ok && result.contract.unitType, "execute-task");
+  assert.deepEqual(result.ok && result.contract.requiredWorkflowTools, ["gsd_task_complete"]);
+  assert.equal(result.ok && result.contract.toolsPolicy.mode, "all");
+  assert.ok(result.ok && result.contract.validationRules.includes("closeout-tool-present"));
+});
+
+test("Tool Contract fails closed for unknown Units", () => {
+  const result = compileUnitToolContract("custom-step");
+
+  assert.equal(result.ok, false);
+  assert.equal(!result.ok && result.reason, "unknown-unit-type");
+});
+
+test("Recovery Classification covers ADR-015 failure families", () => {
+  const cases = [
+    ["invalid tool schema enum", "tool-schema", "stop"],
+    ["deterministic policy rejection", "deterministic-policy", "stop"],
+    ["stale worker lease", "stale-worker", "stop"],
+    ["worktree root missing .git", "worktree-invalid", "stop"],
+    ["verification drift in state snapshot", "verification-drift", "escalate"],
+    ["rate limit 429", "provider", "retry"],
+    ["unexpected invariant", "runtime-unknown", "escalate"],
+  ] as const;
+
+  for (const [message, failureKind, action] of cases) {
+    const result = classifyFailure({ error: new Error(message), unitType: "execute-task", unitId: "T01" });
+
+    assert.equal(result.failureKind, failureKind);
+    assert.equal(result.action, action);
+  }
+});

package/src/resources/extensions/gsd/tests/safety-harness-false-positives.test.ts

@@ -144,6 +144,18 @@ test("safety-harness-bug2-race: bash evidence survives mid-unit reset between to
   assert.ok(bash[0].outputSnippet.includes("found"), "output snippet captured");
 });
 
+test("safety-harness: gsd_exec counts as execution evidence", () => {
+  resetEvidence();
+
+  recordToolCall("tc-exec-1", "gsd_exec", { command: "grep -n render index.html" });
+  recordToolResult("tc-exec-1", "gsd_exec", "Command exited with code 0\n1:render\n", false);
+
+  const bash = getEvidence().filter((e): e is BashEvidence => e.kind === "bash");
+  assert.equal(bash.length, 1, "gsd_exec must be tracked as execution evidence");
+  assert.equal(bash[0].command, "grep -n render index.html");
+  assert.equal(bash[0].exitCode, 0);
+});
+
 // ─── Bug 3: git diff HEAD~1 scope check ─────────────────────────────────────
 
 test("safety-harness-bug3: validateFileChanges works on initial commit (no HEAD~1)", (t) => {
@@ -237,3 +249,20 @@ test("safety-harness-bug3: validateFileChanges works on merge commit", (t) => {
   // Must produce a valid result without throwing
   assert.ok(audit !== null, "audit must be produced for merge commit repo");
 });
+
+test("safety-harness: planned changed file avoids unexpected-file warning", (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-planned-file-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  execFileSync("git", ["init"], { cwd: base });
+  execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: base });
+  execFileSync("git", ["config", "user.name", "Test User"], { cwd: base });
+  writeFileSync(join(base, "index.html"), "<main></main>\n");
+  execFileSync("git", ["add", "index.html"], { cwd: base });
+  execFileSync("git", ["commit", "-m", "add static app"], { cwd: base });
+
+  const audit = validateFileChanges(base, [], ["index.html"]);
+  assert.ok(audit !== null, "audit must be produced");
+  assert.deepEqual(audit!.unexpectedFiles, [], "planned index.html must not be unexpected");
+  assert.deepEqual(audit!.missingFiles, [], "planned index.html must not be missing");
+});

package/src/resources/extensions/gsd/tests/schema-v27-v28-sequence.test.ts

@@ -0,0 +1,156 @@
+// gsd-2 / V27 + V28 schema migration regression tests
+//
+// Same bug class as #4591 (schema-v21-sequence): a migration block can be
+// added but the SCHEMA_VERSION constant left unchanged, causing fresh-install
+// + upgrade paths to silently skip the column add. This file pins both V27
+// (artifacts.content_hash) and V28 (memories.last_hit_at) at the schema and
+// write-path level on fresh-install DBs.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+import {
+  openDatabase,
+  closeDatabase,
+  _getAdapter,
+  insertArtifact,
+  insertMemoryRow,
+  incrementMemoryHitCount,
+  SCHEMA_VERSION,
+} from "../gsd-db.ts";
+
+function makeTmp(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "gsd-v27v28-"));
+}
+
+function cleanup(base: string): void {
+  try { closeDatabase(); } catch { /* noop */ }
+  try { fs.rmSync(base, { recursive: true, force: true }); } catch { /* noop */ }
+}
+
+test("SCHEMA_VERSION constant is at least 28 (V28 migration committed)", () => {
+  assert.ok(
+    SCHEMA_VERSION >= 28,
+    `SCHEMA_VERSION must be ≥ 28 after V28 migration; got ${SCHEMA_VERSION}`,
+  );
+});
+
+test("fresh-install DB has artifacts.content_hash column (V27)", () => {
+  const base = makeTmp();
+  const dbPath = path.join(base, "gsd.db");
+  try {
+    openDatabase(dbPath);
+    const db = _getAdapter()!;
+    const cols = db.prepare("PRAGMA table_info(artifacts)").all() as Array<Record<string, unknown>>;
+    const colNames = new Set(cols.map((c) => c["name"] as string));
+    assert.ok(
+      colNames.has("content_hash"),
+      "V27 must add content_hash column to artifacts on fresh install",
+    );
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("fresh-install DB has memories.last_hit_at column (V28)", () => {
+  const base = makeTmp();
+  const dbPath = path.join(base, "gsd.db");
+  try {
+    openDatabase(dbPath);
+    const db = _getAdapter()!;
+    const cols = db.prepare("PRAGMA table_info(memories)").all() as Array<Record<string, unknown>>;
+    const colNames = new Set(cols.map((c) => c["name"] as string));
+    assert.ok(
+      colNames.has("last_hit_at"),
+      "V28 must add last_hit_at column to memories on fresh install",
+    );
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("fresh-install DB stamps SCHEMA_VERSION (≥28) in schema_version table", () => {
+  const base = makeTmp();
+  const dbPath = path.join(base, "gsd.db");
+  try {
+    openDatabase(dbPath);
+    const db = _getAdapter()!;
+    const row = db.prepare("SELECT MAX(version) as v FROM schema_version").get() as Record<string, unknown> | undefined;
+    const max = (row?.["v"] as number) ?? 0;
+    assert.ok(max >= 28, `fresh install must record schema_version ≥ 28; got ${max}`);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("insertArtifact populates content_hash with SHA-256 of full_content (V27 write-path)", () => {
+  const base = makeTmp();
+  const dbPath = path.join(base, "gsd.db");
+  try {
+    openDatabase(dbPath);
+    insertArtifact({
+      path: "M001/PROJECT.md",
+      artifact_type: "PROJECT",
+      milestone_id: "M001",
+      slice_id: null,
+      task_id: null,
+      full_content: "hello world",
+    });
+
+    const db = _getAdapter()!;
+    const row = db
+      .prepare("SELECT content_hash FROM artifacts WHERE path = :p")
+      .get({ ":p": "M001/PROJECT.md" }) as Record<string, unknown> | undefined;
+    const hash = row?.["content_hash"] as string | null | undefined;
+
+    // SHA-256 of "hello world" hex-encoded:
+    const expected = "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9";
+    assert.equal(hash, expected, "content_hash must be SHA-256 hex of full_content");
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("incrementMemoryHitCount sets last_hit_at alongside hit_count (V28 write-path)", () => {
+  const base = makeTmp();
+  const dbPath = path.join(base, "gsd.db");
+  try {
+    openDatabase(dbPath);
+
+    const created = "2026-01-01T00:00:00.000Z";
+    insertMemoryRow({
+      id: "MEM001",
+      category: "gotcha",
+      content: "test memory",
+      confidence: 0.9,
+      sourceUnitType: null,
+      sourceUnitId: null,
+      createdAt: created,
+      updatedAt: created,
+      scope: "project",
+      tags: [],
+      structuredFields: null,
+    });
+
+    // Before increment: last_hit_at should be NULL
+    const db = _getAdapter()!;
+    const before = db
+      .prepare("SELECT last_hit_at FROM memories WHERE id = :id")
+      .get({ ":id": "MEM001" }) as Record<string, unknown>;
+    assert.equal(before["last_hit_at"], null, "last_hit_at starts NULL on fresh insert");
+
+    const hitTime = "2026-02-01T00:00:00.000Z";
+    incrementMemoryHitCount("MEM001", hitTime);
+
+    const after = db
+      .prepare("SELECT hit_count, last_hit_at FROM memories WHERE id = :id")
+      .get({ ":id": "MEM001" }) as Record<string, unknown>;
+    assert.equal(after["hit_count"], 1, "hit_count increments");
+    assert.equal(after["last_hit_at"], hitTime, "last_hit_at set to provided timestamp");
+  } finally {
+    cleanup(base);
+  }
+});

package/src/resources/extensions/gsd/tests/select-resumable-milestone.test.ts

@@ -0,0 +1,96 @@
+// GSD-2 + src/resources/extensions/gsd/tests/select-resumable-milestone.test.ts
+// Regression: bootstrap must rederive `currentMilestoneId` from an unmerged
+// completed milestone branch when in-memory state was lost across a process
+// restart (#5538-followup).
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { _selectResumableMilestone } from "../auto-start.js";
+
+const ALL_COMPLETE = (_id: string) => true;
+const NEVER_COMPLETE = (_id: string) => false;
+const HAS_COMMITS = (_branch: string) => 1;
+const NO_COMMITS = (_branch: string) => 0;
+
+test("returns null when no branches exist", () => {
+  const result = _selectResumableMilestone([], new Set(), ALL_COMPLETE, HAS_COMMITS);
+  assert.equal(result, null);
+});
+
+test("returns null when every milestone branch is already merged", () => {
+  const branches = ["milestone/M001", "milestone/M002"];
+  const merged = new Set(branches);
+  const result = _selectResumableMilestone(branches, merged, ALL_COMPLETE, HAS_COMMITS);
+  assert.equal(result, null);
+});
+
+test("returns null when no candidate milestones are complete", () => {
+  const branches = ["milestone/M002"];
+  const result = _selectResumableMilestone(branches, new Set(), NEVER_COMPLETE, HAS_COMMITS);
+  assert.equal(result, null);
+});
+
+test("returns null when no branch has commits ahead", () => {
+  const branches = ["milestone/M002"];
+  const result = _selectResumableMilestone(branches, new Set(), ALL_COMPLETE, NO_COMMITS);
+  assert.equal(result, null);
+});
+
+test("returns the unmerged completed milestone (regression: M002 stranded after restart)", () => {
+  // Repro of test12345 state: M001 ✅ merged, M002 ✅ unmerged, M003 🔄.
+  // Bootstrap must seed currentMilestoneId = "M002" so the loop's transition
+  // guard fires when the next iteration sees mid="M003".
+  const branches = ["milestone/M002", "milestone/M003"];
+  const merged = new Set<string>(); // none merged from this list
+  const isComplete = (id: string) => id === "M002"; // M003 still in progress
+  const result = _selectResumableMilestone(branches, merged, isComplete, HAS_COMMITS);
+  assert.equal(result, "M002");
+});
+
+test("picks the lex-greatest milestone when multiple candidates exist", () => {
+  // M001, M002 both unmerged complete -> pick M002 (the most recent).
+  const branches = ["milestone/M001", "milestone/M002"];
+  const result = _selectResumableMilestone(
+    branches,
+    new Set(),
+    ALL_COMPLETE,
+    HAS_COMMITS,
+  );
+  assert.equal(result, "M002");
+});
+
+test("ignores branch names that don't follow the milestone/ prefix", () => {
+  const branches = ["feature/something", "milestone/M002", "fix/bug-1"];
+  const result = _selectResumableMilestone(
+    branches,
+    new Set(),
+    ALL_COMPLETE,
+    HAS_COMMITS,
+  );
+  assert.equal(result, "M002");
+});
+
+test("isComplete callback throwing skips that milestone but does not crash", () => {
+  const branches = ["milestone/M001", "milestone/M002"];
+  const isComplete = (id: string) => {
+    if (id === "M001") throw new Error("db unavailable for M001");
+    return true;
+  };
+  // Implementation choice: a thrown isComplete is propagated. Wrapping in
+  // try/catch happens at the production wrapper level (findUnmergedCompletedMilestone).
+  // Verify the helper itself surfaces the error so callers see real failures.
+  assert.throws(() => _selectResumableMilestone(branches, new Set(), isComplete, HAS_COMMITS));
+});
+
+test("commitsAhead callback throwing for one branch falls through to others", () => {
+  // Production wrapper: commits-ahead failures should not abort the search.
+  // The helper catches throws from commitsAhead per-branch and treats as 0.
+  const branches = ["milestone/M001", "milestone/M002"];
+  const commitsAhead = (branch: string) => {
+    if (branch === "milestone/M001") throw new Error("rev-walk failed");
+    return 5;
+  };
+  const result = _selectResumableMilestone(branches, new Set(), ALL_COMPLETE, commitsAhead);
+  assert.equal(result, "M002");
+});

package/src/resources/extensions/gsd/tests/session-model-override.test.ts

@@ -1,7 +1,5 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
 
 import {
   clearSessionModelOverride,
@@ -9,8 +7,6 @@ import {
   setSessionModelOverride,
 } from "../session-model-override.js";
 
-const phasesSource = readFileSync(join(import.meta.dirname, "..", "auto", "phases.ts"), "utf-8");
-
 test("setSessionModelOverride stores provider/model for the session", () => {
   const sessionId = `session-override-${Date.now()}`;
   setSessionModelOverride(sessionId, { provider: "openai-codex", id: "gpt-5.4" });
@@ -27,9 +23,18 @@ test("clearSessionModelOverride removes the session override", () => {
   assert.equal(getSessionModelOverride(sessionId), undefined);
 });
 
-test("auto dispatch threads manual session model override into selectAndApplyModel", () => {
-  assert.ok(
-    phasesSource.includes("s.manualSessionModelOverride"),
-    "auto/phases.ts should pass s.manualSessionModelOverride into selectAndApplyModel",
-  );
+test("session model overrides are isolated by session id", () => {
+  const first = `session-first-${Date.now()}`;
+  const second = `session-second-${Date.now()}`;
+  setSessionModelOverride(first, { provider: "openai-codex", id: "gpt-5.4" });
+  setSessionModelOverride(second, { provider: "anthropic", id: "claude-sonnet-4-6" });
+
+  assert.deepEqual(getSessionModelOverride(first), {
+    provider: "openai-codex",
+    id: "gpt-5.4",
+  });
+  assert.deepEqual(getSessionModelOverride(second), {
+    provider: "anthropic",
+    id: "claude-sonnet-4-6",
+  });
 });

package/src/resources/extensions/gsd/tests/session-start-footer.test.ts

@@ -206,6 +206,83 @@ test("session_start does NOT call setFooter or suppress gsd-health when isAutoAc
   assert.equal(healthWidgetHideCount, 0, "gsd-health must NOT be hidden when isAutoActive() is false");
 });
 
+test("session_start installs the welcome screen as the TUI header", async (t) => {
+  const dir = join(
+    tmpdir(),
+    `gsd-welcome-header-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+  );
+  mkdirSync(join(dir, "bin"), { recursive: true });
+  mkdirSync(join(dir, "dist"), { recursive: true });
+  writeFileSync(join(dir, "bin", "welcome-screen.js"), "export const stale = true;\n", "utf-8");
+  writeFileSync(
+    join(dir, "dist", "welcome-screen.js"),
+    [
+      "export function buildWelcomeScreenLines(opts) {",
+      "  return [`welcome ${opts.version} ${opts.remoteChannel ?? 'none'} ${opts.width}`];",
+      "}",
+      "",
+    ].join("\n"),
+    "utf-8",
+  );
+
+  const originalCwd = process.cwd();
+  const originalGsdPkgRoot = process.env.GSD_PKG_ROOT;
+  const originalGsdBinPath = process.env.GSD_BIN_PATH;
+  const originalGsdVersion = process.env.GSD_VERSION;
+  const originalFirstRunBanner = process.env.GSD_FIRST_RUN_BANNER;
+  process.chdir(dir);
+  process.env.GSD_PKG_ROOT = dir;
+  process.env.GSD_BIN_PATH = join(dir, "bin", "loader.js");
+  process.env.GSD_VERSION = "9.9.9-test";
+  delete process.env.GSD_FIRST_RUN_BANNER;
+  t.after(() => {
+    process.chdir(originalCwd);
+    if (originalGsdPkgRoot === undefined) delete process.env.GSD_PKG_ROOT;
+    else process.env.GSD_PKG_ROOT = originalGsdPkgRoot;
+    if (originalGsdBinPath === undefined) delete process.env.GSD_BIN_PATH;
+    else process.env.GSD_BIN_PATH = originalGsdBinPath;
+    if (originalGsdVersion === undefined) delete process.env.GSD_VERSION;
+    else process.env.GSD_VERSION = originalGsdVersion;
+    if (originalFirstRunBanner === undefined) delete process.env.GSD_FIRST_RUN_BANNER;
+    else process.env.GSD_FIRST_RUN_BANNER = originalFirstRunBanner;
+    try { rmSync(dir, { recursive: true, force: true }); } catch { /* best-effort */ }
+  });
+
+  const handlers = new Map<string, (event: unknown, ctx: any) => Promise<void> | void>();
+  const pi = {
+    on(event: string, handler: (event: unknown, ctx: any) => Promise<void> | void) {
+      handlers.set(event, handler);
+    },
+  } as any;
+
+  registerHooks(pi, []);
+
+  const sessionStart = handlers.get("session_start");
+  assert.ok(sessionStart, "session_start handler must be registered");
+
+  let headerFactory: ((tui: unknown, theme: unknown) => { render(width: number): string[] }) | undefined;
+  await sessionStart!({}, {
+    hasUI: true,
+    ui: {
+      notify: () => {},
+      setStatus: () => {},
+      setFooter: () => {},
+      setHeader: (factory: typeof headerFactory) => {
+        headerFactory = factory;
+      },
+      setWorkingMessage: () => {},
+      onTerminalInput: () => () => {},
+      setWidget: () => {},
+    },
+    sessionManager: { getSessionId: () => null },
+    model: null,
+  } as any);
+
+  assert.equal(typeof headerFactory, "function", "session_start should install a header factory");
+  const header = headerFactory!({}, {});
+  assert.deepEqual(header.render(123), ["welcome 9.9.9-test none 123"]);
+});
+
 test("session_start and session_switch apply disabled model provider policy from current preferences", async (t) => {
   const dir = join(
     tmpdir(),