@blackbelt-technology/pi-agent-dashboard 0.4.6 → 0.5.0

package/packages/server/src/spawn-register-watchdog.ts

@@ -0,0 +1,236 @@
+/**
+ * Spawn-register watchdog.
+ *
+ * Arms a per-spawn timer after every successful `spawnPiSession`. If the
+ * spawned pi session never sends `session_register` within the timeout
+ * window, emits `spawn_register_timeout` to the originating WebSocket.
+ *
+ * Two index maps handle the two spawn families:
+ *  - `byPid` — headless spawns where the dashboard owns the PID.
+ *  - `byCwd` — tmux/wt/wsl-tmux spawns where any `session_register` from
+ *    that directory clears the watch.
+ *
+ * Late registrations (pi finally registers after the watchdog fired) are
+ * detected via `recentlyFired` (60 s TTL) and cause a `spawn_register_recovered`
+ * message to auto-clear the timeout banner.
+ *
+ * See change: spawn-failure-diagnostics.
+ */
+import WebSocket from "ws";
+import { readFileSync } from "node:fs";
+import type { SpawnMechanism } from "@blackbelt-technology/pi-dashboard-shared/platform/spawn-mechanism.js";
+import type {
+  SpawnRegisterTimeoutMessage,
+  SpawnRegisterRecoveredMessage,
+} from "@blackbelt-technology/pi-dashboard-shared/browser-protocol.js";
+import { clampSpawnRegisterTimeoutMs, loadConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import { appendSpawnFailure } from "./spawn-failure-log.js";
+
+export interface WatchdogArmOptions {
+  pid?: number;
+  cwd: string;
+  mechanism: SpawnMechanism;
+  logPath?: string;
+  ws: WebSocket;
+}
+
+interface Entry {
+  timer: ReturnType<typeof setTimeout>;
+  cwd: string;
+  pid?: number;
+  mechanism: SpawnMechanism;
+  logPath?: string;
+  ws: WebSocket;
+  timeoutMs: number;
+}
+
+interface RecentlyFiredEntry {
+  firedAt: number;
+  pid?: number;
+  ws: WebSocket;
+}
+
+const RECENTLY_FIRED_TTL_MS = 60_000;
+
+export class SpawnRegisterWatchdog {
+  /** Default timeout used when arm() callers do not supply one. */
+  readonly timeoutMs: number;
+  private readonly byPid = new Map<number, Entry>();
+  private readonly byCwd = new Map<string, Entry>();
+  private readonly recentlyFired = new Map<string, RecentlyFiredEntry>();
+
+  constructor(timeoutMs: number) {
+    this.timeoutMs = clampSpawnRegisterTimeoutMs(timeoutMs);
+  }
+
+  arm(opts: WatchdogArmOptions & { timeoutMs?: number }): void {
+    // Read-on-arm: caller passes the current config value so a Settings change
+    // takes effect on the next spawn without a server restart.
+    // See change: spawn-failure-diagnostics (fix W1).
+    const effectiveTimeout = clampSpawnRegisterTimeoutMs(opts.timeoutMs ?? this.timeoutMs);
+    const { pid, cwd, mechanism, logPath, ws } = opts;
+    const entry: Entry = {
+      timer: null as unknown as ReturnType<typeof setTimeout>,
+      cwd, pid, mechanism, logPath, ws,
+      timeoutMs: effectiveTimeout,
+    };
+    entry.timer = setTimeout(() => this._fireEntry(entry), effectiveTimeout);
+    // Always index by cwd so a `session_register` clears the watchdog even
+    // when the bridge's reported pid differs from the spawner's pid (e.g.
+    // Unix headless wraps pi in `sh -c "tail -f /dev/null | pi …"`, so
+    // spawnResult.pid is the sh wrapper, not pi). Index by pid additionally
+    // for late-recovery lookup. Replace any prior entry for the same
+    // cwd/pid to avoid leaking timers.
+    const priorCwd = this.byCwd.get(cwd);
+    if (priorCwd) clearTimeout(priorCwd.timer);
+    this.byCwd.set(cwd, entry);
+    if (pid !== undefined) {
+      const priorPid = this.byPid.get(pid);
+      if (priorPid && priorPid !== priorCwd) clearTimeout(priorPid.timer);
+      this.byPid.set(pid, entry);
+    }
+  }
+
+  clearByPid(pid: number): void {
+    const entry = this.byPid.get(pid);
+    if (entry) {
+      clearTimeout(entry.timer);
+      this.byPid.delete(pid);
+      // Also clear cwd entry if it points at the same arm.
+      const cwdEntry = this.byCwd.get(entry.cwd);
+      if (cwdEntry === entry) this.byCwd.delete(entry.cwd);
+      return;
+    }
+    // Check for late recovery.
+    this._checkRecoveryByPid(pid);
+  }
+
+  clearByCwd(cwd: string): void {
+    const entry = this.byCwd.get(cwd);
+    if (entry) {
+      clearTimeout(entry.timer);
+      this.byCwd.delete(cwd);
+      // Also clear pid entry if it points at the same arm.
+      if (entry.pid !== undefined) {
+        const pidEntry = this.byPid.get(entry.pid);
+        if (pidEntry === entry) this.byPid.delete(entry.pid);
+      }
+      return;
+    }
+    // Check for late recovery.
+    this._checkRecoveryByCwd(cwd);
+  }
+
+  private _fireEntry(entry: Entry): void {
+    const { cwd, pid, logPath, ws, timeoutMs: entryTimeoutMs } = entry;
+    // Remove from active maps.
+    if (pid !== undefined) {
+      const pidEntry = this.byPid.get(pid);
+      if (pidEntry === entry) this.byPid.delete(pid);
+    }
+    const cwdEntry = this.byCwd.get(cwd);
+    if (cwdEntry === entry) this.byCwd.delete(cwd);
+
+    // Record in recentlyFired for late-recovery detection.
+    this.recentlyFired.set(cwd, { firedAt: Date.now(), pid, ws });
+
+    // Read stderr tail if logPath available.
+    let stderrTail: string | undefined;
+    if (logPath) {
+      stderrTail = readLogTail(logPath);
+    }
+
+    // Persist the timeout to the rolling failure log. See change: spawn-failure-diagnostics.
+    appendSpawnFailure({
+      ts: new Date().toISOString(),
+      cwd,
+      strategy: entry.mechanism,
+      code: "REGISTER_TIMEOUT",
+      message: `Pi session spawned but never registered (timeout ${this.timeoutMs}ms)`,
+      ...(pid !== undefined ? { pid } : {}),
+      ...(stderrTail ? { stderrTail } : {}),
+    });
+
+    if (ws.readyState !== WebSocket.OPEN) return;
+
+    const msg: SpawnRegisterTimeoutMessage = {
+      type: "spawn_register_timeout",
+      cwd,
+      timeoutMs: entryTimeoutMs,
+      ...(pid !== undefined ? { pid } : {}),
+      ...(stderrTail ? { stderrTail } : {}),
+    };
+    ws.send(JSON.stringify(msg));
+  }
+
+  private _checkRecoveryByPid(pid: number): void {
+    // recentlyFired is keyed by cwd; scan to find matching pid.
+    for (const [cwd, fired] of this.recentlyFired) {
+      if (fired.pid === pid) {
+        this._emitRecovery(cwd, fired);
+        return;
+      }
+    }
+  }
+
+  private _checkRecoveryByCwd(cwd: string): void {
+    const fired = this.recentlyFired.get(cwd);
+    if (!fired) return;
+    this._emitRecovery(cwd, fired);
+  }
+
+  private _emitRecovery(cwd: string, fired: RecentlyFiredEntry): void {
+    // TTL check.
+    if (Date.now() - fired.firedAt > RECENTLY_FIRED_TTL_MS) {
+      this.recentlyFired.delete(cwd);
+      return;
+    }
+
+    this.recentlyFired.delete(cwd);
+
+    if (fired.ws.readyState !== WebSocket.OPEN) return;
+
+    const msg: SpawnRegisterRecoveredMessage = {
+      type: "spawn_register_recovered",
+      cwd,
+      ...(fired.pid !== undefined ? { pid: fired.pid } : {}),
+    };
+    fired.ws.send(JSON.stringify(msg));
+  }
+}
+
+// ── Singleton ────────────────────────────────────────────────────────────────
+
+let _instance: SpawnRegisterWatchdog | null = null;
+
+/**
+ * Lazy singleton. On first call, reads `spawnRegisterTimeoutMs` from config.
+ * Tests can swap the instance via `_setSpawnRegisterWatchdogForTests`.
+ */
+export function getSpawnRegisterWatchdog(): SpawnRegisterWatchdog {
+  if (!_instance) {
+    const config = loadConfig();
+    _instance = new SpawnRegisterWatchdog(config.spawnRegisterTimeoutMs);
+  }
+  return _instance;
+}
+
+/** Swap the singleton for tests. Pass `null` to reset. */
+export function _setSpawnRegisterWatchdogForTests(w: SpawnRegisterWatchdog | null): void {
+  _instance = w;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function readLogTail(filePath: string, maxBytes = 4096): string | undefined {
+  try {
+    const buf = readFileSync(filePath);
+    if (!buf.length) return undefined;
+    const slice = buf.length <= maxBytes ? buf : buf.slice(buf.length - maxBytes);
+    let start = 0;
+    while (start < slice.length && (slice[start]! & 0xC0) === 0x80) start++;
+    return slice.slice(start).toString("utf-8");
+  } catch {
+    return undefined;
+  }
+}

package/packages/server/src/terminal-manager.ts

@@ -185,7 +185,18 @@ export function createTerminalManager(options?: TerminalManagerOptions): Termina
         try {
           const msg: TerminalControlMessage = JSON.parse(str);
           if (msg.type === "resize") {
-            entry.pty.resize(msg.cols, msg.rows);
+            // Defense in depth: reject degenerate resize messages.
+            // A PTY at <2 cols/rows is non-functional for every supported
+            // shell binding; no legitimate user intent maps there. xterm's
+            // FitAddon is supposed to guard against zero, but a transient
+            // display:none container measured during a route transition
+            // can leak a 1 through. See change:
+            // fix-terminal-half-height-dual-mount.
+            if (msg.cols < 2 || msg.rows < 2) {
+              // ignore — keep previous PTY dimensions
+            } else {
+              entry.pty.resize(msg.cols, msg.rows);
+            }
           } else if (msg.type === "title") {
             // title control message — handled elsewhere
           } else {

package/packages/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackbelt-technology/pi-dashboard-shared",
-  "version": "0.4.6",
+  "version": "0.5.0",
   "description": "Shared types and utilities for pi-dashboard",
   "type": "module",
   "repository": {

package/packages/shared/src/__tests__/bootstrap/__snapshots__/cube.test.ts.snap

@@ -352,6 +352,7 @@ source: system
 path:   C:/Program Files/nodejs/node.exe
 tried:
   override     no override set
+  managed      missing: <HOME>/.pi-dashboard/node/node.exe
   managed      missing: <HOME>/.pi-dashboard/node_modules/.bin/node.cmd
   where        ok
 argv:

package/packages/shared/src/__tests__/bootstrap/families/__snapshots__/g-windows-specifics.test.ts.snap

@@ -39,6 +39,7 @@ source: system
 path:   C:/Program Files/nodejs/node.exe
 tried:
   override     no override set
+  managed      missing: <HOME>/.pi-dashboard/node/node.exe
   managed      missing: <HOME>/.pi-dashboard/node_modules/.bin/node.cmd
   where        ok
 argv:

package/packages/shared/src/__tests__/bootstrap-install-resolve-npm.test.ts

@@ -0,0 +1,72 @@
+/**
+ * Regression: `resolveNpmArgv` from `bootstrap-install.ts` MUST consult
+ * the injected `ToolRegistry` for `npm` before falling back to the
+ * platform `npm` / `npm.cmd` PATH binary.
+ *
+ * The change `embed-managed-node-runtime` adds a managedRuntime
+ * strategy to the npm chain in the registry. If a future refactor
+ * accidentally bypasses the registry inside `resolveNpmArgv`, the
+ * managed Node runtime would stop being preferred for shared bootstrap
+ * spawns \u2014 the user-visible regression class this whole change exists
+ * to prevent.
+ *
+ * See change: embed-managed-node-runtime (task 4.2).
+ */
+import { describe, expect, it } from "vitest";
+import { resolveNpmArgv } from "../bootstrap-install.js";
+import type {
+  Resolution,
+  ToolRegistry,
+} from "../tool-registry/index.js";
+
+function fakeRegistry(opts: {
+  hasNpm?: boolean;
+  resolveResult?: Partial<Resolution>;
+}): ToolRegistry {
+  // Only the methods `resolveNpmArgv` actually calls.
+  return {
+    has: (name: string) => name === "npm" && (opts.hasNpm ?? true),
+    resolve: () =>
+      ({
+        name: "npm",
+        ok: true,
+        path: "/managed/node/bin/npm",
+        source: "managed",
+        tried: [],
+        resolvedAt: Date.now(),
+        ...opts.resolveResult,
+      }) as Resolution,
+  } as unknown as ToolRegistry;
+}
+
+describe("resolveNpmArgv", () => {
+  it("explicit npmArgv wins over registry", () => {
+    const argv = resolveNpmArgv({
+      npmArgv: ["/explicit/node", "/explicit/npm-cli.js"],
+      registry: fakeRegistry({}),
+    });
+    expect(argv).toEqual(["/explicit/node", "/explicit/npm-cli.js"]);
+  });
+
+  it("uses ToolRegistry.resolve('npm') when no explicit argv", () => {
+    const argv = resolveNpmArgv({
+      registry: fakeRegistry({
+        resolveResult: { ok: true, path: "/managed/node/bin/npm" } as Partial<Resolution>,
+      }),
+    });
+    expect(argv).toEqual(["/managed/node/bin/npm"]);
+  });
+
+  it("falls back to npm/npm.cmd on PATH when registry has no entry", () => {
+    const argv = resolveNpmArgv({
+      registry: {
+        has: () => false,
+        resolve: () => {
+          throw new Error("should not be called");
+        },
+      } as unknown as ToolRegistry,
+    });
+    expect(argv).toHaveLength(1);
+    expect(argv[0]).toMatch(/^npm(\.cmd)?$/);
+  });
+});

package/packages/shared/src/__tests__/browser-protocol-types.test.ts

@@ -12,8 +12,13 @@ import type {
   BrowserPromptDismissMessage,
   BrowserPromptCancelMessage,
   BrowserExtUiDecoratorMessage,
+  BrowserAssetRegisterMessage,
 } from "../browser-protocol.js";
-import type { ExtensionToServerMessage, ExtUiDecoratorMessage } from "../protocol.js";
+import type {
+  ExtensionToServerMessage,
+  ExtUiDecoratorMessage,
+  AssetRegisterMessage,
+} from "../protocol.js";
 import type { DecoratorDescriptor } from "../types.js";
 
 // Type-level assertion: if these types are NOT in the union, this will fail to compile.
@@ -26,6 +31,11 @@ type _PromptCancelInUnion = AssertExtends<BrowserPromptCancelMessage, ServerToBr
 // esbuild strips the switch arms in production builds.
 type _ExtUiDecoratorInExtensionUnion = AssertExtends<ExtUiDecoratorMessage, ExtensionToServerMessage>;
 type _ExtUiDecoratorInBrowserUnion   = AssertExtends<BrowserExtUiDecoratorMessage, ServerToBrowserMessage>;
+// chat-markdown-local-images-and-math: asset_register must live in BOTH the
+// extension→server union (so the server's switch arm survives esbuild) AND
+// the server→browser union (so the client's reducer arm survives esbuild).
+type _AssetRegisterInExtensionUnion = AssertExtends<AssetRegisterMessage, ExtensionToServerMessage>;
+type _AssetRegisterInBrowserUnion   = AssertExtends<BrowserAssetRegisterMessage, ServerToBrowserMessage>;
 
 // Runtime verification that the type discriminants are reachable in a switch
 function extractPromptType(msg: ServerToBrowserMessage): string | null {
@@ -119,3 +129,39 @@ describe("ext_ui_decorator is a member of both protocol unions", () => {
     expect(msg.descriptor.kind).toBe("footer-segment");
   });
 });
+
+// chat-markdown-local-images-and-math: asset_register switch-arm reachability.
+function extractAssetHash(msg: ServerToBrowserMessage): string | null {
+  switch (msg.type) {
+    case "asset_register":
+      return msg.hash;
+    default:
+      return null;
+  }
+}
+
+describe("asset_register is a member of both protocol unions", () => {
+  it("server→browser asset_register is a valid discriminant", () => {
+    const msg: BrowserAssetRegisterMessage = {
+      type: "asset_register",
+      sessionId: "s1",
+      hash: "abc1234567890123",
+      mimeType: "image/png",
+      data: "iVBORw0KGgo=",
+    };
+    expect(extractAssetHash(msg)).toBe("abc1234567890123");
+  });
+
+  it("extension→server asset_register carries the same shape", () => {
+    const msg: AssetRegisterMessage = {
+      type: "asset_register",
+      sessionId: "s1",
+      hash: "abc1234567890123",
+      mimeType: "image/svg+xml",
+      data: "PHN2Zy8+",
+    };
+    expect(msg.type).toBe("asset_register");
+    expect(msg.hash).toBe("abc1234567890123");
+    expect(msg.mimeType).toBe("image/svg+xml");
+  });
+});

package/packages/shared/src/__tests__/config.test.ts

@@ -471,3 +471,51 @@ describe("loadConfig reattachPlacement", () => {
     expect(content.reattachPlacement).toBeUndefined();
   });
 });
+
+describe("loadConfig spawnRegisterTimeoutMs", () => {
+  let testDir: string;
+  let configFile: string;
+  let origHome: string;
+
+  beforeEach(() => {
+    testDir = path.join(os.tmpdir(), `test-config-srt-${Date.now()}`);
+    fs.mkdirSync(path.join(testDir, ".pi", "dashboard"), { recursive: true });
+    configFile = path.join(testDir, ".pi", "dashboard", "config.json");
+    origHome = process.env.HOME!;
+    process.env.HOME = testDir;
+  });
+
+  afterEach(() => {
+    process.env.HOME = origHome;
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true });
+  });
+
+  it("defaults to 30000 when field is omitted", () => {
+    expect(loadConfig().spawnRegisterTimeoutMs).toBe(30000);
+  });
+
+  it("preserves in-range value", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ spawnRegisterTimeoutMs: 45000 }));
+    expect(loadConfig().spawnRegisterTimeoutMs).toBe(45000);
+  });
+
+  it("clamps below-range value to 5000", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ spawnRegisterTimeoutMs: 1000 }));
+    expect(loadConfig().spawnRegisterTimeoutMs).toBe(5000);
+  });
+
+  it("clamps above-range value to 120000", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ spawnRegisterTimeoutMs: 999999 }));
+    expect(loadConfig().spawnRegisterTimeoutMs).toBe(120000);
+  });
+
+  it("falls back to default for non-number string", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ spawnRegisterTimeoutMs: "thirty" }));
+    expect(loadConfig().spawnRegisterTimeoutMs).toBe(30000);
+  });
+
+  it("falls back to default for null", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ spawnRegisterTimeoutMs: null }));
+    expect(loadConfig().spawnRegisterTimeoutMs).toBe(30000);
+  });
+});

package/packages/shared/src/__tests__/dashboard-starter.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { parseDashboardStarter } from "../dashboard-starter.js";
+
+describe("parseDashboardStarter", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("returns Standalone when env is empty object", () => {
+    expect(parseDashboardStarter({})).toBe("Standalone");
+  });
+
+  it("returns Standalone when DASHBOARD_STARTER is undefined", () => {
+    expect(parseDashboardStarter({ DASHBOARD_STARTER: undefined })).toBe("Standalone");
+  });
+
+  it("returns Standalone when DASHBOARD_STARTER is empty string", () => {
+    expect(parseDashboardStarter({ DASHBOARD_STARTER: "" })).toBe("Standalone");
+  });
+
+  it("returns Bridge for valid value", () => {
+    expect(parseDashboardStarter({ DASHBOARD_STARTER: "Bridge" })).toBe("Bridge");
+  });
+
+  it("returns Standalone for valid value", () => {
+    expect(parseDashboardStarter({ DASHBOARD_STARTER: "Standalone" })).toBe("Standalone");
+  });
+
+  it("returns Electron for valid value", () => {
+    expect(parseDashboardStarter({ DASHBOARD_STARTER: "Electron" })).toBe("Electron");
+  });
+
+  it("returns Standalone and warns on invalid value", () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const result = parseDashboardStarter({ DASHBOARD_STARTER: "bogus" });
+    expect(result).toBe("Standalone");
+    expect(warnSpy).toHaveBeenCalledOnce();
+    expect(warnSpy.mock.calls[0]![0]).toContain("bogus");
+  });
+});

package/packages/shared/src/__tests__/detached-spawn.test.ts

@@ -61,6 +61,30 @@ describe("spawnDetached", () => {
     rmSync(path.dirname(logPath), { recursive: true, force: true });
   });
 
+  // See change: fix-electron-extracted-jiti-and-stdio-capture.
+  it("redirects BOTH stdout and stderr to logFd when provided", async () => {
+    const logPath = tmpLog();
+    const fd = openSync(logPath, "a");
+    try {
+      const r = await spawnDetached({
+        cmd: process.execPath,
+        args: [
+          "-e",
+          "console.log('STDOUT-LINE'); process.stderr.write('STDERR-LINE'); setTimeout(() => process.exit(0), 100)",
+        ],
+        logFd: fd,
+      });
+      expect(r.ok).toBe(true);
+      await new Promise((res) => r.process!.once("exit", res));
+    } finally {
+      try { closeSync(fd); } catch { /* ignore */ }
+    }
+    const content = readFileSync(logPath, "utf-8");
+    expect(content).toContain("STDOUT-LINE");
+    expect(content).toContain("STDERR-LINE");
+    rmSync(path.dirname(logPath), { recursive: true, force: true });
+  });
+
   it("does not keep parent event loop alive (unref)", async () => {
     // Can only check behaviour indirectly: the returned pid/process exist
     // and the child is running detached. Lifecycle survival is covered by

package/packages/shared/src/__tests__/doctor-core.test.ts

@@ -0,0 +1,134 @@
+/**
+ * Doctor core — section assignment, suggestion taxonomy, and the
+ * Decision-8 lint (every non-ok check has non-empty
+ * message/detail/suggestion). See change: doctor-rich-output.
+ */
+import { describe, it, expect } from "vitest";
+import {
+  SECTION_OF,
+  SUGGESTIONS,
+  stampSectionsAndSuggestions,
+  type DoctorCheck,
+  type DoctorStatus,
+} from "../doctor-core.js";
+
+const ALL_CHECK_NAMES = Object.keys(SECTION_OF);
+
+describe("SECTION_OF", () => {
+  it("maps every canonical check name to one of the five sections", () => {
+    const allowed = new Set(["runtime", "pi-tooling", "server", "setup", "diagnostics"]);
+    for (const name of ALL_CHECK_NAMES) {
+      expect(allowed.has(SECTION_OF[name])).toBe(true);
+    }
+  });
+
+  it("covers all five sections (none empty)", () => {
+    const sections = new Set(Object.values(SECTION_OF));
+    for (const s of ["runtime", "pi-tooling", "server", "setup", "diagnostics"]) {
+      expect(sections.has(s as never)).toBe(true);
+    }
+  });
+});
+
+describe("SUGGESTIONS", () => {
+  it("returns undefined for status=ok across every check name", () => {
+    for (const name of ALL_CHECK_NAMES) {
+      const fn = SUGGESTIONS[name];
+      expect(fn).toBeDefined();
+      expect(fn?.("ok")).toBeUndefined();
+    }
+  });
+
+  it("returns a non-empty string for status=error or warning when defined", () => {
+    for (const name of ALL_CHECK_NAMES) {
+      const fn = SUGGESTIONS[name];
+      // Electron is the only one that returns undefined even for non-ok
+      // (because today it never fails). Skip it.
+      if (name === "Electron") continue;
+      const w = fn?.("warning");
+      const e = fn?.("error");
+      expect(typeof w === "string" && w.length > 0).toBe(true);
+      expect(typeof e === "string" && e.length > 0).toBe(true);
+    }
+  });
+
+  it("constrains suggestion text to the allowed Markdown subset", () => {
+    // Allowed: **bold**, single-backtick code, [text](url). Disallow: tables,
+    // headings, fenced blocks, raw HTML.
+    for (const name of ALL_CHECK_NAMES) {
+      const fn = SUGGESTIONS[name];
+      const candidates: (string | undefined)[] = [
+        fn?.("warning"),
+        fn?.("error"),
+        fn?.("error", undefined, "not-found"),
+        fn?.("error", undefined, "permission-denied"),
+        fn?.("error", undefined, "timeout"),
+        fn?.("error", undefined, "non-zero-exit"),
+      ];
+      for (const s of candidates) {
+        if (!s) continue;
+        // No fenced code blocks.
+        expect(/```/.test(s)).toBe(false);
+        // No headings at line start.
+        expect(/^#{1,6}\s/m.test(s)).toBe(false);
+        // No raw HTML tags (closing, self-closing, or with attributes).
+        // Plain `<placeholder>` text is allowed (used as prose).
+        expect(/<\/[a-zA-Z]|<[a-zA-Z][^>]*\s+[^>]+>|<[a-zA-Z][^>]*\/>/.test(s)).toBe(false);
+        // Triple-asterisk or underline for bold not allowed.
+        expect(/\*\*\*|___/.test(s)).toBe(false);
+      }
+    }
+  });
+});
+
+describe("stampSectionsAndSuggestions (Decision 8 lint)", () => {
+  it("stamps section + suggestion on non-ok rows by name", () => {
+    const checks: DoctorCheck[] = [
+      { name: "pi CLI", section: undefined as unknown as never, status: "error", message: "Not found", detail: "Searched PATH" },
+      { name: "System Node.js", section: undefined as unknown as never, status: "ok", message: "v22 at /usr/bin/node" },
+    ];
+    const out = stampSectionsAndSuggestions(checks);
+    expect(out[0].section).toBe("pi-tooling");
+    expect(out[0].suggestion).toBeDefined();
+    expect(out[1].section).toBe("runtime");
+    expect(out[1].suggestion).toBeUndefined();
+  });
+
+  it("every non-ok row produced through stamping has non-empty message + detail + suggestion", () => {
+    const statuses: DoctorStatus[] = ["warning", "error"];
+    for (const name of ALL_CHECK_NAMES) {
+      // Electron suggestion is always undefined (decision-by-design); skip.
+      if (name === "Electron") continue;
+      for (const status of statuses) {
+        const checks: DoctorCheck[] = [
+          {
+            name,
+            section: undefined as unknown as never,
+            status,
+            message: "synthetic message",
+            detail: "synthetic detail",
+          },
+        ];
+        const [stamped] = stampSectionsAndSuggestions(checks);
+        expect(stamped.message.length).toBeGreaterThan(0);
+        expect((stamped.detail ?? "").length).toBeGreaterThan(0);
+        expect((stamped.suggestion ?? "").length).toBeGreaterThan(0);
+      }
+    }
+  });
+
+  it("does not overwrite an existing suggestion", () => {
+    const checks: DoctorCheck[] = [
+      {
+        name: "pi CLI",
+        section: "pi-tooling",
+        status: "error",
+        message: "x",
+        detail: "y",
+        suggestion: "custom",
+      },
+    ];
+    const out = stampSectionsAndSuggestions(checks);
+    expect(out[0].suggestion).toBe("custom");
+  });
+});