karajan-code 2.7.4 → 2.9.0

package/src/commands/architect.js

@@ -2,6 +2,7 @@ import { createAgent } from "../agents/index.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { resolveRole } from "../config.js";
 import { buildArchitectPrompt, parseArchitectOutput } from "../prompts/architect.js";
+import { createCliProgressReporter } from "../utils/cli-progress.js";
 
 function formatLayers(layers, lines) {
   lines.push("### Layers");
@@ -67,8 +68,12 @@ export async function architectCommand({ task, config, logger, context, json })
 
     const agent = createAgent(architectRole.provider, config, logger);
     const prompt = await buildArchitectPrompt({ task, researchContext: context });
-    const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
-    const result = await agent.runTask({ prompt, onOutput, role: "architect" });
+    const progress = createCliProgressReporter({ role: "architect" });
+    let result;
+    try {
+      result = await agent.runTask({ prompt, onOutput: progress.onOutput, role: "architect" });
+      progress.finish(result.ok ? "done" : "failed");
+    } catch (err) { progress.finish("failed"); throw err; }
 
     if (!result.ok) {
       throw new Error(result.error || result.output || "Architect failed");
@@ -86,6 +91,28 @@ export async function architectCommand({ task, config, logger, context, json })
     } else {
       console.log(result.output);
     }
+
+    // Persist ADRs from the architect's tradeoffs[] (v2.7.5). One ADR
+    // per tradeoff in Nygard format under `~/.kj/plans/_loose/adrs/`.
+    // Coder/reviewer in subsequent runs can pull the active ADRs into
+    // their prompt for context — done in a follow-up PR.
+    if (parsed?.architecture && config?.projectDir) {
+      try {
+        const { persistAdrsFromArchitecture } = await import("../plan/adr-generator.js");
+        const { adrs, paths } = await persistAdrsFromArchitecture({
+          projectDir: config.projectDir,
+          planId: null,                  // standalone architect → "_loose" bucket
+          architecture: parsed.architecture,
+        });
+        if (paths.length > 0) {
+          console.log(`\n${adrs.length} ADR${adrs.length === 1 ? "" : "s"} written:`);
+          for (const p of paths) console.log(`  - ${p}`);
+        }
+      } catch (err) {
+        logger.warn(`ADR write skipped: ${err.message}`);
+      }
+    }
+
     logger.info("Architect completed.");
     return { ok: true };
   });

package/src/commands/audit.js

@@ -1,8 +1,36 @@
-import { createAgent } from "../agents/index.js";
+import path from "node:path";
+import fs from "node:fs/promises";
+import readline from "node:readline";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { resolveRole } from "../config.js";
-import { buildAuditPrompt, parseAuditOutput, AUDIT_DIMENSIONS } from "../prompts/audit.js";
+import { AUDIT_DIMENSIONS } from "../prompts/audit.js";
+import { AuditRole } from "../roles/audit-role.js";
 import { withCliRunLog } from "../utils/cli-run-log.js";
+import { createCliProgressReporter } from "../utils/cli-progress.js";
+import { runAgentReadiness, formatAgentReadinessReport } from "../audit/agent-readiness.js";
+import { formatDeterministicSummary } from "../audit/deterministic-summary.js";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Prompt the user (TTY only) to decide whether to continue with the LLM
+ * phase after deterministic findings have been printed. KJC-TSK-0364.
+ *
+ * @returns {Promise<boolean>} true to continue with LLM, false to skip
+ */
+function promptContinueWithLlm({ promptFn = null } = {}) {
+  if (typeof promptFn === "function") return promptFn();
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) { resolve(true); return; } // CI / piped input → continue
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question("Continue with LLM analysis? [y/N] ", (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test((answer || "").trim()));
+    });
+  });
+}
 
 function formatFindings(findings) {
   const lines = [];
@@ -42,10 +70,11 @@ const DIMENSION_LABELS = {
   codeQuality: "Code Quality",
   performance: "Performance",
   architecture: "Architecture",
-  testing: "Testing"
+  testing: "Testing",
+  accessibility: "Accessibility (WCAG 2.x)"
 };
 
-function formatAudit(parsed) {
+function formatAudit(parsed, usage = null) {
   const lines = [];
   lines.push("## Codebase Health Report");
   lines.push(`**Overall Health:** ${parsed.summary.overallHealth}`);
@@ -63,45 +92,251 @@ function formatAudit(parsed) {
   }
 
   if (parsed.textSummary) lines.push(`---\n${parsed.textSummary}`);
+
+  const usageBlock = formatUsageSummary(usage);
+  if (usageBlock) {
+    lines.push("");
+    lines.push(usageBlock);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format the LLM token + cost summary that closes every audit report.
+ * KJC-TSK-0363: makes the LLM cost visible (was silently discarded
+ * pre-patch — auditCommand never read roleResult.usage).
+ *
+ * @param {object|null} usage - shape produced by AuditRole's extractUsage
+ * @returns {string|null} markdown block, or null when there's nothing useful to show
+ */
+function formatUsageSummary(usage) {
+  if (!usage) return null;
+  const lines = ["## LLM Usage"];
+  lines.push(`- Provider: ${usage.provider}${usage.model ? ` (${usage.model})` : ""}`);
+  if (typeof usage.durationMs === "number") {
+    lines.push(`- Duration: ${(usage.durationMs / 1000).toFixed(1)}s`);
+  }
+  if (!usage.available) {
+    lines.push(`- Tokens: usage data not available — ${usage.reason || "provider does not report it"}`);
+    return lines.join("\n");
+  }
+  // Force en-US locale so the comma grouping is deterministic across CI
+  // machines (Node's default Intl.NumberFormat depends on the runtime
+  // locale; without this the rendering would look like "1234" on
+  // locale-less Node and "1,234" on a US-locale workstation).
+  const fmt = (n) => n.toLocaleString("en-US");
+  lines.push(`- Tokens: ${fmt(usage.total_tokens)} total (${fmt(usage.tokens_in)} in, ${fmt(usage.tokens_out)} out)`);
+  if (typeof usage.cost_usd === "number") {
+    lines.push(`- Estimated cost: $${usage.cost_usd.toFixed(4)} USD`);
+  }
   return lines.join("\n");
 }
 
-export async function auditCommand({ task, config, logger, dimensions, json }) {
+/**
+ * Resolve where to write the audit report on disk, given a flag value, an
+ * env override, and the desired format. Returns null if no write target
+ * was requested. Creates parent directories on demand.
+ *
+ * Resolution rules (KJC-TSK-0362):
+ *   - flag undefined + no env → null (legacy behaviour, stdout only)
+ *   - flag is a directory → write `audit-<ISO>.{md,json}` inside it
+ *   - flag is a non-directory path → use it verbatim (extension drives format
+ *     when --json/--md not explicit)
+ *   - flag is undefined but env $KJ_AUDIT_REPORT_DIR is set → treat env as dir
+ */
+async function resolveReportFilePath(flagValue, isJson) {
+  const envDir = process.env.KJ_AUDIT_REPORT_DIR;
+  const target = flagValue || (envDir ? envDir : null);
+  if (!target) return null;
+
+  const ext = isJson ? "json" : "md";
+  let stats = null;
+  try { stats = await fs.stat(target); } catch { /* not a directory yet */ }
+  const isDir = stats?.isDirectory() || target.endsWith(path.sep) || target === envDir;
+
+  let resolved;
+  if (isDir) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    resolved = path.resolve(target, `audit-${stamp}.${ext}`);
+  } else {
+    resolved = path.resolve(target);
+  }
+
+  await fs.mkdir(path.dirname(resolved), { recursive: true });
+  return resolved;
+}
+
+/**
+ * Build the markdown header that prefixes a persisted report — captures
+ * timestamp + repo state + invocation flags so the file is reproducible.
+ */
+async function buildReportHeader(projectDir, invocation) {
+  const lines = ["# Karajan Audit Report", ""];
+  lines.push(`- **Generated:** ${new Date().toISOString()}`);
+  lines.push(`- **Project:** ${projectDir || process.cwd()}`);
+
+  // Best-effort git info — silent if outside a repo.
+  try {
+    const branch = (await execFileAsync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: projectDir, timeout: 2000 })).stdout.trim();
+    const commit = (await execFileAsync("git", ["rev-parse", "--short", "HEAD"], { cwd: projectDir, timeout: 2000 })).stdout.trim();
+    lines.push(`- **Branch:** ${branch}`);
+    lines.push(`- **Commit:** ${commit}`);
+  } catch { /* not a git repo or git missing */ }
+
+  if (invocation) lines.push(`- **Invocation:** \`${invocation}\``);
+  lines.push("");
+  lines.push("---");
+  lines.push("");
+  return lines.join("\n");
+}
+
+function describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, json, deterministicOnly, yes }) {
+  const parts = ["kj audit"];
+  if (task && task !== "Analyze the full codebase") parts.push(JSON.stringify(task));
+  if (dimensions && dimensions !== "all") parts.push(`--dimensions=${dimensions}`);
+  if (noSonar) parts.push("--no-sonar");
+  if (noOsv) parts.push("--no-osv");
+  if (noSemgrep) parts.push("--no-semgrep");
+  if (deterministicOnly) parts.push("--deterministic-only");
+  if (yes) parts.push("--yes");
+  if (json) parts.push("--json");
+  return parts.join(" ");
+}
+
+export async function auditCommand({ task, config, logger, dimensions, json, agentReadiness, path: pathArg, noSonar = false, noOsv = false, noSemgrep = false, reportFile = null, deterministicOnly = false, yes = false, promptFn = null }) {
+  // --agent-readiness is a STANDALONE, deterministic, LLM-free audit
+  // dimension. It scores any third-party repo for AI-agent readability
+  // (llms.txt presence, page token budgets, robots allowlist, etc.).
+  // Per addyosmani/agentic-seo. Issue #542.
+  if (agentReadiness) {
+    const rootDir = path.resolve(pathArg || config?.projectDir || process.cwd());
+    logger.info(`Auditing agent-readiness of ${rootDir}`);
+    const report = runAgentReadiness(rootDir);
+    if (json) {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      console.log(formatAgentReadinessReport(report, rootDir));
+    }
+    // Exit code: 0 always (audit succeeded). The score is the signal.
+    return;
+  }
+
   return withCliRunLog("audit", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
-    const auditRole = resolveRole(config, "audit");
-    await assertAgentsAvailable([auditRole.provider]);
-    logger.info(`Audit (${auditRole.provider}) starting...`);
-    runLog.logText(`[audit] provider=${auditRole.provider} dimensions=${dimensions || "all"}`);
-
-    const agent = createAgent(auditRole.provider, config, logger);
-    const dimList = dimensions && dimensions !== "all"
-      ? dimensions.split(",").map(d => d.trim().toLowerCase()).map(d => d === "quality" ? "codeQuality" : d).filter(d => AUDIT_DIMENSIONS.includes(d))
-      : null;
-
-    const prompt = buildAuditPrompt({ task: task || "Analyze the full codebase", dimensions: dimList });
-    const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
-    const result = await agent.runTask({ prompt, onOutput, role: "audit" });
-
-    if (!result.ok) {
-      throw new Error(result.error || result.output || "Audit failed");
+    const auditRoleConfig = resolveRole(config, "audit");
+    await assertAgentsAvailable([auditRoleConfig.provider]);
+    logger.info(`Audit (${auditRoleConfig.provider}) starting...`);
+    runLog.logText(`[audit] provider=${auditRoleConfig.provider} dimensions=${dimensions || "all"} deterministicOnly=${deterministicOnly}`);
+
+    // Two-phase audit (KJC-TSK-0364) — collect deterministic findings
+    // first; show them; ask the user (when TTY + not --yes + not
+    // --deterministic-only) whether to spend tokens on the LLM analysis.
+    // CI / piped input / --yes / --deterministic-only never prompts.
+    const role = new AuditRole({ config, logger });
+    const roleInput = {
+      task: task || "Analyze the full codebase",
+      dimensions: dimensions || null,
+      noSonar,
+      noOsv,
+      noSemgrep,
+    };
+    const deterministicCtx = await role.collectDeterministic(roleInput);
+    const deterministicMd = formatDeterministicSummary(deterministicCtx);
+
+    // --json suppresses the interactive flow regardless: it would mangle
+    // a script's stdout. JSON consumers always get the full audit unless
+    // they explicitly pass deterministicOnly.
+    const reportPath = await resolveReportFilePath(reportFile, json);
+    let runLlm = !deterministicOnly;
+    if (runLlm && !json && !yes) {
+      console.log(deterministicMd);
+      console.log("");
+      const ok = await promptContinueWithLlm({ promptFn });
+      runLlm = ok;
+      if (!ok) logger.info("LLM analysis skipped (deterministic-only mode).");
     }
 
-    const parsed = parseAuditOutput(result.output);
-    if (parsed?.summary) {
+    if (!runLlm) {
+      // Deterministic-only path. Produce the report from what we already
+      // have, persist it (md or json), and exit. Zero tokens spent.
+      const stdoutContent = json
+        ? JSON.stringify({ deterministic: deterministicCtx, mode: "deterministic-only" }, null, 2)
+        : (deterministicOnly ? deterministicMd : ""); // already printed above when interactive
+      if (json || deterministicOnly) console.log(stdoutContent);
+
+      if (reportPath) {
+        let payload;
+        if (reportPath.endsWith(".json")) {
+          payload = JSON.stringify({ deterministic: deterministicCtx, mode: "deterministic-only" }, null, 2);
+        } else {
+          const header = await buildReportHeader(config?.projectDir, describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, json, deterministicOnly, yes }));
+          payload = header + deterministicMd + "\n";
+        }
+        await fs.writeFile(reportPath, payload, "utf8");
+        runLog.logText(`[audit] report written (deterministic-only) → ${reportPath}`);
+        logger.info(`Audit report written: ${reportPath}`);
+      }
+      logger.info("Audit completed (deterministic-only).");
+      return { ok: true, mode: "deterministic-only", reportPath: reportPath || undefined };
+    }
+
+    // Continue with the LLM phase using the already-collected context.
+    const progress = createCliProgressReporter({ role: "auditor" });
+    let roleResult;
+    try {
+      roleResult = await role.executeWithDeterministic({ ...roleInput, onOutput: progress.onOutput }, deterministicCtx);
+      progress.finish(roleResult.ok ? "done" : "failed");
+    } catch (err) { progress.finish("failed"); throw err; }
+
+    if (!roleResult.ok) {
+      const err = roleResult.result?.error || "Audit failed";
+      throw new Error(err);
+    }
+
+    const parsed = roleResult.result;
+    const usage = roleResult.usage;
+    if (parsed?.summary?.overallHealth) {
       runLog.logText(`[audit] findings=${parsed.summary.totalFindings} (critical=${parsed.summary.critical}, high=${parsed.summary.high})`);
     }
+    if (usage?.available) {
+      runLog.logText(`[audit] usage tokens=${usage.total_tokens} cost=$${(usage.cost_usd ?? 0).toFixed(4)} duration=${(usage.durationMs / 1000).toFixed(1)}s`);
+    }
 
+    let stdoutContent;
     if (json) {
-      console.log(JSON.stringify(parsed || result.output, null, 2));
-      return { ok: true };
+      const jsonPayload = parsed
+        ? { ...parsed, usage: usage || undefined }
+        : { ...roleResult, usage: usage || undefined };
+      stdoutContent = JSON.stringify(jsonPayload, null, 2);
+    } else if (parsed?.summary?.overallHealth) {
+      stdoutContent = formatAudit(parsed, usage);
+    } else if (parsed?.raw) {
+      stdoutContent = parsed.raw + (usage ? `\n\n${formatUsageSummary(usage) || ""}` : "");
+    } else {
+      stdoutContent = roleResult.summary || "Audit complete.";
     }
+    console.log(stdoutContent);
 
-    if (parsed?.summary) {
-      console.log(formatAudit(parsed));
-    } else {
-      console.log(result.output);
+    if (reportPath) {
+      let payload;
+      if (reportPath.endsWith(".json")) {
+        const jsonPayload = parsed
+          ? { ...parsed, usage: usage || undefined }
+          : { ...roleResult, usage: usage || undefined };
+        payload = JSON.stringify(jsonPayload, null, 2);
+      } else {
+        const header = await buildReportHeader(config?.projectDir, describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, json, deterministicOnly, yes }));
+        payload = header + stdoutContent + "\n";
+      }
+      await fs.writeFile(reportPath, payload, "utf8");
+      runLog.logText(`[audit] report written → ${reportPath}`);
+      logger.info(`Audit report written: ${reportPath}`);
     }
+
     logger.info("Audit completed.");
-    return { ok: true };
+    return { ok: true, reportPath: reportPath || undefined };
   });
 }
+
+// Exposed for tests — kept module-private otherwise.
+export { formatAudit, formatUsageSummary, AUDIT_DIMENSIONS };

package/src/commands/board.js

@@ -1,8 +1,10 @@
 import fs from "node:fs";
+import http from "node:http";
 import path from "node:path";
 import net from "node:net";
 import { spawn } from "node:child_process";
 import { getKarajanHome } from "../utils/paths.js";
+import { getPortOccupant } from "../utils/port-occupant.js";
 
 const BOARD_DIR = path.resolve(import.meta.dirname, "../../packages/hu-board");
 const PID_FILE = path.join(getKarajanHome(), "hu-board.pid");
@@ -25,6 +27,27 @@ function isProcessAlive(pid) {
   }
 }
 
+/**
+ * HTTP-probe the board's /api/dashboard. Returns true when it
+ * responds with 2xx within ~750ms. Used as a fallback when the PID
+ * file is missing/stale to detect "board is up, just untracked".
+ */
+async function isBoardReachable(port, timeoutMs = 750) {
+  return new Promise((resolve) => {
+    const req = http.request(
+      { host: '127.0.0.1', port, path: '/api/dashboard', method: 'GET', timeout: timeoutMs },
+      (res) => {
+        const ok = res.statusCode >= 200 && res.statusCode < 500;
+        res.resume();   // drain
+        resolve(ok);
+      }
+    );
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+    req.end();
+  });
+}
+
 /**
  * Check if a TCP port is available on localhost.
  * Returns true when we can successfully bind (port is free).
@@ -52,11 +75,45 @@ async function findAvailablePort(desiredPort, maxTries = 10) {
   return null;
 }
 
-export async function startBoard(desiredPort = 4000) {
+/**
+ * Build the board URL. When `projectSlug` is provided, the URL points at
+ * the per-project view (`/p/<slug>`) so the caller's project shows up
+ * pre-filtered instead of "All projects".
+ * @param {number} port
+ * @param {string|null} [projectSlug]
+ * @returns {string}
+ */
+function buildBoardUrl(port, projectSlug) {
+  const base = `http://localhost:${port}`;
+  return projectSlug ? `${base}/p/${projectSlug}` : base;
+}
+
+export async function startBoard(desiredPort = 4000, opts = {}) {
+  const { projectSlug = null } = opts;
   const existingPid = readPid();
   if (existingPid && isProcessAlive(existingPid)) {
     // Trust the saved PID — port info comes from the PID file if present
-    return { ok: true, alreadyRunning: true, pid: existingPid, url: `http://localhost:${desiredPort}` };
+    return {
+      ok: true,
+      alreadyRunning: true,
+      pid: existingPid,
+      url: buildBoardUrl(desiredPort, projectSlug),
+    };
+  }
+
+  // Belt-and-suspenders (v2.7.5 fix): even if the PID file is missing
+  // or stale, HTTP-probe the configured port before spawning. If
+  // /api/dashboard responds, a board is already there — reuse it. The
+  // pre-fix scenario: 🔁 self-restart didn't update the PID file
+  // (now fixed), so a `kj plan` afterwards saw a stale PID, spawned
+  // a duplicate board on port 4001, and confused the user.
+  if (await isBoardReachable(desiredPort)) {
+    return {
+      ok: true,
+      alreadyRunning: true,
+      pid: existingPid || null,
+      url: buildBoardUrl(desiredPort, projectSlug),
+    };
   }
 
   // Find a free port starting from desiredPort
@@ -79,34 +136,85 @@ export async function startBoard(desiredPort = 4000) {
   });
   // Swallow spawn errors so an HU Board failure never crashes the pipeline.
   child.on("error", () => { /* non-blocking — caller logs via tryAutoStartBoard catch */ });
-  child.unref();
-
   if (!child.pid) {
     throw new Error("Failed to spawn HU Board server");
   }
   fs.writeFileSync(PID_FILE, String(child.pid));
-  return { ok: true, alreadyRunning: false, pid: child.pid, url: `http://localhost:${port}`, port };
+  // Detach for real: `detached: true` only sets up the new session;
+  // without `unref()` the parent's event loop still holds a reference
+  // to the child handle and `kj board start` hangs at the prompt
+  // instead of returning. Pair this with stdio:"ignore" (already set)
+  // to ensure the parent isn't waiting on any of the child's pipes.
+  child.unref();
+  return { ok: true, alreadyRunning: false, pid: child.pid, url: buildBoardUrl(port, projectSlug), port };
 }
 
-export async function stopBoard() {
+export async function stopBoard(opts = {}) {
+  const { port = 4000 } = opts;
+  // Path 1: live PID in the file → straight SIGTERM. Pre-v2.7.5
+  // this was the only path; if the file was missing or stale (e.g.
+  // user ran a board built before the server-writes-own-PID fix in
+  // PR #508) we'd return "wasn't running" while the ghost server
+  // happily kept serving requests. The fallbacks below close that gap.
   const pid = readPid();
-  if (!pid || !isProcessAlive(pid)) {
-    try { fs.unlinkSync(PID_FILE); } catch { /* ignore */ }
-    return { ok: true, wasRunning: false };
+  if (pid && isProcessAlive(pid)) {
+    try { process.kill(pid, "SIGTERM"); } catch { /* race with dying process */ }
+    fs.rmSync(PID_FILE, { force: true });
+    return { ok: true, wasRunning: true, pid, via: "pidfile" };
   }
+  fs.rmSync(PID_FILE, { force: true });
 
-  try {
-    process.kill(pid, "SIGTERM");
-  } catch { /* process already dead */
-    // already dead
+  // Path 2: HTTP-ask the server to exit cleanly. Works for any
+  // running server that has the /api/board/shutdown endpoint —
+  // even when there's no PID file, no process tree to walk, etc.
+  const shutdownUrl = `/api/board/shutdown`;
+  const shutdownOk = await postBoardShutdown(port, shutdownUrl);
+  if (shutdownOk) {
+    return { ok: true, wasRunning: true, pid: null, via: "api" };
   }
-  try { fs.unlinkSync(PID_FILE); } catch { /* ignore */ }
-  return { ok: true, wasRunning: true, pid };
+
+  // Path 3: there's something on the port and the API didn't take it
+  // down. Find its PID via lsof / ss / netstat and SIGTERM it.
+  // Works against truly old servers that don't have the shutdown
+  // endpoint, with the cost of one extra subprocess call.
+  try {
+    const occupant = await getPortOccupant(port);
+    if (occupant?.pid) {
+      try { process.kill(occupant.pid, "SIGTERM"); } catch { /* gone */ }
+      return { ok: true, wasRunning: true, pid: occupant.pid, via: "port-occupant" };
+    }
+  } catch { /* lsof not installed etc — fall through */ }
+
+  return { ok: true, wasRunning: false };
+}
+
+/**
+ * Best-effort POST to the board's shutdown endpoint. Returns true
+ * when the server acks (and is presumably exiting); false on any
+ * error so the caller falls through to the next strategy.
+ */
+function postBoardShutdown(port, urlPath, timeoutMs = 750) {
+  return new Promise((resolve) => {
+    const req = http.request(
+      { host: '127.0.0.1', port, path: urlPath, method: 'POST', timeout: timeoutMs,
+        headers: { 'Content-Type': 'application/json', 'Content-Length': '2' } },
+      (res) => {
+        const ok = res.statusCode >= 200 && res.statusCode < 400;
+        res.resume();
+        resolve(ok);
+      }
+    );
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+    req.write('{}');
+    req.end();
+  });
 }
 
 export async function boardStatus(port = 4000) {
   const pid = readPid();
   const running = pid !== null && isProcessAlive(pid);
+
   return {
     ok: true,
     running,
@@ -115,27 +223,46 @@ export async function boardStatus(port = 4000) {
   };
 }
 
+// Strip ANSI escapes so we can measure the actual on-screen width of a
+// styled string. Used to size the rules around the banner content.
+const ANSI_RE = /\[[0-9;]*m/g;
+const visibleWidth = (s) => s.replace(ANSI_RE, "").length;
+
 /**
- * Render a highlighted cyan box with the HU Board URL + optional project name.
- * Centralizes the banner used by both the init-time auto-start (flow-runner.js)
- * and the post-planner auto-HU generation safety net so they stay in sync.
+ * Render a HU Board announcement framed by two horizontal rules of EQUAL
+ * length. Pre-v2.7.5 we used a fixed 50-char rounded box drawn with
+ * corners + verticals — fine when the URL fit, but a project slug
+ * pushed past the right wall and the box looked broken. The user's
+ * verdict: "looks worse than no box at all when it overflows".
+ *
+ * New rule: just an over-and-under rule sized to the longest visible
+ * content line. No left/right verticals, no fixed width. Always tidy.
  *
  * @param {Object} params
  * @param {string} params.url           - "http://localhost:4000"
  * @param {string} params.status        - "started" | "already running"
  * @param {string} [params.projectName] - optional project label
- * @returns {string} ANSI-escaped box ready for console.log
+ * @returns {string} ANSI-coloured banner ready for console.log
  */
 export function renderBoardBanner({ url, status, projectName }) {
-  const title = projectName ? `  Project: \u001b[1m${projectName}\u001b[0m` : null;
-  const lines = [
-    "",
-    "\u001b[36m\u256d\u2500 HU Board \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e",
-    `\u001b[36m\u2502\u001b[0m  \u001b[1m${status}\u001b[0m  \u001b[4m${url}\u001b[0m`,
-  ];
-  if (title) lines.push(`\u001b[36m\u2502\u001b[0m${title}`);
-  lines.push("\u001b[36m\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\u001b[0m", "");
-  return lines.join("\n");
+  const cyan = (s) => `${s}`;
+  const bold = (s) => `${s}`;
+  const underline = (s) => `${s}`;
+
+  const heading = `  ${bold("HU Board")} · ${status}  →  ${underline(url)}`;
+  const content = [heading];
+  if (projectName) content.push(`  Project: ${bold(projectName)}`);
+
+  // Width = widest visible content line + 2-cell padding. Cap at the
+  // terminal width so a silly-long URL doesn't draw a 200-char rule.
+  const termWidth = (process.stdout.columns && process.stdout.columns > 20)
+    ? process.stdout.columns
+    : 100;
+  const longest = Math.max(...content.map(visibleWidth));
+  const ruleWidth = Math.min(longest + 2, termWidth);
+  const rule = cyan("─".repeat(ruleWidth));
+
+  return ["", rule, ...content, rule, ""].join("\n");
 }
 
 export async function boardCommand({ action = "start", port = 4000, logger }) {
@@ -150,9 +277,11 @@ export async function boardCommand({ action = "start", port = 4000, logger }) {
       return result;
     }
     case "stop": {
-      const result = await stopBoard();
+      const result = await stopBoard({ port });
       if (result.wasRunning) {
-        logger.info(`HU Board stopped (PID ${result.pid})`);
+        const pidPart = result.pid ? ` (PID ${result.pid})` : "";
+        const viaPart = result.via && result.via !== "pidfile" ? ` [via ${result.via}]` : "";
+        logger.info(`HU Board stopped${pidPart}${viaPart}`);
       } else {
         logger.info("HU Board was not running");
       }
@@ -174,6 +303,7 @@ export async function boardCommand({ action = "start", port = 4000, logger }) {
         await startBoard(port);
       }
       const url = `http://localhost:${port}`;
+      // eslint-disable-next-line import-x/no-unresolved -- optional peer; the .catch handles its absence
       const { default: open } = await import("open").catch(() => ({ default: null }));
       if (open) {
         await open(url);