wavework 0.0.0-stage → 0.1.1

package/src/targets.mjs

@@ -0,0 +1,100 @@
+/**
+ * Which template becomes which file in a target repository. Pure: no file system access.
+ *
+ * Contract (consumed by the init/update CLI):
+ *
+ *   templateTargets(config) -> [{ template, target, vars, mode }]
+ *     template  path below `templates/` (always `/`-separated), e.g. `skills/next-task/SKILL.md`
+ *     target    path relative to the repository root, e.g. `.claude/skills/next-task/SKILL.md`
+ *     vars      extra template variables, merged OVER buildContext(config, options); `{}` for most templates
+ *     mode      file mode: 0o644 for text, 0o755 for scripts
+ *     verbatim  optional, `true`: copy the template byte for byte instead of rendering it (JavaScript/CSS
+ *               that may contain braces). Only the dashboard runtime uses it.
+ *
+ *   One entry per file to write, for ALL templates (skills, agents, scripts). The agent template
+ *   `agents/implementer.md` appears once per implementer model (the keys of `models.implementers.rules`
+ *   plus `models.implementers.default`), each with `vars.agent = { model, name, description, rule, isDefault, defaultName }` (`description` is a quoted YAML scalar).
+ *   With `dashboard.enabled` there is one more entry per file of `templates/dashboard/` (DASHBOARD_FILES, verbatim,
+ *   target `.claude/wavework/dashboard/<path>`) plus `.claude/wavework/dashboard/config.json` rendered from
+ *   `templates/dashboard-config.json` (port, tokensFile). Disabled: none of them, so `update` removes them.
+ *   Targets are unique. A model name that is not safe as a file name throws.
+ *
+ *   renderTargets(config, options) -> [{ target, content, mode }]
+ *     Renders every entry with buildContext(config, options) (same `options` as buildContext) plus `vars`.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { buildContext, implementerAgents } from './context.mjs';
+import { render } from './render.mjs';
+
+export const SKILLS = [
+  'next-task', 'next-task-batch', 'next-task-beads', 'next-task-branch', 'next-task-code',
+  'next-task-deps', 'next-task-e2e', 'next-task-findings', 'next-task-finish', 'next-task-implement',
+  'next-task-plan', 'next-task-review', 'next-task-test', 'next-task-write-tests',
+  'text-to-task', 'watch-ci',
+];
+
+/** Where the dashboard runtime lives in a repository. Skills and hooks call it by this path (tests keep them in sync). */
+export const DASHBOARD_DIR = '.claude/wavework/dashboard';
+/** Files of templates/dashboard/ (test/targets.test.mjs checks the list against the directory). */
+export const DASHBOARD_FILES = [
+  'README.md', 'pricing.json', 'record.mjs', 'server.mjs',
+  'hooks/session-start.mjs', 'hooks/subagent-stop.mjs',
+  'lib/ci.mjs', 'lib/derive.mjs', 'lib/settings.mjs', 'lib/tokens.mjs',
+  'public/app.css', 'public/app.js', 'public/default-theme.css', 'public/format.mjs', 'public/index.html',
+];
+
+const SCRIPTS = ['red-green-check.sh', 'red-green-check.test.sh'];
+const AGENT_TEMPLATE = 'agents/implementer.md';
+const SAFE_MODEL = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/** A JSON string is a valid YAML double-quoted scalar, so rule texts with ": ", quotes or "#" cannot break the frontmatter. */
+function agentDescription(rule) {
+  return JSON.stringify(rule
+    ? `Implements a planned beads task. Scope: ${rule} Pass the bead ID.`
+    : 'Implements a planned beads task. Default implementer for work that no other model rule covers. Pass the bead ID.');
+}
+
+export function templateTargets(config) {
+  const entries = SKILLS.map((name) => ({
+    template: `skills/${name}/SKILL.md`,
+    target: `.claude/skills/${name}/SKILL.md`,
+    vars: {},
+    mode: 0o644,
+  }));
+  const agents = implementerAgents(config);
+  const defaultName = `implementer-${config.models.implementers.default}`;
+  for (const { model, rule, isDefault } of agents) {
+    if (!SAFE_MODEL.test(model)) throw new Error(`implementer model "${model}" cannot be used as an agent file name (allowed: letters, digits, ".", "_", "-")`);
+    entries.push({
+      template: AGENT_TEMPLATE,
+      target: `.claude/agents/implementer-${model}.md`,
+      vars: { agent: { model, name: `implementer-${model}`, description: agentDescription(rule), rule: rule ?? '', isDefault, defaultName } },
+      mode: 0o644,
+    });
+  }
+  for (const name of SCRIPTS) {
+    entries.push({ template: `scripts/${name}`, target: `.claude/scripts/${name}`, vars: {}, mode: 0o755 });
+  }
+  if (config.dashboard?.enabled) {
+    for (const name of DASHBOARD_FILES) {
+      entries.push({ template: `dashboard/${name}`, target: `${DASHBOARD_DIR}/${name}`, vars: {}, mode: 0o644, verbatim: true });
+    }
+    const settings = { port: config.dashboard.port, tokensFile: config.dashboard.tokensFile ?? null };
+    entries.push({
+      template: 'dashboard-config.json',
+      target: `${DASHBOARD_DIR}/config.json`,
+      vars: { dashboardConfigJson: JSON.stringify(settings, null, 2) },
+      mode: 0o644,
+    });
+  }
+  return entries;
+}
+
+export function renderTargets(config, options = {}) {
+  const context = buildContext(config, options);
+  return templateTargets(config).map(({ template, target, vars, mode, verbatim }) => {
+    const text = readFileSync(fileURLToPath(new URL(`../templates/${template}`, import.meta.url)), 'utf8');
+    return { target, content: verbatim === true ? text : render(text, { ...context, ...vars }, template), mode };
+  });
+}

package/templates/agents/implementer.md

@@ -0,0 +1,16 @@
+---
+name: {{agent.name}}
+description: {{agent.description}}
+model: {{agent.model}}
+---
+
+You implement exactly one planned beads task in this codebase. You do not plan or redesign.
+
+Follow `.claude/skills/next-task-implement/SKILL.md` step by step: check you are in the worktree and on the branch your prompt names (never switch branches), claim the bead, {{#if codeMap}}grep `{{codeMap.path}}` to find files (only when needed), {{/if}}write tests first, implement, e2e where a setup exists, run focused tests via `.claude/skills/next-task-test/SKILL.md`, {{#if codeMap}}update your `{{codeMap.path}}` lines, {{/if}}report out-of-scope findings.
+
+Do not commit, push or close the bead: whoever delegated the task verifies your work, commits and closes it. Report back as the skill describes.
+{{#if agent.isDefault}}
+{{else}}
+
+If the task turns out larger or riskier than described, or outside the scope in your description, stop and report back so it can go to {{agent.defaultName}}.
+{{/if}}

package/templates/dashboard/README.md

@@ -0,0 +1,96 @@
+# Pipeline dashboard
+
+Installed by `wavework init` / `wavework update` into `.claude/wavework/dashboard/` (managed by the lock file: do not edit, change `dashboard` in `.claude/wavework.json` instead). Dev tooling (Node >= 22, built-ins only, no node_modules) that records and shows `/next-task*` runs. This folder holds the recorder (`record.mjs`), the SubagentStop and SessionStart hooks (`hooks/`), the server (`server.mjs`, `lib/`), the UI (`public/`) and `config.json` (port and tokensFile, written from the config).
+
+## Store
+
+`$(git rev-parse --git-common-dir)/pipeline-runs/<run-id>/`, shared by every worktree of the repo (never committed, lives inside `.git`). Override with `WAVEWORK_PIPELINE_STORE=<dir>` (used by tests).
+
+- `run.json`: summary, replaced atomically (write temp file, rename).
+- `events.jsonl`: append-only, one JSON object per line, written with `O_APPEND` so parallel sub-agents do not interleave lines.
+
+`run.json` fields: `id`, `kind` (`next-task|beads|batch`), `units` (epic/bead ids), `parent` (run id of the batch, for batch members), `branch`, `worktree`, `status` (`running|done|blocked|failed`), `started`, `ended` (ISO timestamps, `ended` is null while running).
+
+## CLI
+
+```
+node .claude/wavework/dashboard/record.mjs <event> [--run <id>] [--key value ...]
+```
+
+Without `--run` the run is found by cwd: the running run whose `worktree` contains the current directory (deepest worktree wins). `--units a,b` is a list, known numeric keys are stored as numbers, `--some-key` becomes `someKey`. Run ids match `[A-Za-z0-9][A-Za-z0-9._-]*` and are at most 128 characters. `readRun` applies the same check and returns null for anything else, so URL params can be passed in safely.
+
+Recording never blocks the pipeline: any error prints one `pipeline-record: ...` line to stderr and the exit code is 0.
+
+## Events
+
+Every event has `ts` (ISO), `type` and `run`, plus:
+
+| type | fields |
+| --- | --- |
+| `run-start` | `kind`, `units`, `parent`, `branch`, `worktree` (creates `run.json`) |
+| `run-end` | `status` (`done` default, `blocked`, `failed`; updates `run.json`) |
+| `step-start`, `step-end` | `step` (`deps`, `plan`, `wave`, `review`, `finish`, `push`), `wave` (on `wave` steps; start and end are paired by step + wave), `sha` (on `step-end --step push`) |
+| `child-start`, `child-end` | `bead`, `model`, `wave`, `result`, `redBeforeGreen` (evidence) |
+| `review` | `verdict`, `mustFix` (count), `round` |
+| `tests` | `scope`, `passed`, `failed`, `duration` |
+| `finding` | `bead` (id of the finding bead) |
+| `agent` | `agentId`, `agentType`, `bead` (from the first user prompt, after the word "bead"; absent if none), `model`, `durationMs`, `tokensIn`, `tokensOut`, `tokensCacheRead`, `tokensCacheWrite`, `cost` (estimate); written by the SubagentStop hook |
+
+Other keys passed on the command line are stored as given, except `ts`, `type` and `run`, which are always set by the recorder.
+
+`run-start` for an existing id rewrites `run.json` from scratch (status back to `running`); events stay appended. `run-end` without a prior `run-start` creates a minimal `run.json` (`started` null).
+
+## Agent events and pricing
+
+The `agent` events come from the SubagentStop hook (`hooks/subagent-stop.mjs`, registered in `.claude/settings.json` by wavework). Claude Code passes `cwd`, `agent_id`, `agent_type` and `agent_transcript_path` on stdin. The hook reads the sub-agent transcript: usage is taken from assistant messages (`message.usage`, `message.model`), deduplicated by message id (streamed content blocks repeat the id; the max per field wins), duration is last minus first timestamp. The run is found by cwd (falling back to the cwd recorded in the transcript); no running run means nothing is written. The hook always exits 0 and prints nothing to stdout.
+
+`pricing.json` holds USD per million tokens (`input`, `output`, `cacheRead`, `cacheWrite`) per model id. The cost is the sum over messages, each priced with its own model. If any message's model is missing from the table, the event has no `cost` field (never 0). Prices are estimates: cache write is the 5-minute rate (1.25x input), and Haiku uses the rate card for prompts up to 100K tokens.
+
+## Importing
+
+`record.mjs` exports `resolveStoreDir`, `findRunByCwd`, `recordEvent`, `readRun`, `listRuns`, `parseArgs`, `main`, `EVENT_TYPES`, `RUN_ID`, so the server and hooks reuse store resolution and lookup.
+
+## SessionStart hook
+
+`hooks/session-start.mjs` is registered in `.claude/settings.json` by wavework. At session start it checks `GET /api/health` on the dashboard port (`PIPELINE_DASHBOARD_PORT`, else `config.json`, else 4690) (300 ms timeout):
+
+- Health answers `{"ok":true, "root":"<dir>"}` and `root` exists: prints nothing.
+- Health answers but its `root` (the checkout `server.mjs` runs from) no longer exists, e.g. a deleted worktree: stops that server via `<store>/server.pid` and starts a fresh one. The pid file is `{"pid","port","root"}`. The hook kills the recorded pid only when port and root match the answering server and `lsof` lists that pid as the single listener on the port while `ps` shows that record's own `<root>/server.mjs` (so another repo's dashboard is never touched) (a recorded pid alone is not proof, pids get reused). If the record does not match or either check cannot run, it prints one warning and kills nothing.
+- Nothing listens: starts `server.mjs` detached (`stdio` to `<store>/server.log`, pid file `<store>/server.pid`) and prints `{"systemMessage":"Pipeline dashboard: http://127.0.0.1:<port>"}` once it answers. The server runs from the main checkout's `.claude/wavework/dashboard/server.mjs` (main checkout = parent of `git rev-parse --path-format=absolute --git-common-dir`) when that exists, else from the copy the hook belongs to. So the long-lived server does not depend on a worktree that `/next-task-finish` later deletes.
+- Another process holds the port: prints one `systemMessage` warning and starts nothing.
+- Nothing answers within the start wait (2 s) after the spawn: prints `{"systemMessage":"Pipeline dashboard: could not start, see <store>/server.log"}`. The spawned pid is recorded at spawn, so a server that is still starting stays stoppable.
+
+`PIPELINE_DASHBOARD_START_WAIT_MS` overrides the start wait. It is a test-only knob (tests set it near zero to force the "gave up waiting" path); do not set it in normal use.
+
+A pid record is not overwritten while it names a live server on the same port, and a spawned child clears the record only if it exits without ever answering health.
+
+Two sessions starting together start one server: an exclusive `<store>/server.starting` lock lets only one hook spawn; the other waits for the server. A lock older than 5 s (crashed hook) is taken over by renaming it to a unique name first (rename is atomic, so only one hook moves a given lock); a fresh lock moved by mistake is linked back.
+
+Timing: the hook always exits 0 and has a worst case of about 1.5 s on the stale-server replace path (probe 300 ms, `lsof`/`ps` checks with a 500 ms timeout each, stop wait 250 ms, start wait 600 ms, probes of 150 ms, plus node start-up). Output format: `systemMessage` on stdout JSON, per the Claude Code hooks docs. The 5 s `timeout` in `.claude/settings.json` is only a hard kill.
+
+## Server/API
+
+`wavework dashboard` (or `node .claude/wavework/dashboard/server.mjs`) binds `127.0.0.1` only, port `PIPELINE_DASHBOARD_PORT`, else `config.json` (`dashboard.port`), else 4690, reads the store via `resolveStoreDir`. `createServer({storeDir, port, publicDir, tokensPath, project, ghRunner, ciRefreshMs, watch, pollMs})` is the factory used by tests (`port: 0`, stubbed `ghRunner`; `await server.listen()`, `server.port`, `await server.close()`).
+
+- `GET /api/health`: `{ok:true, root}`; `root` is the directory `server.mjs` runs from (the SessionStart hook uses it to spot a server whose checkout is gone).
+- `GET /api/runs`: run summaries (`run.json` fields + `totals`), newest `started` first; batch members (runs whose `parent` is another run) are nested in the batch's `children`.
+- `GET /api/runs/:id`: `{run, events, timeline, ci}`. `timeline` = `steps` (paired step-start/end with `durationMs`, `sha` on push), `children` (per bead: model, wave, result, `redBeforeGreen`, `durationMs`, `agents` summed from `agent` events by `bead`, else by the child's time window), `reviews`, `tests`, `totals` (tokens, `cost`, `agents`, `durationMs`; `cost` is null when there are no agents or any agent has no cost, never 0 or a partial sum), `sha`. Invalid id (not the run-id pattern, `../`, encoded `%2e%2e%2f`, `%2F`, NUL) is 400, unknown id 404.
+- A batch that is still `running` but whose members have all ended is reported as ended (`blocked` if any member is blocked/failed, else `done`, `ended` = latest member end) in both endpoints.
+- Requests need a `Host` of `127.0.0.1:<port>` or `localhost:<port>`, else 403 (DNS-rebinding guard).
+- `GET /api/events`: Server-Sent Events, `event: run-changed` with `data: {"id": "<run id>"}` when a store file changes (`fs.watch` recursive as trigger, polling fallback, also if the store does not exist yet).
+- `GET /api/info`: `{project}`, the repo directory name (the main checkout), shown in the UI.
+- `/tokens.css` is the project's own tokens file (`dashboard.tokensFile`, resolved inside the repo, symlinks leaving it refused) or an empty stylesheet when none is configured; everything else is served from `public/` only (resolved, symlinks and traversal refused).
+
+**CI status:** the pushed SHA is the `sha` field of the last `step-end` event with `step=push` (the skill emits `record.mjs step-end --step push --sha <sha>`). For such runs, `ci` is `{sha, state, runs[]}` from `gh run list --commit <sha> --json status,conclusion,url,name` (execFile with an argument list, SHA must be 7-40 hex chars). `state` is `success|failure|pending|none|unknown`; missing/failing `gh` gives `unknown`. Results are cached per SHA; only `success` is cached for good, everything else (pending, failure because CI may be re-run, none, unknown) is refreshed after `ciRefreshMs` (15 s). `ci` is null without a pushed SHA.
+
+## UI
+
+Open `http://127.0.0.1:4690/` (your port) after starting the server. Plain HTML/CSS/JS in `public/` (no build): `index.html`, `default-theme.css` (neutral tokens, light and dark), `app.css` (design tokens only, `prefers-reduced-motion`; the project's `/tokens.css` loads after the default theme and may override any token), `app.js` (hash routing, SSE) and `format.mjs` (pure helpers).
+
+- `#/` lists all runs: running first, then newest; batch members are nested under their batch. It refreshes on every `run-changed` SSE event, no reload. The header shows `Live` or `Reconnecting`.
+- `#/runs/<id>` is a deep link to a run: header stats, step timeline, children (model, wave, duration, tokens, cost, result, review verdict and rounds, red-before-green), reviews, tests, findings filed and CI links.
+- Costs are estimates (marked as such); an unknown cost is shown as `—`, never `$0.00`.
+- The list view fetches `/api/runs/:id` per run to get the CI state (the list endpoint has no `ci`).
+- Untrusted strings are rendered with `textContent`; CI links must be http(s).
+
+Tests live in the wavework package (`test/dashboard/`), not in the target repository.

package/templates/dashboard/hooks/session-start.mjs

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+// SessionStart hook: makes sure the pipeline dashboard server runs and tells the user its URL.
+// Health answers from a live checkout -> silent. Port free -> start server.mjs detached (log in <store>/server.log)
+// and print the URL. Port held by something else, or by a server whose checkout was deleted and is not the
+// recorded one -> one warning. Always exits 0.
+// Time budget (hard kill is the 5 s `timeout` in settings.json), worst case = stale-server replace path:
+//   probe 300 ms + lsof 800 + ps 800 + stop wait 250 + start wait 2000 + probes 150 + node start-up ~100  =  about 4.4 s.
+// Keep the sum under 5 s when changing any of these.
+// Output format: https://code.claude.com/docs/en/hooks.md (systemMessage on stdout JSON; exit 0).
+import { execFile, execFileSync, spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { closeSync, existsSync, linkSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveStoreDir } from '../record.mjs';
+import { resolvePort } from '../lib/settings.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const OWN_SERVER = path.join(HERE, '..', 'server.mjs');
+// Where the dashboard lives in a checkout (wavework init puts it there).
+const DASHBOARD_REL = ['.claude', 'wavework', 'dashboard'];
+const PROBE_MS = 300;        // first health probe
+const LOOP_PROBE_MS = 150;   // probes while waiting for a started server
+// How long a started server gets to answer. The env override is for tests (a near-zero wait forces "gave up waiting").
+const WAIT_MS = Number(process.env.PIPELINE_DASHBOARD_START_WAIT_MS) > 0 ? Number(process.env.PIPELINE_DASHBOARD_START_WAIT_MS) : 2000;
+const EXEC_MS = 800;         // lsof / ps each (a loaded machine can be slow; see the budget above)
+const STOP_WAIT_MS = 250;    // how long a stopped stale server gets to release the port
+const STALE_LOCK_MS = 5000;  // a start lock this old belongs to a crashed hook
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function emit(systemMessage) {
+  process.stdout.write(JSON.stringify({ systemMessage }) + '\n');
+}
+
+const inUse = (port) => `Pipeline dashboard: port ${port} is in use by another process (set dashboard.port in .claude/wavework.json and run wavework update to change it)`;
+const staleInUse = (port) => `Pipeline dashboard: port ${port} is in use by a server from a missing checkout that is not the recorded one; stop it to start the dashboard`;
+const couldNotStart = (logFile) => `Pipeline dashboard: could not start, see ${logFile}`;
+
+/**
+ * Health probe. state: 'ok' (our health answers {"ok":true}), 'free' (connection refused),
+ * 'foreign' (something else answers, or accepts the connection but does not answer in time).
+ * root: the checkout directory the server reports, when it reports one.
+ */
+function probe(port, timeout) {
+  return new Promise((resolve) => {
+    const req = http.get({ host: '127.0.0.1', port, path: '/api/health', timeout, agent: false }, (res) => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (d) => { body += d; });
+      res.on('end', () => {
+        try {
+          const json = JSON.parse(body);
+          if (res.statusCode === 200 && json.ok === true) {
+            resolve({ state: 'ok', root: typeof json.root === 'string' ? json.root : null });
+            return;
+          }
+        } catch { /* not our health answer */ }
+        resolve({ state: 'foreign', root: null });
+      });
+      res.on('error', () => resolve({ state: 'foreign', root: null }));
+    });
+    req.on('timeout', () => { req.destroy(); resolve({ state: 'foreign', root: null }); });
+    req.on('error', (e) => resolve({ state: e.code === 'ECONNREFUSED' ? 'free' : 'foreign', root: null }));
+  });
+}
+
+const isMissingCheckout = (root) => typeof root === 'string' && !existsSync(root);
+
+
+/** Runs a fixed program with an argument list (no shell). Resolves to stdout, or null when it cannot run or fails. */
+function run(file, args) {
+  return new Promise((resolve) => {
+    execFile(file, args, { encoding: 'utf8', timeout: EXEC_MS }, (err, stdout) => resolve(err ? null : stdout));
+  });
+}
+
+/**
+ * True only when `pid` is the single listener on `port` and its command line is the dashboard server. A pid that is
+ * merely recorded (pids get reused) is not enough. Anything that cannot be checked (no lsof or ps, no listener) counts
+ * as not proven, so nothing is killed.
+ */
+/** True when `command` names `serverFile` as a whole argument (not merely as the tail of a longer path). */
+export function commandNamesServer(command, serverFile) {
+  const escaped = serverFile.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`(^|\\s)${escaped}(\\s|$)`).test(command.trim());
+}
+
+async function isDashboardListener(pid, port, serverFile) {
+  const listing = await run('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t']);
+  if (listing === null) return false;
+  const pids = listing.split('\n').filter(Boolean).map(Number);
+  if (pids.length !== 1 || pids[0] !== pid) return false;
+  const command = await run('ps', ['-p', String(pid), '-o', 'command=']);
+  return command !== null && commandNamesServer(command, serverFile);
+}
+
+/** The main checkout's directory (the common git dir's parent), or null outside git. */
+function mainCheckout() {
+  try {
+    const common = execFileSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
+      cwd: process.cwd(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return path.dirname(common);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Which server.mjs to run: the main checkout's when it has one, so the long-lived server does not depend on a
+ * worktree that a later /next-task-finish deletes; otherwise the copy this hook belongs to.
+ */
+function serverLocation() {
+  const main = mainCheckout();
+  const mainServer = main ? path.join(main, ...DASHBOARD_REL, 'server.mjs') : null;
+  if (mainServer && existsSync(mainServer)) return { server: mainServer, cwd: main, root: path.dirname(mainServer) };
+  return { server: OWN_SERVER, cwd: process.cwd(), root: path.dirname(OWN_SERVER) };
+}
+
+/** Exclusive create of the start lock. A lock older than STALE_LOCK_MS (crashed hook) is taken over. */
+function acquireLock(lockFile) {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      return openSync(lockFile, 'wx');
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      if (!takeOverStaleLock(lockFile)) return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Removes a stale lock without racing other hooks: rename is atomic, so the lock file is moved to a unique name
+ * and only the hook that moved it inspects it. A fresh lock that was moved by mistake is linked back (link does
+ * not overwrite, so a lock someone else created meanwhile is never replaced). Returns true if a stale lock was removed.
+ */
+function takeOverStaleLock(lockFile) {
+  const parked = `${lockFile}.${process.pid}.${randomUUID()}`;
+  try {
+    renameSync(lockFile, parked);
+  } catch {
+    return false; // gone, or moved by another hook
+  }
+  let stale = false;
+  try {
+    stale = Date.now() - statSync(parked).mtimeMs >= STALE_LOCK_MS;
+  } catch { /* unreadable: treat as not ours */ }
+  if (!stale) {
+    try { linkSync(parked, lockFile); } catch { /* someone else created a lock meanwhile */ }
+  }
+  rmSync(parked, { force: true });
+  return stale;
+}
+
+const readRecord = (pidFile) => {
+  try {
+    return JSON.parse(readFileSync(pidFile, 'utf8'));
+  } catch {
+    return null;
+  }
+};
+
+const isAlive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === 'EPERM';
+  }
+};
+
+/**
+ * Records the pid of a freshly spawned server, unless <store>/server.pid already names a live server on the same
+ * port (then that server stays recorded). Returns true when the record was written.
+ */
+export async function recordSpawnedPid(pidFile, record) {
+  const current = readRecord(pidFile);
+  if (current && current.port === record.port && Number.isInteger(current.pid) && isAlive(current.pid)
+      && (await probe(record.port, LOOP_PROBE_MS)).state === 'ok') {
+    return false;
+  }
+  writeFileSync(pidFile, JSON.stringify(record));
+  return true;
+}
+
+/**
+ * Spawns the detached server and records its pid at once, before any health wait: a server that is still starting
+ * when the hook stops waiting must stay stoppable (the next session or a test cleanup reads this record).
+ */
+async function startServer({ server, cwd, root }, { logFile, pidFile, port }) {
+  const logFd = openSync(logFile, 'a');
+  let child;
+  try {
+    child = spawn(process.execPath, [server], { cwd, env: { ...process.env, PIPELINE_DASHBOARD_PORT: String(port) }, detached: true, stdio: ['ignore', logFd, logFd] });
+  } finally {
+    closeSync(logFd);
+  }
+  const spawned = { child, exited: false, answered: false };
+  if (child.pid) await recordSpawnedPid(pidFile, { pid: child.pid, port, root });
+  // A child that exits clears only its own record, and only if it never answered health: a process that served
+  // is a real server, and its record is not this hook's to drop.
+  const forget = () => {
+    spawned.exited = true;
+    if (spawned.answered) return;
+    if (readRecord(pidFile)?.pid === child.pid) rmSync(pidFile, { force: true });
+  };
+  child.once('exit', forget);
+  child.once('error', forget);
+  child.unref();
+  return spawned;
+}
+
+/** Probes until the server answers ok, the spawned child exits, or WAIT_MS passes. Returns the last probe. */
+async function waitForServer(port, spawned) {
+  const deadline = Date.now() + WAIT_MS;
+  for (;;) {
+    const last = await probe(port, LOOP_PROBE_MS);
+    if (last.state === 'ok') {
+      if (spawned) spawned.answered = true;
+      return { state: 'ok', last };
+    }
+    if (spawned?.exited || Date.now() >= deadline) return { state: 'failed', last };
+    await sleep(100);
+  }
+}
+
+/**
+ * Stops the server recorded in <store>/server.pid, but only when the record matches the answering server exactly
+ * (same port and same checkout root). Returns true once the port is free.
+ */
+async function stopRecordedServer(pidFile, port, root) {
+  const record = readRecord(pidFile);
+  if (!record || record.port !== port || record.root !== root || !Number.isInteger(record.pid) || record.pid < 1) return false;
+  // The command line must name this record's own server file (<root>/server.mjs): another repo's dashboard, or
+  // a developer's own, never matches, so one repo's hook can only ever stop the server it started itself.
+  if (!(await isDashboardListener(record.pid, port, path.join(String(record.root), 'server.mjs')))) return false;
+  try {
+    process.kill(record.pid, 'SIGTERM');
+  } catch {
+    return false;
+  }
+  const deadline = Date.now() + STOP_WAIT_MS;
+  while (Date.now() < deadline) {
+    if ((await probe(port, LOOP_PROBE_MS)).state === 'free') {
+      rmSync(pidFile, { force: true });
+      return true;
+    }
+    await sleep(50);
+  }
+  return false;
+}
+
+async function main() {
+  const port = resolvePort(path.join(HERE, '..'));
+  if (!Number.isInteger(port) || port < 1 || port > 65535) return;
+  const url = `http://127.0.0.1:${port}`;
+
+  const first = await probe(port, PROBE_MS);
+  if (first.state === 'foreign') return emit(inUse(port));
+  if (first.state === 'ok' && !isMissingCheckout(first.root)) return;
+
+  const storeDir = resolveStoreDir({ cwd: process.cwd() });
+  mkdirSync(storeDir, { recursive: true });
+  const pidFile = path.join(storeDir, 'server.pid');
+  const logFile = path.join(storeDir, 'server.log');
+  if (first.state === 'ok') {
+    // Healthy server whose checkout was deleted: replace it, but only the process we recorded for this port and root.
+    if (!(await stopRecordedServer(pidFile, port, first.root))) return emit(staleInUse(port));
+  }
+
+  // Only the session holding the lock spawns; a concurrent session waits for that server instead.
+  const lockFile = path.join(storeDir, 'server.starting');
+  const lock = acquireLock(lockFile);
+  if (lock === null) {
+    const r = await waitForServer(port, null);
+    if (r.state === 'ok') return emit(`Pipeline dashboard: ${url}`);
+    return emit(r.last.state === 'foreign' ? inUse(port) : couldNotStart(logFile));
+  }
+  let r;
+  try {
+    const spawned = await startServer(serverLocation(), { logFile, pidFile, port });
+    r = await waitForServer(port, spawned);
+    if (r.state === 'ok') return emit(`Pipeline dashboard: ${url}`);
+  } finally {
+    closeSync(lock);
+    rmSync(lockFile, { force: true });
+  }
+  emit(r.last.state === 'foreign' ? inUse(port) : couldNotStart(logFile));
+}
+
+// Runs only as the CLI entry (tests import the helpers). Let the process end on its own (no process.exit, so stdout
+// is never cut short); nothing here keeps the loop alive.
+const isEntry = (() => {
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+if (isEntry) {
+  main().catch(() => { /* never fail the session */ }).finally(() => { process.exitCode = 0; });
+}

package/templates/dashboard/hooks/subagent-stop.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// SubagentStop hook: appends one `agent` event (duration, tokens, estimated cost) to the active pipeline run.
+// Input (stdin JSON, Claude Code hooks docs): cwd, agent_id, agent_type, agent_transcript_path.
+// Never blocks or fails the session: exit 0 always, nothing on stdout.
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findRunByCwd, recordEvent, resolveStoreDir } from '../record.mjs';
+
+const PRICING_FILE = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'pricing.json');
+const TOKEN_FIELDS = {
+  input: 'input_tokens', output: 'output_tokens',
+  cacheRead: 'cache_read_input_tokens', cacheWrite: 'cache_creation_input_tokens',
+};
+
+export function loadPricing(file = PRICING_FILE) {
+  try { return JSON.parse(readFileSync(file, 'utf8')).models ?? {}; } catch { return {}; }
+}
+
+const BEAD = /\bbead\b\s*:?\s*([a-z][a-z0-9]*-[a-z0-9]+(?:\.[0-9]+)*)\b/i;
+
+function promptText(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) return content.map((c) => (typeof c?.text === 'string' ? c.text : '')).join('\n');
+  return '';
+}
+
+const num = (v) => (Number.isFinite(v) && v >= 0 ? v : 0);
+
+/** Parses a sub-agent transcript (JSONL). Bad lines are skipped. Returns the event fields and the transcript cwd. */
+export function summarizeTranscript(text, pricing = loadPricing()) {
+  const messages = new Map(); // message id -> { model, usage } (streamed lines repeat the id: keep the max per field)
+  let first = null;
+  let last = null;
+  let cwd = null;
+  let anon = 0;
+  let bead = null;
+  let seenPrompt = false;
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    let o;
+    try { o = JSON.parse(line); } catch { continue; }
+    if (!o || typeof o !== 'object') continue;
+    const t = Date.parse(o.timestamp);
+    if (Number.isFinite(t)) {
+      if (first === null || t < first) first = t;
+      if (last === null || t > last) last = t;
+    }
+    if (!cwd && typeof o.cwd === 'string') cwd = o.cwd;
+    const m = o.message;
+    if (o.type === 'user' && !seenPrompt && m) {
+      seenPrompt = true; // only the first user prompt names the bead
+      bead = BEAD.exec(promptText(m.content))?.[1] ?? null;
+    }
+    if (o.type !== 'assistant' || !m || typeof m.usage !== 'object' || m.usage === null) continue;
+    const id = typeof m.id === 'string' ? m.id : `anon-${anon++}`;
+    const cur = messages.get(id) ?? { model: null, usage: {} };
+    if (typeof m.model === 'string' && m.model && m.model !== '<synthetic>') cur.model = m.model;
+    for (const f of Object.values(TOKEN_FIELDS)) cur.usage[f] = Math.max(num(cur.usage[f]), num(m.usage[f]));
+    messages.set(id, cur);
+  }
+
+  const fields = {};
+  if (first !== null) fields.durationMs = last - first;
+  if (bead) fields.bead = bead;
+  if (messages.size === 0) return { fields, cwd };
+
+  const totals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+  let cost = 0;
+  let priced = true;
+  let model = null;
+  for (const msg of messages.values()) {
+    for (const [k, f] of Object.entries(TOKEN_FIELDS)) totals[k] += msg.usage[f] ?? 0;
+    if (msg.model) model = msg.model;
+    if (Object.values(msg.usage).every((v) => v === 0)) continue; // zero usage costs nothing, whatever its model
+    const p = msg.model ? pricing[msg.model] : null;
+    if (!p) { priced = false; continue; }
+    for (const k of Object.keys(totals)) cost += ((msg.usage[TOKEN_FIELDS[k]] ?? 0) * num(p[k])) / 1e6;
+  }
+  if (model) fields.model = model;
+  Object.assign(fields, {
+    tokensIn: totals.input, tokensOut: totals.output,
+    tokensCacheRead: totals.cacheRead, tokensCacheWrite: totals.cacheWrite,
+  });
+  if (priced) fields.cost = Number(cost.toFixed(6)); // unknown model: no cost field, never 0
+  return { fields, cwd };
+}
+
+/** Handles one hook input. Returns the recorded event or null (no-op). May throw; main() swallows. */
+export function handle(input, { env = process.env, pricing = loadPricing() } = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  const file = input.agent_transcript_path;
+  if (typeof file !== 'string' || !file) return null;
+  const { fields, cwd: transcriptCwd } = summarizeTranscript(readFileSync(file, 'utf8'), pricing);
+
+  let run = null;
+  let storeDir = null;
+  for (const cwd of [input.cwd, transcriptCwd]) {
+    if (typeof cwd !== 'string' || !cwd) continue;
+    try {
+      storeDir = resolveStoreDir({ cwd, env });
+      run = findRunByCwd(cwd, { storeDir });
+    } catch { run = null; }
+    if (run) break;
+  }
+  if (!run) return null;
+
+  const event = {};
+  if (typeof input.agent_id === 'string' && input.agent_id) event.agentId = input.agent_id;
+  if (typeof input.agent_type === 'string' && input.agent_type) event.agentType = input.agent_type;
+  return recordEvent(storeDir, run.id, 'agent', { ...event, ...fields });
+}
+
+function readStdin() {
+  try { return readFileSync(0, 'utf8'); } catch { return ''; }
+}
+
+export function main() {
+  try {
+    handle(JSON.parse(readStdin()));
+  } catch (err) {
+    console.error(`pipeline-subagent-stop: ${err?.message ?? err}`);
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+  process.exitCode = 0;
+}