@tekyzinc/gsd-t 3.16.12 → 3.18.11

package/scripts/gsd-t-compact-detector.js

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/**
+ * gsd-t-compact-detector.js
+ *
+ * SessionStart hook that records compaction events.
+ *
+ * Claude Code fires SessionStart with `source: "compact"` immediately after an
+ * auto-compaction. By contrast, a fresh launch fires with `source: "startup"`
+ * and a resumed session fires with `source: "resume"`. Only `compact` is
+ * recorded — it's the transition marker that separates one Context Window
+ * from the next.
+ *
+ * Without this hook, Context Window boundaries are invisible: every iter
+ * silently looks like a single CW. That breaks the canonical measurement
+ * hierarchy (Run → Iter → Context Window → Turn → Tool call).
+ *
+ * Behavior:
+ * - Zero-dep. Reads stdin JSON, silently fails on any error. Always exits 0 —
+ *   throwing here would break Claude Code session startup.
+ * - Only acts when `source === "compact"`.
+ * - Appends one NDJSON row to `<cwd>/.gsd-t/metrics/compactions.jsonl`.
+ * - Appends one compact_marker frame to the most-recently-modified
+ *   `<cwd>/.gsd-t/transcripts/*.ndjson` (the live transcript). No-ops
+ *   silently when no transcript exists.
+ * - 1 MiB stdin cap (defense in depth; real payloads are tiny).
+ * - Path-traversal guard: refuses any cwd that doesn't let the resolved
+ *   output path stay under `<cwd>/.gsd-t/metrics/`.
+ * - Off switch: if `<cwd>/.gsd-t/` does not exist, silent no-op. Creating it
+ *   is opt-in; deleting it disables the hook without having to edit
+ *   settings.json.
+ *
+ * Contract: .gsd-t/contracts/compaction-events-contract.md
+ */
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const MAX_STDIN = 1024 * 1024; // 1 MiB
+const SCHEMA_VERSION = 1;
+
+let input = "";
+let aborted = false;
+
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  input += chunk;
+  if (input.length > MAX_STDIN) {
+    aborted = true;
+    try { process.stdin.destroy(); } catch { /* noop */ }
+  }
+});
+process.stdin.on("error", () => { /* silent */ });
+process.stdin.on("end", () => {
+  if (aborted) { exitClean(); return; }
+  let payload;
+  try {
+    payload = JSON.parse(input);
+  } catch {
+    exitClean();
+    return;
+  }
+
+  if (!payload || typeof payload !== "object") { exitClean(); return; }
+
+  // Only record `compact`. Startup / resume are no-ops.
+  if (payload.source !== "compact") { exitClean(); return; }
+
+  try {
+    writeRow(payload);
+  } catch {
+    // silent — never throw
+  }
+  try {
+    writeTranscriptMarker(payload);
+  } catch {
+    // silent — never throw
+  }
+  exitClean();
+});
+
+function writeRow(payload) {
+  // `cwd` must be absolute when present. An invalid value is NOT silently
+  // coerced to process.cwd() — that would let a malformed payload write
+  // into whatever dir the hook happened to be spawned from.
+  let cwd;
+  if (typeof payload.cwd === "string") {
+    if (!path.isAbsolute(payload.cwd)) return; // invalid — no-op
+    cwd = payload.cwd;
+  } else if (payload.cwd === undefined || payload.cwd === null) {
+    cwd = process.cwd();
+  } else {
+    return; // non-string cwd — no-op
+  }
+
+  // `.gsd-t/` must exist — acts as the off-switch.
+  const gsdDir = path.join(cwd, ".gsd-t");
+  if (!fs.existsSync(gsdDir)) return;
+
+  const metricsDir = path.join(gsdDir, "metrics");
+  const outPath = path.join(metricsDir, "compactions.jsonl");
+
+  // Path-traversal guard.
+  const resolvedOut = path.resolve(outPath);
+  const resolvedMetrics = path.resolve(metricsDir) + path.sep;
+  if (!resolvedOut.startsWith(resolvedMetrics)) return;
+
+  try {
+    fs.mkdirSync(metricsDir, { recursive: true });
+  } catch {
+    return;
+  }
+
+  const row = {
+    ts: new Date().toISOString(),
+    schemaVersion: SCHEMA_VERSION,
+    session_id: typeof payload.session_id === "string" ? payload.session_id : null,
+    prior_session_id: typeof payload.prior_session_id === "string"
+      ? payload.prior_session_id
+      : (typeof payload.previous_session_id === "string"
+          ? payload.previous_session_id
+          : null),
+    source: "compact",
+    cwd,
+    hook: "SessionStart",
+  };
+
+  fs.appendFileSync(outPath, JSON.stringify(row) + "\n", "utf8");
+}
+
+/**
+ * Find the most-recently-modified .ndjson in <cwd>/.gsd-t/transcripts/.
+ * Returns the absolute path, or null if none exists or the directory is absent.
+ */
+function findActiveTranscript(cwd) {
+  const transcriptsDir = path.join(cwd, ".gsd-t", "transcripts");
+  let entries;
+  try {
+    entries = fs.readdirSync(transcriptsDir);
+  } catch {
+    return null;
+  }
+  const ndjsons = entries.filter((e) => e.endsWith(".ndjson"));
+  if (!ndjsons.length) return null;
+
+  let newest = null;
+  let newestMtime = -1;
+  for (const name of ndjsons) {
+    const full = path.join(transcriptsDir, name);
+    try {
+      const stat = fs.statSync(full);
+      if (stat.mtimeMs > newestMtime) {
+        newestMtime = stat.mtimeMs;
+        newest = full;
+      }
+    } catch {
+      // skip unreadable entries
+    }
+  }
+  return newest;
+}
+
+/**
+ * Append a compact_marker frame to the active transcript NDJSON.
+ * No-ops silently when no transcript exists.
+ */
+function writeTranscriptMarker(payload) {
+  let cwd;
+  if (typeof payload.cwd === "string") {
+    if (!path.isAbsolute(payload.cwd)) return;
+    cwd = payload.cwd;
+  } else if (payload.cwd === undefined || payload.cwd === null) {
+    cwd = process.cwd();
+  } else {
+    return;
+  }
+
+  const gsdDir = path.join(cwd, ".gsd-t");
+  if (!fs.existsSync(gsdDir)) return;
+
+  const transcriptPath = findActiveTranscript(cwd);
+  if (!transcriptPath) return;
+
+  // Path-traversal guard: resolved transcript path must stay under <cwd>/.gsd-t/transcripts/
+  const transcriptsDir = path.join(gsdDir, "transcripts") + path.sep;
+  if (!path.resolve(transcriptPath).startsWith(path.resolve(transcriptsDir))) return;
+
+  const marker = {
+    type: "compact_marker",
+    ts: new Date().toISOString(),
+    source: "compact",
+    session_id: typeof payload.session_id === "string" ? payload.session_id : null,
+    prior_session_id: typeof payload.prior_session_id === "string"
+      ? payload.prior_session_id
+      : (typeof payload.previous_session_id === "string"
+          ? payload.previous_session_id
+          : null),
+  };
+
+  // Include optional fields when present.
+  if (typeof payload.trigger === "string") marker.trigger = payload.trigger;
+  if (typeof payload.preTokens === "number") marker.preTokens = payload.preTokens;
+  if (typeof payload.postTokens === "number") marker.postTokens = payload.postTokens;
+  // Also check nested compactMetadata (scanner shape).
+  if (payload.compactMetadata && typeof payload.compactMetadata === "object") {
+    if (typeof payload.compactMetadata.trigger === "string" && !marker.trigger) {
+      marker.trigger = payload.compactMetadata.trigger;
+    }
+    if (typeof payload.compactMetadata.preTokens === "number" && marker.preTokens == null) {
+      marker.preTokens = payload.compactMetadata.preTokens;
+    }
+    if (typeof payload.compactMetadata.postTokens === "number" && marker.postTokens == null) {
+      marker.postTokens = payload.compactMetadata.postTokens;
+    }
+  }
+
+  fs.appendFileSync(transcriptPath, JSON.stringify(marker) + "\n", "utf8");
+}
+
+function exitClean() {
+  try { process.stdout.write(""); } catch { /* noop */ }
+  process.exit(0);
+}

package/scripts/gsd-t-compaction-scanner.js

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+/**
+ * gsd-t-compaction-scanner.js
+ *
+ * Historical backfill for compaction events.
+ *
+ * Claude Code writes one JSONL file per session under
+ * `~/.claude/projects/<cwd-slug>/`. Each auto-compaction emits a single row
+ * of shape:
+ *
+ *   { "type": "system", "subtype": "compact_boundary",
+ *     "timestamp": "…", "sessionId": "…", "cwd": "…",
+ *     "compactMetadata": { "trigger": "auto",
+ *                          "preTokens": …, "postTokens": …,
+ *                          "durationMs": … } }
+ *
+ * This tool scans those session files, extracts the boundaries, dedups
+ * against the existing `<projectDir>/.gsd-t/metrics/compactions.jsonl`, and
+ * — only when `--write` is passed — appends the missing rows with
+ * `source: "compact-backfill"`.
+ *
+ * Defaults to DRY-RUN. The `--write` flag is required to mutate state.
+ *
+ * Contract: .gsd-t/contracts/compaction-events-contract.md
+ *
+ * Usage:
+ *   node scripts/gsd-t-compaction-scanner.js [--write] [--project-dir DIR]
+ *                                            [--sessions-root DIR]
+ *                                            [--limit N]
+ */
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const readline = require("readline");
+
+const SCHEMA_VERSION = 1;
+
+/* ───────────────────────── arg parsing ───────────────────────── */
+
+function parseArgs(argv) {
+  const args = { write: false, projectDir: process.cwd(), sessionsRoot: null, limit: null, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--write") args.write = true;
+    else if (a === "--project-dir") args.projectDir = argv[++i];
+    else if (a === "--sessions-root") args.sessionsRoot = argv[++i];
+    else if (a === "--limit") args.limit = parseInt(argv[++i], 10) || null;
+    else if (a === "-h" || a === "--help") args.help = true;
+  }
+  return args;
+}
+
+function printHelp() {
+  process.stdout.write(
+    [
+      "gsd-t-compaction-scanner — backfill .gsd-t/metrics/compactions.jsonl",
+      "",
+      "Usage: node scripts/gsd-t-compaction-scanner.js [flags]",
+      "",
+      "  --write                  Actually write. Default is dry-run.",
+      "  --project-dir DIR        Project root (default: cwd).",
+      "  --sessions-root DIR      Override sessions root (default: derive from",
+      "                           ~/.claude/projects/<slug-of-project-dir>).",
+      "  --limit N                Stop after scanning N files (diagnostic).",
+      "  -h, --help               Show this help.",
+      "",
+      "Default is DRY-RUN. Pass --write to mutate compactions.jsonl.",
+      "",
+    ].join("\n")
+  );
+}
+
+/* ───────────────── sessions-root slug helper ───────────────── */
+
+/**
+ * Claude Code encodes project directories in `~/.claude/projects/` by
+ * replacing `/` with `-`. For `/Users/david/projects/GSD-T` → slug is
+ * `-Users-david-projects-GSD-T`. Leading dash is intentional.
+ */
+function deriveSessionsRoot(projectDir) {
+  const abs = path.resolve(projectDir);
+  const slug = abs.replace(/\//g, "-");
+  return path.join(os.homedir(), ".claude", "projects", slug);
+}
+
+/* ───────────────── scanner ───────────────── */
+
+/**
+ * Scan one session JSONL file and yield compact_boundary rows. Returns an
+ * array (sessions rarely exceed tens of MB of NDJSON; a synchronous pass
+ * would still be fine but we use streaming to be safe on huge files).
+ *
+ * Silent-fail on any read/parse error per line (the goal is best-effort
+ * historical extraction, not validation of Claude Code's archive format).
+ *
+ * @returns {Promise<Array<object>>}
+ */
+async function scanSessionFile(filePath) {
+  const out = [];
+  if (!fs.existsSync(filePath)) return out;
+
+  let stream;
+  try {
+    stream = fs.createReadStream(filePath, { encoding: "utf8" });
+  } catch {
+    return out;
+  }
+
+  const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+  for await (const line of rl) {
+    if (!line || line.length < 2) continue;
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (obj && obj.type === "system" && obj.subtype === "compact_boundary") {
+      out.push(obj);
+    }
+  }
+  return out;
+}
+
+/**
+ * Convert a compact_boundary JSONL row into our canonical compaction row.
+ */
+function boundaryToRow(b) {
+  const row = {
+    ts: typeof b.timestamp === "string" ? b.timestamp : new Date().toISOString(),
+    schemaVersion: SCHEMA_VERSION,
+    session_id: typeof b.sessionId === "string" ? b.sessionId : null,
+    // `logicalParentUuid` is the last message in the pre-compact window — as
+    // close as the archive gets to a "prior session id" for in-place
+    // compactions. It's NOT a true session id, but it's a stable boundary
+    // anchor that consumers can join on.
+    prior_session_id:
+      typeof b.logicalParentUuid === "string" ? b.logicalParentUuid : null,
+    source: "compact-backfill",
+    cwd: typeof b.cwd === "string" ? b.cwd : null,
+    hook: "SessionStart",
+  };
+
+  const meta = b.compactMetadata || {};
+  if (typeof meta.trigger === "string") row.trigger = meta.trigger;
+  if (Number.isFinite(meta.preTokens)) row.preTokens = meta.preTokens;
+  if (Number.isFinite(meta.postTokens)) row.postTokens = meta.postTokens;
+  if (Number.isFinite(meta.durationMs)) row.durationMs = meta.durationMs;
+
+  return row;
+}
+
+/**
+ * Load existing compactions.jsonl (if any) and build a dedup key set.
+ * Key = `${ts}\t${session_id}`.
+ */
+function loadExistingKeys(compactionsPath) {
+  const keys = new Set();
+  if (!fs.existsSync(compactionsPath)) return keys;
+  let raw;
+  try {
+    raw = fs.readFileSync(compactionsPath, "utf8");
+  } catch {
+    return keys;
+  }
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const obj = JSON.parse(line);
+      keys.add(`${obj.ts || ""}\t${obj.session_id || ""}`);
+    } catch {
+      /* ignore malformed historical rows */
+    }
+  }
+  return keys;
+}
+
+function rowKey(row) {
+  return `${row.ts}\t${row.session_id || ""}`;
+}
+
+/* ───────────────── orchestrator ───────────────── */
+
+async function run({ write, projectDir, sessionsRoot, limit, _sessionFiles, _scanSessionFile, _stdout }) {
+  const root = sessionsRoot || deriveSessionsRoot(projectDir);
+  const stdout = _stdout || ((s) => process.stdout.write(s));
+  const scan = _scanSessionFile || scanSessionFile;
+
+  let files;
+  if (Array.isArray(_sessionFiles)) {
+    files = _sessionFiles;
+  } else if (!fs.existsSync(root)) {
+    stdout(`Sessions root does not exist: ${root}\nNothing to do.\n`);
+    return { scanned: 0, found: 0, newRows: 0, wrote: 0 };
+  } else {
+    try {
+      files = fs
+        .readdirSync(root)
+        .filter((f) => f.endsWith(".jsonl"))
+        .map((f) => path.join(root, f));
+    } catch {
+      files = [];
+    }
+  }
+  if (limit && files.length > limit) files = files.slice(0, limit);
+
+  const metricsDir = path.join(projectDir, ".gsd-t", "metrics");
+  const outPath = path.join(metricsDir, "compactions.jsonl");
+  const existing = loadExistingKeys(outPath);
+
+  stdout(`Scanning ${files.length} session file(s) from ${root}\n`);
+  stdout(`Target sink: ${outPath} (${existing.size} existing row(s))\n`);
+  stdout(write ? "Mode: WRITE\n\n" : "Mode: DRY-RUN (pass --write to mutate)\n\n");
+
+  const newRows = [];
+  let scanned = 0;
+  let found = 0;
+
+  for (const file of files) {
+    scanned++;
+    let boundaries;
+    try {
+      boundaries = await scan(file);
+    } catch {
+      boundaries = [];
+    }
+    for (const b of boundaries) {
+      found++;
+      const row = boundaryToRow(b);
+      const key = rowKey(row);
+      if (existing.has(key)) continue;
+      existing.add(key);
+      newRows.push(row);
+    }
+  }
+
+  // Sort by ts ascending for a stable, chronologically-ordered append.
+  newRows.sort((a, b) => String(a.ts).localeCompare(String(b.ts)));
+
+  stdout(`Scanned: ${scanned} file(s)\n`);
+  stdout(`Compact boundaries found: ${found}\n`);
+  stdout(`New rows (post-dedup): ${newRows.length}\n\n`);
+
+  if (newRows.length > 0) {
+    stdout("Sample (first up to 5):\n");
+    for (const r of newRows.slice(0, 5)) {
+      stdout(`  ${r.ts}  session=${r.session_id || "?"}  ` +
+             `trigger=${r.trigger || "?"}  ` +
+             `pre=${r.preTokens ?? "?"} post=${r.postTokens ?? "?"}\n`);
+    }
+    stdout("\n");
+  }
+
+  let wrote = 0;
+  if (write && newRows.length > 0) {
+    try {
+      fs.mkdirSync(metricsDir, { recursive: true });
+      const payload = newRows.map((r) => JSON.stringify(r)).join("\n") + "\n";
+      fs.appendFileSync(outPath, payload, "utf8");
+      wrote = newRows.length;
+      stdout(`Wrote ${wrote} row(s) to ${outPath}\n`);
+    } catch (e) {
+      stdout(`Write failed: ${e && e.message ? e.message : e}\n`);
+    }
+  } else if (!write) {
+    stdout("Dry-run — no changes made. Re-run with --write to persist.\n");
+  }
+
+  return { scanned, found, newRows: newRows.length, wrote };
+}
+
+/* ───────────────── CLI ───────────────── */
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    printHelp();
+    process.exit(0);
+  }
+  try {
+    const result = await run(args);
+    // Success even when nothing new — exit 0. Exit 1 only on catastrophic
+    // error (caught below).
+    process.exit(0);
+    return result;
+  } catch (e) {
+    process.stderr.write(`scanner error: ${e && e.message ? e.message : e}\n`);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  run,
+  scanSessionFile,
+  boundaryToRow,
+  deriveSessionsRoot,
+  loadExistingKeys,
+  rowKey,
+};
+
+if (require.main === module) {
+  main();
+}

package/scripts/gsd-t-dashboard-autostart.cjs

@@ -0,0 +1,172 @@
+'use strict';
+/**
+ * GSD-T Dashboard Autostart (M43 D6-T4)
+ *
+ * Idempotent, silent starter for the transcript/dashboard server. Called at
+ * every spawn start path in `bin/headless-auto-spawn.cjs` so the URL banner
+ * printed next to it (D6-T3) always resolves to a live listener.
+ *
+ * Design notes:
+ *   - The port is resolved via `projectScopedDefaultPort(projectDir)` from
+ *     the multi-project isolation quick (df34eb2) — each project has its
+ *     own deterministic default port.
+ *   - We probe the port with `net.createServer().listen(...)` — if it binds
+ *     the port was free and we fork-detach the dashboard server. If the
+ *     probe fails with EADDRINUSE, we assume the server is already running
+ *     (or some other process grabbed the port; we defer to the user in that
+ *     case and return alreadyRunning:true — the banner link still points
+ *     there, and if it's foreign the user sees a friendlier failure than
+ *     a stacktrace).
+ *   - PID file lives at `.gsd-t/.dashboard.pid` relative to projectDir.
+ *     Distinct from M38's `.gsd-t/dashboard.pid` (hyphen vs. dot) so the
+ *     two lifecycles don't collide.
+ *
+ * Zero deps.
+ */
+
+const fs = require('fs');
+const net = require('net');
+const path = require('path');
+const { spawn, spawnSync } = require('child_process');
+
+const PID_REL = path.join('.gsd-t', '.dashboard.pid');
+
+function _pidPath(projectDir) {
+  return path.join(projectDir || '.', PID_REL);
+}
+
+/**
+ * Check if a port is already bound by someone. Resolves `{ busy: bool, reason? }`.
+ *
+ * @param {number} port
+ * @param {string} [host='127.0.0.1']
+ * @returns {Promise<{busy: boolean, reason?: string}>}
+ */
+function _probePort(port, host) {
+  return new Promise((resolve) => {
+    const srv = net.createServer();
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      try { srv.close(); } catch (_) { /* ok */ }
+      resolve(result);
+    };
+    srv.once('error', (err) => {
+      if (err && err.code === 'EADDRINUSE') finish({ busy: true, reason: 'EADDRINUSE' });
+      else finish({ busy: true, reason: String(err && err.code ? err.code : err) });
+    });
+    srv.once('listening', () => {
+      finish({ busy: false });
+    });
+    try {
+      srv.listen(port, host || '127.0.0.1');
+    } catch (err) {
+      finish({ busy: true, reason: String(err && err.code ? err.code : err) });
+    }
+  });
+}
+
+/**
+ * Synchronous port-busy probe. Forks a tiny node child that attempts to
+ * `net.createServer().listen(port)` and exits 1 if EADDRINUSE, else
+ * closes the server and exits 0. This gives us a definitive answer
+ * in O(50ms) from a synchronous caller — Node's `net.Server#listen` is
+ * async, which makes a purely in-process synchronous probe impossible
+ * without busy-looping the event loop (which doesn't advance during JS
+ * execution).
+ *
+ * Important: we probe with **no host** to match the dashboard server's
+ * `server.listen(port)` (which binds to the IPv6 wildcard `::`). On macOS
+ * dual-stack, binding to `127.0.0.1` alongside a wildcard on `::` is
+ * permitted and would make a host-specific probe falsely report "free".
+ * The `host` parameter is accepted for backward compatibility but, when
+ * omitted, we use the host-less form. Passing an explicit host preserves
+ * legacy semantics for callers that rely on it.
+ *
+ * Returns `true` if the port is in use (EADDRINUSE), `false` otherwise.
+ * On spawn failure we conservatively return `false` so the caller tries
+ * to start the server — it will then fail fast and the caller falls back
+ * to the "assume running" path via its own handling.
+ */
+function _isPortBusySync(port, host) {
+  const listenArgs = host
+    ? `${JSON.stringify(port)}, ${JSON.stringify(host)}`
+    : `${JSON.stringify(port)}`;
+  const script = `
+    const net = require('net');
+    const srv = net.createServer();
+    srv.once('error', (e) => { if (e && e.code === 'EADDRINUSE') process.exit(1); process.exit(2); });
+    srv.once('listening', () => { srv.close(() => process.exit(0)); });
+    srv.listen(${listenArgs});
+  `;
+  try {
+    const r = spawnSync(process.execPath, ['-e', script], { timeout: 10000, stdio: 'ignore' });
+    return r.status === 1;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Ensure the dashboard server is running on the project's scoped port.
+ *
+ * Idempotent: safe to call on every spawn. Silent: no stdout/stderr writes
+ * on the happy path; the detached child's stdio is ignored.
+ *
+ * **Synchronous contract**: returns immediately with `{port, pid, alreadyRunning}`.
+ *  - If the port is already bound, returns `alreadyRunning: true`.
+ *  - Otherwise fork-detaches the dashboard server and records its pid.
+ *
+ * @param {object} opts
+ * @param {string} [opts.projectDir='.']
+ * @param {number} [opts.port]
+ * @param {string} [opts.host='127.0.0.1']
+ * @returns {{port: number, pid: number|null, alreadyRunning: boolean}}
+ */
+function ensureDashboardRunning(opts) {
+  const projectDir = (opts && opts.projectDir) || '.';
+  const host = (opts && opts.host) || '127.0.0.1';
+  let port = opts && opts.port;
+  if (!port) {
+    const srv = require('./gsd-t-dashboard-server.js');
+    port = srv.projectScopedDefaultPort(projectDir);
+  }
+
+  // Probe with no host to match the dashboard server's listen(port) — which
+  // binds to the IPv6 wildcard. Probing a specific host would falsely report
+  // "free" on macOS dual-stack. `host` is retained only for the spawn env.
+  const busy = _isPortBusySync(port);
+  if (busy) {
+    return { port, pid: null, alreadyRunning: true };
+  }
+
+  // Port was free — fork-detach the dashboard server.
+  const serverScript = path.join(__dirname, 'gsd-t-dashboard-server.js');
+  const child = spawn(process.execPath, [serverScript, '--port', String(port)], {
+    cwd: projectDir,
+    detached: true,
+    stdio: 'ignore',
+    env: Object.assign({}, process.env, {
+      GSD_T_PROJECT_DIR: path.resolve(projectDir),
+    }),
+  });
+  child.unref();
+
+  // Record pid. Best-effort; does not throw on filesystem failure.
+  const pidFile = _pidPath(projectDir);
+  try {
+    fs.mkdirSync(path.dirname(pidFile), { recursive: true });
+    fs.writeFileSync(pidFile, String(child.pid));
+  } catch (_) { /* pid-file writing is best-effort */ }
+
+  return { port, pid: child.pid || null, alreadyRunning: false };
+}
+
+module.exports = {
+  ensureDashboardRunning,
+  _probePort,
+  _isPortBusySync,
+  _pidPath,
+  PID_REL,
+};