@ucsandman/legcli 0.7.0

package/src/store.mjs

@@ -0,0 +1,90 @@
+// store — read side of the ledger plus thin wrappers around the ledger CLI
+// (src/ledger.mjs stays the only writer). Everything the orchestrator,
+// scheduler, board and CLI need to look at cards goes through here.
+import { execFileSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { homedir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { readEvents as ledgerReadEvents } from './ledger.mjs'
+
+const SRC = dirname(fileURLToPath(import.meta.url))
+export const LEDGER = join(SRC, 'ledger.mjs')
+export const RUNNER = join(SRC, 'runner.mjs')
+export const LEG_ACTOR = { type: 'leg' }
+export const BATON_ACTOR = LEG_ACTOR
+
+export function home() {
+  if (process.env.LEG_HOME) return process.env.LEG_HOME
+  if (process.env.BATON_HOME) return process.env.BATON_HOME
+  const leg = join(homedir(), '.leg')
+  const baton = join(homedir(), '.baton')
+  if (existsSync(leg)) return leg
+  if (existsSync(baton)) return baton
+  return leg
+}
+
+export function cardDir(id) { return join(home(), 'cards', id) }
+
+export function readCard(id) {
+  const f = join(cardDir(id), 'card.json')
+  if (!existsSync(f)) return null
+  try { return JSON.parse(readFileSync(f, 'utf8')) } catch { return null }
+}
+
+export function listCards() {
+  const root = join(home(), 'cards')
+  if (!existsSync(root)) return []
+  return readdirSync(root).sort().map(readCard).filter(Boolean)
+}
+
+export function readRuns(id) {
+  const dir = join(cardDir(id), 'runs')
+  if (!existsSync(dir)) return []
+  return readdirSync(dir).map(Number).filter((n) => Number.isInteger(n) && n > 0).sort((a, b) => a - b)
+    .map((n) => {
+      try { return JSON.parse(readFileSync(join(dir, String(n), 'run.json'), 'utf8')) } catch { return null }
+    }).filter(Boolean)
+}
+
+export function readEvents(id) { return ledgerReadEvents(id) }
+
+function ledger(args) {
+  return execFileSync(process.execPath, [LEDGER, ...args], { windowsHide: true, encoding: 'utf8', env: process.env })
+}
+
+export function ledgerCreate(fields) {
+  const args = ['create']
+  for (const [k, v] of Object.entries(fields)) {
+    if (v === undefined || v === null) continue
+    args.push(`--${k}`, typeof v === 'string' ? v : JSON.stringify(v))
+  }
+  return ledger(args).trim()
+}
+
+export function ledgerAppend(id, { actor = BATON_ACTOR, type, summary, body, station, leg }) {
+  const args = ['append', '--card', id, '--actor', JSON.stringify(actor), '--type', type, '--summary', summary]
+  if (body) args.push('--body', String(body).slice(0, 4000))
+  if (station) args.push('--station', station)
+  if (leg !== undefined && leg !== null) args.push('--leg', String(leg))
+  ledger(args)
+}
+
+export function ledgerLog({ actor = BATON_ACTOR, type, summary, body }) {
+  const args = ['log', '--actor', JSON.stringify(actor), '--type', type, '--summary', summary]
+  if (body) args.push('--body', String(body).slice(0, 4000))
+  ledger(args)
+}
+
+export function ledgerUpdate(id, { status, station, leg, sessionId, patch }) {
+  const args = ['update', '--card', id]
+  if (status) args.push('--status', status)
+  if (station) args.push('--station', station)
+  if (leg !== undefined && leg !== null) args.push('--leg', String(leg))
+  if (sessionId) args.push('--session-id', sessionId)
+  if (patch && Object.keys(patch).length) args.push('--patch', JSON.stringify(patch))
+  if (args.length === 3) return
+  ledger(args)
+}
+
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms))

package/src/sync/dashclaw.mjs

@@ -0,0 +1,70 @@
+// dashclaw sync — records every ledger event as a DashClaw action over native
+// http/https (LESSONS 07-12: no global fetch). Off unless BATON_SYNC_DASHCLAW=1
+// and DASHCLAW_URL + DASHCLAW_API_KEY are set. Field names come from
+// DashClaw's validator (app/lib/validate.js ACTION_RECORD_SCHEMA): agent_id,
+// action_type and declared_goal are required; status is one of running,
+// completed, failed, cancelled, pending, pending_approval, blocked.
+import http from 'node:http'
+import https from 'node:https'
+
+export function dashclawConfig(env = process.env) {
+  if ((env.LEG_SYNC_DASHCLAW || env.BATON_SYNC_DASHCLAW) !== '1') return null
+  const url = env.DASHCLAW_URL
+  const key = env.DASHCLAW_API_KEY
+  if (!url || !key) return null
+  return { url: url.replace(/\/$/, ''), key }
+}
+
+const STATUS_BY_TYPE = {
+  card_created: 'pending', leg_started: 'running', leg_progress: 'running', leg_exited: 'completed',
+  limit_detected: 'blocked', handoff_written: 'completed', leg_resumed: 'running', station_done: 'completed',
+  bounced: 'failed', landed: 'completed', land_warning: 'completed', land_retry: 'running', blocked_by: 'blocked',
+  scheduler_started: 'running', scheduler_stopped: 'completed', approval_needed: 'pending_approval', approved: 'completed',
+  reassigned: 'completed', paused: 'blocked', resumed: 'running', killed: 'cancelled', done: 'completed',
+  failed: 'failed', error: 'failed', status: 'completed',
+}
+
+// One ledger event → one action record (the request body).
+export function actionForEvent(ev, card = null) {
+  const actor = ev.actor ?? { type: 'baton' }
+  const agent = actor.type === 'agent' ? `baton/${actor.adapter}` : actor.type === 'human' ? `baton/human:${actor.id}` : 'baton'
+  const body = {
+    agent_id: agent,
+    action_type: `baton_${ev.type}`,
+    declared_goal: String(ev.summary ?? ev.type).slice(0, 2000),
+    status: STATUS_BY_TYPE[ev.type] ?? 'completed',
+    reversible: true,
+    risk_score: ev.type === 'landed' ? 40 : ev.type === 'killed' ? 30 : 10,
+    trigger: ev.card_id ? `card ${ev.card_id}` : 'scheduler',
+    systems_touched: [ev.card_id, card?.repo].filter(Boolean).slice(0, 50),
+    input_summary: JSON.stringify({ card_id: ev.card_id, station: ev.station, leg: ev.leg, actor, task: card?.task ?? null }).slice(0, 4000),
+    timestamp_start: ev.ts,
+    timestamp_end: ev.ts,
+  }
+  if (ev.body) body.output_summary = String(ev.body).slice(0, 4000)
+  return body
+}
+
+export function request(cfg, method, path, body, { timeoutMs = 5000 } = {}) {
+  const data = JSON.stringify(body ?? {})
+  const url = new URL(cfg.url + path)
+  const client = url.protocol === 'https:' ? https : http
+  return new Promise((resolvePromise) => {
+    const req = client.request(url, {
+      method,
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(data), Connection: 'close', 'x-api-key': cfg.key },
+      timeout: timeoutMs,
+    }, (res) => {
+      let text = ''
+      res.on('data', (c) => { text += c })
+      res.on('end', () => resolvePromise({ ok: res.statusCode >= 200 && res.statusCode < 300, status: res.statusCode, text }))
+    })
+    req.on('timeout', () => req.destroy())
+    req.on('error', (err) => resolvePromise({ ok: false, status: 0, text: err.message }))
+    req.end(data)
+  })
+}
+
+export async function record(cfg, ev, card) {
+  return request(cfg, 'POST', '/api/actions', actionForEvent(ev, card))
+}

package/src/sync/index.mjs

@@ -0,0 +1,54 @@
+// sync fan-out — best effort, off by default, never throws into the ledger.
+// The ledger calls notify() after it has written its own files; a sync that
+// fails becomes one `status` event (`[sync:<name>] …`) at most once a minute
+// and a buffered retry for DashClaw (unsynced.jsonl, flushed by `ledger sync`).
+import { existsSync, statSync, writeFileSync, appendFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { dashclawConfig, record } from './dashclaw.mjs'
+import { workboardEnabled, mirror } from './workboard.mjs'
+
+export function enabledSyncs(env = process.env) {
+  const out = []
+  if (workboardEnabled(env)) out.push('workboard')
+  if (dashclawConfig(env)) out.push('dashclaw')
+  return out
+}
+
+function throttled(home, name, minMs = 60000) {
+  const f = join(home, `sync-${name}.last-failure`)
+  if (existsSync(f) && Date.now() - statSync(f).mtimeMs < minMs) return true
+  writeFileSync(f, new Date().toISOString())
+  return false
+}
+
+// Called by the ledger. `report(summary)` appends the status event through the
+// ledger's own writer (passed in to avoid a circular import).
+export async function notify({ kind, ev, card, home, env = process.env, report = () => {} }) {
+  const results = {}
+  if (workboardEnabled(env) && card && (kind === 'create' || kind === 'status')) {
+    try {
+      const r = mirror(card.status === 'done' && kind === 'status' ? 'done' : kind, card, { home, env })
+      results.workboard = r
+      if (r.first_unavailable) report(`[sync:workboard] unavailable (plugin disabled): ${r.message}`)
+      else if (r.error && !throttled(home, 'workboard')) report(`[sync:workboard] failed: ${r.error}`)
+    } catch (err) {
+      results.workboard = { error: err.message }
+      if (!throttled(home, 'workboard')) report(`[sync:workboard] failed: ${err.message}`)
+    }
+  }
+  const cfg = dashclawConfig(env)
+  if (cfg && ev) {
+    try {
+      const r = await record(cfg, ev, card)
+      results.dashclaw = r
+      if (!r.ok) {
+        if (ev.card_id) appendFileSync(join(home, 'cards', ev.card_id, 'unsynced.jsonl'), JSON.stringify({ op: 'record', ev, card: card ? { repo: card.repo, task: card.task } : null }) + '\n')
+        if (!throttled(home, 'dashclaw')) report(`[sync:dashclaw] failed (${r.status}): ${String(r.text).slice(0, 120)}; buffered`)
+      }
+    } catch (err) {
+      results.dashclaw = { ok: false, text: err.message }
+      if (!throttled(home, 'dashclaw')) report(`[sync:dashclaw] failed: ${err.message}`)
+    }
+  }
+  return results
+}

package/src/sync/workboard.mjs

@@ -0,0 +1,54 @@
+// workboard sync — mirrors cards to the OpenClaw Workboard through the
+// `openclaw workboard` CLI, argv only (node <openclaw.mjs> …, never a shell).
+// Off unless BATON_SYNC_WORKBOARD=1. On the build machine the plugin is
+// disabled (`plugins.allow` excludes "workboard"; fixtures/sync/workboard-help.txt
+// holds the verbatim message), so the verb mapping below is written against
+// the argv stub in test/sync.test.mjs. When the plugin is enabled, adjust
+// VERBS here from `openclaw workboard --help`; nothing else needs to change.
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { resolveNpmCliEntry } from '../adapters/resolve.mjs'
+
+export const VERBS = {
+  create: (card) => ['add', '--title', card.title ?? card.task, '--id', card.card_id, '--column', card.status],
+  status: (card) => ['move', card.card_id, card.status === 'done' ? 'done' : card.status],
+  done: (card) => ['done', card.card_id],
+}
+
+export function workboardEnabled(env = process.env) { return (env.LEG_SYNC_WORKBOARD || env.BATON_SYNC_WORKBOARD) === '1' }
+
+export function resolveOpenclaw(env = process.env) {
+  if (env.OPENCLAW_BIN && /\.(mjs|cjs|js)$/.test(env.OPENCLAW_BIN)) return { bin: process.execPath, prefix: [env.OPENCLAW_BIN] }
+  const entry = resolveNpmCliEntry('openclaw', 'openclaw', { pkgDir: env.OPENCLAW_PKG_DIR })
+  if (entry) return { bin: process.execPath, prefix: [entry] }
+  return null
+}
+
+const UNAVAILABLE_RE = /is unavailable because|plugins\.allow/i
+
+function markerPath(home) { return join(home, 'sync-workboard.unavailable') }
+
+// Returns { ran, argv, unavailable, first_unavailable, error }.
+export function mirror(kind, card, { home, env = process.env } = {}) {
+  const verb = VERBS[kind]
+  if (!verb) return { ran: false, error: `unknown mirror kind ${kind}` }
+  const marker = home ? markerPath(home) : null
+  if (marker && existsSync(marker)) return { ran: false, unavailable: true, first_unavailable: false }
+  const oc = resolveOpenclaw(env)
+  if (!oc) return { ran: false, error: 'openclaw not installed (set OPENCLAW_PKG_DIR or OPENCLAW_BIN)' }
+  const argv = ['workboard', ...verb(card)]
+  const r = spawnSync(oc.bin, [...oc.prefix, ...argv], { windowsHide: true, encoding: 'utf8', timeout: 20000, env })
+  const text = `${r.stdout ?? ''}\n${r.stderr ?? ''}`
+  if (UNAVAILABLE_RE.test(text)) {
+    if (marker) writeFileSync(marker, `${new Date().toISOString()} ${text.trim().split('\n')[0]}\n`)
+    return { ran: true, argv, unavailable: true, first_unavailable: true, message: text.trim().split('\n')[0] }
+  }
+  if (r.error || r.status !== 0) return { ran: true, argv, error: (r.error?.message || r.stderr || r.stdout || `exit ${r.status}`).trim().slice(0, 300) }
+  return { ran: true, argv, ok: true }
+}
+
+export function unavailableMessage(home) {
+  const p = markerPath(home)
+  return existsSync(p) ? readFileSync(p, 'utf8').trim() : null
+}

package/src/taps/agy.mjs

@@ -0,0 +1,64 @@
+// agy tap — Antigravity CLI 1.2.0 is a closed Go binary with no hooks and no
+// usage percentage on any surface Baton can read (its own status line fetches
+// a quota summary from the backend; the value is not written anywhere). What
+// it does give:
+//   --log-file <path>       one log per Baton session; the wall shows up as
+//                           RESOURCE_EXHAUSTED / "it resets in <d>" / "out of quota"
+//                           (strings present in agy.exe; docs-only until hit live)
+//   ~/.gemini/antigravity-cli/history.jsonl
+//                           {display, timestamp, workspace, conversationId} per
+//                           prompt (observed live) → task text + conversation id
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { LAYOUT } from '../accounts.mjs'
+
+export function historyFile(agyHome = LAYOUT.agy.home()) { return join(agyHome, 'history.jsonl') }
+
+const LIMIT_RES = [
+  ['agy-resource-exhausted', /RESOURCE_EXHAUSTED/],
+  ['agy-resets-in', /it resets in\s+\S+/i],
+  ['agy-out-of-quota', /out of quota/i],
+  ['agy-quota-exhausted', /quota (exhausted|exceeded)/i],
+]
+
+// Log text → { signal, detail, resets_at } | null
+export function scanLog(text) {
+  for (const [id, re] of LIMIT_RES) {
+    const m = re.exec(text)
+    if (!m) continue
+    const at = text.lastIndexOf(m[0])
+    const detail = text.slice(Math.max(0, at - 80), at + 160).replace(/\s+/g, ' ').trim()
+    let resets_at = null
+    // "Resets in 71h19m42s" has more than one unit: sum them all, not just the
+    // first, or the agent is restarted from the bundle before it is actually back
+    const dm = /resets in\s+((?:\d+\s*[smhd])+)/i.exec(text.slice(at))
+    if (dm) {
+      let secs = 0
+      for (const [, n, u] of dm[1].matchAll(/(\d+)\s*([smhd])/gi)) secs += parseInt(n, 10) * { s: 1, m: 60, h: 3600, d: 86400 }[u.toLowerCase()]
+      if (secs) resets_at = Math.floor(Date.now() / 1000) + secs
+    }
+    return { signal: id, detail, resets_at }
+  }
+  return null
+}
+
+function sameDir(a, b) {
+  const n = (x) => String(x ?? '').replace(/\\/g, '/').replace(/\/$/, '').toLowerCase()
+  return n(a) === n(b)
+}
+
+// Prompts typed into agy in `cwd` since `sinceMs`.
+export function promptsSince({ agyHome, cwd, sinceMs }) {
+  const f = historyFile(agyHome)
+  if (!existsSync(f)) return []
+  const out = []
+  for (const line of readFileSync(f, 'utf8').split('\n')) {
+    if (!line) continue
+    let j
+    try { j = JSON.parse(line) } catch { continue }
+    if (j.timestamp >= sinceMs - 2000 && sameDir(j.workspace, cwd)) out.push({ text: String(j.display ?? ''), ts: j.timestamp, conversationId: j.conversationId ?? null })
+  }
+  return out
+}
+
+export function logSize(path) { try { return statSync(path).size } catch { return 0 } }

package/src/taps/claude-usage.mjs

@@ -0,0 +1,67 @@
+// claude usage — the 5h / 7d percentages for a Claude Code login, from the
+// same endpoint Claude Code's own /usage and built-in status line read.
+// Why not the status line: Claude Code 2.1.268 renders its built-in status
+// line and does not run a custom `statusLine` command passed via --settings
+// or a project settings file (verified 2026-09-11 with an `echo` command at
+// both levels; hooks from the same --settings file do run). So Baton asks the
+// usage endpoint directly with the OAuth token Claude Code stored at login.
+// The token is read by this process only, sent only to api.anthropic.com,
+// and never written anywhere (the ledger scrubs bearer tokens regardless).
+// Native https, not fetch: Node 24 on Windows can crash at exit with an open
+// fetch (test/lessons.test.mjs no-global-fetch).
+import https from 'node:https'
+import http from 'node:http'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { LAYOUT } from '../accounts.mjs'
+
+export const USAGE_URL = (process.env.LEG_CLAUDE_USAGE_URL || process.env.BATON_CLAUDE_USAGE_URL) || 'https://api.anthropic.com/api/oauth/usage'
+
+function readToken(configDir) {
+  const f = join(configDir, '.credentials.json')
+  if (!existsSync(f)) return null
+  try {
+    const j = JSON.parse(readFileSync(f, 'utf8'))
+    const o = j.claudeAiOauth ?? j.oauth ?? null
+    if (!o?.accessToken) return null
+    return { token: o.accessToken, expired: Boolean(o.expiresAt && Date.now() > o.expiresAt) }
+  } catch { return null }
+}
+
+function window(x) {
+  if (!x || typeof x !== 'object') return null
+  const pct = Number(x.utilization ?? x.used_percentage ?? x.used_percent)
+  if (!Number.isFinite(pct)) return null
+  let resets = x.resets_at ?? x.resetsAt ?? null
+  if (typeof resets === 'string') { const t = Date.parse(resets); resets = Number.isFinite(t) ? Math.floor(t / 1000) : null }
+  return { pct, resets_at: resets }
+}
+
+function getJson(url, headers, timeoutMs) {
+  return new Promise((resolvePromise) => {
+    const u = new URL(url)
+    // http only for a local test double through BATON_CLAUDE_USAGE_URL
+    const mod = u.protocol === 'http:' ? http : https
+    const req = mod.request({ host: u.hostname, port: u.port || (u.protocol === 'http:' ? 80 : 443), path: u.pathname + u.search, method: 'GET', headers, timeout: timeoutMs }, (res) => {
+      let d = ''
+      res.setEncoding('utf8')
+      res.on('data', (c) => { d += c })
+      res.on('end', () => resolvePromise({ status: res.statusCode, text: d }))
+    })
+    req.on('timeout', () => { req.destroy(new Error('usage endpoint timed out')) })
+    req.on('error', (err) => resolvePromise({ status: 0, text: '', error: err.message }))
+    req.end()
+  })
+}
+
+// → { ok, limits: {five_hour, seven_day}|null, status, error, expired }
+export async function fetchClaudeUsage({ configDir = LAYOUT.claude.home(), timeoutMs = 8000, url = USAGE_URL } = {}) {
+  const t = readToken(configDir)
+  if (!t) return { ok: false, limits: null, error: 'no claude.ai login found in ' + configDir }
+  const r = await getJson(url, { Authorization: `Bearer ${t.token}`, 'anthropic-beta': 'oauth-2025-04-20', Accept: 'application/json', 'User-Agent': 'legcli' }, timeoutMs)
+  if (r.error) return { ok: false, limits: null, status: 0, error: r.error }
+  if (r.status !== 200) return { ok: false, limits: null, status: r.status, expired: t.expired, error: `usage endpoint ${r.status}: ${r.text.slice(0, 120)}` }
+  let j
+  try { j = JSON.parse(r.text) } catch { return { ok: false, limits: null, status: r.status, error: 'usage endpoint returned no JSON' } }
+  return { ok: true, limits: { five_hour: window(j.five_hour), seven_day: window(j.seven_day) }, status: r.status, expired: t.expired, raw_keys: Object.keys(j) }
+}

package/src/taps/claude.mjs

@@ -0,0 +1,170 @@
+// claude tap — how `baton claude` sees inside a normal interactive Claude Code.
+// Nothing in ~/.claude is edited: the session gets one extra settings file via
+// `--settings` (hooks merge with the user's; statusLine is the only key that
+// replaces, so Baton's status line runs the user's own command first).
+// Sources: code.claude.com/docs/en/hooks (StopFailure `error: rate_limit`),
+// docs/en/statusline (rate_limits.five_hour/seven_day used_percentage,
+// resets_at), docs/en/settings (`--settings` sits above user settings).
+import { existsSync, readFileSync } from 'node:fs'
+import { join, dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { sessionDir, updateSession, appendEvent, readSession, workRoot } from '../sessions.mjs'
+import { recordUsage, markLimited, WARN_PCT } from '../usage.mjs'
+import { writeJsonAtomic } from '../fsx.mjs'
+import { LAYOUT } from '../accounts.mjs'
+
+const HOOK = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'hook.mjs')
+const q = (p) => `"${String(p).replace(/\\/g, '\\\\')}"`
+
+// The user's own statusLine command, if any, so it keeps running.
+export function userStatusLine(configDir = LAYOUT.claude.home()) {
+  for (const f of ['settings.json', 'settings.local.json']) {
+    const p = join(configDir, f)
+    if (!existsSync(p)) continue
+    try {
+      const s = JSON.parse(readFileSync(p, 'utf8'))
+      if (s.statusLine?.type === 'command' && s.statusLine.command) return s.statusLine
+    } catch {}
+  }
+  return null
+}
+
+export function settingsFor(sessionId, { statusLine = null } = {}) {
+  const cmd = (kind) => ({ type: 'command', command: `node ${q(HOOK)} ${kind} --session ${sessionId}`, timeout: 20 })
+  const settings = {
+    hooks: {
+      SessionStart: [{ hooks: [cmd('claude-hook')] }],
+      UserPromptSubmit: [{ hooks: [cmd('claude-hook')] }],
+      PostToolUse: [{ matcher: 'Edit|Write|MultiEdit|NotebookEdit', hooks: [cmd('claude-hook')] }],
+      Stop: [{ hooks: [cmd('claude-hook')] }],
+      StopFailure: [{ hooks: [cmd('claude-hook')] }],
+      SessionEnd: [{ hooks: [cmd('claude-hook')] }],
+    },
+    statusLine: { type: 'command', command: `node ${q(HOOK)} claude-statusline --session ${sessionId}`, padding: statusLine?.padding ?? 0 },
+    // Baton owns the limit: it hands the work to the next option instead of
+    // waiting in the session for the reset.
+    autoContinueAtUsageLimit: false,
+  }
+  return settings
+}
+
+export function writeSettings(sessionId, opts) {
+  const file = join(sessionDir(sessionId), 'claude-settings.json')
+  writeJsonAtomic(file, settingsFor(sessionId, opts))
+  return file
+}
+
+function textOf(content) {
+  if (typeof content === 'string') return content
+  if (Array.isArray(content)) return content.filter((c) => c?.type === 'text' && c.text).map((c) => c.text).join('\n')
+  return ''
+}
+
+// Last human/assistant messages from a Claude Code transcript (jsonl).
+export function transcriptTail(path, limit = 8) {
+  if (!path || !existsSync(path)) return []
+  const out = []
+  for (const line of readFileSync(path, 'utf8').split('\n')) {
+    if (!line) continue
+    let j
+    try { j = JSON.parse(line) } catch { continue }
+    if (j.type !== 'user' && j.type !== 'assistant') continue
+    if (j.isSidechain) continue
+    const text = textOf(j.message?.content).trim()
+    if (!text || /^<[a-z-]+>/.test(text)) continue
+    out.push({ role: j.type, text: text.slice(0, 1500), ts: j.timestamp ?? null })
+  }
+  return out.slice(-limit)
+}
+
+export function firstPrompt(path) {
+  const t = transcriptTail(path, 1000).find((m) => m.role === 'user')
+  return t ? t.text.slice(0, 500) : null
+}
+
+function limitsFrom(rl) {
+  if (!rl) return null
+  const w = (x) => (x && Number.isFinite(x.used_percentage) ? { pct: x.used_percentage, resets_at: x.resets_at ?? null } : null)
+  return { five_hour: w(rl.five_hour), seven_day: w(rl.seven_day) }
+}
+
+// Hook payload → session record. Returns a short line for the hook log.
+export function handleHook(sessionId, p) {
+  const s = readSession(sessionId)
+  if (!s) return 'no session'
+  const base = { agent_session_id: p.session_id ?? s.agent_session_id, transcript_path: p.transcript_path ?? s.transcript_path, last_activity: new Date().toISOString() }
+  switch (p.hook_event_name) {
+    case 'SessionStart':
+      // reducer: one hook process per tool call, so read `cur` inside the lock
+      updateSession(sessionId, (cur) => ({ ...base, status: cur.status === 'starting' ? 'running' : cur.status }), { event: { type: 'agent_ready', summary: `claude session ${p.session_id ?? '?'} (${p.source ?? 'startup'})` } })
+      return 'session start'
+    case 'UserPromptSubmit': {
+      updateSession(sessionId, (cur) => ({ ...base, task: cur.task ?? (p.prompt ? String(p.prompt).slice(0, 500) : null), turns: (cur.turns ?? 0) + 1 }), { event: { type: 'turn', summary: `prompt: ${String(p.prompt ?? '').slice(0, 120)}` } })
+      return 'prompt'
+    }
+    case 'PostToolUse': {
+      const file = p.tool_input?.file_path ?? p.tool_input?.notebook_path ?? null
+      if (!file) return 'tool (no file)'
+      const rel = relTo(workRoot(s), file)
+      // reducer: concurrent Edit/Write hooks each add their own file without
+      // the last writer overwriting the others' additions
+      updateSession(sessionId, (cur) => ({ ...base, files_touched: cur.files_touched.includes(rel) ? cur.files_touched : [...cur.files_touched, rel].slice(-200) }))
+      return `touched ${rel}`
+    }
+    case 'Stop':
+      // reducer: never turn a 'limit'/'handing_off' back to 'running' by racing
+      updateSession(sessionId, (cur) => ({ ...base, status: cur.status === 'starting' ? 'running' : cur.status }), { event: { type: 'turn_done', summary: String(p.last_assistant_message ?? '').slice(0, 160) || 'turn done' } })
+      return 'stop'
+    case 'StopFailure': {
+      if (p.error === 'rate_limit') {
+        // a simulated wall (baton sessions simulate-limit) clears after two minutes so a test never walls the real login for hours
+        const simulated = Boolean(p.leg_simulated || p.baton_simulated)
+        const u = markLimited('claude', s.account, { reason: 'rate_limit', source: simulated ? 'leg simulate-limit' : 'claude StopFailure', resets_at: simulated ? Math.floor(Date.now() / 1000) + 120 : null })
+        updateSession(sessionId, { ...base, status: 'limit', limit: { reason: 'rate_limit', detail: String(p.last_assistant_message ?? p.error_details ?? '').slice(0, 300), resets_at: u.limited_until, at: new Date().toISOString(), simulated } }, { event: { type: 'limit', summary: `claude usage limit${simulated ? ' (simulated)' : ''}: ${String(p.last_assistant_message ?? p.error_details ?? '').slice(0, 160)}` } })
+        return 'LIMIT'
+      }
+      appendEvent(sessionId, { type: 'error', summary: `claude ${p.error}: ${String(p.last_assistant_message ?? p.error_details ?? '').slice(0, 160)}` })
+      updateSession(sessionId, base)
+      return `error ${p.error}`
+    }
+    case 'SessionEnd':
+      updateSession(sessionId, { ...base, agent_exit_reason: p.reason ?? null }, { event: { type: 'agent_exit', summary: `claude session ended (${p.reason ?? 'unknown'})` } })
+      return 'session end'
+    default:
+      updateSession(sessionId, base)
+      return p.hook_event_name ?? 'unknown'
+  }
+}
+
+export function relTo(root, file) {
+  const a = String(file).replace(/\\/g, '/')
+  const r = String(root ?? '').replace(/\\/g, '/').replace(/\/$/, '')
+  return r && a.toLowerCase().startsWith(r.toLowerCase() + '/') ? a.slice(r.length + 1) : a
+}
+
+// Status line: record the limits and print. Returns the text to print.
+export function handleStatusline(sessionId, p) {
+  const s = readSession(sessionId)
+  if (!s) return { text: '', limits: null }
+  const limits = limitsFrom(p.rate_limits)
+  if (limits) recordUsage('claude', s.account, limits, 'claude statusline')
+  const hot = limits ? [['5h', limits.five_hour], ['7d', limits.seven_day]].filter(([, w]) => w).sort((a, b) => b[1].pct - a[1].pct)[0] : null
+  const warn = hot && hot[1].pct >= WARN_PCT
+  // reducer: the status-line hook is its own process; only nudge running↔warning
+  // from `cur`, so it never overwrites a 'limit' a StopFailure set at the same time
+  updateSession(sessionId, (cur) => {
+    const patch = { last_activity: new Date().toISOString() }
+    if (limits) patch.limits = limits
+    if (p.session_id && !cur.agent_session_id) patch.agent_session_id = p.session_id
+    if (p.transcript_path && !cur.transcript_path) patch.transcript_path = p.transcript_path
+    if (warn && !cur.warning) patch.warning = { window: hot[0], pct: hot[1].pct, resets_at: hot[1].resets_at, at: new Date().toISOString() }
+    if (!warn && cur.warning) patch.warning = null
+    if (warn && cur.status === 'running') patch.status = 'warning'
+    if (!warn && cur.status === 'warning') patch.status = 'running'
+    return patch
+  }, warn && !s.warning ? { event: { type: 'warning', summary: `claude ${hot[0]} window at ${Math.round(hot[1].pct)}%` } } : {})
+  const next = s.chain?.[0] ? `${s.chain[0].agent}${s.chain[0].account !== 'default' ? '/' + s.chain[0].account : ''}` : 'nothing'
+  const pct = limits ? ` 5h ${limits.five_hour ? Math.round(limits.five_hour.pct) + '%' : '-'} · 7d ${limits.seven_day ? Math.round(limits.seven_day.pct) + '%' : '-'}` : ''
+  const text = warn ? `⚠ leg: ${hot[0]} at ${Math.round(hot[1].pct)}% → next ${next}${pct}` : `leg ·${pct || ' limits pending'} · next ${next} · board ${s.board_url ?? ''}`
+  return { text, limits, warn }
+}