@skyf0xx/hedgehog 3.0.4 → 3.0.5

package/README.md

@@ -88,15 +88,14 @@ Artifact
 
 ### Anything else
 
-A CLI, a library, a browser extension, a data pipeline, a compiler — a
-project fitting neither shape gets its own build order, designed from
-your planning documents at intake rather than chosen from a menu. Run
-`init` with no core flag: planning intake names the system shape, picks
+A CLI, a library, a browser extension, a data pipeline, etc. fitting neither shape gets its own build order, designed at intake rather than chosen from a menu.
+
+Run `init` with no core flag: planning intake names the system shape, picks
 the stack, derives the layers, and locks them to `.hedgehog/core.yaml`,
 then generates that workspace and builds it one verified layer at a time.
 
-The layers are bespoke, the enforcement is the same — ordered steps,
-scoped file access, a verification command per layer, one commit each.
+The enforcement remains the same: ordered steps,
+scoped file access and a verification command per layer.
 
 ![Why Hedgehog works: a different way to build with AI, comparing traditional AI workflow to Hedgehog](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/why.png)
 
@@ -133,6 +132,24 @@ This refreshes `.claude/agents/` and `.claude/skills/` only. It never
 touches `CLAUDE.md`, the build graph, the core workspace, or
 `skills/BMAD`, since those carry project-specific or write-once content.
 
+To see the build graph:
+
+``` bash
+npx @skyf0xx/hedgehog graph
+```
+
+Starts a small local server and opens a live, read-only diagram of every
+task and its dependencies — one node per task, coloured by lifecycle
+status, laid out top-to-bottom by dependency order. Click a task to see
+its objective, verify command, and commit message; click empty canvas to
+close it. The page polls for changes, so it keeps updating on its own as
+`hedgehog verify` moves tasks through their lifecycle — no re-running the
+command or reloading the page. Running `graph` again while a server is
+already up reuses it instead of starting a second one. Pass `--no-open`
+to start (or reuse) the server and print its URL instead of launching a
+browser. `hedgehog plan` opens the same live view automatically whenever
+it compiles new tasks.
+
 ## Why Hedgehog
 
 Most AI coding tools improve prompting.

package/bin/cli.mjs

@@ -15,6 +15,7 @@ import { constants } from 'node:fs';
 import { DatabaseSync } from 'node:sqlite';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, relative, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
 import { dbInit, DB_PATH } from '../src/db/init.mjs';
 import { loadCore } from '../src/db/core.mjs';
 import { planTasks } from '../src/db/plan.mjs';
@@ -197,12 +198,15 @@ ${bold('Usage')}
   npx @skyf0xx/hedgehog init --force              overwrite existing files
   npx @skyf0xx/hedgehog update                    refresh .claude/agents + .claude/skills
   npx @skyf0xx/hedgehog db init                   create .hedgehog/hedgehog.db if absent
-  npx @skyf0xx/hedgehog plan                      compile pending intents into tasks + dependencies
+  npx @skyf0xx/hedgehog plan                      compile pending intents into tasks + dependencies,
+                                                   then open the build graph if anything compiled
   npx @skyf0xx/hedgehog intent add [flags]        add an intent (rules/requirements/dependencies)
   npx @skyf0xx/hedgehog intent add --file <path>  add an intent from a JSON file
   npx @skyf0xx/hedgehog next                      print the task packet for one ready task
   npx @skyf0xx/hedgehog verify <task-id>          run scope + verify checks, commit on pass
   npx @skyf0xx/hedgehog status                    graph overview: counts by status, ready list
+  npx @skyf0xx/hedgehog graph                     start (or reuse) the live graph server and open it
+  npx @skyf0xx/hedgehog graph --no-open           start (or reuse) the server; print the URL instead
   npx @skyf0xx/hedgehog why <path>                provenance chain for a file
   npx @skyf0xx/hedgehog friction add "<note>"     log a friction note [--task <task-id>]
   npx @skyf0xx/hedgehog friction list             list logged friction, oldest first
@@ -424,6 +428,18 @@ async function planCommand() {
   console.log(
     `\n${green(bold('Plan complete.'))} ${dim(`${result.compiled.length} intent(s) compiled, ${result.skipped.length} skipped`)}\n`,
   );
+
+  // Only worth opening when this run actually changed the graph's shape
+  // — a plan run that compiled nothing (every intent already had tasks)
+  // would just re-open what's already open. planTasks's own db handle is
+  // closed by this point: the graph server opens its own connection in a
+  // separate process, and holding two write-capable handles on the same
+  // sqlite file across that handoff invites lock contention for no
+  // benefit.
+  if (result.compiled.length > 0) {
+    const { port } = await startOrReuseGraphServer();
+    openInBrowser(`http://localhost:${port}`);
+  }
 }
 
 // Parses `hedgehog intent add` args into the same record shape
@@ -648,6 +664,133 @@ async function statusCommand() {
   console.log(formatStatus(result));
 }
 
+const GRAPH_PIDFILE_PATH = '.hedgehog/graph-server.json';
+const GRAPH_SERVER_MODULE = join(PKG_ROOT, 'src/db/graph-server.mjs');
+const GRAPH_TEMPLATE_PATH = join(PKG_ROOT, 'src/templates/graph.html');
+
+// Opens a URL/file with the OS default handler — the same mechanism
+// `open` (macOS), `xdg-open` (Linux), and `start` (Windows) provide,
+// chosen per-platform so this stays a zero-dependency CLI rather than
+// reaching for an npm package to do what the OS already does.
+function openInBrowser(url) {
+  const platform = process.platform;
+  const cmd =
+    platform === 'darwin' ? 'open' : platform === 'win32' ? 'start' : 'xdg-open';
+  const args = platform === 'win32' ? ['', url] : [url];
+  spawn(cmd, args, { detached: true, stdio: 'ignore', shell: platform === 'win32' }).unref();
+}
+
+// True if `pid` names a live process. Sending signal 0 performs the
+// existence/permission check without actually signalling anything — the
+// standard POSIX idiom `kill -0` follows, and Node exposes it the same
+// way via process.kill.
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Returns the port of a running graph server for this project, starting
+// one if none is live. Both `plan` (auto-open after scoping) and `graph`
+// (explicit request) call this rather than each managing their own
+// server, so a project only ever has one live server no matter which
+// command a person or agent happens to run — re-running `plan` after
+// `graph` is already open reuses the same tab's server instead of
+// spawning a second one bound to a different port.
+async function startOrReuseGraphServer() {
+  const pidfilePath = join(DEST_ROOT, GRAPH_PIDFILE_PATH);
+
+  if (await exists(pidfilePath)) {
+    try {
+      const { pid, port } = JSON.parse(await readFile(pidfilePath, 'utf8'));
+      if (isProcessAlive(pid)) return { port, reused: true };
+    } catch {
+      // Corrupt or half-written pidfile from a killed server — fall
+      // through and start a fresh one rather than failing the command.
+    }
+    await rm(pidfilePath, { force: true });
+  }
+
+  const child = spawn(
+    process.execPath,
+    [GRAPH_SERVER_MODULE, join(DEST_ROOT, DB_PATH), GRAPH_TEMPLATE_PATH, pidfilePath],
+    { detached: true, stdio: ['ignore', 'pipe', 'ignore'] },
+  );
+  child.unref();
+
+  // Waits for graph-server.mjs's own "LISTENING <port>" line rather than
+  // polling the pidfile, so the caller can't race a pidfile that exists
+  // but was written a moment before the port was actually bound.
+  //
+  // child.unref() alone only unrefs the child process handle — the
+  // stdout pipe is a separate stream the parent still holds open, and
+  // leaving a 'data' listener on it keeps the event loop alive even
+  // after this promise resolves (the earlier version of this function
+  // hung the parent CLI process for exactly that reason). Explicitly
+  // removing every listener and unref()-ing the stream once the port is
+  // known lets the parent exit as soon as its own work is done, leaving
+  // the detached child running independently.
+  const port = await new Promise((resolvePort, rejectPort) => {
+    let buf = '';
+    function cleanup() {
+      child.stdout.off('data', onData);
+      child.off('error', onError);
+      child.off('exit', onExit);
+      child.stdout.unref();
+    }
+    function onData(chunk) {
+      buf += chunk;
+      const match = buf.match(/LISTENING (\d+)/);
+      if (match) {
+        cleanup();
+        resolvePort(Number(match[1]));
+      }
+    }
+    function onError(err) {
+      cleanup();
+      rejectPort(err);
+    }
+    function onExit(code) {
+      if (code !== 0) {
+        cleanup();
+        rejectPort(new Error(`graph server exited early (code ${code})`));
+      }
+    }
+    child.stdout.on('data', onData);
+    child.once('error', onError);
+    child.once('exit', onExit);
+  });
+
+  return { port, reused: false };
+}
+
+async function graphCommand(args) {
+  if (!(await exists(DB_PATH))) {
+    console.error(`${red('No build graph found.')} Run ${bold('hedgehog db init')} first.\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const { port, reused } = await startOrReuseGraphServer();
+  const url = `http://localhost:${port}`;
+  console.log(
+    `  ${reused ? dim('reusing') : green('started')}  graph server ${dim(`(${url})`)}`,
+  );
+
+  // --no-open covers headless/SSH sessions where there's no local
+  // browser to hand a URL to — the server itself is still started (or
+  // reused) either way, since a remote person may open the URL manually
+  // via port-forwarding.
+  if (args.includes('--no-open')) {
+    console.log(`\nOpen ${bold(url)} in a browser to view it.`);
+  } else {
+    openInBrowser(url);
+  }
+}
+
 async function whyCommand(args) {
   const path = args[0];
   if (!path) {
@@ -809,6 +952,11 @@ async function main() {
     return;
   }
 
+  if (cmd === 'graph') {
+    await graphCommand(args.slice(1));
+    return;
+  }
+
   if (cmd === 'why') {
     await whyCommand(args.slice(1));
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "3.0.4",
+  "version": "3.0.5",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo.",
   "type": "module",
   "repository": {

package/src/db/graph-server.mjs

@@ -0,0 +1,91 @@
+// The `hedgehog graph` live server: a standalone, detached process (see
+// bin/cli.mjs's startOrReuseGraphServer) that serves the graph viewer
+// page and a fresh /graph.json on every request, so an open browser tab
+// polling /graph.json (src/templates/graph.html) sees task status
+// changes as `hedgehog verify` makes them, without anyone re-running a
+// CLI command or reloading the page.
+//
+// Runs as its own process rather than inline in a CLI command because
+// `hedgehog plan` and `hedgehog graph` both need to exit promptly (the
+// former is typically invoked by an agent, not a human waiting at a
+// terminal) while the graph a human opened stays live. One process
+// serves whichever project invoked it; a second invocation against the
+// same project reuses it (see startOrReuseGraphServer's pidfile check)
+// rather than starting a second server on the same database.
+
+import { createServer } from 'node:http';
+import { readFile, writeFile, rm } from 'node:fs/promises';
+import { DatabaseSync } from 'node:sqlite';
+import { buildGraph } from './graph.mjs';
+
+// Args: <db-path> <template-path> <pidfile-path>. Plain positional argv
+// rather than a flags parser — this process is only ever spawned by
+// bin/cli.mjs, never invoked directly by a person, so there's no usage
+// text or flag surface to design for.
+const [, , dbPath, templatePath, pidfilePath] = process.argv;
+
+if (!dbPath || !templatePath || !pidfilePath) {
+  console.error('graph-server.mjs requires <db-path> <template-path> <pidfile-path>');
+  process.exit(1);
+}
+
+const template = await readFile(templatePath, 'utf8');
+
+function loadGraphJson() {
+  // Opened and closed per request rather than held open: DatabaseSync is
+  // synchronous and local, so the cost is negligible, and it avoids ever
+  // serving a stale read against a handle opened before the last
+  // `hedgehog verify` committed its transaction.
+  const db = new DatabaseSync(dbPath, { readOnly: true });
+  try {
+    return buildGraph(db);
+  } finally {
+    db.close();
+  }
+}
+
+const server = createServer((req, res) => {
+  if (req.url === '/graph.json') {
+    let body;
+    try {
+      body = JSON.stringify(loadGraphJson());
+    } catch (err) {
+      res.writeHead(500, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ error: err.message }));
+      return;
+    }
+    res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+    res.end(body);
+    return;
+  }
+
+  if (req.url === '/' || req.url === '/index.html') {
+    res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+    res.end(template);
+    return;
+  }
+
+  res.writeHead(404);
+  res.end('Not found');
+});
+
+// Port 0: ask the OS for any free port, so multiple hedgehog projects on
+// one machine never collide. The chosen port is written to the pidfile
+// once bound, which is the only way a caller (or a later invocation
+// checking whether to reuse this server) learns what it is.
+server.listen(0, '127.0.0.1', async () => {
+  const { port } = server.address();
+  await writeFile(pidfilePath, JSON.stringify({ pid: process.pid, port }));
+  // Signals bin/cli.mjs's spawn-and-wait handshake that the server is
+  // ready to accept requests, not just that the process has started.
+  console.log(`LISTENING ${port}`);
+});
+
+async function shutdown() {
+  server.close();
+  await rm(pidfilePath, { force: true });
+  process.exit(0);
+}
+
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);

package/src/db/graph.mjs

@@ -0,0 +1,59 @@
+// `hedgehog graph` — read-only dependency-graph export for the build
+// graph: every task as a node, every `dependencies` row as an edge. See
+// hedgehog-persistent-build-graph.md, "Schema", for the `tasks` and
+// `dependencies` tables this mirrors.
+//
+// This module only shapes rows into { nodes, edges }; layout and
+// rendering live in graph-viewer.mjs's HTML template, not here — the
+// same separation status.mjs keeps between graphStatus() (data) and
+// formatStatus() (text rendering).
+
+const ALL_TASKS_SQL = `
+  SELECT t.*, i.goal AS intent_goal FROM tasks t
+  JOIN intents i ON i.id = t.intent_id
+  ORDER BY t.priority, t.id;
+`;
+
+const ALL_DEPENDENCIES_SQL = `
+  SELECT task_id, depends_on_task_id FROM dependencies;
+`;
+
+function loadAllTasks(db) {
+  return db.prepare(ALL_TASKS_SQL).all();
+}
+
+function loadAllDependencies(db) {
+  return db.prepare(ALL_DEPENDENCIES_SQL).all();
+}
+
+// Shapes the full build graph into { nodes, edges } for the viewer.
+// Each node carries exactly the fields the viewer displays on click
+// (objective, verify_command, commit_message) plus the fields that drive
+// layout and status colour — nothing the viewer doesn't render.
+export function buildGraph(db) {
+  const tasks = loadAllTasks(db);
+  const dependencies = loadAllDependencies(db);
+
+  const nodes = tasks.map((t) => ({
+    id: t.id,
+    module: t.module,
+    layer: t.layer,
+    status: t.status,
+    objective: t.objective,
+    verifyCommand: t.verify_command,
+    commitMessage: t.commit_message,
+    intentGoal: t.intent_goal,
+  }));
+
+  // Edge direction follows the dependency, not the SQL column order:
+  // `depends_on_task_id` must finish before `task_id` can start, so the
+  // arrow is drawn from the prerequisite to the dependent — the same
+  // direction hedgehog next's BLOCKED DOWNSTREAM walk assumes.
+  const edges = dependencies.map((d) => ({
+    id: `${d.depends_on_task_id}->${d.task_id}`,
+    source: d.depends_on_task_id,
+    target: d.task_id,
+  }));
+
+  return { nodes, edges };
+}

package/src/golden-cores/full-stack-app/gitignore.template

@@ -6,6 +6,7 @@ out-tsc
 .env.local
 *.log
 .DS_Store
+.hedgehog/graph-server.json
 
 .nx/cache
 .nx/workspace-data

package/src/golden-cores/landing-page/gitignore.template

@@ -7,3 +7,4 @@ dist
 *.log
 .DS_Store
 .idea
+.hedgehog/graph-server.json

package/src/templates/graph.html

@@ -0,0 +1,316 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<title>Hedgehog build graph</title>
+<script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
+<script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
+<script crossorigin src="https://unpkg.com/reactflow@11/dist/umd/index.js"></script>
+<script crossorigin src="https://unpkg.com/dagre@0.8.5/dist/dagre.min.js"></script>
+<link rel="stylesheet" href="https://unpkg.com/reactflow@11/dist/style.css" />
+<style>
+  html, body, #root { height: 100%; margin: 0; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    background: #0d1117;
+    color: #e6edf3;
+  }
+  .rf-task-node {
+    padding: 12px 14px 10px;
+    border-radius: 8px;
+    border: 1px solid var(--node-border);
+    border-top: 5px solid var(--node-border);
+    background: var(--node-bg);
+    font-size: 13px;
+    min-width: 160px;
+    cursor: pointer;
+    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.4);
+    transition: box-shadow 0.1s ease-out, transform 0.1s ease-out;
+  }
+  .rf-task-node:hover {
+    box-shadow: 0 0 0 1px var(--node-border), 0 4px 10px rgba(0, 0, 0, 0.5);
+    transform: translateY(-1px);
+  }
+  .rf-task-node .id { font-weight: 700; color: #f0f6fc; }
+  .rf-task-node .status {
+    display: inline-block;
+    margin-top: 4px;
+    padding: 1px 7px;
+    border-radius: 999px;
+    font-size: 10px;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    color: var(--node-status-fg);
+    background: var(--node-status-bg);
+  }
+  #detail-panel {
+    position: fixed;
+    top: 0;
+    right: 0;
+    width: 360px;
+    height: 100%;
+    background: #161b22;
+    border-left: 1px solid #30363d;
+    padding: 20px;
+    box-sizing: border-box;
+    overflow-y: auto;
+    transform: translateX(100%);
+    transition: transform 0.15s ease-out;
+  }
+  #detail-panel.open { transform: translateX(0); }
+  #detail-panel h2 { margin-top: 0; font-size: 16px; }
+  #detail-panel .field-label {
+    font-size: 11px;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    color: #8b949e;
+    margin-top: 16px;
+  }
+  #detail-panel pre {
+    white-space: pre-wrap;
+    word-break: break-word;
+    background: #0d1117;
+    padding: 8px;
+    border-radius: 6px;
+    font-size: 12px;
+  }
+  #legend {
+    position: fixed;
+    bottom: 16px;
+    left: 16px;
+    background: #161b22;
+    border: 1px solid #30363d;
+    border-radius: 8px;
+    padding: 10px 14px;
+    font-size: 12px;
+  }
+  #legend .row { display: flex; align-items: center; gap: 8px; margin: 3px 0; }
+  #legend .swatch { width: 4px; height: 14px; border-radius: 2px; }
+  #loading {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    height: 100%;
+    color: #8b949e;
+    font-size: 14px;
+  }
+</style>
+</head>
+<body>
+<div id="root"></div>
+<script>
+(function () {
+  const { useState, useEffect, useMemo, useRef, createElement: h } = React;
+  const {
+    default: ReactFlowCanvas,
+    Background,
+    Controls,
+    MarkerType,
+    Handle,
+    Position,
+  } = window.ReactFlow;
+
+  // Mirrors status.mjs's TASK_STATUSES lifecycle order and colour intent:
+  // grey (not started) -> blue (in progress) -> amber (needs attention) ->
+  // green (done) -> red (blocked). Each status gets a distinct hue rather
+  // than reusing green for both `ready` and `verified` (the two are
+  // different points in the lifecycle and looked identical before).
+  const STATUS_STYLE = {
+    proposed:    { bg: '#282e37', border: '#6e7681', badgeBg: '#6e768133', badgeFg: '#c9d1d9' },
+    planned:     { bg: '#122a4d', border: '#58a6ff', badgeBg: '#58a6ff33', badgeFg: '#79c0ff' },
+    ready:       { bg: '#1c3a29', border: '#3fb950', badgeBg: '#3fb95033', badgeFg: '#56d364' },
+    implemented: { bg: '#3d2f0a', border: '#d29922', badgeBg: '#d2992233', badgeFg: '#e3b341' },
+    verified:    { bg: '#123a3c', border: '#39c5cf', badgeBg: '#39c5cf33', badgeFg: '#56d4dd' },
+    complete:    { bg: '#0f2818', border: '#238636', badgeBg: '#23863633', badgeFg: '#3fb950' },
+    failed:      { bg: '#3d1418', border: '#f85149', badgeBg: '#f8514933', badgeFg: '#ff7b72' },
+  };
+
+  function layout(nodes, edges) {
+    const g = new dagre.graphlib.Graph();
+    g.setGraph({ rankdir: 'TB', nodesep: 60, ranksep: 70 });
+    g.setDefaultEdgeLabel(() => ({}));
+    const width = 180;
+    const height = 56;
+    for (const n of nodes) g.setNode(n.id, { width, height });
+    for (const e of edges) g.setEdge(e.source, e.target);
+    dagre.layout(g);
+    return nodes.map((n) => {
+      const pos = g.node(n.id);
+      return { ...n, position: { x: pos.x - width / 2, y: pos.y - height / 2 } };
+    });
+  }
+
+  function TaskNode({ data }) {
+    const style = STATUS_STYLE[data.task.status] || STATUS_STYLE.proposed;
+    return h(
+      'div',
+      {
+        className: 'rf-task-node',
+        style: {
+          '--node-bg': style.bg,
+          '--node-border': style.border,
+          '--node-status-bg': style.badgeBg,
+          '--node-status-fg': style.badgeFg,
+        },
+        // Selecting a node opens the detail panel; React Flow's own pane
+        // click (see App's onPaneClick) closes it again on lose-of-focus,
+        // so this only ever needs to open.
+        onClick: (e) => {
+          e.stopPropagation();
+          data.onSelect(data.task.id);
+        },
+      },
+      h(Handle, { type: 'target', position: Position.Top }),
+      h('div', { className: 'id' }, data.task.id),
+      h('div', null, data.task.layer),
+      h('div', { className: 'status' }, data.task.status),
+      h(Handle, { type: 'source', position: Position.Bottom }),
+    );
+  }
+
+  const nodeTypes = { task: TaskNode };
+
+  function DetailPanel({ task }) {
+    if (!task) return h('div', { id: 'detail-panel' });
+    return h(
+      'div',
+      { id: 'detail-panel', className: 'open' },
+      h('h2', null, task.id),
+      h('div', { className: 'field-label' }, 'Intent'),
+      h('div', null, task.intentGoal),
+      h('div', { className: 'field-label' }, 'Objective'),
+      h('div', null, task.objective),
+      h('div', { className: 'field-label' }, 'Verify command'),
+      h('pre', null, task.verifyCommand),
+      h('div', { className: 'field-label' }, 'Commit message'),
+      h('pre', null, task.commitMessage),
+    );
+  }
+
+  function Legend() {
+    return h(
+      'div',
+      { id: 'legend' },
+      Object.entries(STATUS_STYLE).map(([status, style]) =>
+        h(
+          'div',
+          { className: 'row', key: status },
+          h('span', {
+            className: 'swatch',
+            style: { background: style.border, boxShadow: `0 0 6px ${style.border}` },
+          }),
+          h('span', null, status),
+        ),
+      ),
+    );
+  }
+
+  const POLL_INTERVAL_MS = 2000;
+
+  function App() {
+    const [raw, setRaw] = useState(null);
+    // Holds the selected task's id, not the task object itself, so the
+    // open detail panel always reflects the latest poll (e.g. a status
+    // flip from `ready` to `complete` while the panel is open) instead
+    // of freezing on whatever the task looked like at click time.
+    const [selectedId, setSelectedId] = useState(null);
+    // Tracks the last-rendered graph's JSON so a poll that returns
+    // identical data (the common case — nothing changed since last
+    // tick) skips relayout entirely instead of jittering node positions
+    // or resetting the user's pan/zoom on every 2s tick.
+    const lastJsonRef = useRef(null);
+    const firstLoadRef = useRef(true);
+
+    useEffect(() => {
+      let cancelled = false;
+      async function poll() {
+        try {
+          const res = await fetch('/graph.json', { cache: 'no-store' });
+          const data = await res.json();
+          if (cancelled) return;
+          const json = JSON.stringify(data);
+          if (json !== lastJsonRef.current) {
+            lastJsonRef.current = json;
+            setRaw(data);
+          }
+        } catch {
+          // Server briefly unreachable (e.g. mid-restart) — next tick retries.
+        }
+      }
+      poll();
+      const id = setInterval(poll, POLL_INTERVAL_MS);
+      return () => {
+        cancelled = true;
+        clearInterval(id);
+      };
+    }, []);
+
+    const nodes = useMemo(() => {
+      if (!raw) return [];
+      const positioned = layout(raw.nodes, raw.edges);
+      return positioned.map((n) => ({
+        id: n.id,
+        type: 'task',
+        position: n.position,
+        data: { task: n, onSelect: setSelectedId },
+      }));
+    }, [raw]);
+
+    const edges = useMemo(() => {
+      if (!raw) return [];
+      return raw.edges.map((e) => ({
+        ...e,
+        markerEnd: { type: MarkerType.ArrowClosed },
+        style: { stroke: '#484f58' },
+      }));
+    }, [raw]);
+
+    // fitView only on the graph's first paint — a later poll that adds
+    // or moves nodes re-lays-out in place without recentering the view
+    // the user has already panned or zoomed.
+    const shouldFitView = firstLoadRef.current && nodes.length > 0;
+    if (shouldFitView) firstLoadRef.current = false;
+
+    if (!raw) {
+      return h('div', { id: 'loading' }, 'Loading build graph…');
+    }
+
+    // Derived fresh from the latest poll every render, rather than the
+    // task object captured at click time, so the open panel tracks a
+    // status change (e.g. ready -> complete) live instead of freezing.
+    // A task removed since selection (id no longer present) closes the
+    // panel implicitly, since selectedTask is then undefined/falsy.
+    const selectedTask = selectedId
+      ? raw.nodes.find((n) => n.id === selectedId)
+      : null;
+
+    return h(
+      React.Fragment,
+      null,
+      h(
+        ReactFlowCanvas,
+        {
+          nodes,
+          edges,
+          nodeTypes,
+          fitView: shouldFitView,
+          // Clicking empty canvas is the graph losing focus, same as
+          // clicking away from any open panel — close the detail panel.
+          // Node clicks stop propagation (see TaskNode) so this never
+          // fires for a click that's opening a different task instead.
+          onPaneClick: () => setSelectedId(null),
+        },
+        h(Background, { color: '#21262d' }),
+        h(Controls, null),
+      ),
+      h(Legend),
+      h(DetailPanel, { task: selectedTask }),
+    );
+  }
+
+  ReactDOM.createRoot(document.getElementById('root')).render(h(App));
+})();
+</script>
+</body>
+</html>