@ucsandman/legcli 0.10.0 → 0.12.0

package/src/sessions.mjs

@@ -48,15 +48,31 @@ export function isActive(s) { return ACTIVE.includes(s?.status) }
 // it one (repo stays the main checkout, for grouping and landing), else the repo.
 export function workRoot(s) { return s?.worktree?.path ?? s?.repo ?? s?.cwd ?? null }
 
-export function createSession({ id, agent, account = 'default', cwd, repo = null, branch = null, argv = [], runner_pid = process.pid, chain = [], worktree = null, owner = null, handoffOrder = AGENTS, installed = null, runtimeCapabilities = [] }) {
+export function createSession({ id, agent, account = 'default', cwd, repo = null, branch = null, argv = [], runner_pid = process.pid, chain = [], worktree = null, owner = null, handoffOrder = AGENTS, installed = null, runtimeCapabilities = [], model = null }) {
   const session = {
     session_id: id, agent, account, cwd, repo, branch, argv, worktree, owner,
     repo_name: repo ? repo.split(/[\\/]/).filter(Boolean).pop() : null,
+    // the model this leg resolved to: the `--model`/`-m` the human passed, else
+    // null. Never a guessed default — a printed model nobody chose is a wrong
+    // number in disguise. For claude the runner refreshes it from the
+    // transcript's per-assistant-line `message.model`, so a silent fallback off
+    // Fable becomes visible on the row (docs/redesign-2026-09-17.md B.1).
+    model,
+    // what this terminal is waiting for, or null. Two shapes, told apart by
+    // `type`: `{ type: 'reset', agent, account, resets_at, since }` is the
+    // all-out countdown the runner writes (src/attach.mjs), and
+    // `{ type: 'permission_prompt'|'idle_prompt'|'agent_needs_input'|'quota_auto_resume', message, since }`
+    // is a human being waited on, from Claude Code's Notification hook.
+    waiting: null,
     status: 'starting', runner_pid, pid: null,
     started_at: now(), updated_at: now(), ended_at: null, last_activity: now(),
     agent_session_id: null, transcript_path: null,
     task: null, turns: 0,
     files_touched: [], files_dirty: [], head: null, head_at_start: null,
+    // commits this checkout is ahead of its upstream (else of head_at_start),
+    // refreshed by the runner's git poll. null until it has been counted, and
+    // null again whenever it cannot be: never a zero standing in for unknown.
+    ahead: null,
     limits: null, limit: null, warning: null,
     bundle: null, handoff: null, chain, checkpoints: [],
     handoff_order: normalizeHandoffOrder(handoffOrder), installed,

package/src/share.mjs

@@ -6,15 +6,29 @@
 // (`BATON_PERSON`, else the owner). With it off nothing changes: loopback is
 // open and `BATON_TOKEN` is the only token.
 import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'
-import { existsSync, readFileSync, mkdirSync } from 'node:fs'
+import { existsSync, readFileSync, mkdirSync, statSync } from 'node:fs'
 import { networkInterfaces, userInfo } from 'node:os'
 import { createSocket } from 'node:dgram'
 import { join } from 'node:path'
 import { home } from './store.mjs'
 import { writeJsonAtomic } from './fsx.mjs'
 
-export const OFF = { version: 1, on: false, bind: null, bind_kind: null, port: null, owner: null, people: [] }
-export const ROLES = ['owner', 'guest']
+export const OFF = { version: 1, on: false, bind: null, bind_kind: null, port: null, owner: null, people: [], tls: null }
+
+// Three roles, because two were not enough to describe a second human who runs
+// cards on this machine but has no business in its settings or its project map.
+//   owner     everything: machine settings, the harness, every terminal, cards
+//   operator  the pipeline board and their own terminals; not the settings,
+//             not the history index, not anyone else's terminal
+//   guest     the terminals lane, read-only and redacted; may ask for a hand-off
+export const ROLES = ['owner', 'operator', 'guest']
+
+// One place that says what a role may reach, so no endpoint decides for itself.
+// `cards` is the pipeline side of the board. `machine` is everything that
+// describes this computer rather than the work: the settings, the harness
+// policy, the history index and the worktree map.
+export function mayUseCards(role) { return role === 'owner' || role === 'operator' }
+export function mayUseMachine(role) { return role === 'owner' }
 
 export function sharePath() { return join(home(), 'share.json') }
 
@@ -55,9 +69,49 @@ export function identify(share, presented) {
 export function personNamed(share, name) { return share.people.find((p) => p.name.toLowerCase() === String(name ?? '').toLowerCase()) ?? null }
 export function isOwner(person) { return person?.role === 'owner' }
 
+// ---- TLS ----
+// Leg does not make certificates. It uses a pair you already have, which on a
+// Tailscale network is one command (`tailscale cert <machine>.<tailnet>.ts.net`)
+// and gives a certificate browsers already trust. A self-signed pair would
+// teach everyone on the board to click through a warning, which is worse than
+// no TLS at all on a network that is already private.
+export class TlsRefused extends Error {
+  constructor(msg) { super(msg); this.name = 'TlsRefused'; this.exitCode = 3 }
+}
+
+function tlsPaths(share, env) {
+  return {
+    cert: env.LEG_TLS_CERT || env.BATON_TLS_CERT || share?.tls?.cert || null,
+    key: env.LEG_TLS_KEY || env.BATON_TLS_KEY || share?.tls?.key || null,
+  }
+}
+
+// → { cert, key, cert_path, key_path } | null. Throws TlsRefused when a pair is
+// configured but unusable: a board that quietly fell back to plaintext after
+// being told to use TLS is the one failure this must not have.
+export function readTls(share = readShare(), env = process.env) {
+  const { cert: certPath, key: keyPath } = tlsPaths(share, env)
+  if (!certPath && !keyPath) return null
+  if (!certPath || !keyPath) throw new TlsRefused('TLS needs both a certificate and a key (--tls-cert and --tls-key, or LEG_TLS_CERT and LEG_TLS_KEY)')
+  for (const [label, file] of [['certificate', certPath], ['key', keyPath]]) {
+    if (!existsSync(file)) throw new TlsRefused(`TLS ${label} not found: ${file}`)
+    try { statSync(file) } catch (err) { throw new TlsRefused(`TLS ${label} ${file}: ${err.message}`) }
+  }
+  let cert
+  let key
+  try { cert = readFileSync(certPath) } catch (err) { throw new TlsRefused(`TLS certificate ${certPath}: ${err.message}`) }
+  try { key = readFileSync(keyPath) } catch (err) { throw new TlsRefused(`TLS key ${keyPath}: ${err.message}`) }
+  if (!cert.length || !key.length) throw new TlsRefused('the TLS certificate or key is empty')
+  return { cert, key, cert_path: certPath, key_path: keyPath }
+}
+
+export function tlsConfigured(share = readShare(), env = process.env) { return Boolean(tlsPaths(share, env).cert) }
+
+export function scheme(share = readShare(), env = process.env) { return tlsConfigured(share, env) ? 'https' : 'http' }
+
 export function addPerson(name, { role = 'guest', share = readShare() } = {}) {
   if (!validName(name)) throw new Error(`bad name "${name}": letters, digits, dash and underscore, up to 32 characters`)
-  if (!ROLES.includes(role)) throw new Error(`bad role "${role}" (owner|guest)`)
+  if (!ROLES.includes(role)) throw new Error(`bad role "${role}" (${ROLES.join('|')})`)
   if (personNamed(share, name)) throw new Error(`"${name}" is already on the board; baton share rotate ${name} issues a new link`)
   const token = newToken()
   const person = { name, role, token_sha256: hashToken(token), created_at: new Date().toISOString(), last_seen: null }
@@ -122,7 +176,7 @@ export async function resolveBind(kind = 'tailscale') {
   return lan.address
 }
 
-export function linkFor(share, token) { return `http://${share.bind}:${share.port}/?token=${token}` }
+export function linkFor(share, token) { return `${scheme(share)}://${share.bind}:${share.port}/?token=${token}` }
 
 // Whose terminal this is: BATON_PERSON, else the board's owner, else 'local'.
 export function whoami(share = readShare()) {
@@ -131,9 +185,15 @@ export function whoami(share = readShare()) {
   return share.owner || 'local'
 }
 
-export async function turnOn({ bind = 'tailscale', port = Number(process.env.LEG_PORT || process.env.BATON_PORT || 4747), owner } = {}) {
+export async function turnOn({ bind = 'tailscale', port = Number(process.env.LEG_PORT || process.env.BATON_PORT || 4747), owner, tlsCert = null, tlsKey = null } = {}) {
   const share = readShare()
   const address = await resolveBind(bind)
+  if (tlsCert || tlsKey) {
+    if (!tlsCert || !tlsKey) throw new TlsRefused('TLS needs both --tls-cert and --tls-key')
+    share.tls = { cert: tlsCert, key: tlsKey }
+    // read the pair now, so a bad one fails here and not at the next board start
+    readTls(share, {})
+  }
   share.on = true
   share.bind = address
   share.bind_kind = ['tailscale', 'lan'].includes(String(bind).toLowerCase()) ? String(bind).toLowerCase() : 'address'

package/src/taps/claude-usage.mjs

@@ -14,6 +14,7 @@ import http from 'node:http'
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { LAYOUT } from '../accounts.mjs'
+import { MODEL_ALIASES } from '../buckets.mjs'
 
 export const USAGE_URL = (process.env.LEG_CLAUDE_USAGE_URL || process.env.BATON_CLAUDE_USAGE_URL) || 'https://api.anthropic.com/api/oauth/usage'
 
@@ -37,6 +38,87 @@ function window(x) {
   return { pct, resets_at: resets }
 }
 
+function epoch(x) {
+  if (x === null || x === undefined) return null
+  if (typeof x === 'number') return Number.isFinite(x) ? Math.floor(x > 1e12 ? x / 1000 : x) : null
+  const t = Date.parse(x)
+  return Number.isFinite(t) ? Math.floor(t / 1000) : null
+}
+
+// The model a limit row is scoped to, lowercased, or null when the row is an
+// account-wide bucket. The endpoint is undocumented, so the scope is read by
+// shape (a `model` object carrying a display name) rather than by a type word.
+// A display name carries a version the rest of Leg never says ("Fable 5.1",
+// "Claude Opus 5"), and every other model name in the system is an alias: the
+// walls (src/buckets.mjs), the rungs (src/preferences.mjs) and the board all
+// join on one. So the name is matched word by word against the alias list and
+// the alias is what is stored; a name Leg does not know keeps its own
+// lowercased text, because inventing a model is worse than printing an unknown
+// one.
+function scopeModel(scope) {
+  const name = scope?.model?.display_name ?? scope?.model?.displayName ?? null
+  if (typeof name !== 'string' || !name.trim()) return null
+  const raw = name.trim().toLowerCase()
+  for (const alias of MODEL_ALIASES.claude) {
+    if (raw.split(/[^a-z0-9]+/).includes(alias)) return alias
+  }
+  return raw
+}
+
+function groupOf(kind) {
+  const k = String(kind ?? '')
+  if (k.startsWith('weekly')) return 'weekly'
+  if (k.startsWith('session') || k.startsWith('five_hour')) return 'session'
+  if (k.startsWith('spend') || k.startsWith('extra')) return 'spend'
+  return k || 'unknown'
+}
+
+// One `limits[]` row → a bucket. Percentages only: what a row *means* (whether
+// a model switch helps) is decided in src/buckets.mjs from the wall wording,
+// never from a number.
+export function bucketOf(x) {
+  if (!x || typeof x !== 'object') return null
+  const kind = x.type ?? x.kind ?? x.name ?? null
+  if (!kind) return null
+  const percent = Number(x.utilization ?? x.used_percentage ?? x.used_percent ?? x.percent)
+  if (!Number.isFinite(percent)) return null
+  return {
+    kind: String(kind),
+    group: groupOf(kind),
+    model: scopeModel(x.scope),
+    percent,
+    resets_at: epoch(x.resets_at ?? x.resetsAt ?? null),
+    is_active: Boolean(x.is_active ?? x.isActive ?? false),
+    severity: typeof x.severity === 'string' ? x.severity : 'normal',
+  }
+}
+
+export function bucketsFrom(j) {
+  if (!Array.isArray(j?.limits)) return []
+  return j.limits.map(bucketOf).filter(Boolean)
+}
+
+// `extra_usage` / `spend`, the two sentences the capacity drawer prints. Only
+// the fields that exist are carried; the eighteen codename keys the payload
+// also holds (tangelo, iguana_necktie, ...) are never read.
+export function extraUsageFrom(j) {
+  const e = j?.extra_usage
+  const s = j?.spend
+  if ((!e || typeof e !== 'object') && (!s || typeof s !== 'object')) return null
+  const out = {}
+  const enabled = e?.is_enabled ?? e?.enabled
+  if (typeof enabled === 'boolean') out.enabled = enabled
+  const reason = e?.disabled_reason ?? e?.reason
+  if (typeof reason === 'string') out.reason = reason
+  const canToggle = s?.can_toggle ?? e?.can_toggle
+  if (typeof canToggle === 'boolean') out.can_toggle = canToggle
+  const limitMinor = Number(e?.monthly_limit ?? e?.limit ?? s?.monthly_limit)
+  if (Number.isFinite(limitMinor)) out.limit_minor = limitMinor
+  const usedMinor = Number(e?.monthly_used ?? e?.used ?? s?.monthly_used ?? s?.used)
+  if (Number.isFinite(usedMinor)) out.used_minor = usedMinor
+  return Object.keys(out).length ? out : null
+}
+
 function getJson(url, headers, timeoutMs) {
   return new Promise((resolvePromise) => {
     const u = new URL(url)
@@ -54,7 +136,12 @@ function getJson(url, headers, timeoutMs) {
   })
 }
 
-// → { ok, limits: {five_hour, seven_day}|null, status, error, expired }
+// → { ok, limits: {five_hour, seven_day, buckets, extra_usage}|null, status, error, expired }
+// The two windows keep their shape and their place: every older reader of this
+// function still gets exactly what it got before. `buckets` is OMITTED when the
+// payload has no `limits` array, which is what an older endpoint answers: that
+// is no information about buckets, and recordUsage's `Array.isArray` guard then
+// leaves the last measured ones in place instead of erasing them.
 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 }
@@ -63,5 +150,7 @@ export async function fetchClaudeUsage({ configDir = LAYOUT.claude.home(), timeo
   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) }
+  const limits = { five_hour: window(j.five_hour), seven_day: window(j.seven_day), extra_usage: extraUsageFrom(j) }
+  if (Array.isArray(j.limits)) limits.buckets = bucketsFrom(j)
+  return { ok: true, limits, status: r.status, expired: t.expired, raw_keys: Object.keys(j) }
 }

package/src/taps/claude.mjs

@@ -5,12 +5,14 @@
 // 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 { existsSync, readFileSync, openSync, closeSync, fstatSync, readSync } 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 { bucketFromWall, MODEL_ALIASES } from '../buckets.mjs'
 import { writeJsonAtomic } from '../fsx.mjs'
+import { readPreferences } from '../preferences.mjs'
 import { LAYOUT } from '../accounts.mjs'
 
 const HOOK = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'hook.mjs')
@@ -29,6 +31,19 @@ export function userStatusLine(configDir = LAYOUT.claude.home()) {
   return null
 }
 
+// The four Notification types Leg acts on, as one matcher. Notification
+// "matches on notification type" and, not being FileChanged or StopFailure,
+// takes `|` as the alternation separator (hooks doc lines 173, 165, 1424).
+// The other eight types (auth_success, the elicitation family, agent_completed,
+// quota_auto_resume_stale, quota_auto_resume_disabled) say nothing about a
+// human being waited on, so they never start a hook process.
+export const WAITING_TYPES = ['permission_prompt', 'idle_prompt', 'agent_needs_input']
+export const NOTIFY_MATCHER = [...WAITING_TYPES, 'quota_auto_resume_fired'].join('|')
+// Claude Code waiting at the limit by itself. Leg sets autoContinueAtUsageLimit
+// false, but the human's own settings can re-enable it; two waiters on one
+// terminal is the failure to avoid, so Leg stands down and the row says so.
+export const QUOTA_STAND_DOWN = 'Claude Code is waiting at the limit itself; Leg is not handing this one off.'
+
 export function settingsFor(sessionId, { statusLine = null } = {}) {
   const cmd = (kind) => ({ type: 'command', command: `node ${q(HOOK)} ${kind} --session ${sessionId}`, timeout: 20 })
   const settings = {
@@ -36,6 +51,7 @@ export function settingsFor(sessionId, { statusLine = null } = {}) {
       SessionStart: [{ hooks: [cmd('claude-hook')] }],
       UserPromptSubmit: [{ hooks: [cmd('claude-hook')] }],
       PostToolUse: [{ matcher: 'Edit|Write|MultiEdit|NotebookEdit', hooks: [cmd('claude-hook')] }],
+      Notification: [{ matcher: NOTIFY_MATCHER, hooks: [cmd('claude-hook')] }],
       Stop: [{ hooks: [cmd('claude-hook')] }],
       StopFailure: [{ hooks: [cmd('claude-hook')] }],
       SessionEnd: [{ hooks: [cmd('claude-hook')] }],
@@ -84,6 +100,58 @@ export function transcriptTail(path, limit = 8) {
   return messagesFromLines(readFileSync(path, 'utf8').split('\n'), limit)
 }
 
+// A model id from a CLI (`claude-fable-5-1`) said as the name the ladder, the
+// picker and the row use (`fable`). An id that matches no alias is kept raw:
+// printing a model Leg does not recognise is honest, inventing one is not.
+export function modelAlias(agent, id) {
+  const raw = String(id ?? '').trim()
+  if (!raw) return null
+  for (const alias of MODEL_ALIASES[agent] ?? []) {
+    // whitespace is a separator too: a display name reads "Claude Opus 5" where
+    // a CLI id reads "claude-opus-5", and both name the same rung
+    if (new RegExp(`(?:^|[-_\\s])${alias}(?:$|[-_.\\s])`, 'i').test(raw)) return alias
+  }
+  return raw
+}
+
+// The model that actually answered, from the transcript's per-assistant-line
+// `message.model` (VERIFIED: 29 assistant lines of the newest jsonl for this
+// repo carry "claude-fable-5-1"). This is how a silent fallback off Fable
+// becomes visible, so it reads the file itself rather than trusting the argv.
+//
+// Two Windows facts shape the read. The file is appended to while Claude Code
+// runs, so a read can land mid-write: it is retried, and a torn last line is
+// dropped by the per-line JSON.parse rather than failing the whole read. And
+// mtime is not a content clock here, so nothing is skipped on a timestamp — the
+// tail is read every time and the answer is whatever the bytes say.
+export function modelFromTranscript(path, { agent = 'claude', tailBytes = 262144, attempts = 3 } = {}) {
+  if (!path || !existsSync(path)) return null
+  for (let i = 0; i < attempts; i++) {
+    let fd = null
+    try {
+      fd = openSync(path, 'r')
+      const size = fstatSync(fd).size
+      const want = Math.min(size, tailBytes)
+      const buf = Buffer.alloc(want)
+      readSync(fd, buf, 0, want, size - want)
+      const lines = buf.toString('utf8').split('\n')
+      // a partial first line when the tail starts mid-file, a partial last line
+      // when the writer is mid-append: both are dropped by the parse below
+      for (let k = lines.length - 1; k >= 0; k--) {
+        let j
+        try { j = JSON.parse(lines[k]) } catch { continue }
+        if (j?.type !== 'assistant') continue
+        const id = j.message?.model
+        if (id) return modelAlias(agent, id)
+      }
+      return null
+    } catch {
+      // EBUSY / EPERM / a share violation while Claude Code writes: try again
+    } finally { if (fd !== null) try { closeSync(fd) } catch {} }
+  }
+  return null
+}
+
 export function firstPrompt(path) {
   const t = transcriptTail(path, 1000).find((m) => m.role === 'user')
   return t ? t.text.slice(0, 500) : null
@@ -95,6 +163,40 @@ function limitsFrom(rl) {
   return { five_hour: w(rl.five_hour), seven_day: w(rl.seven_day) }
 }
 
+// The all-out countdown the runner owns (src/attach.mjs) also lives on
+// `waiting`. A Notification never overwrites it: while that is set the child is
+// already dead and nobody is being waited on in the terminal.
+const humanWait = (w) => Boolean(w) && w.type !== 'reset'
+const clearHumanWait = (cur) => (humanWait(cur.waiting) ? { waiting: null } : {})
+
+// What the hook prints back to Claude Code. `terminalSequence` is emitted by
+// Claude Code itself on events that discard systemMessage and continue, which
+// Notification is (hooks doc lines 608, 622, 1490); OSC 9 is the desktop
+// notification Windows Terminal renders (line 617). Restricted to the OSC
+// 0/1/2/9/99/777 allowlist, so anything in the message that could close or open
+// a sequence is dropped rather than risking the whole field being ignored (608).
+// Every control byte out, ESC and BEL included: one of them inside the message
+// would close the sequence Leg is building and open whatever followed it.
+// Written as a scan rather than a regex because a control-character class is
+// exactly what the linter stops, and for good reason.
+// The C1 range (U+0080 to U+009F) goes out with C0 and DEL: on a terminal that
+// decodes C1 from UTF-8, U+009C is ST and closes the sequence Leg is building,
+// and U+009D is OSC and opens whatever follows it. That is the same hazard as a
+// raw ESC or BEL, in two bytes instead of one.
+export const printable = (s) => [...String(s ?? '')].map((c) => {
+  const cp = c.codePointAt(0)
+  return cp < 0x20 || (cp >= 0x7f && cp <= 0x9f) ? ' ' : c
+}).join('')
+
+export function terminalSequenceFor(p, { preferences = null } = {}) {
+  if (p?.hook_event_name !== 'Notification') return null
+  if (!WAITING_TYPES.includes(String(p.notification_type ?? ''))) return null
+  const prefs = preferences ?? readPreferences()
+  if (!prefs.notify_terminal) return null
+  const text = printable(p.message).trim().slice(0, 160)
+  return `\x1b]9;${text || 'leg: this terminal is waiting on you'}\x07`
+}
+
 // Hook payload → session record. Returns a short line for the hook log.
 export function handleHook(sessionId, p) {
   const s = readSession(sessionId)
@@ -106,7 +208,8 @@ export function handleHook(sessionId, p) {
       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)}` } })
+      // the human typed, so whatever was being waited on has been answered
+      updateSession(sessionId, (cur) => ({ ...base, ...clearHumanWait(cur), 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': {
@@ -118,16 +221,52 @@ export function handleHook(sessionId, p) {
       updateSession(sessionId, (cur) => ({ ...base, files_touched: cur.files_touched.includes(rel) ? cur.files_touched : [...cur.files_touched, rel].slice(-200) }))
       return `touched ${rel}`
     }
+    case 'Notification': {
+      const type = String(p.notification_type ?? '')
+      const since = new Date().toISOString()
+      // reducer, and the hazard the status-line handler documents: this hook is
+      // its own process and a StopFailure can be writing `status: 'limit'` in
+      // the same moment. Only `waiting` is touched from `cur` inside the lock —
+      // never status, never limit — so a Notification can never erase a wall.
+      if (type === 'quota_auto_resume_fired') {
+        updateSession(sessionId, (cur) => ({ ...base, waiting: cur.waiting?.type === 'reset' ? cur.waiting : { type: 'quota_auto_resume', message: QUOTA_STAND_DOWN, since } }),
+          { event: { type: 'status', summary: QUOTA_STAND_DOWN } })
+        return 'notify quota_auto_resume'
+      }
+      if (!WAITING_TYPES.includes(type)) { updateSession(sessionId, base); return `notify ${type || 'unknown'}` }
+      // the question verbatim: a paraphrase of what an agent is asking for is
+      // the one thing a human cannot check against the terminal in front of them
+      const message = String(p.message ?? '').slice(0, 160)
+      updateSession(sessionId, (cur) => ({ ...base, waiting: cur.waiting?.type === 'reset' ? cur.waiting : { type, message, since } }),
+        { event: { type: 'waiting', summary: `waiting on you (${type}): ${message}` } })
+      return `notify ${type}`
+    }
     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' } })
+      updateSession(sessionId, (cur) => ({ ...base, ...clearHumanWait(cur), 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)}` } })
+        const detail = String(p.last_assistant_message ?? p.error_details ?? '').slice(0, 300)
+        // which bucket the wording walled: one model family, or the whole
+        // login. Unrecognised wording walls the login (src/buckets.mjs rule 5).
+        const hit = bucketFromWall('claude', p.last_assistant_message)
+        // markLimited takes the same cross-process lock recordUsage does, so a
+        // percentage arriving from the poller in this same moment cannot erase
+        // the wall this hook is writing (that race handed the baton straight
+        // back to a walled login).
+        const u = markLimited('claude', s.account, {
+          reason: hit.scope === 'model' ? 'model_limit' : 'rate_limit',
+          source: simulated ? 'leg simulate-limit' : 'claude StopFailure',
+          resets_at: simulated ? Math.floor(Date.now() / 1000) + 120 : null,
+          scope: hit.scope,
+          model: hit.model ?? null,
+          evidence: detail,
+        })
+        const resets = hit.scope === 'model' ? (u.walls?.[hit.model]?.limited_until ?? null) : u.limited_until
+        updateSession(sessionId, { ...base, status: 'limit', limit: { reason: 'rate_limit', detail, resets_at: resets, at: new Date().toISOString(), simulated, scope: hit.scope, model: hit.model ?? null } }, { event: { type: 'limit', summary: `claude usage limit${simulated ? ' (simulated)' : ''}${hit.scope === 'model' ? ` (${hit.model})` : ''}: ${detail.slice(0, 160)}` } })
         return 'LIMIT'
       }
       appendEvent(sessionId, { type: 'error', summary: `claude ${p.error}: ${String(p.last_assistant_message ?? p.error_details ?? '').slice(0, 160)}` })

package/src/taps/codex.mjs

@@ -155,6 +155,20 @@ export function normalizeRateLimits(rateLimits) {
   return out
 }
 
+// What the rollout says about the account in words rather than percentages:
+// the plan it is on and the credit balance it prints. Measured, carried
+// through untouched, and never summed with anything: they are strings from
+// codex, not a figure Leg computed. Observed live in the newest rollout
+// (plan_type "prolite", credits.balance "0").
+export function factsFromRateLimits(rateLimits) {
+  const out = {}
+  const plan = rateLimits?.plan_type ?? rateLimits?.planType
+  if (typeof plan === 'string' && plan) out.plan_type = plan
+  const balance = rateLimits?.credits?.balance
+  if (typeof balance === 'string' || typeof balance === 'number') out.credits_balance = String(balance)
+  return out
+}
+
 function parseRetryAt(msg) {
   const m = RETRY_AT_RE.exec(msg ?? '')
   if (!m) return null
@@ -165,16 +179,21 @@ function parseRetryAt(msg) {
 
 // lines → { limits, limit, messages, turnsDone, taskStarted, threadId }
 export function parseLines(lines) {
-  const out = { limits: null, limits_at: null, limit: null, messages: [], turnsDone: 0, taskStarted: 0, threadId: null, files: [] }
+  const out = { limits: null, limits_at: null, limit: null, messages: [], turnsDone: 0, taskStarted: 0, threadId: null, files: [], facts: {} }
   for (const line of lines) {
     let j
     try { j = JSON.parse(line) } catch { continue }
     const p = j.payload ?? {}
-    if (j.type === 'session_meta') { out.threadId = p.id ?? null; continue }
+    if (j.type === 'session_meta') {
+      out.threadId = p.id ?? null
+      if (typeof p.model === 'string' && p.model) out.facts.model = p.model
+      continue
+    }
     if (j.type === 'event_msg') {
       if (p.type === 'token_count' && p.rate_limits) {
         out.limits = normalizeRateLimits(p.rate_limits)
         out.limits_at = j.timestamp ?? null
+        Object.assign(out.facts, factsFromRateLimits(p.rate_limits))
       } else if (p.type === 'task_started') out.taskStarted += 1
       else if (p.type === 'task_complete') {
         out.turnsDone += 1
@@ -265,8 +284,9 @@ export function readCodexUsage({ codexHome = LAYOUT.codex.home(), timeoutMs = 80
           if (message.error || !message.result) return stop('codex rate-limit read failed')
           const snapshot = message.result.rateLimitsByLimitId?.codex ?? message.result.rateLimits
           const limits = normalizeRateLimits(snapshot)
+          const facts = factsFromRateLimits(snapshot)
           const available = typeof message.result.ordinaryUsageAllowed === 'boolean' ? message.result.ordinaryUsageAllowed : null
-          return finish({ ok: available !== null || Boolean(limits.five_hour || limits.seven_day), limits, available, observed_at: new Date().toISOString(), error: null })
+          return finish({ ok: available !== null || Boolean(limits.five_hour || limits.seven_day), limits, facts, available, observed_at: new Date().toISOString(), error: null })
         }
       }
     })

package/src/taps/grok.mjs

@@ -183,6 +183,10 @@ const LIMIT_RES = [
   ['grok-rate-limit-event', /"rate_limit"/i],
   ['grok-free-usage-exhausted', /subscription:free-usage-exhausted|You've used all of your free queries/i],
   ['grok-too-many-requests', /TOO_MANY_REQUESTS/],
+  // Observed live 2026-09-17 on grok 1.0.34: an account with no balance left
+  // answers 402, never 429, and none of the strings above appear. Without this
+  // the terminal sat on an exhausted login instead of handing off.
+  ['grok-balance-exhausted', /usage balance exhausted|status 402 Payment Required/i],
 ]
 
 // Scans log or stream text for Grok rate limit signals.