@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.eed73bea

package/src/resources/extensions/gsd/tests/replan-handler.test.ts

@@ -21,7 +21,7 @@ import { parsePlan } from '../parsers-legacy.ts';
 
 function makeTmpBase(): string {
   const base = mkdtempSync(join(tmpdir(), 'gsd-replan-'));
-  mkdirSync(join(base, '.gsd', 'milestones', 'M001', 'slices', 'S01', 'tasks'), { recursive: true });
+  mkdirSync(join(base, '.gsd', 'phases', '01-test'), { recursive: true });
   return base;
 }
 
@@ -230,11 +230,11 @@ test('handleReplanSlice succeeds when modifying only incomplete tasks', async ()
     assert.equal(t01?.status, 'complete');
 
     // Verify rendered PLAN.md exists on disk
-    const planPath = join(base, '.gsd', 'milestones', 'M001', 'slices', 'S01', 'S01-PLAN.md');
+    const planPath = join(base, '.gsd', 'phases', '01-test', '01-01-PLAN.md');
     assert.ok(existsSync(planPath), 'PLAN.md should be rendered to disk');
 
     // Verify REPLAN.md exists on disk
-    const replanPath = join(base, '.gsd', 'milestones', 'M001', 'slices', 'S01', 'S01-REPLAN.md');
+    const replanPath = join(base, '.gsd', 'phases', '01-test', '01-01-REPLAN.md');
     assert.ok(existsSync(replanPath), 'REPLAN.md should be rendered to disk');
     const replanContent = readFileSync(replanPath, 'utf-8');
     assert.ok(replanContent.includes('Blocker Description'), 'REPLAN.md should contain blocker section');
@@ -272,7 +272,7 @@ test('handleReplanSlice cache invalidation: re-parsing PLAN.md reflects mutation
     assert.ok(!('error' in result), `unexpected error: ${'error' in result ? result.error : ''}`);
 
     // Re-parse PLAN.md from disk to verify cache invalidation worked
-    const planPath = join(base, '.gsd', 'milestones', 'M001', 'slices', 'S01', 'S01-PLAN.md');
+    const planPath = join(base, '.gsd', 'phases', '01-test', '01-01-PLAN.md');
     const content = readFileSync(planPath, 'utf-8');
     const parsed = parsePlan(content);
 

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

@@ -114,19 +114,19 @@ describe("resume: missing worktree warning emission", () => {
     assert.equal(peekLogs().length, 0);
   });
 
-  test("warning message mentions project-root fallback action", () => {
+  test("warning message mentions project-root fallback and worktree recreation", () => {
     const missingPath = join(projectDir, ".gsd", "worktrees", "M099-deleted");
     _warnIfWorktreeMissingForTest(missingPath, "M099");
 
     const logs = peekLogs();
     assert.equal(logs.length, 1);
     assert.ok(
-      logs[0].message.includes("project-root mode"),
-      "warning should mention project-root mode fallback",
+      logs[0].message.includes("project root"),
+      "warning should mention project-root fallback",
     );
     assert.ok(
-      logs[0].message.includes("gsd-debug"),
-      "warning should suggest /gsd-debug recovery action",
+      logs[0].message.includes("/gsd next"),
+      "warning should suggest /gsd next to recreate the worktree",
     );
   });
 });

package/src/resources/extensions/gsd/tests/roadmap-parse-regression.test.ts

@@ -396,4 +396,44 @@ test('T. #1736: Checkbox format unchanged', () => {
     assert.deepStrictEqual(slices[1].done, false, '#1736 checkbox compat: S02 not done');
 });
 
+// ═══════════════════════════════════════════════════════════════════════
+// U. Regression #566: double-bracket depends serialization recovery
+// ═══════════════════════════════════════════════════════════════════════
+test('U. #566: double-bracket depends:[[S01]] recovers to ["S01"]', () => {
+    // Simulates a roadmap written by markdown-renderer when the DB had
+    // depends=["[S01]"] — produces `depends:[[S01]]` on disk.
+    const content = [
+      '# M020: Corrupted Depends',
+      '',
+      '## Slices',
+      '',
+      '- [ ] **S01: Foundation** `risk:low` `depends:[]`',
+      '- [ ] **S02: Build** `risk:medium` `depends:[[S01]]`',
+      '- [ ] **S03: Ship** `risk:high` `depends:[[S01, S02]]`',
+      '',
+    ].join('\n');
+
+    const slices = parseRoadmapSlices(content);
+    assert.deepStrictEqual(slices.length, 3, '#566 double-bracket: 3 slices');
+    assert.deepStrictEqual(slices[1].depends, ['S01'], '#566: S02 depends recovered to ["S01"]');
+    assert.deepStrictEqual(slices[2].depends, ['S01', 'S02'], '#566: S03 depends recovered to ["S01","S02"]');
+});
+
+test('U. #566: bracket-wrapped single element depends:[[S01]] recovers to ["S01"]', () => {
+    // Simulates the exact DB corruption seen in the forensic evidence: depends=["[S01]"]
+    const content = [
+      '# M020: Single Bracket Corruption',
+      '',
+      '## Slices',
+      '',
+      '- [ ] **S01: First** `risk:low` `depends:[]`',
+      '- [ ] **S02: Second** `risk:medium` `depends:[[S01]]`',
+      '',
+    ].join('\n');
+
+    const slices = parseRoadmapSlices(content);
+    assert.deepStrictEqual(slices[1].depends.length, 1, '#566 single: S02 has exactly 1 dep');
+    assert.deepStrictEqual(slices[1].depends[0], 'S01', '#566 single: dep is "S01" not "[S01]"');
+});
+
 });

package/src/resources/extensions/gsd/tests/roadmap-slices.test.ts

@@ -200,6 +200,74 @@ test("parseRoadmapSlices: checkbox slices with pipe characters do not switch to
   assert.deepEqual(slices[2]?.depends, ["S01", "S02"]);
 });
 
+test("parseRoadmapSlices: demo markdown table does not switch checkbox roadmap to table mode (#721)", () => {
+  const checkboxWithDemoTable = [
+    "# M004: Demo Table Repro",
+    "",
+    "## Slices",
+    "",
+    "- [x] **S01: First** `risk:low` `depends:[]`",
+    "  > After this: cli can render examples:",
+    "| Example | Meaning |",
+    "| --- | --- |",
+    "| S01 | Not a roadmap row |",
+    "- [ ] **S02: Second** `risk:medium` `depends:[S01]`",
+    "  > After this: cat file | sort returns stable output.",
+    "",
+  ].join("\n");
+
+  const slices = parseRoadmapSlices(checkboxWithDemoTable);
+  assert.equal(slices.length, 2);
+  assert.equal(slices[0]?.id, "S01");
+  assert.equal(slices[0]?.title, "First");
+  assert.equal(slices[0]?.done, true);
+  assert.equal(slices[1]?.id, "S02");
+  assert.deepEqual(slices[1]?.depends, ["S01"]);
+});
+
+test("parseRoadmapSlices: table preceded by intro prose still parsed as table (#722)", () => {
+  const tableWithIntro = [
+    "# M005: Intro Before Table",
+    "",
+    "## Slices",
+    "",
+    "This milestone is broken into the following slices:",
+    "",
+    "| Slice | Title | Risk | Status |",
+    "| --- | --- | --- | --- |",
+    "| S01 | Foundation | Low | [x] Done |",
+    "| S02 | Core | High | [ ] Pending |",
+    "",
+  ].join("\n");
+
+  const slices = parseRoadmapSlices(tableWithIntro);
+  assert.equal(slices.length, 2);
+  assert.equal(slices[0]?.id, "S01");
+  assert.equal(slices[0]?.done, true);
+  assert.equal(slices[1]?.id, "S02");
+  assert.equal(slices[1]?.done, false);
+});
+
+test("parseRoadmapSlices: table without markdown separator row still parsed as table (#722)", () => {
+  const tableWithoutSeparator = [
+    "# M006: No Separator",
+    "",
+    "## Slices",
+    "",
+    "| Slice | Title | Risk | Status |",
+    "| S01 | Foundation | Low | [x] Done |",
+    "| S02 | Core | High | [ ] Pending |",
+    "",
+  ].join("\n");
+
+  const slices = parseRoadmapSlices(tableWithoutSeparator);
+  assert.equal(slices.length, 2);
+  assert.equal(slices[0]?.id, "S01");
+  assert.equal(slices[0]?.done, true);
+  assert.equal(slices[1]?.id, "S02");
+  assert.equal(slices[1]?.done, false);
+});
+
 // --- Prose slice header completion marker tests (#1803) ---
 
 test("parseRoadmapSlices: prose headers with ✓ marker detected as done", () => {

package/src/resources/extensions/gsd/tests/round-trip-property.test.ts

@@ -0,0 +1,137 @@
+// Project/App: gsd-pi
+// File Purpose: Round-trip property test — for any gsd-core .gsd/ fixture,
+// import → render → import must produce a stable hierarchy snapshot, and
+// re-rendering must produce stable markdown. Catches lossy-projection bugs
+// that would otherwise silently destroy state across cross-tool round-trips.
+import test, { afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { cpSync, mkdtempSync, rmSync, readdirSync, readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+import { openDatabase, closeDatabase, getAllMilestones, getMilestoneSlices, getSliceTasks } from "../gsd-db.ts";
+import { migrateHierarchyToDb } from "../md-importer.ts";
+import { renderAllFromDb } from "../markdown-renderer.ts";
+import { invalidateStateCache } from "../state.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const FIXTURE_ROOT = join(__dirname, "__fixtures__", "round-trip");
+
+const tmpDirs: string[] = [];
+afterEach(() => {
+  closeDatabase();
+  for (const d of tmpDirs) { try { rmSync(d, { recursive: true, force: true }); } catch { /* */ } }
+  tmpDirs.length = 0;
+});
+
+function copyFixture(name: string): string {
+  const base = mkdtempSync(join(tmpdir(), `gsd-rt-${randomUUID()}`));
+  cpSync(join(FIXTURE_ROOT, name), base, { recursive: true });
+  tmpDirs.push(base);
+  return base;
+}
+
+interface HierarchySnapshot {
+  milestones: Array<{ id: string; title: string; status: string }>;
+  slices: Array<{ mid: string; id: string; title: string; status: string }>;
+  tasks: Array<{ mid: string; sid: string; id: string; title: string; status: string }>;
+}
+
+function snapshotHierarchy(): HierarchySnapshot {
+  const milestones = getAllMilestones().map((m) => ({ id: m.id, title: m.title, status: m.status }));
+  const slices: HierarchySnapshot["slices"] = [];
+  const tasks: HierarchySnapshot["tasks"] = [];
+  for (const m of milestones) {
+    for (const s of getMilestoneSlices(m.id)) {
+      slices.push({ mid: m.id, id: s.id, title: s.title, status: s.status });
+      for (const t of getSliceTasks(m.id, s.id)) {
+        tasks.push({ mid: m.id, sid: s.id, id: t.id, title: t.title, status: t.status });
+      }
+    }
+  }
+  // Sort for stable comparison across DB row-order variations.
+  const cmp = <T extends { id: string }>(a: T, b: T) => a.id.localeCompare(b.id);
+  milestones.sort(cmp);
+  slices.sort((a, b) => `${a.mid}/${a.id}`.localeCompare(`${b.mid}/${b.id}`));
+  tasks.sort((a, b) => `${a.mid}/${a.sid}/${a.id}`.localeCompare(`${b.mid}/${b.sid}/${b.id}`));
+  return { milestones, slices, tasks };
+}
+
+test("round-trip is stable: import → render → import produces the same hierarchy snapshot", async () => {
+  // Only .gsd/-bearing fixtures — the .planning/ fixtures belong to the
+  // planning round-trip suite (different layout, no .gsd/ to import from).
+  const fixtures = readdirSync(FIXTURE_ROOT, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && existsSync(join(FIXTURE_ROOT, d.name, ".gsd")))
+    .map((d) => d.name);
+
+  assert.ok(fixtures.length > 0, "expected at least one round-trip fixture");
+
+  for (const name of fixtures) {
+    const base = copyFixture(name);
+    openDatabase(join(base, ".gsd", "gsd.db"));
+
+    // Pass 1: import fixture markdown → DB
+    migrateHierarchyToDb(base);
+    invalidateStateCache();
+    const snapshot1 = snapshotHierarchy();
+    assert.ok(snapshot1.milestones.length > 0, `fixture ${name}: expected at least one milestone after import`);
+
+    // Render DB → markdown (projection)
+    const render1 = await renderAllFromDb(base);
+    assert.deepEqual(render1.errors, [], `pass 1 render errors for ${name}: ${JSON.stringify(render1.errors)}`);
+
+    // Pass 2: re-import the projected markdown → DB. migrateHierarchyToDb is
+    // an idempotent upsert (INSERT OR IGNORE), so this simulates a second tool
+    // opening the re-projected files and importing them.
+    migrateHierarchyToDb(base);
+    invalidateStateCache();
+    const snapshot2 = snapshotHierarchy();
+
+    // Property: hierarchy must be stable across the round-trip.
+    assert.deepEqual(
+      snapshot2,
+      snapshot1,
+      `round-trip drift for fixture ${name}: hierarchy changed across import → render → import`,
+    );
+  }
+});
+
+test("round-trip is idempotent: rendering twice produces stable markdown", async () => {
+  const fixtures = readdirSync(FIXTURE_ROOT, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && existsSync(join(FIXTURE_ROOT, d.name, ".gsd")))
+    .map((d) => d.name);
+
+  for (const name of fixtures) {
+    const base = copyFixture(name);
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    migrateHierarchyToDb(base);
+    invalidateStateCache();
+    await renderAllFromDb(base);
+
+    // Snapshot all rendered markdown files (normalized: CRLF→LF, trailing
+    // whitespace trimmed) so cosmetic differences don't false-positive.
+    const snapshotFiles = (b: string): Record<string, string> => {
+      const out: Record<string, string> = {};
+      const walk = (dir: string) => {
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+          const p = join(dir, e.name);
+          if (e.isDirectory()) walk(p);
+          else if (e.name.endsWith(".md")) {
+            out[p.replace(b + "/", "")] = readFileSync(p, "utf-8").replace(/\r\n/g, "\n").replace(/[ \t]+\n/g, "\n");
+          }
+        }
+      };
+      walk(join(b, ".gsd"));
+      return out;
+    };
+    const after1 = snapshotFiles(base);
+
+    // Render again
+    await renderAllFromDb(base);
+    const after2 = snapshotFiles(base);
+
+    assert.deepEqual(after2, after1, `re-rendering changed markdown for fixture ${name}`);
+  }
+});

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

@@ -6,7 +6,11 @@ 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 {
+  compileUnitContextContract,
+  compileUnitToolContract,
+  getUnitWorkflowDispatchReadinessError,
+} from "../tool-contract.js";
 import { shouldBlockAutoUnitToolCall } from "../auto-unit-tool-scope.js";
 import type { GSDState } from "../types.js";
 
@@ -63,11 +67,27 @@ test("Tool Contract compiles known Unit prompt and tool policy", () => {
 
   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.deepEqual(result.ok && result.contract.requiredWorkflowTools, [
+    "gsd_task_complete",
+    "gsd_exec",
+    "gsd_exec_search",
+    "gsd_resume",
+    "gsd_capture_thought",
+  ]);
   assert.deepEqual(result.ok && result.contract.forbiddenWorkflowTools, []);
   assert.equal(result.ok && result.contract.toolsPolicy.mode, "all");
   assert.ok(result.ok && result.contract.validationRules.includes("closeout-tool-present"));
   assert.ok(result.ok && result.contract.validationRules.includes("source-observation-contract-present"));
+  assert.deepEqual(result.ok && result.contract.promptContext.artifacts.inline, [
+    "task-plan",
+    "slice-plan",
+    "prior-task-summaries",
+    "templates",
+  ]);
+  assert.deepEqual(result.ok && result.contract.promptContext.artifacts.onDemand, ["slice-research"]);
+  assert.ok(result.ok && result.contract.promptObligations.includes("context-inline:task-plan,slice-plan,prior-task-summaries,templates"));
+  assert.ok(result.ok && result.contract.promptObligations.includes("context-on-demand:slice-research"));
+  assert.ok(result.ok && result.contract.promptObligations.includes("source-observations:whole-file-active-unit"));
   assert.deepEqual(result.ok && result.contract.sourceObservations, {
     mode: "whole-file-active-unit",
     seedFields: ["task.files", "task.inputs"],
@@ -77,6 +97,34 @@ test("Tool Contract compiles known Unit prompt and tool policy", () => {
   });
 });
 
+test("Tool Contract derives dispatch readiness from Unit workflow tools", () => {
+  const error = getUnitWorkflowDispatchReadinessError({
+    provider: "claude-code",
+    unitType: "plan-slice",
+    projectRoot: "/tmp/project",
+    env: { GSD_WORKFLOW_MCP_COMMAND: "node" },
+    surface: "auto-mode",
+    authMode: "externalCli",
+    baseUrl: "local://claude-code",
+  });
+
+  assert.equal(error, null);
+});
+
+test("Unit Context Contract exposes prompt context without workflow tool surface", () => {
+  const result = compileUnitContextContract("execute-task");
+
+  assert.equal(result.ok, true);
+  assert.equal(result.ok && result.contract.unitType, "execute-task");
+  assert.equal(result.ok && result.contract.contextMode, "execution");
+  assert.equal(result.ok && result.contract.toolsPolicy.mode, "all");
+  assert.deepEqual(result.ok && result.contract.artifacts.excerpt, []);
+  assert.deepEqual(result.ok && result.contract.artifacts.computed, []);
+  assert.deepEqual(result.ok && result.contract.artifacts.prepend, []);
+  assert.equal(result.ok && result.contract.maxSystemPromptChars, 1_500_000);
+  assert.equal(result.ok && result.contract.sourceObservations.mode, "whole-file-active-unit");
+});
+
 test("Tool Contract records high-risk cross-phase tool boundaries without single-owning every tool", () => {
   const completeSlice = compileUnitToolContract("complete-slice");
   const runUat = compileUnitToolContract("run-uat");
@@ -140,6 +188,7 @@ test("Recovery Classification covers ADR-015 failure families", () => {
   const cases = [
     ["invalid tool schema enum", "tool-schema", "stop"],
     ["Tool Contract failure: complete-slice cannot use gsd_uat_result_save", "tool-contract", "stop"],
+    ["No such tool available: mcp__gsd-workflow__gsd_uat_exec", "tool-unavailable", "retry"],
     ["deterministic policy rejection", "deterministic-policy", "stop"],
     ["cannot legally advance because required UAT Assessment artifact is missing", "lifecycle-progression", "stop"],
     ["stale worker lease", "stale-worker", "stop"],

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

@@ -266,3 +266,41 @@ test("safety-harness: planned changed file avoids unexpected-file warning", (t)
   assert.deepEqual(audit!.unexpectedFiles, [], "planned index.html must not be unexpected");
   assert.deepEqual(audit!.missingFiles, [], "planned index.html must not be missing");
 });
+
+// ─── External engine evidence (claude-code-cli pre-executed tools) ──────────
+// External engines skip beforeToolCall/tool_call, so register-hooks.ts records
+// evidence at tool_execution_start instead. These tests lock the collector
+// semantics that wiring relies on: idempotent recording by toolCallId, and
+// capitalized external tool names (Bash/Write/Edit) being recognized.
+
+test("safety-harness: recordToolCall is idempotent by toolCallId", () => {
+  resetEvidence();
+
+  // Native tools fire tool_execution_start AND tool_call — both record.
+  recordToolCall("tc-dup-1", "bash", { command: "npm test" });
+  recordToolCall("tc-dup-1", "bash", { command: "npm test" });
+
+  assert.equal(getEvidence().length, 1, "same toolCallId must not duplicate");
+});
+
+test("safety-harness: external capitalized Bash call records and resolves evidence", () => {
+  resetEvidence();
+
+  // tool_execution_start with Claude Code's native tool name
+  recordToolCall("ext-bash-1", "Bash", { command: "node /tmp/t01-verify.mjs" });
+  const entries = getEvidence().filter((e): e is BashEvidence => e.kind === "bash");
+  assert.equal(entries.length, 1, "capitalized Bash must be recognized as execution tool");
+  assert.equal(entries[0]!.command, "node /tmp/t01-verify.mjs");
+
+  // tool_execution_end fills the result
+  recordToolResult("ext-bash-1", "Bash", { content: [{ type: "text", text: "13 checks passed" }] }, false);
+  assert.equal(entries[0]!.exitCode, 0, "non-error external result resolves to exitCode 0");
+});
+
+test("safety-harness: external Write call records file evidence", () => {
+  resetEvidence();
+
+  recordToolCall("ext-write-1", "Write", { file_path: "/tmp/app/index.html" });
+  const writes = getEvidence().filter((e) => e.kind === "write");
+  assert.equal(writes.length, 1, "capitalized Write must record file evidence");
+});

package/src/resources/extensions/gsd/tests/session-lock-transient-read.test.ts

@@ -8,6 +8,7 @@
  *
  * Tests:
  *   - readExistingLockDataWithRetry retries on transient read failure
+ *   - readExistingLockDataWithRetry sleeps between retries without CPU spin
  *   - readExistingLockDataWithRetry returns data when file becomes readable after retries
  *   - readExistingLockDataWithRetry returns null only when ALL retries exhausted
  *   - onCompromised does not declare compromise when lock file is transiently unreadable
@@ -75,6 +76,31 @@ async function main(): Promise<void> {
     }
   }
 
+  // ─── 2b. Retry delay sleeps without CPU spin ──────────────────────────────
+  console.log('\n=== 2b. readExistingLockDataWithRetry sleeps between retry attempts ===');
+  {
+    const base = mkdtempSync(join(tmpdir(), 'gsd-transient-'));
+    mkdirSync(join(base, '.gsd'), { recursive: true });
+    const originalWait = Atomics.wait;
+    const waits: Array<number | undefined> = [];
+
+    try {
+      const lockFile = join(gsdRoot(base), 'auto.lock');
+      Atomics.wait = ((_typedArray: Int32Array, _index: number, _value: number, timeout?: number) => {
+        waits.push(timeout);
+        return 'timed-out';
+      }) as typeof Atomics.wait;
+
+      const result = readExistingLockDataWithRetry(lockFile, { maxAttempts: 3, delayMs: 17 });
+      assertEq(result, null, 'null for missing file after instrumented retries');
+      assertEq(waits.length, 2, 'sleep called only between failed attempts');
+      assertEq(waits, [17, 17], 'sleep preserves delayMs across retries');
+    } finally {
+      Atomics.wait = originalWait;
+      rmSync(base, { recursive: true, force: true });
+    }
+  }
+
   // ─── 3. readExistingLockDataWithRetry recovers after transient rename ──────
   console.log('\n=== 3. readExistingLockDataWithRetry recovers after transient unavailability ===');
   {
@@ -96,8 +122,8 @@ async function main(): Promise<void> {
 
       // Simulate transient unavailability: move file away, spawn a child process
       // to restore it shortly after. The child runs outside our event loop so it
-      // fires even during busy-wait retries. Give the test extra retry budget so
-      // it stays stable under full-suite CPU contention.
+      // fires even during synchronous retry sleeps. Give the test extra retry
+      // budget so it stays stable under full-suite CPU contention.
       renameSync(lockFile, tmpFile);
       spawn('bash', ['-c', `sleep 0.05 && mv "${tmpFile}" "${lockFile}"`], { stdio: 'ignore', detached: true }).unref();
 

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

@@ -24,6 +24,7 @@ import { fileURLToPath } from "node:url";
 
 import { autoSession } from "../auto-runtime-state.ts";
 import { registerHooks } from "../bootstrap/register-hooks.ts";
+import { _resetPreferenceDiagnosticNotificationsForTests } from "../preferences-diagnostics.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const HOOKS_SOURCE = readFileSync(
@@ -298,6 +299,74 @@ test("session_start installs the welcome screen as the TUI header", async (t) =>
   assert.deepEqual(header.render(123), ["welcome 9.9.9-test none 123"]);
 });
 
+test("session_start suppresses the welcome header while auto-mode is active", async (t) => {
+  const dir = join(
+    tmpdir(),
+    `gsd-welcome-header-auto-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+  );
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+  mkdirSync(join(dir, "dist"), { recursive: true });
+  writeFileSync(
+    join(dir, "dist", "welcome-screen.js"),
+    "export function buildWelcomeScreenLines() { return ['welcome header']; }\n",
+    "utf-8",
+  );
+
+  const originalCwd = process.cwd();
+  const originalGsdPkgRoot = process.env.GSD_PKG_ROOT;
+  process.chdir(dir);
+  process.env.GSD_PKG_ROOT = dir;
+  autoSession.reset();
+  autoSession.active = true;
+  t.after(() => {
+    autoSession.reset();
+    process.chdir(originalCwd);
+    if (originalGsdPkgRoot === undefined) delete process.env.GSD_PKG_ROOT;
+    else process.env.GSD_PKG_ROOT = originalGsdPkgRoot;
+    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,
+    setCompactionThresholdOverride: () => {},
+    modelRegistry: {
+      setDisabledModelProviders: () => {},
+      getProviderAuthMode: () => undefined,
+      isProviderRequestReady: () => false,
+    },
+  } as any);
+
+  assert.equal(typeof headerFactory, "function", "session_start should install a header factory during auto-mode");
+  const header = headerFactory!({}, {});
+  assert.deepEqual(header.render(120), [], "auto-mode session_start must keep the welcome banner suppressed");
+});
+
 test("session hooks preserve closeout-boundary UI during completion reroot", async (t) => {
   const dir = join(
     tmpdir(),
@@ -485,3 +554,82 @@ test("session_start and session_switch apply disabled model provider policy from
     "session_switch should re-read preferences for the switched project/session context",
   );
 });
+
+test("session_start surfaces malformed preference diagnostics through visible notifications", async (t) => {
+  const dir = join(
+    tmpdir(),
+    `gsd-session-pref-diagnostics-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+  );
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+  const tempGsdHome = join(dir, "home");
+  mkdirSync(tempGsdHome, { recursive: true });
+
+  const originalCwd = process.cwd();
+  const originalGsdHome = process.env.GSD_HOME;
+  process.env.GSD_HOME = tempGsdHome;
+  process.chdir(dir);
+  _resetPreferenceDiagnosticNotificationsForTests();
+  t.after(() => {
+    process.chdir(originalCwd);
+    if (originalGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = originalGsdHome;
+    _resetPreferenceDiagnosticNotificationsForTests();
+    try { rmSync(dir, { recursive: true, force: true }); } catch { /* best-effort */ }
+  });
+
+  writeFileSync(
+    join(dir, ".gsd", "PREFERENCES.md"),
+    [
+      "---",
+      "version: 1",
+      "models:",
+      "  validation:",
+      "    openrouter/deepseek/deepseek-v4-pro",
+      "    thinking: high",
+      "---",
+      "",
+    ].join("\n"),
+    "utf-8",
+  );
+
+  const notifications: Array<{ message: string; level?: string }> = [];
+  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;
+  const ctx = {
+    hasUI: true,
+    ui: {
+      notify: (message: string, level?: string) => notifications.push({ message, level }),
+      setStatus: () => {},
+      setFooter: () => {},
+      setWorkingMessage: () => {},
+      onTerminalInput: () => () => {},
+      setWidget: () => {},
+    },
+    sessionManager: { getSessionId: () => null },
+    model: null,
+    setCompactionThresholdOverride: () => {},
+    modelRegistry: {
+      setDisabledModelProviders: () => {},
+      getProviderAuthMode: () => undefined,
+      isProviderRequestReady: () => false,
+    },
+  };
+
+  registerHooks(pi, []);
+
+  const sessionStart = handlers.get("session_start");
+  assert.ok(sessionStart, "session_start handler must be registered");
+  await sessionStart!({}, ctx);
+
+  const diagnostic = notifications.find((notification) =>
+    notification.message.includes("GSD project preferences error"),
+  );
+  assert.equal(diagnostic?.level, "error");
+  assert.match(diagnostic?.message ?? "", /could not be parsed/);
+  assert.match(diagnostic?.message ?? "", /line 5, column 5/);
+  assert.match(diagnostic?.message ?? "", /Preferences from this file were ignored/);
+});