Bellows keeps the fire going: time, work, learning

#!/usr/bin/env node
// kit/scripts/bellows.mjs — Bellows, the dispatcher.
//
// Runs on a timer (Windows Task Scheduler, cron, or a GitHub Action every 10
// minutes). Each tick: read the Linear issues that changed state, decide which
// agent the state calls for, check the gates, start the agent with the right
// kickoff prompt, parse the last line of what it wrote, move the issue, and
// record time and work in telemetry/events.jsonl. It never merges, never
// deploys without Priya's yes, and never argues with a gate.
//
//   node kit/scripts/bellows.mjs --once          one tick
//   node kit/scripts/bellows.mjs --watch         every 10 minutes
//   node kit/scripts/bellows.mjs --issue ALD-42  force one issue
//
// Env: LINEAR_API_KEY, LINEAR_TEAM (key, e.g. ALD), PREVIEW_URL (optional),
//      GATE_WEBHOOK (Slack incoming webhook or similar), AGENT_TIMEOUT_MIN.

import { readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync } from 'node:fs';
import { spawnSync } from 'node:child_process';
import { join } from 'node:path';

const ROOT = process.cwd();
const GATES = JSON.parse(readFileSync(join(ROOT, '.claude', 'gates.json'), 'utf8'));
const STATE_FILE = join(ROOT, 'telemetry', 'bellows-state.json');
const state = existsSync(STATE_FILE) ? JSON.parse(readFileSync(STATE_FILE, 'utf8')) : { issues: {} };
const args = process.argv.slice(2);
const TEAM = process.env.LINEAR_TEAM || 'ALD';

// ---- which agent a state calls for --------------------------------------
// Sub-steps inside a state are tracked in state.issues[id].phase so one Linear
// state can run several agents in order (build → cross-review → test → security).
const PLAN = {
  'Idea':            [{ agent: 'anvil',  runner: 'claude', prompt: 'scope' }],
  'Scoped':          [{ agent: 'warden', runner: 'claude', prompt: 'threat', onlyIfFlagged: true }, { agent: 'anvil', runner: 'claude', prompt: 'details' }],
  'Detailed':        [{ agent: 'builder', runner: 'auto',  prompt: 'build' }],
  'In Progress':     [{ agent: 'reviewer', runner: 'auto', prompt: 'review' }],
  'In Test':         [{ agent: 'gauge',  runner: 'codex',  prompt: 'qa' }, { agent: 'warden', runner: 'claude', prompt: 'security' }, { agent: 'beacon', runner: 'claude', prompt: 'journey' }],
  'Ready to Deploy': [{ agent: 'bellows', runner: 'self', prompt: 'deploy' }],
  'Deployed':        [{ agent: 'quill',  runner: 'claude', prompt: 'writeback' }, { agent: 'beacon', runner: 'claude', prompt: 'release-note' }]
};

// ---- Linear -------------------------------------------------------------
async function linear(query, variables) {
  const r = await fetch('https://api.linear.app/graphql', { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: process.env.LINEAR_API_KEY }, body: JSON.stringify({ query, variables }) });
  const j = await r.json(); if (j.errors) throw new Error(JSON.stringify(j.errors)); return j.data;
}
async function activeIssues() {
  const d = await linear(`query($team:String!){ issues(filter:{ team:{ key:{ eq:$team } }, state:{ name:{ nin:["Deployed","Canceled","Duplicate"] } } }, first:50){ nodes{ id identifier title description estimate labels{ nodes{ name } } state{ name } updatedAt comments{ nodes{ body createdAt } } } } }`, { team: TEAM });
  return d.issues.nodes;
}
async function moveTo(issue, stateName) {
  const d = await linear(`query($team:String!){ workflowStates(filter:{ team:{ key:{ eq:$team } } }){ nodes{ id name } } }`, { team: TEAM });
  const s = d.workflowStates.nodes.find(x => x.name === stateName); if (!s) throw new Error('no state ' + stateName);
  await linear(`mutation($id:String!,$s:String!){ issueUpdate(id:$id, input:{ stateId:$s }){ success } }`, { id: issue.id, s: s.id });
  log({ event: 'state', agent: 'bellows', issue: issue.identifier, to: stateName });
}
async function comment(issue, body) { await linear(`mutation($id:String!,$b:String!){ commentCreate(input:{ issueId:$id, body:$b }){ success } }`, { id: issue.id, b: body }); }

// ---- telemetry ----------------------------------------------------------
function log(ev) { mkdirSync(join(ROOT, 'telemetry'), { recursive: true }); appendFileSync(join(ROOT, 'telemetry', 'events.jsonl'), JSON.stringify({ ts: new Date().toISOString(), ...ev }) + '\n'); }
function save() { mkdirSync(join(ROOT, 'telemetry'), { recursive: true }); writeFileSync(STATE_FILE, JSON.stringify(state, null, 2)); }

// ---- gates --------------------------------------------------------------
async function askPriya(issue, escalationId, detail) {
  const rule = GATES.escalations.find(e => e.id === escalationId) || { reason: escalationId };
  const text = `GATE · ${issue.identifier} · ${rule.reason}\n${detail}\nReply in Linear with "approve ${escalationId}" or "reject ${escalationId}".`;
  log({ event: 'gate', agent: 'bellows', issue: issue.identifier, gate: escalationId, decision: 'ask', detail });
  if (process.env.GATE_WEBHOOK) await fetch(process.env.GATE_WEBHOOK, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ text }) });
  await comment(issue, '🛎️ **Bellows** ' + text);
}
function approved(issue, escalationId) { return issue.comments.nodes.some(c => new RegExp(`^approve ${escalationId}`, 'im').test(c.body)); }
function rejected(issue, escalationId) { return issue.comments.nodes.some(c => new RegExp(`^reject ${escalationId}`, 'im').test(c.body)); }

// ---- running an agent ---------------------------------------------------
function pickBuilder(issue) {
  // Ember for UI-heavy, multi-file slices; Flint for well-specified back-end slices; Anvil's recommendation wins.
  const rec = /builder:\s*(ember|flint)/i.exec(issue.description || '');
  if (rec) return rec[1].toLowerCase();
  const labels = issue.labels.nodes.map(l => l.name.toLowerCase());
  return labels.includes('backend') || labels.includes('api') ? 'flint' : 'ember';
}
function kickoff(promptName, issue, extra) {
  const tpl = readFileSync(join(ROOT, 'kit', 'prompts', promptName + '.md'), 'utf8');
  return tpl.replace(/\{\{ISSUE_ID\}\}/g, issue.identifier).replace(/\{\{ISSUE_TITLE\}\}/g, issue.title).replace(/\{\{PREVIEW_URL\}\}/g, process.env.PREVIEW_URL || '(no preview yet)').replace(/\{\{EXTRA\}\}/g, extra || '');
}
function run(agent, runner, prompt, issue) {
  const started = Date.now();
  const env = { ...process.env, AGENT_NAME: agent, ISSUE_ID: issue.identifier };
  const timeout = (Number(process.env.AGENT_TIMEOUT_MIN) || GATES.budgets.maxMinutesPerRun) * 60 * 1000;
  log({ event: 'start', agent, issue: issue.identifier, runner, prompt });
  let res;
  if (runner === 'codex') {
    // Codex CLI, non-interactive. Check `codex exec --help` in your version for the sandbox flag you want.
    res = spawnSync('codex', ['exec', '--full-auto', prompt], { cwd: ROOT, env, encoding: 'utf8', timeout, shell: process.platform === 'win32' });
  } else {
    // Claude Code headless. The agent file is selected by asking for it in the prompt; hooks and permissions come from .claude/settings.json.
    res = spawnSync('claude', ['-p', prompt, '--output-format', 'text', '--permission-mode', 'acceptEdits'], { cwd: ROOT, env, encoding: 'utf8', timeout, shell: process.platform === 'win32' });
  }
  const out = (res.stdout || '') + (res.stderr || '');
  const minutes = Math.round((Date.now() - started) / 6000) / 10;
  const last = out.trim().split('\n').filter(Boolean).pop() || '';
  log({ event: 'end', agent, issue: issue.identifier, minutes, status: res.status, last });
  return { out, last, minutes };
}

// ---- one tick -----------------------------------------------------------
async function tick(only) {
  const issues = await activeIssues();
  for (const issue of issues) {
    if (only && issue.identifier !== only) continue;
    const st = state.issues[issue.identifier] || (state.issues[issue.identifier] = { phase: 0, state: null, runsToday: 0, day: today(), reviewRounds: 0, qaFails: 0 });
    if (st.day !== today()) { st.day = today(); st.runsToday = 0; }
    if (st.state !== issue.state.name) { st.state = issue.state.name; st.phase = 0; }
    if (st.runsToday >= GATES.budgets.maxRunsPerIssuePerDay) { await askPriya(issue, 'budget', `${st.runsToday} runs today.`); continue; }

    const plan = PLAN[issue.state.name]; if (!plan || st.phase >= plan.length) continue;
    const step = plan[st.phase];
    const flagged = /flags:\s*(?!none)/i.test(issue.description || '');
    if (step.onlyIfFlagged && !flagged) { st.phase++; save(); continue; }

    // The gates that live in the plan itself
    if (step.prompt === 'build' && flagged && !approved(issue, 'customer-data')) { if (!rejected(issue, 'customer-data')) await askPriya(issue, 'customer-data', 'Anvil flagged this slice.'); continue; }
    if (step.prompt === 'build' && (issue.estimate || 0) > 5 && !approved(issue, 'scope-size')) { await askPriya(issue, 'scope-size', `${issue.estimate} points.`); continue; }
    if (step.prompt === 'deploy') {
      if (!approved(issue, 'prod-deploy')) { if (!rejected(issue, 'prod-deploy')) await askPriya(issue, 'prod-deploy', 'Tests green, Warden clear, Beacon reviewed.'); continue; }
      const r = spawnSync('vercel', ['--prod', '--yes'], { cwd: ROOT, encoding: 'utf8', shell: process.platform === 'win32' });
      log({ event: 'deploy', agent: 'bellows', issue: issue.identifier, status: r.status });
      if (r.status === 0) {
        await moveTo(issue, 'Deployed');
        // Deployed issues drop out of activeIssues() on the next tick, so the
        // write-back steps (Quill, then Beacon's release note) run right now.
        for (const s of PLAN['Deployed']) {
          const done = run(s.agent, s.runner, kickoff(s.prompt, issue), issue);
          await comment(issue, `⚙️ **Bellows** ran **${cap(s.agent)}** (${s.runner}, ${done.minutes} min). Result: \`${done.last.slice(0, 160)}\``);
        }
      } else { await askPriya(issue, 'budget', 'Deploy failed:\n' + (r.stderr || '').slice(-800)); }
      continue;
    }

    // Who runs
    let agent = step.agent, runner = step.runner;
    if (agent === 'builder') { agent = st.builder || (st.builder = pickBuilder(issue)); runner = agent === 'flint' ? 'codex' : 'claude'; }
    if (agent === 'reviewer') { agent = st.builder === 'flint' ? 'ember' : 'flint'; runner = agent === 'flint' ? 'codex' : 'claude'; }

    const { last, minutes } = run(agent, runner, kickoff(step.prompt, issue), issue);
    st.runsToday++;

    // Parse the last line and move the state machine
    if (/^ANVIL: Scoped/.test(last)) await moveTo(issue, st.phase === 0 && issue.state.name === 'Idea' ? 'Scoped' : 'Detailed');
    else if (/REQUEST CHANGES/.test(last)) { st.reviewRounds++; if (st.reviewRounds >= GATES.budgets.maxReviewRounds) await askPriya(issue, 'review-deadlock', last); else { st.phase = 0; } }
    else if (/^ESCALATE:/.test(last)) await askPriya(issue, 'review-deadlock', last);
    else if (/^APPROVE$/m.test(last)) await moveTo(issue, 'In Test');
    else if (/QA RED/.test(last)) { st.qaFails++; if (st.qaFails >= GATES.budgets.maxQaFailsPerIssue) await askPriya(issue, 'qa-third-fail', last); else await moveTo(issue, 'In Progress'); }
    else if (/^FLAKY:/.test(last)) await askPriya(issue, 'flaky', last);
    else if (/^COVERAGE:/.test(last)) await askPriya(issue, 'qa-third-fail', 'Not every criterion has a test. ' + last);
    else if (/WARDEN BLOCK|SECRET FOUND/.test(last)) await askPriya(issue, 'security-high', last);
    else st.phase++;
    if (st.phase >= plan.length && issue.state.name === 'In Test') await moveTo(issue, 'Ready to Deploy');
    save();
    await comment(issue, `⚙️ **Bellows** ran **${cap(agent)}** (${runner}, ${minutes} min). Result: \`${last.slice(0, 160)}\``);
  }
}
function today() { return new Date().toISOString().slice(0, 10); }
function cap(s) { return s.charAt(0).toUpperCase() + s.slice(1); }

const only = args.includes('--issue') ? args[args.indexOf('--issue') + 1] : null;
if (args.includes('--watch')) { const loop = async () => { try { await tick(only); } catch (e) { log({ event: 'error', agent: 'bellows', error: String(e) }); } setTimeout(loop, 10 * 60 * 1000); }; loop(); }
else tick(only).catch(e => { console.error(e); process.exit(1); });

Walkthrough

1. The PLAN table: state → agents

   Each Linear state maps to an ordered list of agents. In Test runs three in a row: Gauge, then Warden, then Beacon. The phase field in the state file remembers how far down the list an issue is, so one Linear state can carry several runs. builder and reviewer are placeholders filled at run time. onlyIfFlagged skips Warden's threat note when Anvil wrote flags: none.

   Linear state	Agents, in order	What ends the phase
   Idea	Anvil (scope)	ANVIL: Scoped → Scoped
   Scoped	Warden (threat, only if flagged) → Anvil (details)	ANVIL: Scoped → Detailed
   Detailed	builder: Ember or Flint (build)	PR open; the builder moves the issue to In Progress
   In Progress	reviewer: whoever did not build (review)	APPROVE → In Test · REQUEST CHANGES → round two
   In Test	Gauge (qa) → Warden (security) → Beacon (journey)	All three pass → Ready to Deploy · QA RED → In Progress
   Ready to Deploy	Bellows itself (deploy)	approve prod-deploy → vercel --prod → Deployed
   Deployed	Quill (writeback) → Beacon (release-note)	QUILL DONE · RELEASE NOTE READY

2. Linear over GraphQL

   Three helpers and no SDK. activeIssues pulls every open issue on the team with its state, estimate, labels, description and comments in one query. moveTo looks the state up by name and updates the issue. comment posts. Each is one fetch to api.linear.app/graphql with LINEAR_API_KEY from the environment. State names are what Linear shows, which is why chapter 8 told you the names matter.

3. pickBuilder

   Anvil's recommendation wins: a line builder: ember or builder: flint in the issue body. Without one, the labels backend or api send the slice to Flint and everything else to Ember. The choice is saved on the issue's state, so the reviewer is always the other one for the life of the issue.

4. kickoff templating

   kickoff reads kit/prompts/NAME.md and fills four braces: ISSUE_ID, ISSUE_TITLE, PREVIEW_URL and EXTRA. That is the entire templating engine. Prompts stay as readable files you can open and edit. When an agent keeps missing something, you change the prompt file and the next tick uses it.

5. run: claude -p or codex exec

   One function, two runners. Codex gets codex exec --full-auto PROMPT. Claude Code gets claude -p PROMPT --output-format text --permission-mode acceptEdits. Both run in the repo with AGENT_NAME and ISSUE_ID in the environment, which is how the hooks tag their telemetry lines with the right agent. A timeout from gates.json budgets kills a run that wanders. Check both flag sets against the current docs at code.claude.com and developers.openai.com/codex. The pattern is the spawn, the environment and the timeout.

6. The status-line parser

   Every agent file ends with one line Bellows can read: ANVIL: Scoped, APPROVE, REQUEST CHANGES, QA GREEN, QA RED, WARDEN CLEAR, WARDEN BLOCK, JOURNEY REVIEWED. The parser is a chain of regular expressions over the last non-empty line of output. A match moves the state or asks Priya. No match means the phase is done and the next agent in the list is up. That is why the agent files are so strict about their last line.

7. The gates and askPriya

   Three gates live in the plan itself: customer-data before a build on a flagged issue, scope-size above five points, and prod-deploy before vercel --prod. The budgets in gates.json cap runs per issue per day, review rounds and QA fails. askPriya posts a GATE comment on the issue and a message to GATE_WEBHOOK. Approval is a comment on the issue that starts approve prod-deploy. Bellows never argues. It asks, skips to the next issue, and checks again next tick.

8. Telemetry

   log() appends one JSON line to telemetry/events.jsonl: start, end with minutes and the last line, state, gate, deploy, error. save() writes the state file. The hooks in chapter 7 append tool, gate and edit lines to the same file. That one file is everything the dashboard needs.

How learning is measured