buildline 0.5.1 → 0.6.0

package/README.md

@@ -134,7 +134,8 @@ Start at 2. Raise it as your gates and acceptance scenarios earn trust. [More on
 
 <img alt="buildline watch: features on tracks through spec, design, plan, build, verify, review and ship, with an inspector and live event log" src="docs/assets/watch.png">
 
-- a **comet** on the track means an agent can work on it now; a **blinking dot** means it waits on a PM, designer or engineer
+- a **comet** on the track means a Claude Code session is working on it right now, with its latest step; **NEEDS YOU** and **BLOCKED** mean an agent is waiting on your answer
+- run several sessions at once, one per feature: each gets its own track
 - the model under each station is the one that runs it
 - `↑↓` to inspect tasks and history, `⏎` to open the station on its model, `a` to approve, `q` to quit
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buildline",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Install an AI software factory into any project. A spec-driven pipeline for Claude Code (and any AGENTS.md-compatible agent), for developers, designers and product managers.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -7,7 +7,7 @@ import { detect, describeStack } from './detect.js';
 import { AGENTS, AUTONOMY, VERSION, makeConfig, plan, apply, removePlan, applyRemove, defaultGates } from './install.js';
 import { loadManifest } from './files.js';
 import { PHASES, MODEL_STATIONS, CLIS, modelFor, parseModel, parseModelList, describeModel, discoverModelOptions, checkModel, stationPrompt, launchArgs, externalClis } from './models.js';
-import { listFeatures, findFeature, createFeature, approve, setStatus, nextAction, STATIONS, TYPES } from './features.js';
+import { listFeatures, findFeature, createFeature, approve, setStatus, nextAction, moveBlocker, STATIONS, TYPES } from './features.js';
 
 const LOGO = [
   pc.yellow('  ┌┐ ┬ ┬┬┬  ┌┬┐┬  ┬┌┐┌┌─┐'),
@@ -310,6 +310,8 @@ export function moveFeature(root, ref, station, opts) {
   const f = findFeature(root, ref);
   if (!f) throw new Error(`No feature matching "${ref}".`);
   if (!STATIONS.includes(station)) throw new Error(`Station must be one of: ${STATIONS.join(', ')}`);
+  const blocker = opts.force ? null : moveBlocker(f, station, loadConfig(root).autonomy ?? 2);
+  if (blocker) throw new Error(blocker.replace(/node \.buildline\/bin\/feature\.mjs approve/, 'npx buildline approve') + ' Or pass --force.');
   setStatus(f, station, opts.note);
   console.log(`${pc.green('✔')} ${f.id} → ${station}`);
 }

package/src/features.js

@@ -3,6 +3,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { render, templatesDir } from './render.js';
+import { moveBlocker } from '../templates/bin/feature.mjs';
+
+export { moveBlocker };
 
 export const STATIONS = ['new', 'spec', 'design', 'plan', 'build', 'verify', 'review', 'ship', 'done'];
 export const TYPES = ['fix', 'feature', 'epic'];
@@ -126,9 +129,12 @@ export function nextAction(feature, autonomy = 2) {
       if (/TODO/.test(readSpecSection(feature, 'Acceptance') || 'TODO')) return { who: 'pm', text: 'needs requirements & acceptance', cmd: `/buildline-spec ${feature.id}` };
       return autonomy <= 3 && !a.spec ? { who: 'pm', text: 'waiting on spec approval', cmd: `buildline approve ${feature.id} spec` } : { who: 'agent', text: 'ready for design', cmd: `/buildline-design ${feature.id}` };
     case 'design':
+      if (autonomy <= 1 && a.design) return { who: 'agent', text: 'ready for a plan', cmd: `/buildline-plan ${feature.id}` };
       return { who: 'designer', text: 'needs UX / technical design', cmd: `/buildline-design ${feature.id}` };
     case 'plan':
-      return { who: 'eng', text: 'needs a task plan', cmd: `/buildline-plan ${feature.id}` };
+      if (!tasks.length) return { who: 'eng', text: 'needs a task plan', cmd: `/buildline-plan ${feature.id}` };
+      if (feature.type !== 'fix' && autonomy <= 2 && !a.plan) return { who: 'eng', text: 'waiting on plan approval', cmd: `buildline approve ${feature.id} plan` };
+      return { who: 'agent', text: 'ready to build', cmd: `/buildline-build ${feature.id}` };
     case 'build':
       if (feature.type !== 'fix' && autonomy <= 3 && !a.spec) return { who: 'pm', text: 'waiting on spec approval', cmd: `buildline approve ${feature.id} spec` };
       if (feature.type !== 'fix' && autonomy <= 2 && !a.plan && tasks.length) return { who: 'eng', text: 'waiting on plan approval', cmd: `buildline approve ${feature.id} plan` };
@@ -155,3 +161,61 @@ export function readSpecSection(feature, heading) {
     return null;
   }
 }
+
+// ---- live sessions -------------------------------------------------------------
+// Claude Code hooks write one file per session to .buildline/sessions/ (see
+// templates/bin/hook.mjs). A session that hasn't been heard from in a while has
+// most likely crashed or been closed without a SessionEnd.
+
+const WORKING_FOR = 10 * 60e3;
+const WAITING_FOR = 2 * 3600e3;
+
+export function readSessions(root, at = Date.now()) {
+  const dir = path.join(root, '.buildline', 'sessions');
+  const out = [];
+  // `tracked` says hooks are reporting here, so "no session" really means nobody is working.
+  out.tracked = fs.existsSync(dir);
+  if (!out.tracked) return out;
+  for (const name of fs.readdirSync(dir)) {
+    if (!name.endsWith('.json')) continue;
+    try {
+      const s = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'));
+      const age = at - new Date(s.lastAt);
+      if (s.state === 'working' && age < WORKING_FOR) out.push({ ...s, age });
+      else if (s.state === 'waiting' && age < WAITING_FOR) out.push({ ...s, age });
+    } catch {}
+  }
+  return Object.assign(out.sort((a, b) => a.age - b.age), { tracked: true });
+}
+
+/** Recent tool calls from live sessions, oldest first. */
+export function readActivity(root, limit = 200) {
+  try {
+    const text = fs.readFileSync(path.join(root, '.buildline', 'sessions', 'activity.jsonl'), 'utf8');
+    return text.split('\n').filter(Boolean).slice(-limit).flatMap((l) => {
+      try {
+        return [JSON.parse(l)];
+      } catch {
+        return [];
+      }
+    });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * What's happening on a feature right now: live sessions on it, whether one is
+ * working or waiting for a reply. Where no hooks report (agents other than
+ * Claude Code), a feature whose files changed in the last two minutes counts as worked on.
+ */
+export function liveState(feature, sessions, at = Date.now()) {
+  const mine = sessions.filter((s) => s.feature === feature.id);
+  const working = mine.filter((s) => s.state === 'working');
+  const recent = at - new Date(feature.updated || 0) < 2 * 60e3;
+  return {
+    sessions: mine,
+    working: working.length > 0 || (!sessions.tracked && recent && !feature.blocked && feature.status !== 'done'),
+    waiting: !working.length && mine.some((s) => s.state === 'waiting'),
+  };
+}

package/src/install.js

@@ -140,6 +140,7 @@ export function buildEntries(root, config) {
   for (const f of ['spec.md', 'progress.md']) add(`.buildline/templates/${f}`, read(`feature/${f}`));
   add('.buildline/bin/gates.mjs', read('bin/gates.mjs'), { executable: true });
   add('.buildline/bin/hook.mjs', read('bin/hook.mjs'), { executable: true });
+  add('.buildline/bin/feature.mjs', read('bin/feature.mjs'), { executable: true });
   add('.buildline/features/.gitkeep', '');
   if (config.ci) add('.github/workflows/buildline.yml', render(read('ci/buildline.yml'), vars));
   return entries;
@@ -151,7 +152,7 @@ const HOOK_MARK = '.buildline/bin/hook.mjs';
 const hookCmd = (mode) => `node "$CLAUDE_PROJECT_DIR/.buildline/bin/hook.mjs" ${mode}`;
 
 export function settingsAllow(config) {
-  const allow = ['Bash(node .buildline/bin/gates.mjs)', 'Bash(node .buildline/bin/gates.mjs *)', 'Bash(npx buildline *)'];
+  const allow = ['Bash(node .buildline/bin/gates.mjs)', 'Bash(node .buildline/bin/gates.mjs *)', 'Bash(node .buildline/bin/feature.mjs *)', 'Bash(npx buildline *)'];
   for (const g of config.gates) allow.push(`Bash(${g.command})`, `Bash(${g.command} *)`);
   return [...new Set(allow)];
 }
@@ -169,13 +170,20 @@ export function mergeSettings(root, config) {
   }
   const before = JSON.stringify(settings);
   settings.hooks ??= {};
+  // One Buildline hook per event; older installs get their entry upgraded in place.
   const ensureHook = (event, matcher, mode) => {
     const groups = (settings.hooks[event] ??= []);
-    const present = groups.some((g) => (g.hooks || []).some((h) => h.command?.includes(HOOK_MARK)));
-    if (!present) groups.push({ ...(matcher ? { matcher } : {}), hooks: [{ type: 'command', command: hookCmd(mode) }] });
+    const ours = groups.find((g) => (g.hooks || []).some((h) => h.command?.includes(HOOK_MARK)));
+    if (!ours) return groups.push({ ...(matcher ? { matcher } : {}), hooks: [{ type: 'command', command: hookCmd(mode) }] });
+    if (matcher) ours.matcher = matcher;
+    else delete ours.matcher;
+    for (const h of ours.hooks) if (h.command?.includes(HOOK_MARK)) h.command = hookCmd(mode);
   };
   ensureHook('SessionStart', null, 'session-start');
-  ensureHook('PreToolUse', 'Edit|Write|MultiEdit', 'guard');
+  ensureHook('PreToolUse', null, 'pre');
+  ensureHook('UserPromptSubmit', null, 'prompt');
+  ensureHook('Stop', null, 'stop');
+  ensureHook('SessionEnd', null, 'session-end');
 
   settings.permissions ??= {};
   settings.permissions.allow ??= [];

package/src/server.js

@@ -8,7 +8,7 @@ import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import pc from 'picocolors';
-import { listFeatures, findFeature, createFeature, approve, setStatus, nextAction } from './features.js';
+import { listFeatures, findFeature, createFeature, approve, setStatus, nextAction, readSessions, liveState } from './features.js';
 import { AUTONOMY, VERSION } from './install.js';
 import { goalFor } from './cli.js';
 
@@ -35,9 +35,11 @@ function openBrowser(url) {
 
 function state(root) {
   const config = JSON.parse(fs.readFileSync(path.join(root, '.buildline', 'buildline.json'), 'utf8'));
+  const sessions = readSessions(root);
   const features = listFeatures(root).map(({ path: _p, ...f }) => ({
     ...f,
     next: nextAction({ ...f, path: _p }, config.autonomy),
+    live: liveState(f, sessions),
     goal: goalFor(f),
   }));
   const contextDir = path.join(root, '.buildline', 'context');

package/src/tui.js

@@ -7,7 +7,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import pc from 'picocolors';
-import { listFeatures, nextAction, approve } from './features.js';
+import { listFeatures, nextAction, approve, readSessions, readActivity, liveState } from './features.js';
 import { modelFor, describeModel } from './models.js';
 import { AUTONOMY, VERSION } from './install.js';
 
@@ -41,6 +41,7 @@ const C = {
   amberDim: fg('#8a6a1a'),
   green: fg('#4ec27f'),
   red: fg('#f7768e'),
+  cyan: fg('#59c2e6'),
   flash: pc.isColorSupported ? (s) => `\x1b[48;5;94m\x1b[38;5;230m${s}\x1b[39m\x1b[49m` : null,
 };
 const WHO = {
@@ -102,11 +103,17 @@ function box(screen, x, y, w, h, title, { accent = false } = {}) {
 function loadState(root, showShipped) {
   const config = JSON.parse(fs.readFileSync(path.join(root, '.buildline', 'buildline.json'), 'utf8'));
   const all = listFeatures(root);
-  const features = all.filter((f) => showShipped || f.status !== 'done').map((f) => ({ ...f, next: nextAction(f, config.autonomy) }));
+  const sessions = readSessions(root);
+  const features = all
+    .filter((f) => showShipped || f.status !== 'done')
+    .map((f) => ({ ...f, next: nextAction(f, config.autonomy), live: liveState(f, sessions) }));
+  // Station history plus the live tool feed from running sessions, in time order.
+  const tools = readActivity(root).map((a) => ({ at: a.at, id: a.feature, station: a.tool, note: a.detail, tool: true, key: `t|${a.at}|${a.session}|${a.detail}` }));
   const events = all
     .flatMap((f) => (f.history || []).map((h) => ({ ...h, id: f.id, key: `${f.id}|${h.at}|${h.note}` })))
+    .concat(tools)
     .sort((a, b) => String(a.at).localeCompare(String(b.at)));
-  return { config, all, features, events };
+  return { config, all, features, events, sessions };
 }
 
 const stationIndex = (status) => (status === 'new' ? 0 : status === 'done' ? TRACK.length : TRACK.indexOf(status));
@@ -114,6 +121,21 @@ const shortModel = (config, station) => {
   const m = modelFor(config, station);
   return m.cli === 'claude' && !m.model ? 'session' : describeModel(m).replace(/^claude-/, '');
 };
+const ago = (ms) => (ms < 60e3 ? `${Math.max(1, Math.round(ms / 1000))}s` : ms < 3600e3 ? `${Math.round(ms / 60e3)}m` : `${Math.round(ms / 3600e3)}h`);
+
+/** The NEXT UP cell: who or what the feature is waiting on right now. */
+function rowStatus(f, t) {
+  if (f.blocked) return ['BLOCKED', C.red];
+  if (f.live.working) {
+    const n = f.live.sessions.filter((x) => x.state === 'working').length;
+    return [`${SPINNER[t % SPINNER.length]} ${n > 1 ? `×${n} ` : ''}WORKING`, C.amberBold];
+  }
+  if (f.live.waiting) return ['NEEDS YOU', t % 12 < 8 ? C.red : C.faint];
+  if (f.next.who === 'agent') return ['AGENT', C.amberDim];
+  const who = WHO[f.next.who];
+  return who ? [who.label, who.color] : ['', null];
+}
+
 const hash = (s) => [...String(s)].reduce((h, c) => (h * 31 + c.charCodeAt(0)) >>> 0, 7);
 
 function timeLabel(iso) {
@@ -141,7 +163,9 @@ function drawTrack(line, x, f, seg, t) {
   const cur = stationIndex(f.status);
   const who = WHO[f.next.who];
   const skipped = (i) => f.type === 'fix' && i < 3 && cur >= 3;
-  const working = f.next.who === 'agent' && !f.blocked;
+  // The comet only runs while a session is actually working on this feature.
+  const working = f.live?.working && !f.blocked;
+  const idleAgent = f.next.who === 'agent' && !f.blocked && !f.live?.waiting;
   for (let i = 0; i < TRACK.length; i++) {
     const nx = x + i * seg;
     let node = ['○', C.faint];
@@ -149,6 +173,8 @@ function drawTrack(line, x, f, seg, t) {
     else if (i < cur) node = ['●', C.green];
     else if (i === cur && f.blocked) node = ['✖', t % 10 < 5 ? C.red : C.faint];
     else if (i === cur && working) node = [['◉', '◎', '◉', '●'][Math.floor(t / 3) % 4], C.amberBold];
+    else if (i === cur && f.live?.waiting) node = ['◉', t % 12 < 8 ? C.red : C.faint];
+    else if (i === cur && idleAgent) node = ['◉', C.amberDim];
     else if (i === cur) node = ['◉', t % 12 < 8 ? who?.color || C.amber : C.faint];
     line.put(nx, node[0], node[1]);
     if (i === TRACK.length - 1) break;
@@ -180,7 +206,8 @@ function render(st, ui, W, H) {
   const active = st.all.filter((f) => f.status !== 'done');
   const shipped = st.all.length - active.length;
   const tasks = active.flatMap((f) => f.tasks || []);
-  const waiting = active.filter((f) => ['pm', 'designer', 'eng', 'human'].includes(nextAction(f, config.autonomy).who)).length;
+  const waiting = features.filter((f) => f.status !== 'done' && !f.live.working && (f.live.waiting || ['pm', 'designer', 'eng', 'human'].includes(f.next.who))).length;
+  const sessionsWorking = st.sessions.filter((x) => x.state === 'working').length;
 
   // header
   const tall = W >= 96 && H >= 26;
@@ -196,6 +223,7 @@ function render(st, ui, W, H) {
     right(0, [[config.project || path.basename(ui.root), C.bold], ['  ·  ', C.faint], [AUTONOMY[config.autonomy]?.label || `L${config.autonomy}`, C.amber], ['  ·  ', C.faint], [live, C.green]]);
     right(1, [
       ['ACTIVE ', C.muted], [String(active.length), C.bold], ['   SHIPPED ', C.muted], [String(shipped), C.green],
+      ['   SESSIONS ', C.muted], [String(sessionsWorking), sessionsWorking ? C.amberBold : C.bold],
       ['   TASKS ', C.muted], [`${tasks.filter((x) => x.passes).length}/${tasks.length}`, C.bold],
       ['   WAITING ON PEOPLE ', C.muted], [String(waiting), waiting ? WHO.pm.color : C.bold],
     ]);
@@ -230,13 +258,13 @@ function render(st, ui, W, H) {
     if (seg >= 7) screen[top + 2].put(nx - Math.floor(m.length / 2), m, C.faint);
   });
   screen[top + 1].put(rx, 'FEATURE', C.muted);
-  screen[top + 1].put(W - 3 - 7, 'NEXT UP', C.muted);
+  screen[top + 1].put(W - 3 - 3, 'NOW', C.muted);
   const rowsAvail = lineH - 5;
   if (ui.sel < ui.scroll) ui.scroll = ui.sel;
   if (ui.sel >= ui.scroll + rowsAvail) ui.scroll = ui.sel - rowsAvail + 1;
   if (!features.length) {
     const line = screen[top + 4];
-    drawTrack(line, tx, { id: 'idle', status: 'spec', type: 'feature', next: { who: 'agent' } }, seg, t);
+    drawTrack(line, tx, { id: 'idle', status: 'spec', type: 'feature', next: { who: 'agent' }, live: { working: true, sessions: [] } }, seg, t);
     line.put(rx, 'the line is quiet · ', C.muted);
     line.put(rx + 20, 'npx buildline new "…"', C.amber);
   }
@@ -248,8 +276,8 @@ function render(st, ui, W, H) {
     line.put(2, selected ? '▸' : ' ', C.amberBold);
     line.put(4, f.id, flashing ? C.flash : selected ? C.amberBold : C.muted);
     drawTrack(line, tx, f, seg, t);
-    const who = WHO[f.next.who];
-    const whoW = 8;
+    const [label, labelColor] = rowStatus(f, t);
+    const whoW = 12;
     const ts = f.tasks || [];
     const roomy = W - 3 - whoW - rx >= 30;
     const barW = ts.length ? (roomy ? 11 : 5) : 0;
@@ -262,7 +290,7 @@ function render(st, ui, W, H) {
       if (roomy) bx = line.put(line.put(bx, '▰'.repeat(filled), C.green), '▱'.repeat(5 - filled), C.faint) + 1;
       line.put(bx, `${pass}/${ts.length}`, pass === ts.length ? C.green : C.muted);
     }
-    if (who) line.put(W - 3 - who.label.length, who.label, who.color);
+    if (label) line.put(W - 3 - [...label].length, label, labelColor);
   });
   if (features.length > rowsAvail) screen[top + lineH - 1].put(W - 16, ` ${ui.sel + 1}/${features.length} `, C.muted);
 
@@ -306,6 +334,24 @@ function drawInspector(screen, st, f, x, y, w, h) {
     return a ? [[`${s} ✔ ${a.by}  `, C.green]] : [[`${s} ·  `, C.faint]];
   });
   add(['approvals ', C.muted], ...appr.flat());
+  if (f.blocked) {
+    const width = Math.max(10, w - 15);
+    const words = String(f.blocked).split(/\s+/);
+    const lines = [''];
+    for (const word of words) (lines.at(-1) + ' ' + word).trim().length > width ? lines.push(word) : (lines[lines.length - 1] = (lines.at(-1) + ' ' + word).trim());
+    lines.slice(0, 4).forEach((l, i) => add([i ? '           ' : '✖ blocked  ', C.red], [l, C.bold]));
+  }
+  for (const ses of f.live?.sessions || []) {
+    const on = ses.state === 'working';
+    add(
+      [on ? '● ' : '◌ ', on ? C.amberBold : C.red],
+      [`session ${String(ses.id).slice(0, 8)} `, C.muted],
+      [`${(ses.model ? String(ses.model) : shortModel(config, f.status)).replace(/^claude-/, '')} `, C.text],
+      [on ? `${ses.tool || 'thinking'} ` : 'waiting for your reply ', on ? C.cyan : C.red],
+      [on ? `${ses.detail || ''} ` : '', C.text],
+      [`· ${ago(ses.age)} ago`, C.faint],
+    );
+  }
   const ts = f.tasks || [];
   if (ts.length) {
     add();
@@ -324,7 +370,8 @@ function drawInspector(screen, st, f, x, y, w, h) {
   }
   add();
   const who = WHO[f.next.who];
-  add(['next ', C.muted], [who ? who.label + ' ' : '', who?.color || C.text], [f.next.text, C.text]);
+  if (f.blocked) add(['next ', C.muted], ['answer the question in the session that asked it', C.text]);
+  else add(['next ', C.muted], [who ? who.label + ' ' : '', who?.color || C.text], [f.next.text, C.text]);
   if (f.next.cmd) add(['❯ ', C.amberBold], [f.next.cmd, C.amber]);
   const room = h - 2 - rows.length - 2;
   const journey = (f.history || []).slice(-room);
@@ -346,9 +393,9 @@ function drawEvents(screen, st, ui, x, y, w, h) {
     const line = screen[y + 1 + r];
     const fresh = (ui.freshEvents.get(e.key) || 0) > Date.now();
     let cx = line.put(x + 2, timeLabel(e.at), C.faint);
-    cx = line.put(cx + 1, e.id, fresh ? C.flash : C.amber);
-    cx = line.put(cx + 1, String(e.station || '').padEnd(7), C.muted);
-    line.put(cx + 1, e.note || '', fresh ? C.bold : C.text, x + w - 2);
+    cx = line.put(cx + 1, e.id || '···', fresh ? C.flash : C.amber);
+    cx = line.put(cx + 1, clip(e.station || '', 7).padEnd(7), e.tool ? C.cyan : C.muted);
+    line.put(cx + 1, e.note || '', e.tool ? C.muted : fresh ? C.bold : C.text, x + w - 2);
   });
   if (!rows.length) screen[y + 1].put(x + 2, 'nothing yet', C.faint);
 }

package/src/ui/index.html

@@ -55,7 +55,7 @@ main { padding: 16px 20px 40px; }
 .col .owner { display: block; font-size: 11px; font-weight: 500; color: var(--ink-3); text-transform: none; letter-spacing: 0; margin-top: 1px; }
 .card { background: var(--panel); border: 1px solid var(--line); border-radius: 10px; padding: 10px 12px; margin-bottom: 8px; box-shadow: var(--shadow); cursor: pointer; display: block; width: 100%; text-align: left; }
 .card:hover { border-color: var(--accent); }
-.card .top { display: flex; gap: 6px; align-items: center; margin-bottom: 4px; }
+.card .top { display: flex; flex-wrap: wrap; gap: 6px; align-items: center; margin-bottom: 4px; }
 .card .id { font: 12px var(--mono); color: var(--ink-3); }
 .card .title { font-weight: 600; line-height: 1.3; }
 .card .next { font-size: 12px; line-height: 1.35; color: var(--ink-2); margin-top: 6px; display: flex; gap: 6px; align-items: baseline; }
@@ -68,6 +68,20 @@ main { padding: 16px 20px 40px; }
 .who-designer { background: var(--blue-soft); color: var(--blue); }
 .who-eng, .who-agent { background: var(--green-soft); color: var(--green); }
 .who-human { background: var(--red-soft); color: var(--red); }
+.live { font-size: 12px; line-height: 1.4; margin-top: 6px; display: flex; gap: 6px; align-items: baseline; color: var(--ink-2); min-width: 0; }
+.live > span { min-width: 0; flex: 1; }
+.live .line { display: block; overflow: hidden; white-space: nowrap; text-overflow: ellipsis; }
+.live .wrap { display: -webkit-box; -webkit-line-clamp: 4; -webkit-box-orient: vertical; overflow: hidden; overflow-wrap: anywhere; }
+.live b { font-weight: 600; }
+.live.working b { color: var(--ink); }
+.live.waiting b, .live.blocked b { color: var(--red); }
+.live .dot { flex-shrink: 0; width: 8px; height: 8px; border-radius: 50%; background: var(--accent); align-self: center; animation: pulse 1.2s ease-in-out infinite; }
+.live.waiting .dot, .live.blocked .dot { background: var(--red); }
+.live.blocked .dot { animation: none; }
+.live code { font-size: 11px; background: none; padding: 0; }
+.card.is-working { border-color: var(--accent); }
+@keyframes pulse { 50% { opacity: .25; transform: scale(.7); } }
+@media (prefers-reduced-motion: reduce) { .live .dot { animation: none; } }
 .progress { height: 4px; background: var(--line); border-radius: 2px; overflow: hidden; margin-top: 8px; }
 .progress > i { display: block; height: 100%; background: var(--green); }
 .approvals { display: flex; gap: 4px; margin-top: 6px; flex-wrap: wrap; }
@@ -217,14 +231,33 @@ function md(src) {
 function card(f) {
   const tasks = f.tasks || [], done = tasks.filter((t) => t.passes).length;
   const ap = Object.keys(f.approvals || {});
-  return `<button class="card" data-id="${esc(f.id)}">
-    <div class="top"><span class="id">${esc(f.id)}</span><span class="chip type-${esc(f.type)}">${esc(f.type)}</span>${f.blocked ? '<span class="chip type-fix">blocked</span>' : ''}</div>
+  return `<button class="card${f.live?.working ? ' is-working' : ''}" data-id="${esc(f.id)}">
+    <div class="top"><span class="id">${esc(f.id)}</span><span class="chip type-${esc(f.type)}">${esc(f.type)}</span></div>
     <div class="title">${esc(f.title)}</div>
     ${tasks.length ? `<div class="progress" title="${done}/${tasks.length} tasks passing"><i style="width:${(done / tasks.length) * 100}%"></i></div>` : ''}
-    ${f.next?.text && f.status !== 'done' ? `<div class="next">${f.next.who ? `<span class="who who-${esc(f.next.who)}">${esc(f.next.who)}</span>` : ''}${esc(f.next.text)}</div>` : ''}
+    ${liveLine(f)}
+    ${f.next?.text && f.status !== 'done' && !f.blocked ? `<div class="next">${f.next.who ? `<span class="who who-${esc(f.next.who)}">${esc(f.next.who)}</span>` : ''}${esc(f.next.text)}</div>` : ''}
     ${ap.length ? `<div class="approvals">${ap.map((a) => `<span class="chip" title="by ${esc(f.approvals[a].by)}">✓ ${esc(a)}</span>`).join('')}</div>` : ''}
   </button>`;
 }
+const stationModel = (station) => { const m = S.config.models || {}; const v = m[station] ?? m.default; return v && v !== 'inherit' ? v : ''; };
+const ago = (ms) => (ms < 60e3 ? `${Math.max(1, Math.round(ms / 1000))}s` : ms < 3600e3 ? `${Math.round(ms / 60e3)}m` : `${Math.round(ms / 3600e3)}h`);
+/** What is happening on a feature right now: a blocker, a working session, or one waiting for a reply. */
+function liveLine(f) {
+  if (f.blocked) return `<div class="live blocked"><i class="dot"></i><span class="wrap"><b>Blocked:</b> ${esc(f.blocked)}</span></div>`;
+  const ses = f.live?.sessions || [];
+  const on = ses.filter((x) => x.state === 'working');
+  if (f.live?.working) {
+    const s = on[0];
+    if (!s) return `<div class="live working"><i class="dot"></i><span><b>Working</b> · files changing</span></div>`;
+    const model = String(s.model || stationModel(f.status) || '').replace(/^claude-/, '');
+    const head = [`<b>Working${on.length > 1 ? ` ×${on.length}` : ''}</b>`, ago(s.age), model && esc(model)].filter(Boolean).join(' · ');
+    const doing = s.tool ? `${esc(s.tool)} <code>${esc(s.detail || '')}</code>` : 'thinking';
+    return `<div class="live working" title="${esc([s.tool, s.detail].filter(Boolean).join(': '))}"><i class="dot"></i><span><span class="line">${head}</span><span class="line">${doing}</span></span></div>`;
+  }
+  if (f.live?.waiting) return `<div class="live waiting"><i class="dot"></i><span><b>Waiting for your reply</b> in a Claude session</span></div>`;
+  return '';
+}
 function renderBoard() {
   if (!S.features.length) {
     return `<div class="hero"><h1>No features yet</h1><p>Every change in this project flows through the factory: spec, design, plan, build, verify, review, ship.</p>
@@ -234,7 +267,7 @@ function renderBoard() {
   return `<div class="board">${COLUMNS.map(([key, label, owner]) => {
     const items = S.features.filter((f) => f.status === key);
     const model = (S.config.models || {})[key] ?? S.config.models?.default;
-    const modelTag = model && model !== 'inherit' ? ` · <span class="model" title="Model for this station (buildline models)">${esc(model)}</span>` : '';
+    const modelTag = key !== 'done' && model && model !== 'inherit' ? ` · <span class="model" title="Model for this station (buildline models)">${esc(model)}</span>` : '';
     return `<section class="col" aria-label="${label}"><h2><span>${label} <span class="owner">${owner}${modelTag}</span></span><small>${items.length}</small></h2>${items.map(card).join('') || '<div class="empty">—</div>'}</section>`;
   }).join('')}</div>`;
 }
@@ -327,7 +360,7 @@ async function refresh() {
   } catch (e) { toast('Dashboard lost connection: is `buildline ui` still running?'); }
 }
 refresh();
-setInterval(() => { if (!document.hidden && !editing && !ctxEditing) refresh(); }, 3000);
+setInterval(() => { if (!document.hidden && !editing && !ctxEditing) refresh(); }, 2000);
 </script>
 </body>
 </html>

package/templates/AGENTS.block.md

@@ -23,7 +23,7 @@ Each station has a playbook in `.buildline/stations/<station>.md`. Read the play
 
 ### Where things live
 
-- `.buildline/features/<id>-<slug>/feature.json` — state: status, approvals, tasks (each with `passes`), history
+- `.buildline/features/<id>-<slug>/feature.json` — state: status, approvals, tasks (each with `passes`), history. Change it only with `node .buildline/bin/feature.mjs` (run it with no arguments for usage), never by hand.
 - `.buildline/features/<id>-<slug>/spec.md` — the single source of truth for that change
 - `.buildline/features/<id>-<slug>/progress.md` — append-only work log so any session can resume
 - `.buildline/context/` — living product, architecture and design knowledge (update it when you ship)
@@ -45,4 +45,6 @@ A task only gets `"passes": true` after the gates pass **and** its own verificat
 5. **Respect the autonomy level** (`autonomy` in `buildline.json`): pause for human approval where the station playbook says to.
 6. **Small, reversible steps.** Prefer many small commits over one large one. Match the existing code style.
 7. **Ask, don't guess,** when the spec is ambiguous about user-facing behaviour.
-8. **Respect model routing.** `models` in `buildline.json` can send a station to another tool (e.g. `"review": "codex"`). If a station is routed to a different CLI than the one you are, hand it off with `npx buildline step <station> <id> --headless` and summarise the result instead of doing it yourself.
+8. **Record state with the feature script.** `node .buildline/bin/feature.mjs move|task|log|block|approve …` stamps real times, keeps the history the team watches live, and refuses moves that skip a required approval. Never edit `feature.json` by hand.
+9. **Mark it blocked before you ask.** When you need an answer from a person, run `node .buildline/bin/feature.mjs block <id> "<the question>"`, then ask. When they answer, run `node .buildline/bin/feature.mjs unblock <id>` and carry on.
+10. **Respect model routing.** `models` in `buildline.json` can send a station to another tool (e.g. `"review": "codex"`). If a station is routed to a different CLI than the one you are, hand it off with `npx buildline step <station> <id> --headless` and summarise the result instead of doing it yourself.

package/templates/bin/feature.mjs

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+// Feature state for the factory. Managed by buildline. Zero dependencies.
+//
+// Agents record progress through this script instead of editing feature.json by
+// hand: it stamps real times, keeps history, and refuses moves that skip a human
+// approval the autonomy level requires.
+//
+//   node .buildline/bin/feature.mjs new "<title>" [--type fix|feature|epic] [--parent <id>]
+//   node .buildline/bin/feature.mjs show <id>
+//   node .buildline/bin/feature.mjs move <id> <station> [--note "…"]
+//   node .buildline/bin/feature.mjs task <id> add "<title>" [--verify "…"] [--covers R1,A2] [--parallel]
+//   node .buildline/bin/feature.mjs task <id> <T1> pass|fail [--note "what you ran and saw"]
+//   node .buildline/bin/feature.mjs log <id> "<note>"
+//   node .buildline/bin/feature.mjs block <id> "<question or reason>"
+//   node .buildline/bin/feature.mjs unblock <id> [--note "…"]
+//   node .buildline/bin/feature.mjs approve <id> <spec|design|plan> --by "<name>"   (only when that person said yes)
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+export const STATIONS = ['new', 'spec', 'design', 'plan', 'build', 'verify', 'review', 'ship', 'done'];
+const TYPES = ['fix', 'feature', 'epic'];
+const STAGES = ['spec', 'design', 'plan'];
+const now = () => new Date().toISOString();
+
+/** Approvals a feature needs before it may leave a station, by autonomy level. Fixes need none. */
+export function requiredApproval(station, autonomy, type) {
+  if (type === 'fix') return null;
+  if (station === 'spec' && autonomy <= 3) return 'spec';
+  if (station === 'design' && autonomy <= 1) return 'design';
+  if (station === 'plan' && autonomy <= 2) return 'plan';
+  return null;
+}
+
+/** Why moving `feature` to `to` isn't allowed yet, or null. Moving back is always allowed. */
+export function moveBlocker(feature, to, autonomy) {
+  const from = STATIONS.indexOf(feature.status);
+  const target = STATIONS.indexOf(to);
+  if (target < 0) return `Unknown station "${to}". Use one of: ${STATIONS.join(', ')}.`;
+  for (let i = Math.max(from, 0); i < target; i++) {
+    const stage = requiredApproval(STATIONS[i], autonomy, feature.type);
+    if (stage && !feature.approvals?.[stage]) {
+      return (
+        `${feature.id} needs ${stage} approval before it can leave "${STATIONS[i]}" (autonomy L${autonomy}). ` +
+        `Ask the person: "Approve the ${stage}?". If they say yes in this conversation, record it with ` +
+        `node .buildline/bin/feature.mjs approve ${feature.id} ${stage} --by "<their name>". ` +
+        `They can also approve in npx buildline ui or npx buildline watch. Leave the status where it is until then.`
+      );
+    }
+  }
+  return null;
+}
+
+export function featuresDir(root) {
+  return path.join(root, '.buildline', 'features');
+}
+
+export function findFeatureDir(root, ref) {
+  const dir = featuresDir(root);
+  if (!fs.existsSync(dir)) return null;
+  const r = String(ref ?? '').toLowerCase();
+  const dirs = fs.readdirSync(dir).filter((d) => /^\d{3,}-/.test(d) && fs.existsSync(path.join(dir, d, 'feature.json')));
+  const hit = dirs.find((d) => d.split('-')[0] === r.padStart(3, '0')) || dirs.find((d) => d === r) || dirs.find((d) => d.includes(r));
+  return hit ? path.join(dir, hit) : null;
+}
+
+export function load(root, ref) {
+  const dir = findFeatureDir(root, ref);
+  if (!dir) throw new Error(`No feature "${ref}" in .buildline/features.`);
+  return { dir, data: JSON.parse(fs.readFileSync(path.join(dir, 'feature.json'), 'utf8')) };
+}
+
+export function save({ dir, data }) {
+  data.updated = now();
+  fs.writeFileSync(path.join(dir, 'feature.json'), JSON.stringify(data, null, 2) + '\n');
+}
+
+const autonomyOf = (root) => {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, '.buildline', 'buildline.json'), 'utf8')).autonomy ?? 2;
+  } catch {
+    return 2;
+  }
+};
+const record = (data, station, note) => (data.history = [...(data.history || []), { at: now(), station, note }]);
+
+export function move(root, ref, to, { note, force = false } = {}) {
+  const f = load(root, ref);
+  const blocker = force ? null : moveBlocker(f.data, to, autonomyOf(root));
+  if (blocker) throw new Error(blocker);
+  const from = f.data.status;
+  if (['verify', 'review'].includes(from) && to === 'build') f.data.metrics = { ...f.data.metrics, reworks: (f.data.metrics?.reworks || 0) + 1 };
+  if (to === 'done') f.data.metrics = { ...f.data.metrics, shippedAt: now() };
+  f.data.status = to;
+  f.data.blocked = null;
+  record(f.data, to, note || `Moved from ${from} to ${to}`);
+  save(f);
+  return f.data;
+}
+
+export function approve(root, ref, stage, by) {
+  if (!STAGES.includes(stage)) throw new Error(`Approval stage must be one of: ${STAGES.join(', ')}`);
+  if (!by) throw new Error('Say who approved: --by "<name>". Only record an approval the person gave you.');
+  const f = load(root, ref);
+  f.data.approvals = { ...f.data.approvals, [stage]: { by, at: now() } };
+  record(f.data, stage, `${stage} approved by ${by}`);
+  save(f);
+  return f.data;
+}
+
+export function addTask(root, ref, title, { verify, covers, parallel } = {}) {
+  if (!title) throw new Error('A task needs a title.');
+  const f = load(root, ref);
+  const tasks = f.data.tasks || [];
+  const n = tasks.reduce((m, t) => Math.max(m, parseInt(String(t.id).replace(/\D/g, ''), 10) || 0), 0) + 1;
+  const task = { id: `T${n}`, title, ...(covers ? { covers: String(covers).split(',').map((s) => s.trim()).filter(Boolean) } : {}), ...(verify ? { verify } : {}), ...(parallel ? { parallel: true } : {}), passes: false, notes: '' };
+  f.data.tasks = [...tasks, task];
+  save(f);
+  return task;
+}
+
+export function setTask(root, ref, id, passes, note) {
+  const f = load(root, ref);
+  const task = (f.data.tasks || []).find((t) => String(t.id).toLowerCase() === String(id).toLowerCase());
+  if (!task) throw new Error(`${f.data.id} has no task ${id}. Tasks: ${(f.data.tasks || []).map((t) => t.id).join(', ') || 'none yet'}.`);
+  task.passes = passes;
+  if (note) task.notes = note;
+  record(f.data, f.data.status, `${task.id} ${passes ? 'passes' : 'fails'}${note ? `: ${note}` : ''}`);
+  save(f);
+  return task;
+}
+
+export function log(root, ref, note) {
+  if (!note) throw new Error('Nothing to log.');
+  const f = load(root, ref);
+  record(f.data, f.data.status, note);
+  save(f);
+}
+
+export function block(root, ref, reason) {
+  if (!reason) throw new Error('Say what you need: block <id> "<question or reason>".');
+  const f = load(root, ref);
+  f.data.blocked = reason;
+  record(f.data, f.data.status, `Blocked: ${reason}`);
+  save(f);
+}
+
+export function unblock(root, ref, note) {
+  const f = load(root, ref);
+  f.data.blocked = null;
+  record(f.data, f.data.status, note ? `Unblocked: ${note}` : 'Unblocked');
+  save(f);
+}
+
+const slugify = (title) =>
+  title.toLowerCase().normalize('NFKD').replace(/[̀-ͯ]/g, '').replace(/[^a-z0-9]+/g, ' ').trim().split(/\s+/).slice(0, 5).join('-') || 'feature';
+
+export function create(root, title, { type = 'feature', parent = null, owner = null, templates } = {}) {
+  if (!title?.trim()) throw new Error('A feature needs a title.');
+  if (!TYPES.includes(type)) throw new Error(`Type must be one of: ${TYPES.join(', ')}`);
+  const base = featuresDir(root);
+  fs.mkdirSync(base, { recursive: true });
+  const next = fs.readdirSync(base).reduce((m, d) => Math.max(m, /^\d{3,}-/.test(d) ? parseInt(d, 10) : 0), 0) + 1;
+  const id = String(next).padStart(3, '0');
+  const slug = slugify(title);
+  const dir = path.join(base, `${id}-${slug}`);
+  fs.mkdirSync(dir, { recursive: true });
+  const at = now();
+  const data = {
+    id, slug, title: title.trim(), type, status: type === 'fix' ? 'build' : 'spec', owner, parent, blocked: null,
+    approvals: {}, tasks: [], metrics: { reworks: 0, createdAt: at, shippedAt: null },
+    history: [{ at, station: 'new', note: `Opened as ${type}` }], created: at, updated: at,
+  };
+  fs.writeFileSync(path.join(dir, 'feature.json'), JSON.stringify(data, null, 2) + '\n');
+  const vars = { id, title: data.title, type, date: at.slice(0, 10) };
+  for (const name of ['spec.md', 'progress.md']) {
+    const local = path.join(root, '.buildline', 'templates', name);
+    const source = fs.existsSync(local) ? local : templates && path.join(templates, name);
+    const text = source && fs.existsSync(source) ? fs.readFileSync(source, 'utf8') : `# ${data.title}\n`;
+    fs.writeFileSync(path.join(dir, name), text.replace(/\{\{(\w+)\}\}/g, (m, k) => (k in vars ? vars[k] : m)));
+  }
+  return { ...data, dir };
+}
+
+// ---- command line --------------------------------------------------------------
+
+function parse(argv) {
+  const pos = [];
+  const opts = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const val = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : true;
+      opts[key] = val;
+    } else pos.push(a);
+  }
+  return { pos, opts };
+}
+
+function summary(d) {
+  const tasks = d.tasks || [];
+  return `${d.id} ${d.title} · ${d.status}${d.blocked ? ` · BLOCKED: ${d.blocked}` : ''} · ${tasks.filter((t) => t.passes).length}/${tasks.length} tasks`;
+}
+
+function main(argv) {
+  const root = process.env.BUILDLINE_ROOT || path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+  const { pos, opts } = parse(argv);
+  const [cmd, ref, ...rest] = pos;
+  switch (cmd) {
+    case 'new': {
+      const f = create(root, [ref, ...rest].join(' '), { type: opts.type, parent: opts.parent, owner: opts.owner });
+      return console.log(`✔ created ${path.relative(root, f.dir)} · status ${f.status}`);
+    }
+    case 'show':
+      return console.log(JSON.stringify(load(root, ref).data, null, 2));
+    case 'move':
+      return console.log('✔ ' + summary(move(root, ref, rest[0], { note: opts.note, force: !!opts.force })));
+    case 'approve':
+      return console.log('✔ ' + summary(approve(root, ref, rest[0], opts.by)));
+    case 'task': {
+      if (rest[0] === 'add') {
+        const t = addTask(root, ref, rest.slice(1).join(' '), opts);
+        return console.log(`✔ ${t.id} added: ${t.title}`);
+      }
+      const [id, verdict] = rest;
+      if (!['pass', 'fail'].includes(verdict)) throw new Error('Usage: task <id> <T1> pass|fail [--note "…"]');
+      const t = setTask(root, ref, id, verdict === 'pass', opts.note);
+      return console.log(`✔ ${t.id} ${t.passes ? 'passes' : 'fails'} · ${summary(load(root, ref).data)}`);
+    }
+    case 'log':
+      log(root, ref, rest.join(' '));
+      return console.log('✔ logged');
+    case 'block':
+      block(root, ref, rest.join(' '));
+      return console.log(`✔ ${ref} marked blocked. Tell the person what you need; run unblock when they answer.`);
+    case 'unblock':
+      unblock(root, ref, opts.note);
+      return console.log(`✔ ${ref} unblocked`);
+    default:
+      console.log(fs.readFileSync(fileURLToPath(import.meta.url), 'utf8').split('\n').slice(1, 17).map((l) => l.replace(/^\/\/ ?/, '')).join('\n'));
+      if (cmd) process.exitCode = 1;
+  }
+}
+
+const invoked = () => {
+  try {
+    return import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href;
+  } catch {
+    return false;
+  }
+};
+if (process.argv[1] && invoked()) {
+  try {
+    main(process.argv.slice(2));
+  } catch (err) {
+    console.error(`✘ ${err.message}`);
+    process.exitCode = 1;
+  }
+}

package/templates/bin/hook.mjs

@@ -2,8 +2,14 @@
 // Claude Code hooks for the factory. Managed by buildline.
 //
 //   session-start  prints a short factory briefing into the new session's context
+//   pre            before each tool call: the guards below, plus a session heartbeat
 //   guard          blocks edits to a spec's "## Acceptance" section while the
-//                  feature is in build/verify/review, so agents can't move the goalposts
+//                  feature is in build/verify/review, so agents can't move the goalposts,
+//                  and hand edits to feature.json (agents use .buildline/bin/feature.mjs)
+//   prompt / stop / session-end
+//                  heartbeat: which session works on which feature, so
+//                  `buildline watch` and the dashboard can show live work.
+//                  Written to .buildline/sessions/ (git-ignored).
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -11,6 +17,7 @@ import { fileURLToPath } from 'node:url';
 const root = process.env.CLAUDE_PROJECT_DIR || path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 const featuresDir = path.join(root, '.buildline', 'features');
 const mode = process.argv[2];
+const sessionsDir = path.join(root, '.buildline', 'sessions');
 
 function readJson(file) {
   try {
@@ -48,10 +55,22 @@ const acceptance = (text) => {
   return m ? m[1].trim() : null;
 };
 
+const deny = (msg) => {
+  process.stderr.write(msg + '\n');
+  process.exit(2);
+};
+
 function guard(input) {
   const tool = input.tool_name;
   const ti = input.tool_input || {};
   const file = ti.file_path ? path.resolve(root, ti.file_path) : null;
+  const viaScript = 'Use node .buildline/bin/feature.mjs instead (move, task, log, block, approve); run it with no arguments for usage. It records real times and checks approvals.';
+  if (file && file.startsWith(featuresDir + path.sep) && path.basename(file) === 'feature.json' && fs.existsSync(file)) {
+    deny(`buildline guard: don't edit ${path.relative(root, file)} by hand. ${viaScript}`);
+  }
+  if (tool === 'Bash' && /feature\.json/.test(ti.command || '') && !/feature\.mjs/.test(ti.command || '') && /(>|sed\s+-i|writeFile|json\.dump|\btee\b|perl\s+-[a-z]*i)/.test(ti.command || '')) {
+    deny(`buildline guard: don't write feature.json from the shell. ${viaScript}`);
+  }
   if (!file || !file.startsWith(featuresDir + path.sep) || path.basename(file) !== 'spec.md') return;
 
   const feature = readJson(path.join(path.dirname(file), 'feature.json'));
@@ -63,7 +82,9 @@ function guard(input) {
   else if (tool === 'Edit') after = before.replace(ti.old_string ?? '', ti.new_string ?? '');
   else if (Array.isArray(ti.edits)) for (const e of ti.edits) after = after.replace(e.old_string ?? '', e.new_string ?? '');
 
-  if (acceptance(before) !== acceptance(after)) {
+  // An acceptance section still holding the template's TODO may be filled in (fixes start at build).
+  const unfilled = /\bTODO\b/.test(acceptance(before) ?? 'TODO');
+  if (!unfilled && acceptance(before) !== acceptance(after)) {
     process.stderr.write(
       `buildline guard: "## Acceptance" in ${path.relative(root, file)} is locked while the feature is in "${feature.status}". ` +
         'If a scenario is wrong, stop and ask the spec owner; they can change it at the spec station.\n',
@@ -72,6 +93,66 @@ function guard(input) {
   }
 }
 
+// ---- heartbeat -------------------------------------------------------------------
+
+/** The feature a prompt or tool call is about, e.g. "/buildline-build 3" or a path under features/003-…. */
+function featureRef(text) {
+  const s = String(text || '');
+  const m =
+    /\.buildline\/features\/(\d{3,})-/.exec(s) ||
+    /feature\.mjs\s+(?:move|task|log|block|unblock|approve|show)\s+(\d{1,4})\b/.exec(s) ||
+    /\/buildline(?:-[a-z]+)?\s+(\d{1,4})\b/.exec(s) ||
+    /buildline\s+(?:step\s+[a-z]+|run|approve|move)\s+(\d{1,4})\b/.exec(s);
+  return m ? m[1].padStart(3, '0') : null;
+}
+
+function detail(input) {
+  const ti = input.tool_input || {};
+  if (ti.file_path) return path.basename(ti.file_path);
+  if (ti.command) {
+    // Short and readable: drop heredoc bodies and the long feature folder paths.
+    const cmd = String(ti.command).split(/<<|\n/)[0].replace(/\.buildline\/features\/[^/\s]+\//g, '').replace(/\s+/g, ' ').trim();
+    return cmd.length > 48 ? cmd.slice(0, 47) + '…' : cmd;
+  }
+  if (ti.pattern) return String(ti.pattern).slice(0, 40);
+  if (ti.description) return String(ti.description).slice(0, 60);
+  return '';
+}
+
+function heartbeat(input, event) {
+  const id = String(input.session_id || '').replace(/[^\w-]/g, '');
+  if (!id) return;
+  fs.mkdirSync(sessionsDir, { recursive: true });
+  const ignore = path.join(sessionsDir, '.gitignore');
+  if (!fs.existsSync(ignore)) fs.writeFileSync(ignore, '*\n');
+  const file = path.join(sessionsDir, `${id}.json`);
+  if (event === 'end') return fs.rmSync(file, { force: true });
+  const at = new Date().toISOString();
+  const prev = readJson(file) || { id, startedAt: at };
+  const prompt = input.prompt || '';
+  const station = /\/buildline-([a-z]+)/.exec(prompt)?.[1];
+  const ti = input.tool_input || {};
+  // A session stays on the feature it was started for; reading another feature's files doesn't move it.
+  const feature = featureRef(prompt) || prev.feature || featureRef(ti.file_path) || featureRef(ti.command) || featureRef(ti.prompt) || null;
+  const next = {
+    ...prev,
+    feature,
+    station: station || prev.station || null,
+    model: input.model?.id || input.model || prev.model || null,
+    state: event === 'stop' ? 'waiting' : 'working',
+    lastAt: at,
+    ...(event === 'tool' ? { tool: input.tool_name, detail: detail(input) } : {}),
+    ...(event === 'prompt' ? { tool: null, detail: prompt.replace(/\s+/g, ' ').slice(0, 60) } : {}),
+  };
+  fs.writeFileSync(file, JSON.stringify(next, null, 2) + '\n');
+  if (event === 'tool' && feature) {
+    // A short live activity feed for the views; trimmed so it never grows large.
+    const feed = path.join(sessionsDir, 'activity.jsonl');
+    fs.appendFileSync(feed, JSON.stringify({ at, session: id.slice(0, 8), feature, tool: input.tool_name, detail: next.detail }) + '\n');
+    if (fs.statSync(feed).size > 200_000) fs.writeFileSync(feed, fs.readFileSync(feed, 'utf8').split('\n').slice(-500).join('\n'));
+  }
+}
+
 let raw = '';
 process.stdin.on('data', (c) => (raw += c));
 process.stdin.on('end', () => {
@@ -80,8 +161,12 @@ process.stdin.on('end', () => {
     input = raw ? JSON.parse(raw) : {};
   } catch {}
   try {
-    if (mode === 'session-start') sessionStart();
+    if (mode === 'session-start') sessionStart(), heartbeat(input, 'start');
     else if (mode === 'guard') guard(input);
+    else if (mode === 'pre') heartbeat(input, 'tool'), guard(input);
+    else if (mode === 'prompt') heartbeat(input, 'prompt');
+    else if (mode === 'stop') heartbeat(input, 'stop');
+    else if (mode === 'session-end') heartbeat(input, 'end');
   } catch (err) {
     // A broken hook must never break the session.
     process.stderr.write(`buildline hook error: ${err.message}\n`);

package/templates/stations/autopilot.md

@@ -33,7 +33,7 @@ Stop and summarise instead of continuing if:
 - the change needs a secret, a paid service, a production system or a destructive action,
 - `metrics.reworks` reaches 5 (the spec or plan probably needs a human).
 
-Write the blocker to `progress.md` and set `feature.json → blocked` to a one-line reason.
+Write the blocker to `progress.md` and run `node .buildline/bin/feature.mjs block <id> "<one-line reason>"` so the board shows it waiting on a person.
 
 ## Running it with `/goal` (Claude Code)
 

package/templates/stations/build.md

@@ -16,7 +16,10 @@ Resolve the feature from `$ARGUMENTS`, or use the most recent feature with statu
 3. Read `spec.md`: Requirements, Acceptance, Design, Plan.
 4. Run `node .buildline/bin/gates.mjs`. If gates fail **before** you change anything, record it in `progress.md` and fix or report it first. Don't stack new work on a red baseline.
 
-For `fix` features with no tasks: create a single task `T1` ("Reproduce with a failing test, then fix") plus `T2` ("Gates pass and A1 verified").
+For `fix` features:
+
+- If `## Brief` or `## Acceptance` in `spec.md` still say TODO, fill them in yourself from the title and the code: a one-line brief and one scenario that reproduces the bug. Fixes don't wait for a PM. Only if you can't tell what correct looks like (for example, which currency to show), block with the question (see "Asking for help").
+- With no tasks yet, add two: `node .buildline/bin/feature.mjs task <id> add "Reproduce with a failing test, then fix"` and `node .buildline/bin/feature.mjs task <id> add "Gates pass and A1 verified"`.
 
 ## 2. Work the next task
 
@@ -26,14 +29,20 @@ Pick the first task with `"passes": false`.
 2. Implement the smallest change that makes it pass. Follow the conventions in `.buildline/context/architecture.md` and reuse existing components and utilities before making new ones.
 3. Run the task's `verify` step **and** the gates. Read the output; don't assume.
 4. For UI work, run the app and look at it (a screenshot via the browser tools if available). Check the states listed in the design.
-5. Only when everything above is green, set `"passes": true` and write in `notes` what you ran and what you observed (one or two lines).
+5. Only when everything above is green, record it: `node .buildline/bin/feature.mjs task <id> T2 pass --note "<what you ran and what you saw>"`.
 6. Commit with a clear message, e.g. `feat(saved-carts): add model and migration [004/T1]`.
 
-If you get stuck on the same task after two genuinely different attempts, stop: write what you tried in `progress.md`, set `notes` on the task, and ask for help. Don't thrash.
+## Asking for help
+
+If you get stuck on the same task after two genuinely different attempts, or you need a decision only a person can make, stop. Don't thrash or guess:
+
+1. Write what you tried in `progress.md`.
+2. `node .buildline/bin/feature.mjs block <id> "<the question, in one line>"` so the board shows the feature waiting on a person.
+3. Ask the question. When it's answered, `node .buildline/bin/feature.mjs unblock <id> --note "<the answer>"` and carry on.
 
 ## 3. Hard rules
 
-- Never edit `## Acceptance` in `spec.md`, never delete or weaken a test to make it pass, never disable a gate. If you believe the spec or a test is wrong, stop and explain.
+- Never change a filled-in `## Acceptance` in `spec.md` (a fix may fill in an empty one), never delete or weaken a test to make it pass, never disable a gate. If you believe the spec or a test is wrong, stop and explain.
 - Never mark a task as passing without running its verification in this session.
 - Stay inside the feature's scope. Note unrelated problems you find in `progress.md` under "Noticed" instead of fixing them.
 - Don't commit secrets, generated artefacts or debugging leftovers.
@@ -49,4 +58,4 @@ Append to `progress.md`:
 - Next: T3 (UI list); watch out for the cart total rounding in utils/money.ts
 ```
 
-When every task passes: set status to `verify`, append a `history` entry, and continue with `/buildline-verify <id>` (or tell the person to).
+When every task passes: `node .buildline/bin/feature.mjs move <id> verify --note "<n>/<n> tasks pass"` and continue with `/buildline-verify <id>` (or tell the person to).

package/templates/stations/design.md

@@ -34,6 +34,6 @@ Follow the conventions in `architecture.md`. If you're breaking one, say so expl
 
 ## Handoff
 
-- Set status to `plan`. Append a `history` entry.
-- **Approval:** at autonomy L1, ask for explicit design approval and record `approvals.design` only when given. At other levels, the designer can approve UX in the dashboard; flag the feature as waiting for design approval if UX changed and nobody has approved it yet.
+- **Approval:** at autonomy L1, ask for explicit design approval and record it only when given: `node .buildline/bin/feature.mjs approve <id> design --by "<their name>"`.
+- Then `node .buildline/bin/feature.mjs move <id> plan --note "<one line>"`. At other levels, the designer can approve UX in the dashboard; flag the feature as waiting for design approval if UX changed and nobody has approved it yet.
 - Next: `/buildline-plan <id>`.

package/templates/stations/new.md

@@ -24,16 +24,14 @@ State the type and the reason in one line. The person can override.
 
 ## 3. Create the feature
 
-Preferred: run `npx buildline new "<title>" --type <type>`. It creates `.buildline/features/<id>-<slug>/` with `feature.json`, `spec.md` and `progress.md`.
+Run `node .buildline/bin/feature.mjs new "<title>" --type <type>` (add `--owner "<name>"` if the person told you who owns it). It creates `.buildline/features/<id>-<slug>/` with `feature.json`, `spec.md` and `progress.md`, and sets the starting status: `build` for a fix, `spec` otherwise.
 
-If the CLI isn't available, do it by hand: next id = highest existing id + 1, zero-padded to 3 digits; slug = kebab-case title (max 5 words); copy the files from `.buildline/templates/`.
-
-Then fill in `spec.md → ## Brief` (problem, who, outcome, open questions) and set `owner` in `feature.json` if the person told you who owns it.
+Then fill in `spec.md → ## Brief` (problem, who, outcome, open questions).
 
 ## 4. Route
 
-- `fix` → set status to `build`. In `spec.md`, also fill `## Acceptance` with a single scenario that reproduces the bug (it must fail before the fix). Next: `/buildline-build <id>`.
-- `feature` → status `spec`. Next: `/buildline-spec <id>`.
-- `epic` → status `spec`. Next: `/buildline-spec <id>`, which will end by proposing the split into child features.
+- `fix` → it starts at `build`. In `spec.md`, also fill `## Acceptance` with a single scenario that reproduces the bug (it must fail before the fix). Next: `/buildline-build <id>`.
+- `feature` → it starts at `spec`. Next: `/buildline-spec <id>`.
+- `epic` → it starts at `spec`. Next: `/buildline-spec <id>`, which will end by proposing the split into child features.
 
-Append a `history` entry to `feature.json`: `{ "at": "<ISO date>", "station": "new", "note": "<type and one-line reason>" }`.
+Record why: `node .buildline/bin/feature.mjs log <id> "<type and one-line reason>"`.

package/templates/stations/plan.md

@@ -6,19 +6,14 @@ Resolve the feature from `$ARGUMENTS`, or use the most recent feature with statu
 
 ## Write the tasks
 
-Write them into `feature.json → tasks` (replace the placeholder):
-
-```json
-{
-  "id": "T1",
-  "title": "Add `saved_carts` table and model",
-  "covers": ["R1", "A2"],
-  "verify": "`npm test -- saved-cart.model` passes; migration runs up and down",
-  "passes": false,
-  "notes": ""
-}
+Add them in order, one command per task (ids T1, T2, … are assigned for you):
+
+```bash
+node .buildline/bin/feature.mjs task <id> add "Add saved_carts table and model" --covers R1,A2 --verify "npm test -- saved-cart.model passes; migration runs up and down"
 ```
 
+Add `--parallel` to tasks that could run alongside the previous one.
+
 Rules:
 
 - **Small**: each task fits in one focused session and one commit, usually under ~200 changed lines.
@@ -26,7 +21,7 @@ Rules:
 - **Verifiable**: `verify` says exactly what to run or observe. "Works" is not a verification.
 - **Traceable**: `covers` lists the requirement and acceptance ids it moves forward. Every `A*` scenario must be covered by at least one task.
 - **Test-first where it's cheap**: when a task introduces logic, its first step is a failing test for the acceptance scenario.
-- **Ordered**: dependencies come first. Mark tasks that could run in parallel with `"parallel": true`.
+- **Ordered**: dependencies come first. Mark tasks that could run in parallel with `--parallel`.
 - Include the boring tasks: migrations, feature flags, docs, analytics events, cleanup of temporary code.
 
 Then write a one-paragraph `## Plan` summary in `spec.md` (approach, order, risks) so humans don't have to read JSON.
@@ -39,6 +34,6 @@ Then write a one-paragraph `## Plan` summary in `spec.md` (approach, order, risk
 
 ## Handoff
 
-- Set status to `build`. Append a `history` entry.
-- **Approval:** at autonomy ≤ 2, ask the person to approve the plan and record `approvals.plan` only on an explicit yes. At L3+, continue without waiting.
+- **Approval:** at autonomy ≤ 2, ask the person to approve the plan and record it only on an explicit yes: `node .buildline/bin/feature.mjs approve <id> plan --by "<their name>"`. Until then the feature stays at `plan`. At L3+, continue without waiting.
+- Then `node .buildline/bin/feature.mjs move <id> build --note "<n> tasks"`.
 - Next: `/buildline-build <id>`, or `/buildline-autopilot <id>` to run build → verify → review unattended.

package/templates/stations/review.md

@@ -34,4 +34,4 @@ Write `## Review` in `spec.md`: a summary of what changed and why, risk areas to
 
 ## 5. Route
 
-When there are no open blockers or should-fix findings: status `ship`, history entry, next `/buildline-ship <id>`. A human still approves the merge at every autonomy level.
+Blockers and should-fix findings become tasks (`node .buildline/bin/feature.mjs task <id> add "…"`) and the feature goes back with `node .buildline/bin/feature.mjs move <id> build --note "<n> findings"`. When there are none: `node .buildline/bin/feature.mjs move <id> ship --note "review clean"`, next `/buildline-ship <id>`. A human still approves the merge at every autonomy level.

package/templates/stations/ship.md

@@ -27,6 +27,6 @@ Specs are written for one change; the context files carry what lasts. Update the
 
 ## 4. Close
 
-- Set status to `done`, fill `metrics.shippedAt`, append a `history` entry with the PR link.
+- `node .buildline/bin/feature.mjs move <id> done --note "<PR link>"` (this records the ship date).
 - Append a final `progress.md` entry.
 - Suggest the next feature in the queue (`/buildline`).

package/templates/stations/spec.md

@@ -41,6 +41,7 @@ If `type` is `epic`, end by proposing 2–6 child features, each a thin, shippab
 
 ## 6. Approval and handoff
 
-- Set status to `design` (or `plan` if the change has no UX or architecture decisions; say why).
-- **Approval:** the spec needs human approval when autonomy ≤ 3. Ask: "Approve this spec?" Only when the person explicitly approves, record `approvals.spec = { "by": "<name or role>", "at": "<ISO date>" }`. Never record an approval on someone's behalf. They can also approve from `npx buildline ui` or with `npx buildline approve <id> spec`.
-- Append a `history` entry and suggest the next command.
+- **Approval:** the spec needs human approval when autonomy ≤ 3. Ask: "Approve this spec?" Only when the person explicitly approves, record it: `node .buildline/bin/feature.mjs approve <id> spec --by "<their name>"`. Never record an approval on someone's behalf. They can also approve in `npx buildline ui` or `npx buildline watch`. Until then the feature stays at `spec` and the board shows it waiting on them.
+- Once approved (or at L4), move on: `node .buildline/bin/feature.mjs move <id> design --note "<one line>"`, or `plan` if the change has no UX or architecture decisions (say why). The script refuses the move while a required approval is missing.
+- Record what happened: `node .buildline/bin/feature.mjs log <id> "spec drafted, waiting for approval"` (or what changed).
+- Suggest the next command.

package/templates/stations/verify.md

@@ -40,5 +40,5 @@ Save screenshots and logs to `.buildline/features/<id>-<slug>/evidence/`.
 
 ## 4. Route
 
-- All pass → status `review`, history entry, next `/buildline-review <id>`.
-- Any fail → status back to `build`. For each failure, add a new task to `feature.json` (`"title": "Fix A3: empty state copy"`, `"covers": ["A3"]`, `"passes": false`) and increment `metrics.reworks` in `feature.json`. Next: `/buildline-build <id>`.
+- All pass → `node .buildline/bin/feature.mjs move <id> review --note "A1–A<n> pass"`. Next: `/buildline-review <id>`.
+- Any fail → for each failure, `node .buildline/bin/feature.mjs task <id> add "Fix A3: empty state copy" --covers A3`, then `node .buildline/bin/feature.mjs move <id> build --note "<n> scenarios fail"` (this counts a rework). Next: `/buildline-build <id>`.