@blackbelt-technology/pi-agent-dashboard 0.2.9 → 0.4.0

package/packages/server/src/home-lock.ts

@@ -0,0 +1,389 @@
+/**
+ * Per-HOME advisory lock for the dashboard server.
+ *
+ * Ensures one dashboard instance per HOME (`<realpath(os.homedir())>/.pi/`).
+ * See change: single-dashboard-per-home.
+ *
+ * Responsibilities:
+ *   - Canonicalize HOME (avoid symlink/Git-Bash drift)
+ *   - Acquire the lock via `proper-lockfile` (non-blocking, stale-aware)
+ *   - Write / read an atomic metadata sidecar
+ *   - Verify a held lock's liveness via identity-checked health probe
+ *   - Return an `acquired` or `attach` result for the caller to dispatch
+ *
+ * Signal handlers and release-on-exit plumbing live in
+ * `home-lock-release.ts` to keep this module pure + testable.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import properLockfile from "proper-lockfile";
+import { isDashboardRunning } from "@blackbelt-technology/pi-dashboard-shared/server-identity.js";
+import { isProcessAlive } from "@blackbelt-technology/pi-dashboard-shared/platform/process.js";
+
+// ──────────────────────────────────────────────────────────
+// Types
+// ──────────────────────────────────────────────────────────
+
+/** Metadata written alongside the lock file. JSON-serialized. */
+export interface LockMetadata {
+  pid: number;
+  ppid: number;
+  httpPort: number;
+  piPort: number;
+  startedAt: number;
+  /** Stable per-instance identifier. Verified against /api/health to detect
+   *  "port in use by unrelated dashboard or stale process with same pid." */
+  identity: string;
+  version: string;
+  url: string;
+  hostname: string;
+}
+
+/** Result of `acquireOrAttach`. Callers branch on `mode`. */
+export type LockAcquireResult =
+  | {
+      mode: "acquired";
+      meta: LockMetadata;
+      /** Release the lock + remove the metadata sidecar. Idempotent. */
+      release: () => Promise<void>;
+    }
+  | {
+      mode: "attach";
+      meta: LockMetadata;
+    };
+
+/** Thrown when port is held by an unrelated process. Non-fatal to this
+ *  module; caller decides (exit with message / retry / override). */
+export class InstanceLockMismatchError extends Error {
+  readonly code = "E_INSTANCE_MISMATCH";
+  constructor(readonly meta: LockMetadata, readonly observedIdentity: string | null) {
+    super(
+      `Port ${meta.httpPort} is in use by an unrelated process (PID ${meta.pid}). ` +
+        `Configure a different port or stop that process.`,
+    );
+  }
+}
+
+export interface AcquireConfig {
+  httpPort: number;
+  piPort: number;
+  version: string;
+  identity?: string;
+  /** Injection hooks for tests. Production callers pass no options. */
+  hooks?: AcquireHooks;
+}
+
+export interface AcquireHooks {
+  now?: () => number;
+  hostname?: () => string;
+  lockPath?: string;
+  metaPath?: string;
+  probeHealth?: (port: number) => Promise<{ running: boolean; pid?: number; identity?: string } | null>;
+  isProcessAlive?: (pid: number) => boolean;
+  /** Stale threshold forwarded to `proper-lockfile`. Default 10s. */
+  staleMs?: number;
+}
+
+// ──────────────────────────────────────────────────────────
+// Paths
+// ──────────────────────────────────────────────────────────
+
+/**
+ * Canonical HOME directory.
+ *
+ * Uses `os.userInfo().homedir` in preference to `os.homedir()` because on
+ * POSIX the latter honors the `$HOME` environment variable (Node docs say:
+ * "On POSIX, it uses the `$HOME` environment variable if defined"), which
+ * the design (§4) explicitly prohibits — a GUI-launched process and a
+ * shell-launched process would otherwise disagree on "where HOME is".
+ * `userInfo().homedir` consults `getpwuid(3)` on POSIX, immune to `$HOME`.
+ *
+ * On Windows, both APIs ultimately use `USERPROFILE`, so the Git Bash
+ * drift case (`$HOME=/c/Users/R` vs `USERPROFILE=C:\Users\R`) is handled
+ * either way; keeping `userInfo().homedir` first is still correct.
+ *
+ * Result is then passed through `fs.realpathSync` to collapse symlinks,
+ * FileVault migrations, and other canonicalization drift. Tolerant: falls
+ * back to the raw path if realpath fails.
+ */
+export function canonicalHomedir(): string {
+  let raw: string;
+  try {
+    raw = os.userInfo().homedir;
+  } catch {
+    raw = os.homedir();
+  }
+  try {
+    return fs.realpathSync(raw);
+  } catch {
+    return raw;
+  }
+}
+
+/**
+ * Lock file path. This is what `proper-lockfile` locks.
+ */
+export function getLockPath(homedir: string = canonicalHomedir()): string {
+  return path.join(homedir, ".pi", "dashboard", "server.lock");
+}
+
+/**
+ * Metadata sidecar path (`<lockPath>.meta.json`).
+ */
+export function getMetaPath(lockPath: string = getLockPath()): string {
+  return `${lockPath}.meta.json`;
+}
+
+// ──────────────────────────────────────────────────────────
+// Metadata I/O
+// ──────────────────────────────────────────────────────────
+
+/**
+ * Atomically write the metadata sidecar via tmp + rename.
+ * Never leaves a partial file visible.
+ */
+export function writeMetadataAtomic(meta: LockMetadata, metaPath: string = getMetaPath()): void {
+  const dir = path.dirname(metaPath);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmpPath = `${metaPath}.tmp-${process.pid}-${Date.now()}`;
+  fs.writeFileSync(tmpPath, JSON.stringify(meta, null, 2));
+  fs.renameSync(tmpPath, metaPath);
+}
+
+/**
+ * Read the metadata sidecar. Returns null on any failure (missing, corrupt,
+ * permission-denied). Callers MUST treat null as "assume stale."
+ */
+export function readMetadata(metaPath: string = getMetaPath()): LockMetadata | null {
+  try {
+    const raw = fs.readFileSync(metaPath, "utf-8");
+    const parsed = JSON.parse(raw) as unknown;
+    if (!isLockMetadata(parsed)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function isLockMetadata(value: unknown): value is LockMetadata {
+  if (!value || typeof value !== "object") return false;
+  const m = value as Record<string, unknown>;
+  return (
+    typeof m.pid === "number" &&
+    typeof m.httpPort === "number" &&
+    typeof m.piPort === "number" &&
+    typeof m.startedAt === "number" &&
+    typeof m.identity === "string" &&
+    typeof m.version === "string" &&
+    typeof m.url === "string"
+  );
+}
+
+/**
+ * Remove the metadata sidecar. Silent on any error (missing is fine).
+ */
+export function removeMetadata(metaPath: string = getMetaPath()): void {
+  try {
+    fs.unlinkSync(metaPath);
+  } catch {
+    /* ignore */
+  }
+}
+
+// ──────────────────────────────────────────────────────────
+// Liveness
+// ──────────────────────────────────────────────────────────
+
+/**
+ * Determine if the recorded lock holder is a responsive, identity-matching
+ * dashboard. Returns:
+ *   - `"alive-match"`: attach to it
+ *   - `"alive-mismatch"`: someone else is on that port
+ *   - `"dead"`: treat as stale, proceed to acquire
+ */
+export async function isLockHolderResponsive(
+  meta: LockMetadata,
+  hooks: Pick<AcquireHooks, "probeHealth" | "isProcessAlive"> = {},
+): Promise<"alive-match" | "alive-mismatch" | "dead"> {
+  const aliveCheck = hooks.isProcessAlive ?? isProcessAlive;
+  if (!aliveCheck(meta.pid)) return "dead";
+
+  const probe = hooks.probeHealth ?? defaultProbeHealth;
+  const res = await probe(meta.httpPort);
+  if (!res || !res.running) return "dead";
+
+  // Identity check: `identity` field is preferred; fall back to PID match
+  // to stay compatible with older dashboards that predate identity.
+  if (res.identity) {
+    return res.identity === meta.identity ? "alive-match" : "alive-mismatch";
+  }
+  if (typeof res.pid === "number") {
+    return res.pid === meta.pid ? "alive-match" : "alive-mismatch";
+  }
+  // Running but no verifiable identity — conservative: mismatch.
+  return "alive-mismatch";
+}
+
+async function defaultProbeHealth(port: number) {
+  const status = await isDashboardRunning(port);
+  if (!status.running) return { running: false };
+  // `isDashboardRunning` doesn't expose identity today. Re-fetch to peek at
+  // the full health body for the `identity` field. Best-effort.
+  try {
+    const res = await fetch(`http://localhost:${port}/api/health`, {
+      signal: AbortSignal.timeout(1500),
+    });
+    if (res.ok) {
+      const body = (await res.json()) as { pid?: number; identity?: string };
+      return { running: true, pid: body.pid, identity: body.identity };
+    }
+  } catch {
+    /* fall through */
+  }
+  return { running: true, pid: status.pid };
+}
+
+// ──────────────────────────────────────────────────────────
+// Acquire
+// ──────────────────────────────────────────────────────────
+
+/**
+ * Acquire the per-HOME lock, or fall back to attach semantics if a live
+ * dashboard already holds it.
+ *
+ * Flow:
+ *   1. Ensure `~/.pi/dashboard/` exists (proper-lockfile requires parent).
+ *   2. `proper-lockfile.lock(path, { stale, retries: 0 })`
+ *      ↪ on success: write metadata, return { mode: "acquired", release }
+ *      ↪ on ELOCKED: read metadata, check liveness
+ *         - dead: steal via `proper-lockfile.lock({ realpath:false, stale: 0 })`
+ *                 (Note: proper-lockfile already does stale-stealing when
+ *                 `stale` is configured — we just retry once.)
+ *         - alive-match: return { mode: "attach", meta }
+ *         - alive-mismatch: throw InstanceLockMismatchError
+ */
+export async function acquireOrAttach(config: AcquireConfig): Promise<LockAcquireResult> {
+  const hooks = config.hooks ?? {};
+  const lockPath = hooks.lockPath ?? getLockPath();
+  const metaPath = hooks.metaPath ?? getMetaPath(lockPath);
+  const staleMs = hooks.staleMs ?? 10_000;
+  const now = hooks.now ?? Date.now;
+  const hostname = hooks.hostname ?? os.hostname;
+
+  // Ensure the lock file's parent directory exists. proper-lockfile wants
+  // either the target file (which it creates alongside as `<path>.lock/`)
+  // or an existing file — we create an empty sentinel so the API is
+  // deterministic.
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+  if (!fs.existsSync(lockPath)) {
+    fs.writeFileSync(lockPath, "# pi-dashboard per-HOME advisory lock\n");
+  }
+
+  const buildMeta = (): LockMetadata => ({
+    pid: process.pid,
+    ppid: process.ppid,
+    httpPort: config.httpPort,
+    piPort: config.piPort,
+    startedAt: now(),
+    identity: config.identity ?? randomUUID(),
+    version: config.version,
+    url: `http://localhost:${config.httpPort}`,
+    hostname: hostname(),
+  });
+
+  const tryAcquire = async () => {
+    const release = await properLockfile.lock(lockPath, {
+      stale: staleMs,
+      retries: 0,
+      // proper-lockfile uses realpath by default; we already pass a
+      // realpath-based directory, so this is a no-op but kept explicit.
+      realpath: false,
+    });
+    const meta = buildMeta();
+    writeMetadataAtomic(meta, metaPath);
+    const releaseOnce = (() => {
+      let released = false;
+      return async () => {
+        if (released) return;
+        released = true;
+        try {
+          await release();
+        } catch {
+          /* ignore — lock may have been compromised */
+        }
+        removeMetadata(metaPath);
+      };
+    })();
+    return { mode: "acquired" as const, meta, release: releaseOnce };
+  };
+
+  try {
+    return await tryAcquire();
+  } catch (err: unknown) {
+    if (!isELocked(err)) throw err;
+    // Someone else holds the lock. Decide: attach or error.
+    //
+    // Concurrent-launch race: if two callers race, the winner writes the
+    // metadata sidecar a few ms after acquiring. The loser hits ELOCKED
+    // faster and can read the sidecar BEFORE the winner has written it.
+    // Short-poll for metadata to land before concluding "no metadata = stale."
+    let meta: LockMetadata | null = null;
+    for (let i = 0; i < 20; i++) {
+      meta = readMetadata(metaPath);
+      if (meta) break;
+      await new Promise(r => setTimeout(r, 25));
+    }
+    if (!meta) {
+      // Truly no metadata after 500ms → assume stale/corrupt. Force steal.
+      removeMetadata(metaPath);
+      try {
+        return await tryAcquire();
+      } catch (err2) {
+        if (!isELocked(err2)) throw err2;
+        try {
+          await properLockfile.unlock(lockPath, { realpath: false });
+        } catch {
+          /* ignore */
+        }
+        return await tryAcquire();
+      }
+    }
+
+    const liveness = await isLockHolderResponsive(meta, hooks);
+    if (liveness === "alive-match") {
+      return { mode: "attach", meta };
+    }
+    if (liveness === "alive-mismatch") {
+      throw new InstanceLockMismatchError(meta, null);
+    }
+    // Dead holder — steal.
+    try {
+      await properLockfile.unlock(lockPath, { realpath: false });
+    } catch {
+      /* ignore */
+    }
+    removeMetadata(metaPath);
+    return await tryAcquire();
+  }
+}
+
+function isELocked(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const code = (err as { code?: string }).code;
+  return code === "ELOCKED";
+}
+
+// ──────────────────────────────────────────────────────────
+// Escape hatch
+// ──────────────────────────────────────────────────────────
+
+/**
+ * True when the user has opted out of the per-HOME lock. Caller should
+ * log a warning and skip acquireOrAttach when set.
+ */
+export function isLockDisabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  const raw = env.PI_DASHBOARD_ALLOW_MULTIPLE;
+  return raw === "1" || raw === "true";
+}

package/packages/server/src/node-guard.ts

@@ -0,0 +1,52 @@
+/**
+ * Pure predicate + message builder for nodejs/node#58515 affected versions.
+ *
+ * The bug (`ERR_INTERNAL_ASSERTION: Unexpected module status 3`) fires when
+ * Fastify loads its internal ajv-compiler under affected Node versions.
+ *
+ * Affected: Node v22.0–v22.17 and v24.1–v24.2.
+ * Fixed in: v22.18+, v24.3+, v25.x.
+ *
+ * Rationale for a preflight refuse-to-start (instead of a preload workaround):
+ * see openspec/changes/adapt-windows-integration-pr9/proposal.md and
+ * BRANCH-COMPARISON.md §10 on origin/windows-integration.
+ */
+
+export function isAffectedNode(version: string): boolean {
+  const m = version.match(/^v?(\d+)\.(\d+)\.(\d+)/);
+  if (!m) return false;
+  const major = Number(m[1]);
+  const minor = Number(m[2]);
+  if (major === 22 && minor < 18) return true;
+  if (major === 24 && minor >= 1 && minor < 3) return true;
+  return false;
+}
+
+export function buildNodeUpgradeMessage(version: string): string {
+  return [
+    ``,
+    `❌  pi-dashboard cannot start on Node ${version}.`,
+    ``,
+    `    This Node version has a bug that crashes Fastify at startup:`,
+    `    https://github.com/nodejs/node/issues/58515`,
+    ``,
+    `    Fix: upgrade Node to >=22.18.0 (LTS) or >=24.3.0.`,
+    `    Install:`,
+    `      nvm:   nvm install 22 && nvm use 22`,
+    `      brew:  brew upgrade node`,
+    `      Win:   https://nodejs.org/  ->  current 22.x LTS installer`,
+    ``,
+  ].join("\n");
+}
+
+/**
+ * Call at the top of every server entry point (cmdStart, runForeground).
+ * Writes the upgrade message to stderr and exits with code 1 when the
+ * running Node is in the affected range.
+ */
+export function assertNodeVersionSupported(): void {
+  if (isAffectedNode(process.version)) {
+    console.error(buildNodeUpgradeMessage(process.version));
+    process.exit(1);
+  }
+}

package/packages/server/src/npm-search-proxy.ts

@@ -136,8 +136,79 @@ export class PackageNotFoundError extends Error {
   }
 }
 
+// ── Lightweight metadata helpers for recommended-extensions enrichment ──
+
+export interface PackageMeta {
+  description?: string;
+  version?: string;
+}
+
+const metaCache = new Map<string, CacheEntry<PackageMeta | null>>();
+
+/**
+ * Fetch a minimal package.json-ish blob for an npm package (description,
+ * version) from the registry's `/<name>/latest` endpoint. Returns `null`
+ * on any network or parse failure.
+ */
+export async function fetchPackageMeta(packageName: string): Promise<PackageMeta | null> {
+  const cached = metaCache.get(`npm:${packageName}`);
+  if (isFresh(cached)) return cached.data;
+  try {
+    const url = `${NPM_REGISTRY_URL}/${encodeURIComponent(packageName)}/latest`;
+    const res = await fetch(url, { signal: AbortSignal.timeout(10_000) });
+    if (!res.ok) {
+      metaCache.set(`npm:${packageName}`, { data: null, timestamp: Date.now() });
+      return null;
+    }
+    const json: any = await res.json();
+    const meta: PackageMeta = {
+      description: typeof json?.description === "string" ? json.description : undefined,
+      version: typeof json?.version === "string" ? json.version : undefined,
+    };
+    metaCache.set(`npm:${packageName}`, { data: meta, timestamp: Date.now() });
+    return meta;
+  } catch {
+    metaCache.set(`npm:${packageName}`, { data: null, timestamp: Date.now() });
+    return null;
+  }
+}
+
+/**
+ * Fetch `package.json` from a public GitHub repository's default branch
+ * via `raw.githubusercontent.com`. Returns `{description, version}` or
+ * `null` on any failure.
+ */
+export async function fetchGithubPackageJson(
+  owner: string,
+  repo: string,
+): Promise<PackageMeta | null> {
+  const key = `gh:${owner}/${repo}`;
+  const cached = metaCache.get(key);
+  if (isFresh(cached)) return cached.data;
+  // HEAD resolves to the default branch on raw.githubusercontent.com.
+  const url = `https://raw.githubusercontent.com/${owner}/${repo}/HEAD/package.json`;
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(10_000) });
+    if (!res.ok) {
+      metaCache.set(key, { data: null, timestamp: Date.now() });
+      return null;
+    }
+    const json: any = await res.json();
+    const meta: PackageMeta = {
+      description: typeof json?.description === "string" ? json.description : undefined,
+      version: typeof json?.version === "string" ? json.version : undefined,
+    };
+    metaCache.set(key, { data: meta, timestamp: Date.now() });
+    return meta;
+  } catch {
+    metaCache.set(key, { data: null, timestamp: Date.now() });
+    return null;
+  }
+}
+
 /** Clear all caches (for testing). */
 export function clearCaches() {
   searchCache.clear();
   readmeCache.clear();
+  metaCache.clear();
 }

package/packages/server/src/openspec-tasks.ts

@@ -0,0 +1,158 @@
+/**
+ * Parser + writer for an OpenSpec change's `tasks.md` file.
+ *
+ * `tasks.md` uses a rigid line-level format:
+ *   ## 1. Group heading
+ *   - [ ] 1.1 Task text
+ *   - [x] 1.2 Done task
+ *
+ * We parse top-level `- [ ]` / `- [x]` lines only; anything else is ignored
+ * (indented sublists, free-form prose, etc.).
+ *
+ * Writes rewrite exactly one line's checkbox marker and preserve everything
+ * else byte-for-byte; atomic via write-then-rename.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export interface OpenSpecTask {
+  /** e.g. "1.1", "8.3" */
+  id: string;
+  /** Text after the id, trimmed. */
+  text: string;
+  done: boolean;
+  /** 1-indexed line number in `tasks.md` — used as an optimistic-concurrency token. */
+  line: number;
+  /** Nearest preceding `## ` heading text (without the leading "## "). Empty string if none. */
+  group: string;
+}
+
+export class NotFoundError extends Error {
+  readonly code = "NOT_FOUND" as const;
+  constructor(message = "tasks.md not found") {
+    super(message);
+  }
+}
+export class LineMismatchError extends Error {
+  readonly code = "LINE_MISMATCH" as const;
+  constructor(message = "line mismatch") {
+    super(message);
+  }
+}
+export class NotACheckboxError extends Error {
+  readonly code = "NOT_A_CHECKBOX" as const;
+  constructor(message = "target line is not a checkbox") {
+    super(message);
+  }
+}
+
+// Top-level checkbox: allow a single leading `- ` with optional `[ ]`/`[x]`/`[X]`,
+// followed by an id-like token (digits and dots) and remaining text.
+const CHECKBOX_RE = /^- \[([ xX])\] +([0-9]+(?:\.[0-9]+)*)\s+(.*)$/;
+const HEADING_RE = /^##\s+(.*)$/;
+
+export function parseTasksMarkdown(content: string): OpenSpecTask[] {
+  // Split on \n only; trailing \r is trimmed so we handle CRLF inputs too.
+  const lines = content.split("\n");
+  const out: OpenSpecTask[] = [];
+  let currentGroup = "";
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+    const h = HEADING_RE.exec(line);
+    if (h) {
+      currentGroup = h[1].trim();
+      continue;
+    }
+    const m = CHECKBOX_RE.exec(line);
+    if (!m) continue;
+    const done = m[1] === "x" || m[1] === "X";
+    out.push({
+      id: m[2],
+      text: m[3].trim(),
+      done,
+      line: i + 1,
+      group: currentGroup,
+    });
+  }
+  return out;
+}
+
+function tasksMdPath(cwd: string, change: string): string {
+  return path.join(cwd, "openspec", "changes", change, "tasks.md");
+}
+
+export async function readTasks(cwd: string, change: string): Promise<OpenSpecTask[]> {
+  const p = tasksMdPath(cwd, change);
+  let content: string;
+  try {
+    content = await fs.readFile(p, "utf-8");
+  } catch (err: any) {
+    if (err?.code === "ENOENT") throw new NotFoundError();
+    throw err;
+  }
+  return parseTasksMarkdown(content);
+}
+
+export async function toggleTask(
+  cwd: string,
+  change: string,
+  id: string,
+  done: boolean,
+  line: number,
+): Promise<OpenSpecTask> {
+  const p = tasksMdPath(cwd, change);
+  let content: string;
+  try {
+    content = await fs.readFile(p, "utf-8");
+  } catch (err: any) {
+    if (err?.code === "ENOENT") throw new NotFoundError();
+    throw err;
+  }
+
+  // Preserve original line endings by splitting on \n and tracking \r individually.
+  const lines = content.split("\n");
+  if (line < 1 || line > lines.length) throw new LineMismatchError();
+
+  const idx = line - 1;
+  const raw = lines[idx];
+  const hadCR = raw.endsWith("\r");
+  const bare = hadCR ? raw.slice(0, -1) : raw;
+
+  const m = CHECKBOX_RE.exec(bare);
+  if (!m) throw new NotACheckboxError();
+  if (m[2] !== id) throw new LineMismatchError();
+
+  const currentDone = m[1] === "x" || m[1] === "X";
+  // Optimistic concurrency: the caller's `done` is the *target* state; the line
+  // must currently hold the opposite state. If it already matches, we treat
+  // that as a line-mismatch — the file changed under us.
+  if (currentDone === done) throw new LineMismatchError();
+
+  const marker = done ? "x" : " ";
+  const rewritten = bare.replace(CHECKBOX_RE, `- [${marker}] ${m[2]} ${m[3]}`);
+  lines[idx] = hadCR ? rewritten + "\r" : rewritten;
+
+  const newContent = lines.join("\n");
+  const tmp = p + ".tmp";
+  await fs.writeFile(tmp, newContent, "utf-8");
+  await fs.rename(tmp, p);
+
+  return {
+    id,
+    text: m[3].trim(),
+    done,
+    line,
+    group: findGroupForLine(lines, idx),
+  };
+}
+
+function findGroupForLine(lines: string[], idx: number): string {
+  for (let i = idx; i >= 0; i--) {
+    const raw = lines[i];
+    const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+    const h = HEADING_RE.exec(line);
+    if (h) return h[1].trim();
+  }
+  return "";
+}