wavework 0.0.0-stage → 0.1.0

package/src/context.mjs

@@ -0,0 +1,133 @@
+/**
+ * Turns a validated wavework config (src/config.mjs) into the variables the skill templates use
+ * (src/render.mjs). Repeated structures (check areas, model rules, findings epics) are computed here
+ * as Markdown, so the template engine needs no loops.
+ */
+
+const FINDING_CLASSES = {
+  security: { kind: 'Real', typical: 'auth, permission, token, egress, path, subprocess, secret handling, missing re-authorization' },
+  bugs: { kind: 'Real', typical: 'wrong behaviour, data loss, races, broken UX flows' },
+  tests: { kind: 'Quality', typical: 'flaky tests, missing malicious-case or edge tests, CI gaps' },
+  quality: { kind: 'Quality', typical: 'duplication, dead code, naming, design-system gaps, stale docs' },
+};
+const NUMBER_WORDS = ['zero', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten'];
+
+const code = (s) => `\`${s}\``;
+const orList = (items) => items.map(code).join(' or ');
+const fill = (pattern, values) => pattern.replace(/\{(\w+)\}/g, (_, key) => values[key]);
+
+function worktreeExpression(pattern, repoName) {
+  const values = { repo: repoName ?? '$(basename "$MAIN")', unit: '<unit-id>' };
+  // `../x` is a sibling of the main checkout; anything else is anchored at the main checkout itself.
+  return pattern.startsWith('../')
+    ? `$(dirname "$MAIN")/${fill(pattern.slice(3), values)}`
+    : `$MAIN/${fill(pattern, values)}`;
+}
+
+function areaSection(area) {
+  const lines = [
+    `## ${area.name}: files under ${area.whenPaths.map(code).join(', ')}`,
+    '',
+    `- **Focused:** ${code(area.focused)}`,
+    `- **Full:** ${code(area.full)}`,
+  ];
+  if (area.lint) lines.push(`- **Lint:** ${code(area.lint)}`);
+  if (area.build) lines.push(`- **Build:** ${code(area.build)}`);
+  if (area.e2e) lines.push(`- **E2E:** ${code(area.e2e)}`);
+  return lines.join('\n');
+}
+
+function findingsRows(epicTitles) {
+  return Object.entries(epicTitles)
+    .map(([slug, title]) => {
+      const { kind, typical } = FINDING_CLASSES[slug] ?? { kind: 'Quality', typical: '' };
+      return `| ${kind} | ${title.replace(/^Findings:\s*/, '')} | ${code(slug)} | ${typical} |`;
+    })
+    .join('\n');
+}
+
+/**
+ * Implementer models in agent order: the default first, then the other rule keys. The default is included
+ * even without a rule of its own (rule is then null).
+ *
+ * @param {object} config validated config
+ * @returns {{model: string, rule: string|null, isDefault: boolean}[]}
+ */
+export function implementerAgents(config) {
+  const { default: fallback, rules } = config.models.implementers;
+  return [fallback, ...Object.keys(rules).filter((m) => m !== fallback)].map((model) => ({
+    model,
+    rule: Object.hasOwn(rules, model) ? rules[model] : null,
+    isDefault: model === fallback,
+  }));
+}
+
+const AREA_KINDS = [['maven', /\bmvnw?\b/], ['vitest', /\bvitest\b/]];
+
+/**
+ * One line per check area for the `AREAS` table of scripts/red-green-check.sh: `'name|kind|dir'`. The kind
+ * (maven, vitest) is guessed from the area's focused command; anything else is `unsupported` and the script
+ * prints `SKIP <name>: unsupported` for it.
+ */
+function redGreenAreas(checks) {
+  return checks.map((a) => {
+    for (const field of [a.name, a.dir]) {
+      if (/[|'\n]/.test(field)) throw new Error(`area "${a.name}": name and dir must not contain "|", "'" or newlines (red-green-check.sh area table)`);
+    }
+    const kind = AREA_KINDS.find(([, re]) => re.test(a.focused))?.[0] ?? 'unsupported';
+    return `'${a.name}|${kind}|${a.dir.replace(/\/+$/, '') || '.'}'`;
+  }).join('\n');
+}
+
+/**
+ * @param {object} config validated config (see validateConfig)
+ * @param {object} [options]
+ * @param {string} [options.repoName] repository directory name for the worktree path; the skill asks the shell when absent
+ * @returns {object} template variables
+ */
+export function buildContext(config, options = {}) {
+  const { repoName } = options;
+  const { worktree, models, checks } = config;
+  const rules = models.implementers.rules;
+  const labels = Object.keys(rules);
+  if (!labels.includes(models.implementers.default)) labels.push(models.implementers.default);
+  const agents = implementerAgents(config).map((a) => a.model);
+  const branch = (values) => fill(worktree.branchPattern, values);
+  const withE2e = checks.filter((a) => a.e2e);
+  const titles = config.findings.epicTitles;
+  const count = Object.keys(titles).length;
+
+  return {
+    baseBranch: config.baseBranch,
+    repoName: repoName ?? '',
+    worktreeExpr: worktreeExpression(worktree.pathPattern, repoName),
+    worktreeExample: fill(worktree.pathPattern, { repo: repoName ?? 'repo', unit: 'shipr-cxk' }),
+    branchExpr: branch({ prefix: '<prefix>', unit: '<unit-id>', slug: '<slug>' }),
+    epicBranch: branch({ prefix: 'epic', unit: '<epic-id>', slug: '<slug>' }),
+    branchGlob: branch({ prefix: '<prefix>', unit: '<unit-id>', slug: '*' }),
+    taskBranchExample: branch({ prefix: 'task', unit: 'shipr-hae', slug: 'event-worker-interrupt' }),
+    models,
+    orchestrationModelName: models.orchestration.charAt(0).toUpperCase() + models.orchestration.slice(1),
+    modelLabelsOr: orList(labels.map((l) => `model:${l}`)),
+    modelLabelPipe: labels.join('|'),
+    implementerModelPipe: agents.join('|'),
+    implementerAgentsPlain: agents.map((a) => `implementer-${a}`).join(' and '),
+    implementerAgentsOr: orList(agents.map((a) => `implementer-${a}`)),
+    modelRules: Object.entries(rules).map(([model, text]) => `- ${code(model)}: ${text}`).join('\n'),
+    areaNamesPipe: checks.map((a) => a.name).join('|'),
+    checksSection: checks.map(areaSection).join('\n\n'),
+    depsSection: checks.map((a) => `- ${code(a.name)} (${code(a.dir)}, only if it exists)`).join('\n'),
+    fullChecksList: checks.map((a) => `- ${code(a.name)}: ${code(a.full)}`).join('\n'),
+    hasLint: checks.some((a) => a.lint),
+    hasE2e: withE2e.length > 0,
+    e2eList: withE2e.map((a) => `- ${code(a.name)}: ${code(a.e2e)}`).join('\n'),
+    codeMap: config.codeMap ?? false,
+    uiSkill: config.uiSkill ?? false,
+    uiPaths: config.uiSkill ? config.uiSkill.appliesTo.map(code).join(', ') : '',
+    findingsEpics: findingsRows(titles),
+    findingsEpicCount: NUMBER_WORDS[count] ?? String(count),
+    redGreenAreas: redGreenAreas(checks),
+    noAttribution: !config.attribution.allowAiTrailer,
+    dashboard: config.dashboard.enabled,
+  };
+}

package/src/render.mjs

@@ -0,0 +1,148 @@
+/**
+ * Minimal template engine for the skill templates. No dependencies, no escaping (output is Markdown).
+ *
+ * Syntax:
+ *   {{path.to.var}}                 value of a context variable (string or number)
+ *   {{#if key}} ... {{/if}}         body when truthy: true, non-empty string, non-empty array, any object
+ *   {{#if key}} ... {{else}} ... {{/if}}
+ *
+ * Rules:
+ *   - Unknown variables (also in `#if`) are errors, so typos never render as empty text.
+ *   - Blocks must balance, also in branches that are not taken.
+ *   - A block tag alone on its line removes the whole line, so blocks leave no blank lines.
+ *   - A variable alone on an indented line indents every line of a multi-line value the same way.
+ *   - There is no escape for a literal `{{` or `}}`; a stray one is an error.
+ */
+
+const NAME = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+const TAG = /\{\{([^{}]*)\}\}/g;
+
+function fail(name, line, message) {
+  return new Error(`template "${name}", line ${line}: ${message}`);
+}
+
+const lineOf = (text, index) => text.slice(0, index).split('\n').length;
+
+/** Splits the template into text and tag tokens; block tags alone on a line swallow the whole line. */
+function tokenize(text, name) {
+  const tokens = [];
+  let pos = 0;
+  const pushText = (end) => {
+    const chunk = text.slice(pos, end);
+    if (/\{\{|\}\}/.test(chunk)) {
+      const at = pos + chunk.search(/\{\{|\}\}/);
+      throw fail(name, lineOf(text, at), `stray "${text.slice(at, at + 2)}" (no escape exists for literal braces)`);
+    }
+    if (chunk) tokens.push({ type: 'text', value: chunk });
+  };
+  for (const match of text.matchAll(TAG)) {
+    const inner = match[1].trim();
+    const line = lineOf(text, match.index);
+    let start = match.index;
+    let end = match.index + match[0].length;
+    let token;
+    if (inner === '') throw fail(name, line, 'empty tag');
+    if (inner.startsWith('#if ')) {
+      const key = inner.slice(4).trim();
+      if (!NAME.test(key)) throw fail(name, line, `invalid tag "{{${inner}}}"`);
+      token = { type: 'if', key, line };
+    } else if (inner === 'else' || inner === '/if') {
+      token = { type: inner, line };
+    } else if (NAME.test(inner)) {
+      token = { type: 'var', key: inner, line };
+    } else {
+      throw fail(name, line, `invalid tag "{{${inner}}}"`);
+    }
+    if (token.type !== 'var') {
+      const lineStart = text.lastIndexOf('\n', start - 1) + 1;
+      const nl = text.indexOf('\n', end);
+      const lineEnd = nl === -1 ? text.length : nl;
+      if (/^[ \t]*$/.test(text.slice(lineStart, start)) && /^[ \t]*$/.test(text.slice(end, lineEnd))) {
+        start = lineStart;
+        end = nl === -1 ? text.length : nl + 1;
+      }
+    }
+    pushText(start);
+    tokens.push(token);
+    pos = end;
+  }
+  pushText(text.length);
+  return tokens;
+}
+
+/** Builds a tree of { type: 'text' | 'var' | 'if', ... } and checks that blocks balance. */
+function parse(tokens, name) {
+  const root = { children: [] };
+  const stack = [{ node: root, list: root.children }];
+  for (const token of tokens) {
+    const top = stack[stack.length - 1];
+    if (token.type === 'text' || token.type === 'var') {
+      top.list.push(token);
+    } else if (token.type === 'if') {
+      const node = { type: 'if', key: token.key, line: token.line, then: [], otherwise: null };
+      top.list.push(node);
+      stack.push({ node, list: node.then });
+    } else if (token.type === 'else') {
+      if (stack.length === 1) throw fail(name, token.line, '{{else}} outside of an {{#if}} block');
+      if (top.node.otherwise !== null) throw fail(name, token.line, 'more than one {{else}} in one {{#if}} block');
+      top.node.otherwise = [];
+      top.list = top.node.otherwise;
+    } else {
+      if (stack.length === 1) throw fail(name, token.line, '{{/if}} without a matching {{#if}}');
+      stack.pop();
+    }
+  }
+  if (stack.length > 1) {
+    const open = stack[stack.length - 1].node;
+    throw fail(name, open.line, `unclosed block {{#if ${open.key}}}`);
+  }
+  return root.children;
+}
+
+function lookup(context, key, name, line) {
+  let value = context;
+  for (const part of key.split('.')) {
+    if (value === null || typeof value !== 'object' || !Object.hasOwn(value, part)) {
+      throw fail(name, line, `unknown variable "${key}"`);
+    }
+    value = value[part];
+  }
+  return value;
+}
+
+function truthy(value) {
+  if (Array.isArray(value) || typeof value === 'string') return value.length > 0;
+  return Boolean(value);
+}
+
+/**
+ * @param {string} template
+ * @param {object} context variables; see src/context.mjs
+ * @param {string} [name] template name for error messages
+ * @returns {string}
+ */
+export function render(template, context, name = '<template>') {
+  const tree = parse(tokenize(template, name), name);
+  let out = '';
+  const walk = (nodes) => {
+    for (const node of nodes) {
+      if (node.type === 'text') {
+        out += node.value;
+      } else if (node.type === 'var') {
+        const value = lookup(context, node.key, name, node.line);
+        if (typeof value !== 'string' && typeof value !== 'number') {
+          throw fail(name, node.line, `variable "${node.key}" is not a string or number`);
+        }
+        const tail = out.slice(out.lastIndexOf('\n') + 1);
+        const indent = /^[ \t]+$/.test(tail) ? tail : '';
+        out += String(value).split('\n').join(`\n${indent}`);
+      } else if (truthy(lookup(context, node.key, name, node.line))) {
+        walk(node.then);
+      } else if (node.otherwise !== null) {
+        walk(node.otherwise);
+      }
+    }
+  };
+  walk(tree);
+  return out;
+}

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.