buildline 0.6.0 → 0.8.0

package/README.md

@@ -134,10 +134,11 @@ 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 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
+- 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, permission or reply; **BACKGROUND** means it's waiting on something else, such as CI or a background agent, and will carry on by itself
 - 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
+- `↑↓` to inspect tasks and history, `⏎` to open the station on its model, `a` to approve, `e` to hide the event log, `q` to quit
+- a **chime** when a feature starts waiting on you or ships, so you can look away; `m` mutes it, `npx buildline sound off` turns it off for good (the dashboard chimes too)
 
 ## The dashboard
 
@@ -196,6 +197,7 @@ npx buildline watch                  live view of the line in the terminal
 npx buildline step <station> [id]    open a station on its model  --headless --model
 npx buildline models                 choose models  set <station|phase> <model> · check
 npx buildline run <id>               autopilot with Claude Code /goal  --headless
+npx buildline sound [on|off]         chime when a feature needs you or ships
 npx buildline gates                  run quality gates
 npx buildline doctor                 check the setup
 npx buildline update                 refresh managed files, keep your edits

package/bin/buildline.js

@@ -18,10 +18,11 @@ ${pc.bold('Commands')}
   ${pc.cyan('new')} "<title>"            open a feature  ${pc.dim('--type fix|feature|epic  --owner <name>  --parent <id>')}
   ${pc.cyan('approve')} <id> <stage>     record a human approval (spec | design | plan)  ${pc.dim('--by <name>')}
   ${pc.cyan('move')} <id> <station>      move a feature to a station  ${pc.dim('--note "<why>"')}
-  ${pc.cyan('watch')}                    live view of the line in your terminal  ${pc.dim('--shipped  --once  --no-intro')}
-  ${pc.cyan('ui')}                       open the dashboard in your browser  ${pc.dim('--port <n>  --no-open')}
+  ${pc.cyan('watch')}                    live view of the line in your terminal  ${pc.dim('--shipped  --once  --no-intro  --quiet')}
+  ${pc.cyan('ui')}                       open the dashboard in your browser  ${pc.dim('--port <n>  --no-open  --quiet')}
   ${pc.cyan('step')} <station> [id]      open a station in the CLI and model set for it  ${pc.dim('--model <m>  --headless  --print')}
   ${pc.cyan('models')}                   choose models per station  ${pc.dim('set <station|phase> <model> · check')}
+  ${pc.cyan('sound')} [on|off]           chime when a feature needs you or ships (watch and dashboard)
   ${pc.cyan('run')} [id]                 autopilot: build → verify → review with Claude Code /goal  ${pc.dim('--headless  --print')}
   ${pc.cyan('gates')} [names...]         run the quality gates
   ${pc.cyan('doctor')}                   check the setup
@@ -75,13 +76,14 @@ const { values: opts, positionals } = parseArgs({
     once: { type: 'boolean' },
     shipped: { type: 'boolean' },
     'no-intro': { type: 'boolean' },
+    quiet: { type: 'boolean', short: 'q' },
     help: { type: 'boolean', short: 'h' },
     version: { type: 'boolean', short: 'v' },
   },
 });
 
 const root = path.resolve(opts.cwd || process.cwd());
-const o = { ...opts, dryRun: opts['dry-run'], ci: opts['no-ci'] ? false : opts.ci, open: !opts['no-open'], intro: !opts['no-intro'] };
+const o = { ...opts, dryRun: opts['dry-run'], ci: opts['no-ci'] ? false : opts.ci, open: !opts['no-open'], intro: !opts['no-intro'], sound: !opts.quiet };
 const [cmd, ...rest] = positionals;
 
 async function main() {
@@ -117,6 +119,8 @@ async function main() {
       return cli.models(root, rest, o);
     case 'run':
       return cli.run(root, rest[0], o);
+    case 'sound':
+      return cli.sound(root, rest[0]);
     case 'gates':
       return cli.gates(root, rest);
     case 'doctor':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buildline",
-  "version": "0.6.0",
+  "version": "0.8.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

@@ -8,6 +8,7 @@ import { AGENTS, AUTONOMY, VERSION, makeConfig, plan, apply, removePlan, applyRe
 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, moveBlocker, STATIONS, TYPES } from './features.js';
+import { chime } from './sound.js';
 
 const LOGO = [
   pc.yellow('  ┌┐ ┬ ┬┬┬  ┌┬┐┬  ┬┌┐┌┌─┐'),
@@ -270,6 +271,19 @@ export async function watch(root, opts = {}) {
   if (next?.action === 'ui') return (await import('./server.js')).serve(root, {});
 }
 
+export function sound(root, value) {
+  const config = loadConfig(root);
+  if (value) {
+    if (!['on', 'off'].includes(value)) throw new Error('Usage: buildline sound [on|off]');
+    if (value === 'on') delete config.sound;
+    else config.sound = false;
+    fs.writeFileSync(configPath(root), JSON.stringify(config, null, 2) + '\n');
+  }
+  const on = config.sound !== false;
+  console.log(`${on ? pc.green('♪') : pc.dim('♪')} Sound is ${on ? 'on' : 'off'}: ${on ? '`watch` and the dashboard chime when a feature needs you or ships.' : 'no chime.'} ${pc.dim(on ? 'Turn off: buildline sound off' : 'Turn on: buildline sound on')}`);
+  if (on && value === 'on') chime();
+}
+
 // ---- new / approve / move ----------------------------------------------------
 
 export async function newFeature(root, title, opts) {

package/src/features.js

@@ -181,8 +181,11 @@ export function readSessions(root, at = Date.now()) {
     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 });
+      // How long it has been in this state, and since the session started.
+      const timing = { for: at - new Date(s.since || s.lastAt), total: at - new Date(s.startedAt || s.lastAt) };
+      // A long command (tests, a deploy watch) keeps a session working with no new events.
+      if (s.state === 'working' && age < (s.inTool ? WAITING_FOR : WORKING_FOR)) out.push({ ...s, age, ...timing });
+      else if ((s.state === 'waiting' || s.state === 'background') && age < WAITING_FOR) out.push({ ...s, age, ...timing });
     } catch {}
   }
   return Object.assign(out.sort((a, b) => a.age - b.age), { tracked: true });
@@ -205,17 +208,35 @@ export function readActivity(root, limit = 200) {
 }
 
 /**
- * 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
+ * What's happening on a feature right now: live sessions on it, and whether one
+ * waits on a person (that wins), one is working, or one finished its turn with
+ * work still running in the background (a CI watch, a background agent). 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;
+  const waiting = mine.find((s) => s.state === 'waiting');
   return {
     sessions: mine,
     working: working.length > 0 || (!sessions.tracked && recent && !feature.blocked && feature.status !== 'done'),
-    waiting: !working.length && mine.some((s) => s.state === 'waiting'),
+    waiting: Boolean(waiting),
+    // why: 'reply' | 'question' | 'permission', and what the agent said or asked
+    waitingFor: waiting ? { why: waiting.waitingFor || 'reply', said: waiting.said || null, for: waiting.for } : null,
+    background: !working.length && !waiting ? mine.filter((s) => s.state === 'background').flatMap((s) => s.background || []) : [],
+    backgroundFor: Math.max(0, ...mine.filter((s) => s.state === 'background').map((s) => s.for || 0)),
   };
 }
+
+/** What the chime is for: 'waiting' when a feature needs a person, 'done' once it ships, else null. */
+export function attention(feature, live) {
+  if (feature.status === 'done') return 'done';
+  return feature.blocked || live?.waiting ? 'waiting' : null;
+}
+
+/** Ids whose attention changed to waiting or done since `before` (a Map from the last look). */
+export function newAttention(before, now) {
+  if (!before) return [];
+  return [...now].filter(([id, a]) => a && before.get(id) !== a).map(([id]) => id);
+}

package/src/install.js

@@ -182,6 +182,9 @@ export function mergeSettings(root, config) {
   ensureHook('SessionStart', null, 'session-start');
   ensureHook('PreToolUse', null, 'pre');
   ensureHook('UserPromptSubmit', null, 'prompt');
+  ensureHook('PostToolUse', null, 'post');
+  // Claude asked for permission or input mid-turn: the session waits on a person.
+  ensureHook('Notification', 'permission_prompt|elicitation_dialog', 'notify');
   ensureHook('Stop', null, 'stop');
   ensureHook('SessionEnd', null, 'session-end');
 

package/src/server.js

@@ -33,8 +33,9 @@ function openBrowser(url) {
   } catch {}
 }
 
-function state(root) {
+function state(root, opts = {}) {
   const config = JSON.parse(fs.readFileSync(path.join(root, '.buildline', 'buildline.json'), 'utf8'));
+  if (opts.sound === false) config.sound = false;
   const sessions = readSessions(root);
   const features = listFeatures(root).map(({ path: _p, ...f }) => ({
     ...f,
@@ -89,7 +90,7 @@ export function serve(root, opts = {}) {
       if (!url.pathname.startsWith('/api/')) return send(404, { error: 'Not found' });
       if (req.method !== 'GET' && req.headers['x-buildline-token'] !== token) return send(403, { error: 'Bad token' });
 
-      if (req.method === 'GET' && url.pathname === '/api/state') return send(200, state(root));
+      if (req.method === 'GET' && url.pathname === '/api/state') return send(200, state(root, opts));
 
       if (url.pathname === '/api/file') {
         if (req.method === 'GET') {

package/src/sound.js

@@ -0,0 +1,29 @@
+// The one sound Buildline makes: a short chime when a feature needs a person or
+// ships. Plays the system's own notification sound where there is one, and falls
+// back to the terminal bell. Off with `"sound": false` in buildline.json.
+import fs from 'node:fs';
+import { spawn } from 'node:child_process';
+
+const PLAYERS = {
+  darwin: ['afplay', '/System/Library/Sounds/Glass.aiff'],
+  linux: ['paplay', '/usr/share/sounds/freedesktop/stereo/complete.oga'],
+};
+
+let last = 0;
+
+export function chime(out = process.stdout) {
+  if (Date.now() - last < 3000) return; // several features at once still make one sound
+  last = Date.now();
+  const bell = () => out.write('\x07');
+  const player = PLAYERS[process.platform];
+  if (!player || !fs.existsSync(player[1])) return bell();
+  try {
+    const child = spawn(player[0], [player[1]], { stdio: 'ignore', detached: true });
+    child.on('error', bell);
+    child.unref();
+  } catch {
+    bell();
+  }
+}
+
+export const soundOn = (config) => config?.sound !== false;

package/src/tui.js

@@ -1,13 +1,15 @@
 // `buildline watch`: a live, full-screen view of the line in the terminal.
 // Every feature is a track running through the stations; the dot shows where it
-// is, a moving comet means an agent can work on it, a blinking dot means it waits
+// is, a moving comet means a session is working on it, a turning clock means work
+// runs in the background (CI, a background agent), a blinking dot means it waits
 // on a person. Zero dependencies beyond picocolors: raw ANSI on a cell canvas.
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import pc from 'picocolors';
-import { listFeatures, nextAction, approve, readSessions, readActivity, liveState } from './features.js';
+import { listFeatures, nextAction, approve, readSessions, readActivity, liveState, attention, newAttention } from './features.js';
+import { chime, soundOn } from './sound.js';
 import { modelFor, describeModel } from './models.js';
 import { AUTONOMY, VERSION } from './install.js';
 
@@ -15,6 +17,8 @@ const TRACK = ['spec', 'design', 'plan', 'build', 'verify', 'review', 'ship'];
 const LOGO = ['┌┐ ┬ ┬┬┬  ┌┬┐┬  ┬┌┐┌┌─┐', '├┴┐│ │││   ││││  ││││├┤ ', '└─┘└─┘┴┴─┘─┴┘┴─┘┴┘└┘└─┘'];
 const SPINNER = '⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏';
 const SPARK = ' ▁▂▃▄▅▆▇█';
+const CLOCK = '◴◷◶◵';
+const WAITS = { reply: 'waiting for your reply', question: 'asking you a question', permission: 'waiting for your permission' };
 
 // ---- colour ------------------------------------------------------------------
 
@@ -113,7 +117,8 @@ function loadState(root, showShipped) {
     .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, sessions };
+  const needs = new Map(all.map((f) => [f.id, attention(f, liveState(f, sessions))]));
+  return { config, all, features, events, sessions, needs };
 }
 
 const stationIndex = (status) => (status === 'new' ? 0 : status === 'done' ? TRACK.length : TRACK.indexOf(status));
@@ -121,16 +126,17 @@ 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`);
+const ago = (ms) => (ms < 60e3 ? `${Math.max(1, Math.round(ms / 1000))}s` : ms < 3600e3 ? `${Math.floor(ms / 60e3)}m` : `${Math.floor(ms / 3600e3)}h${Math.floor(ms / 60e3) % 60 ? `${Math.floor(ms / 60e3) % 60}m` : ''}`);
 
 /** 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.waiting) return ['NEEDS YOU', t % 12 < 8 ? C.red : C.faint];
   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.live.background.length) return [`${CLOCK[Math.floor(t / 4) % CLOCK.length]} BACKGROUND`, C.cyan];
   if (f.next.who === 'agent') return ['AGENT', C.amberDim];
   const who = WHO[f.next.who];
   return who ? [who.label, who.color] : ['', null];
@@ -164,7 +170,8 @@ function drawTrack(line, x, f, seg, t) {
   const who = WHO[f.next.who];
   const skipped = (i) => f.type === 'fix' && i < 3 && cur >= 3;
   // The comet only runs while a session is actually working on this feature.
-  const working = f.live?.working && !f.blocked;
+  const working = f.live?.working && !f.blocked && !f.live.waiting;
+  const background = f.live?.background?.length && !f.blocked && !f.live.waiting;
   const idleAgent = f.next.who === 'agent' && !f.blocked && !f.live?.waiting;
   for (let i = 0; i < TRACK.length; i++) {
     const nx = x + i * seg;
@@ -174,6 +181,7 @@ function drawTrack(line, x, f, seg, t) {
     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 && background) node = [CLOCK[Math.floor(t / 4) % CLOCK.length], C.cyan];
     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]);
@@ -206,8 +214,9 @@ 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 = 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;
+  const busy = (f) => f.live.working || f.live.background.length;
+  const waiting = features.filter((f) => f.status !== 'done' && (f.live.waiting || (!busy(f) && ['pm', 'designer', 'eng', 'human'].includes(f.next.who)))).length;
+  const sessionsWorking = st.sessions.filter((x) => x.state !== 'waiting').length;
 
   // header
   const tall = W >= 96 && H >= 26;
@@ -298,13 +307,13 @@ function render(st, ui, W, H) {
   const by = top + lineH;
   const bh = H - 1 - by;
   if (bh >= 5) {
-    const split = W >= 100 ? Math.floor(W * 0.52) : W;
+    const split = W >= 100 && ui.events !== false ? Math.floor(W * 0.52) : W;
     drawInspector(screen, st, sel, 0, by, split, bh);
     if (split < W) drawEvents(screen, st, ui, split, by, W - split, bh);
   }
 
   // footer
-  const keys = [['↑↓', 'select'], ['⏎', 'open'], ['a', 'approve'], ['u', 'dashboard'], ['s', ui.shipped ? 'hide shipped' : 'shipped'], ['q', 'quit']];
+  const keys = [['↑↓', 'select'], ['⏎', 'open'], ['a', 'approve'], ['u', 'dashboard'], ['s', ui.shipped ? 'hide shipped' : 'shipped'], ['e', ui.events === false ? 'events' : 'hide events'], ['m', ui.sound ? 'mute' : 'unmute'], ['q', 'quit']];
   let fx = 1;
   const foot = screen[H - 1];
   if (ui.message && ui.messageUntil > Date.now()) fx = foot.put(1, ` ${ui.message} `, C.flash);
@@ -342,15 +351,23 @@ function drawInspector(screen, st, f, x, y, w, h) {
     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],
-    );
+    // "● c41c8a97 opus-5-5  working 4m · up 1h12m", then what it's doing or waiting for.
+    const model = (ses.model ? String(ses.model) : shortModel(config, f.status)).replace(/^claude-/, '');
+    const up = ses.total - (ses.for ?? 0) > 60e3 ? [` · up ${ago(ses.total)}`, C.faint] : ['', null];
+    const head = (icon, iconColor, label, color) => add([icon + ' ', iconColor], [`${String(ses.id).slice(0, 8)} `, C.muted], [`${model}  `, C.text], [`${label} ${ago(ses.for ?? ses.age)}`, color], up);
+    const sub = (text, color) => text && add(['    ', null], [text, color]);
+    if (ses.state === 'working') {
+      head('●', C.amberBold, 'working', C.amberBold);
+      sub(`${ses.tool || 'thinking'} ${ses.detail || ''}`, C.cyan);
+    } else if (ses.state === 'background') {
+      head(CLOCK[Math.floor(Date.now() / 440) % CLOCK.length], C.cyan, 'background', C.cyan);
+      for (const job of (ses.background || []).slice(0, 3)) sub(job, C.text);
+      sub(ses.said, C.muted);
+    } else {
+      head('◌', C.red, 'needs you', C.red);
+      sub(WAITS[ses.waitingFor] || WAITS.reply, C.red);
+      sub(ses.said, C.bold);
+    }
   }
   const ts = f.tasks || [];
   if (ts.length) {
@@ -446,8 +463,10 @@ export async function watch(root, opts = {}) {
   }
   const ui = { root, tick: 0, sel: 0, scroll: 0, flash: new Map(), freshEvents: new Map(), shipped: false, message: '', messageUntil: 0 };
   let st = loadState(root, ui.shipped);
+  ui.sound = opts.sound !== false && soundOn(st.config);
   let lastStatus = new Map(st.all.map((f) => [f.id, f.status]));
   let seen = new Set(st.events.map((e) => e.key));
+  let needs = st.needs;
 
   out.write('\x1b[?1049h\x1b[?25l');
   if (opts.intro !== false) await boot(out, st, root);
@@ -462,6 +481,8 @@ export async function watch(root, opts = {}) {
       if (lastStatus.has(f.id) && lastStatus.get(f.id) !== f.status) ui.flash.set(f.id, Date.now() + 2500);
     }
     for (const e of st.events) if (!seen.has(e.key)) ui.freshEvents.set(e.key, Date.now() + 4000);
+    if (newAttention(needs, st.needs).length && ui.sound) chime(out);
+    needs = st.needs;
     lastStatus = new Map(st.all.map((f) => [f.id, f.status]));
     seen = new Set(st.events.map((e) => e.key));
     ui.sel = Math.max(0, Math.min(ui.sel, st.features.length - 1));
@@ -496,6 +517,8 @@ export async function watch(root, opts = {}) {
       if (k === '\x1b[A' || k === 'k') ui.sel = Math.max(0, ui.sel - 1);
       else if (k === '\x1b[B' || k === 'j') ui.sel = Math.min(st.features.length - 1, ui.sel + 1);
       else if (k === 's') (ui.shipped = !ui.shipped), refresh();
+      else if (k === 'e') (ui.events = ui.events === false), out.write('\x1b[2J');
+      else if (k === 'm') (ui.sound = !ui.sound), say(ui.sound ? '♪ sound on' : 'sound muted until you quit');
       else if (k === 'u') return done({ action: 'ui' });
       else if ((k === '\r' || k === '\n') && f) {
         if (f.status === 'done') say(`${f.id} has shipped`);

package/src/ui/index.html

@@ -78,6 +78,8 @@ main { padding: 16px 20px 40px; }
 .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.background b { color: var(--blue); }
+.live.background .dot { background: var(--blue); animation-duration: 2.4s; }
 .live code { font-size: 11px; background: none; padding: 0; }
 .card.is-working { border-color: var(--accent); }
 @keyframes pulse { 50% { opacity: .25; transform: scale(.7); } }
@@ -152,6 +154,7 @@ dialog h2 { margin: 0 0 12px; font-size: 17px; }
     <button role="tab" aria-selected="false" data-view="context">Context</button>
   </nav>
   <span class="spacer"></span>
+  <button class="btn" id="soundBtn" aria-pressed="true"></button>
   <button class="btn" id="whoami" title="Name used for approvals"></button>
   <button class="btn primary" id="newBtn">+ New</button>
 </header>
@@ -241,21 +244,25 @@ function card(f) {
   </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. */
+const ago = (ms) => (ms < 60e3 ? `${Math.max(1, Math.round(ms / 1000))}s` : ms < 3600e3 ? `${Math.floor(ms / 60e3)}m` : `${Math.floor(ms / 3600e3)}h${Math.floor(ms / 60e3) % 60 ? `${Math.floor(ms / 60e3) % 60}m` : ''}`);
+const WAITS = { reply: 'Waiting for your reply', question: 'Asking you', permission: 'Needs your permission' };
+/** What is happening on a feature right now: a blocker, a session waiting on you, one working, or work left running in the background. */
 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 w = f.live?.waitingFor;
+  if (w) return `<div class="live waiting" title="${esc(w.said || '')}"><i class="dot"></i><span><b>${WAITS[w.why] || WAITS.reply}</b>${w.for != null ? ` · ${ago(w.for)}` : ''}${w.said ? `<span class="wrap">${esc(w.said)}</span>` : ' in a Claude session'}</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 head = [`<b>Working${on.length > 1 ? ` ×${on.length}` : ''}</b>`, ago(s.for ?? 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>`;
+    return `<div class="live working" title="${esc([[s.tool, s.detail].filter(Boolean).join(': '), s.total != null && `session running ${ago(s.total)}`].filter(Boolean).join('\n'))}"><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>`;
+  const bg = f.live?.background || [];
+  if (bg.length) return `<div class="live background" title="${esc(bg.join('\n'))}"><i class="dot"></i><span><b>In the background</b> · ${ago(f.live.backgroundFor)}${bg.length > 1 ? ` · ${bg.length} jobs` : ''}<span class="line"><code>${esc(bg[0])}</code></span></span></div>`;
   return '';
 }
 function renderBoard() {
@@ -287,6 +294,10 @@ async function render() {
   $('#project').textContent = S.config.project;
   $('#autonomy').textContent = S.autonomyLabel || `L${S.config.autonomy}`;
   $('#whoami').textContent = me() ? `👤 ${me()}` : 'Set your name';
+  const on = soundOn();
+  $('#soundBtn').textContent = on ? '♪ Sound on' : '♪ Sound off';
+  $('#soundBtn').setAttribute('aria-pressed', on);
+  $('#soundBtn').title = on ? 'Chimes when a feature needs you or ships. Click to mute.' : 'Click to chime when a feature needs you or ships.';
   document.querySelectorAll('nav.tabs button').forEach((b) => b.setAttribute('aria-selected', b.dataset.view === view));
   if (!(view === 'context' && ctxEditing && $('#ctxEditor'))) $('#main').innerHTML = view === 'board' ? renderBoard() : await renderContext();
   if (openId) await renderDrawer();
@@ -343,6 +354,7 @@ $('#newDialog').addEventListener('close', async () => {
 });
 $('#newBtn').onclick = newFeature;
 $('#whoami').onclick = askName;
+$('#soundBtn').onclick = () => { try { localStorage.setItem('buildline.sound', soundOn() ? 'off' : 'on'); } catch {} render(); if (soundOn()) chime(true); };
 $('#backdrop').onclick = closeDrawer;
 document.addEventListener('keydown', (e) => { if (e.key === 'Escape' && openId && !editing) closeDrawer(); });
 document.addEventListener('click', (e) => {
@@ -352,15 +364,42 @@ document.addEventListener('click', (e) => {
   const x = e.target.closest('[data-ctx]'); if (x) { ctxPath = x.dataset.ctx; ctxEditing = false; render(); }
 });
 
+// ---- sound: one chime when a feature needs a person or ships ----
+let audio = null, needs = null, lastChime = 0;
+const soundOn = () => { let v = null; try { v = localStorage.getItem('buildline.sound'); } catch {} return v ? v === 'on' : S?.config.sound !== false; };
+const attention = (f) => (f.status === 'done' ? 'done' : f.blocked || f.live?.waiting ? 'waiting' : null);
+// Browsers only allow sound after the page has been touched, so the audio starts on the first click or key.
+const unlock = () => { audio ||= new (window.AudioContext || window.webkitAudioContext)(); audio.resume(); };
+['pointerdown', 'keydown'].forEach((e) => document.addEventListener(e, unlock, { once: true }));
+function chime(force = false) {
+  if (!audio || (!force && Date.now() - lastChime < 3000)) return;
+  lastChime = Date.now();
+  const t = audio.currentTime, out = audio.createGain();
+  out.connect(audio.destination);
+  out.gain.setValueAtTime(0.0001, t);
+  out.gain.exponentialRampToValueAtTime(0.25, t + 0.01);
+  out.gain.exponentialRampToValueAtTime(0.0001, t + 1.2);
+  for (const [hz, level] of [[880, 1], [1320, 0.35], [1760, 0.15]]) {
+    const o = audio.createOscillator(), g = audio.createGain();
+    o.frequency.value = hz; g.gain.value = level;
+    o.connect(g).connect(out); o.start(t); o.stop(t + 1.25);
+  }
+}
+function listen() {
+  const now = new Map(S.features.map((f) => [f.id, attention(f)]));
+  if (needs && soundOn() && [...now].some(([id, a]) => a && needs.get(id) !== a)) chime();
+  needs = now;
+}
+
 async function refresh() {
   try {
     const next = await api('/api/state');
     const changed = JSON.stringify(next) !== JSON.stringify(S);
-    S = next; if (changed) await render();
+    S = next; listen(); if (changed) await render();
   } catch (e) { toast('Dashboard lost connection: is `buildline ui` still running?'); }
 }
 refresh();
-setInterval(() => { if (!document.hidden && !editing && !ctxEditing) refresh(); }, 2000);
+setInterval(() => { if (!editing && !ctxEditing) refresh(); }, 2000);
 </script>
 </body>
 </html>

package/templates/bin/hook.mjs

@@ -6,10 +6,11 @@
 //   guard          blocks edits to a spec's "## Acceptance" section while the
 //                  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).
+//   prompt / post / notify / stop / session-end
+//                  heartbeat: which session works on which feature and whether
+//                  it is working, running something in the background, or
+//                  waiting for a person, 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';
@@ -106,6 +107,12 @@ function featureRef(text) {
   return m ? m[1].padStart(3, '0') : null;
 }
 
+/** A prompt in a line. Background tasks finishing arrive as <task-notification> prompts: show their summary. */
+function promptDetail(prompt) {
+  const done = /^\s*<task-notification>[\s\S]*?<summary>([\s\S]*?)<\/summary>/.exec(prompt);
+  return done ? oneLine(done[1], 90) : oneLine(prompt, 60);
+}
+
 function detail(input) {
   const ti = input.tool_input || {};
   if (ti.file_path) return path.basename(ti.file_path);
@@ -119,6 +126,56 @@ function detail(input) {
   return '';
 }
 
+// Tools that stop the turn to ask the person something.
+const ASKS = ['AskUserQuestion', 'ExitPlanMode'];
+
+const oneLine = (s, n) => {
+  const t = String(s || '').replace(/\s+/g, ' ').trim();
+  return t.length > n ? t.slice(0, n - 1) + '…' : t;
+};
+
+/** What a session left running when its turn ended: background shells, subagents, scheduled checks. */
+function stillRunning(input) {
+  const tasks = (Array.isArray(input.background_tasks) ? input.background_tasks : [])
+    .filter((t) => !t.status || t.status === 'running')
+    .map((t) => (t.type === 'shell' ? detail({ tool_input: { command: t.command || t.description } }) : `agent: ${oneLine(t.description, 40)}`));
+  const crons = (Array.isArray(input.session_crons) ? input.session_crons : []).map((c) => `scheduled: ${oneLine(c.prompt || c.cron || c.schedule || 'check', 36)}`);
+  return [...tasks, ...crons];
+}
+
+/** The end of the agent's last message (its last paragraph, or last sentence when that's long): what it's waiting for. */
+function lastWords(message) {
+  const para = oneLine(String(message || '').trim().split(/\n\s*\n/).pop(), 1000);
+  if (para.length <= 90) return para || null;
+  return oneLine(/[^.!?]+[.!?]*\s*$/.exec(para)?.[0] || para, 140);
+}
+
+/** The last thing the agent said ends with a question: it wants an answer even if work runs on. */
+const asks = (message) => /\?\s*$/.test(String(message || '').replace(/[`*_)\]\s]+$/, ''));
+
+const quietParent = (prev) => prev.state === 'background' || prev.state === 'waiting';
+
+/** What a session is doing after this event: working, background (turn over, tasks still running) or waiting on a person. */
+function nextState(prev, input, event) {
+  const tool = input.tool_name;
+  const fromSubagent = Boolean(input.agent_id);
+  if (event === 'stop') {
+    const running = stillRunning(input);
+    const said = lastWords(input.last_assistant_message);
+    if (running.length && !asks(input.last_assistant_message)) return { state: 'background', waitingFor: null, background: running, said };
+    return { state: 'waiting', waitingFor: 'reply', background: running, said };
+  }
+  // A background subagent working on its own doesn't make the session busy again,
+  // nor does it answer a question the session is waiting on.
+  if (fromSubagent && quietParent(prev)) return {};
+  if (event === 'notify') return { state: 'waiting', waitingFor: prev.waitingFor === 'question' ? 'question' : 'permission', said: prev.waitingFor === 'question' ? prev.said : oneLine(input.message, 140) };
+  if (event === 'tool' && ASKS.includes(tool)) {
+    const q = input.tool_input?.questions?.[0]?.question || (tool === 'ExitPlanMode' ? 'Approve the plan?' : 'A question');
+    return { state: 'waiting', waitingFor: 'question', said: oneLine(q, 140), inTool: true };
+  }
+  return { state: 'working', waitingFor: null, background: [], said: null, inTool: event === 'tool' };
+}
+
 function heartbeat(input, event) {
   const id = String(input.session_id || '').replace(/[^\w-]/g, '');
   if (!id) return;
@@ -139,11 +196,13 @@ function heartbeat(input, event) {
     feature,
     station: station || prev.station || null,
     model: input.model?.id || input.model || prev.model || null,
-    state: event === 'stop' ? 'waiting' : 'working',
+    ...nextState(prev, input, event),
     lastAt: at,
-    ...(event === 'tool' ? { tool: input.tool_name, detail: detail(input) } : {}),
-    ...(event === 'prompt' ? { tool: null, detail: prompt.replace(/\s+/g, ' ').slice(0, 60) } : {}),
+    ...(event === 'tool' && !(input.agent_id && quietParent(prev)) ? { tool: input.tool_name, detail: detail(input) } : {}),
+    ...(event === 'prompt' ? { tool: null, detail: promptDetail(prompt) } : {}),
   };
+  // When the session entered its current state, so the views can say "working 4m", "waiting 12m".
+  next.since = next.state === prev.state && prev.since ? prev.since : at;
   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.
@@ -165,6 +224,8 @@ process.stdin.on('end', () => {
     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 === 'post') heartbeat(input, 'post');
+    else if (mode === 'notify') heartbeat(input, 'notify');
     else if (mode === 'stop') heartbeat(input, 'stop');
     else if (mode === 'session-end') heartbeat(input, 'end');
   } catch (err) {