gsd-pi 2.80.0-dev.3065f7bfa → 2.80.0-dev.488219eb6

package/src/resources/extensions/gsd/tests/restore-tools-after-discuss.test.ts

@@ -1,93 +1,61 @@
 /**
- * Regression test for #3628 — restore tool set after discuss flow scoping
- *
- * The discuss flow narrows the active tool set to avoid "grammar too complex"
- * errors. Without restoring after sendMessage, the narrowed tools leaked into
- * subsequent dispatches, breaking plan/execute flows.
- *
- * The fix saves the full tool set before scoping and restores it after
- * sendMessage returns.
+ * Regression test for #3628 — restore tool set after discuss flow scoping.
  */
 
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-import { readFileSync } from 'node:fs'
-import { resolve } from 'node:path'
-import { extractSourceRegion } from "./test-helpers.ts";
-
-const src = readFileSync(
-  resolve(process.cwd(), 'src', 'resources', 'extensions', 'gsd', 'guided-flow.ts'),
-  'utf-8',
-)
-
-describe('restore tools after discuss flow scoping (#3628)', () => {
-  it('savedTools is declared before the discuss scoping block', () => {
-    // savedTools must be declared before the discuss-* check
-    const savedToolsDecl = src.indexOf('let savedTools')
-    const discussCheck = src.indexOf('if (unitType?.startsWith("discuss-")')
-    assert.ok(savedToolsDecl !== -1, 'savedTools variable must be declared')
-    assert.ok(discussCheck !== -1, 'discuss-* type check must exist')
-    assert.ok(
-      savedToolsDecl < discussCheck,
-      'savedTools must be declared before the discuss scoping block',
-    )
-  })
-
-  it('savedTools captures current tools before scoping can mutate active state', () => {
-    const discussCheck = src.indexOf('if (unitType?.startsWith("discuss-")')
-    assert.ok(discussCheck !== -1)
-
-    const currentToolsDecl = src.indexOf('const currentTools = pi.getActiveTools()')
-    const savedToolsAssign = src.indexOf('savedTools = {', currentToolsDecl)
-    const firstMutation = src.indexOf('pi.setActiveTools(scopedTools)')
-    assert.ok(
-      currentToolsDecl !== -1 && savedToolsAssign !== -1 && firstMutation !== -1,
-      'guided-flow.ts must capture current tools, save them, and then scope active tools',
-    )
-    assert.ok(
-      currentToolsDecl < savedToolsAssign && savedToolsAssign < firstMutation,
-      'savedTools must capture currentTools before any discuss scoping mutation',
-    )
-    assert.ok(
-      src.slice(savedToolsAssign, firstMutation).includes('tools: currentTools'),
-      'savedTools must include currentTools before the first scoping mutation',
-    )
-  })
-
-  it('scoping and workflow read happen inside the restore try block', () => {
-    const savedToolsDecl = src.indexOf('let savedTools')
-    const tryIdx = src.indexOf('try {', savedToolsDecl)
-    const firstMutation = src.indexOf('pi.setActiveTools(scopedTools)')
-    const workflowRead = src.indexOf('readFileSync(workflowPath')
-    const finallyIdx = src.indexOf('} finally {', tryIdx)
-
-    assert.ok(savedToolsDecl !== -1, 'savedTools variable must be declared')
-    assert.ok(tryIdx !== -1, 'restore try block must exist')
-    assert.ok(firstMutation !== -1, 'discuss scoping mutation must exist')
-    assert.ok(workflowRead !== -1, 'workflow file read must exist')
-    assert.ok(finallyIdx !== -1, 'restore finally block must exist')
-    assert.ok(tryIdx < firstMutation && firstMutation < finallyIdx, 'scoping mutation must be inside try/finally')
-    assert.ok(tryIdx < workflowRead && workflowRead < finallyIdx, 'workflow file read must be inside try/finally')
-  })
-
-  it('savedTools is restored after sendMessage', () => {
-    // #4573: guided-flow.ts now contains multiple `triggerTurn: true` calls
-    // (ready-phrase and empty-turn recovery paths). The discuss-flow scoping
-    // sendMessage is the one that follows `tools: currentTools`, so
-    // anchor the search there rather than at the first `triggerTurn: true`.
-    const savedToolsAssign = src.indexOf('tools: currentTools')
-    assert.ok(savedToolsAssign !== -1, 'savedTools must capture currentTools')
-
-    const sendMsg = src.indexOf('triggerTurn: true', savedToolsAssign)
-    assert.ok(sendMsg !== -1, 'discuss-flow sendMessage with triggerTurn must exist after savedTools capture')
-
-    // After sendMessage, savedTools should be restored via the shared helper.
-    // Use fromIdx to anchor at the discuss-flow sendMessage, not the first
-    // triggerTurn: true occurrence in the file.
-    const afterSend = extractSourceRegion(src, 'triggerTurn: true', { fromIdx: savedToolsAssign })
-    assert.ok(
-      afterSend.includes('restoreGsdWorkflowTools(pi, savedTools)'),
-      'restoreGsdWorkflowTools(pi, savedTools) must restore the full scoped state',
-    )
-  })
-})
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { _dispatchWorkflowForTest } from "../guided-flow.ts";
+
+test("discuss workflow scopes tools for the queued turn and restores the full tool set", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-discuss-tools-"));
+  const workflowPath = join(dir, "GSD-WORKFLOW.md");
+  const originalWorkflowPath = process.env.GSD_WORKFLOW_PATH;
+  const originalTools = [
+    "gsd_task_complete",
+    "gsd_summary_save",
+    "shell_exec",
+    "gsd_plan_milestone",
+  ];
+  let activeTools = [...originalTools];
+  let sentTools: string[] | null = null;
+  let triggerTurn = false;
+
+  const pi = {
+    getActiveTools: () => [...activeTools],
+    setActiveTools: (tools: string[]) => {
+      activeTools = [...tools];
+    },
+    sendMessage: (_message: unknown, options?: { triggerTurn?: boolean }) => {
+      sentTools = [...activeTools];
+      triggerTurn = options?.triggerTurn === true;
+    },
+  };
+
+  try {
+    writeFileSync(workflowPath, "# Workflow\n", "utf-8");
+    process.env.GSD_WORKFLOW_PATH = workflowPath;
+
+    await _dispatchWorkflowForTest(
+      pi as any,
+      "Interview the user.",
+      "gsd-discuss",
+      undefined,
+      "discuss-milestone",
+    );
+
+    assert.deepEqual(sentTools, ["gsd_summary_save"]);
+    assert.deepEqual(activeTools, originalTools);
+    assert.equal(triggerTurn, true);
+  } finally {
+    if (originalWorkflowPath === undefined) {
+      delete process.env.GSD_WORKFLOW_PATH;
+    } else {
+      process.env.GSD_WORKFLOW_PATH = originalWorkflowPath;
+    }
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/resume-dispatch-worktree.test.ts

@@ -1,15 +1,6 @@
 /**
- * Tests for fix of #3723: auto-mode resume/crash-recovery dispatches
- * from project root instead of milestone worktree.
- *
- * During resume, the paused-session metadata may record `worktreePath` that
- * was active when the session paused. The resume path must use that path (or
- * derive the worktree path via filesystem lookup) to set the dispatch context
- * (`s.basePath`), rather than defaulting to the project root.
- *
- * The fix adds an early worktree-path resolution step in the paused-session
- * resume block of auto.ts — immediately after `s.basePath = base` — so that
- * the correct dispatch directory is used before the dispatch loop runs.
+ * Tests for fix of #3723: auto-mode resume/crash-recovery dispatches from
+ * the paused milestone worktree when that worktree still exists.
  */
 
 import test from "node:test";
@@ -18,95 +9,8 @@ import { readFileSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
-import { fileURLToPath } from "node:url";
-import { dirname } from "node:path";
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const autoSrc = readFileSync(join(__dirname, "..", "auto.ts"), "utf-8");
-
-// ── Source-structure tests ────────────────────────────────────────────────────
-
-/**
- * Extract the paused-session resume block from auto.ts.
- *
- * The block we care about is the `if (s.paused) { ... }` section inside
- * startAuto, which contains `s.basePath = base` (line ~1473) followed by the
- * `enterMilestone` call.
- *
- * We find it by locating the `s.basePath = base` assignment that appears
- * WITHIN the s.paused branch (there's only one: all other basePath assignments
- * use originalBasePath or a different value). We extract from that assignment
- * up to just before `enterMilestone(`.
- */
-function getBasepathToEnterMilestoneSegment(): string {
-  // Find `s.basePath = base;` in the s.paused branch
-  // This assignment appears uniquely inside the resume block
-  const assignPattern = "s.basePath = base;";
-  const assignIdx = autoSrc.indexOf(assignPattern);
-  assert.ok(
-    assignIdx > -1,
-    `auto.ts must contain '${assignPattern}' in the resume block`,
-  );
-
-  // Find the next enterMilestone call after this assignment
-  const enterMilestoneIdx = autoSrc.indexOf("enterMilestone(", assignIdx);
-  assert.ok(
-    enterMilestoneIdx > assignIdx,
-    "auto.ts must call enterMilestone after the s.basePath = base assignment",
-  );
-
-  // Return the code between the assignment and enterMilestone
-  return autoSrc.slice(assignIdx, enterMilestoneIdx);
-}
-
-test("auto.ts resume block resolves paused-session worktreePath and applies it to s.basePath before entering worktree (fixes #3723)", () => {
-  // The segment between `s.basePath = base` and `enterMilestone(` must
-  // contain logic that resolves the paused-session worktreePath and applies
-  // it to s.basePath when the worktree exists on disk.
-  //
-  // The fix reads the worktree path from freshStartAssessment.pausedSession
-  // (since `meta` is out of scope at this point in startAuto) and assigns
-  // it to s.basePath, guarded by existsSync.
-  //
-  // Without this fix, the dispatch loop runs from `base` (project root)
-  // instead of the worktree, causing split-brain execution (#3723).
-  const segment = getBasepathToEnterMilestoneSegment();
-
-  // The fix uses freshStartAssessment.pausedSession?.worktreePath via a
-  // local variable (resumeWorktreePath) and assigns to s.basePath.
-  const hasWorktreePathResolution =
-    segment.includes("worktreePath") &&
-    segment.includes("existsSync") &&
-    segment.includes("s.basePath =");
-
-  assert.ok(
-    hasWorktreePathResolution,
-    "auto.ts must resolve the paused-session worktreePath, check existsSync, and assign " +
-    "s.basePath before enterMilestone — crash-recovery currently dispatches from project root " +
-    "instead of milestone worktree (issue #3723). The fix belongs between `s.basePath = base` " +
-    "and the enterMilestone call.",
-  );
-});
-
-test("auto.ts worktreePath assignment in resume block guards against non-existent path (fixes #3723)", () => {
-  // The assignment to s.basePath from the paused-session worktreePath must
-  // be guarded by existsSync to avoid setting an invalid basePath if the
-  // worktree was cleaned up between pause and resume.
-  const segment = getBasepathToEnterMilestoneSegment();
-
-  // Must have existsSync guard AND a worktreePath reference AND s.basePath assignment
-  const hasGuardedAssignment =
-    segment.includes("existsSync") &&
-    segment.includes("worktreePath") &&
-    segment.includes("s.basePath =");
-
-  assert.ok(
-    hasGuardedAssignment,
-    "auto.ts must guard the s.basePath = worktreePath assignment with existsSync (fixes #3723)",
-  );
-});
-
-// ── Functional tests ──────────────────────────────────────────────────────────
+import { _resolvePausedResumeBasePathForTest } from "../auto.ts";
 
 function makeTmpBase(): string {
   const base = join(tmpdir(), `gsd-resume-wt-${randomUUID()}`);
@@ -115,7 +19,7 @@ function makeTmpBase(): string {
 }
 
 function cleanup(base: string): void {
-  try { rmSync(base, { recursive: true, force: true }); } catch { /* */ }
+  try { rmSync(base, { recursive: true, force: true }); } catch { /* noop */ }
 }
 
 function writePausedSession(
@@ -142,7 +46,6 @@ function makeWorktreePath(base: string, milestoneId: string): string {
 
 function setupWorktreeOnDisk(wt: string): void {
   mkdirSync(wt, { recursive: true });
-  // Simulate a git worktree: .git file with gitdir pointer
   writeFileSync(
     join(wt, ".git"),
     "gitdir: /project/.git/worktrees/M001-test\n",
@@ -150,81 +53,46 @@ function setupWorktreeOnDisk(wt: string): void {
   );
 }
 
-function writeRoadmap(base: string, milestoneId = "M001-test"): void {
-  const milestoneDir = join(base, ".gsd", "milestones", milestoneId);
-  mkdirSync(join(milestoneDir, "slices", "S01", "tasks"), { recursive: true });
-  writeFileSync(
-    join(milestoneDir, `${milestoneId}-ROADMAP.md`),
-    [
-      `# ${milestoneId}: Test Milestone`,
-      "",
-      "## Slices",
-      "",
-      "- [ ] **S01: Test slice** `risk:low`",
-      "  After this: Demo",
-    ].join("\n"),
-    "utf-8",
-  );
-}
+test("resume base path uses paused-session worktreePath when the worktree exists", () => {
+  const base = makeTmpBase();
+  const wt = makeWorktreePath(base, "M001-test");
+  try {
+    setupWorktreeOnDisk(wt);
+    assert.equal(
+      _resolvePausedResumeBasePathForTest(base, wt),
+      wt,
+    );
+  } finally {
+    cleanup(base);
+  }
+});
 
-test("readPausedSessionMetadata round-trips worktreePath from paused-session.json", () => {
-  // Verify that the paused-session metadata correctly stores and reads back
-  // the worktreePath field — this is what the resume path in auto.ts uses
-  // to determine the dispatch basePath (#3723).
-  //
-  // Implemented inline to avoid slow import chain from interrupted-session.ts.
+test("resume base path falls back to project root when paused worktree is missing", () => {
+  const base = makeTmpBase();
+  const wt = makeWorktreePath(base, "M001-test");
+  try {
+    assert.equal(
+      _resolvePausedResumeBasePathForTest(base, wt),
+      base,
+    );
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("read paused-session metadata round-trips worktreePath from paused-session.json", () => {
   const base = makeTmpBase();
   const wt = makeWorktreePath(base, "M001-test");
   try {
     setupWorktreeOnDisk(wt);
     writePausedSession(base, "M001-test", wt);
 
-    // Simulate readPausedSessionMetadata without importing the full module
     const pausedPath = join(base, ".gsd", "runtime", "paused-session.json");
     const meta = JSON.parse(readFileSync(pausedPath, "utf-8"));
 
-    assert.ok(meta, "paused-session metadata must be readable");
     assert.equal(meta.milestoneId, "M001-test");
-    assert.equal(meta.worktreePath, wt, "worktreePath must round-trip through paused-session.json");
+    assert.equal(meta.worktreePath, wt);
   } finally {
     cleanup(base);
   }
 });
-
-test("auto.ts resume block uses worktreePath from freshStartAssessment.pausedSession as dispatch basePath when worktree exists (#3723)", () => {
-  // End-to-end structural verification: the auto.ts source must contain code
-  // that reads the worktreePath from freshStartAssessment.pausedSession AND
-  // applies it to s.basePath (guarded by existsSync) between the
-  // `s.basePath = base` assignment and `enterMilestone`.
-  //
-  // This is the core of the #3723 fix. Without this check, a session that
-  // paused while operating inside a worktree will resume dispatching from the
-  // project root, not the worktree — causing split-brain execution where some
-  // operations target the worktree and others target the project root.
-  const segment = getBasepathToEnterMilestoneSegment();
-
-  // Must reference freshStartAssessment.pausedSession?.worktreePath or
-  // equivalent local variable, AND contain an existsSync guard
-  const hasAssessmentWorktreePath =
-    segment.includes("freshStartAssessment.pausedSession") &&
-    segment.includes("worktreePath");
-
-  assert.ok(
-    hasAssessmentWorktreePath,
-    "auto.ts must read worktreePath from freshStartAssessment.pausedSession between " +
-    "s.basePath=base and enterMilestone",
-  );
-  assert.ok(
-    segment.includes("existsSync"),
-    "auto.ts must guard worktreePath usage with existsSync",
-  );
-  // The actual basePath re-assignment must be present in the segment
-  // (note: there are multiple `s.basePath =` assignments — we need one after
-  // the initial `s.basePath = base` assignment within this segment)
-  const worktreeAssignIdx = segment.lastIndexOf("s.basePath =");
-  const baseAssignIdx = segment.indexOf("s.basePath = base");
-  assert.ok(
-    worktreeAssignIdx > baseAssignIdx,
-    "auto.ts must assign s.basePath to the worktree path after `s.basePath = base` in the resume block",
-  );
-});

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/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(),