@ucsandman/legcli 0.11.0 → 0.13.0

package/src/board/strip.js

@@ -0,0 +1,163 @@
+// The capacity strip: one 44px band, one token per login, and the bucket that
+// will actually stop the work printed in it.
+//
+// THIS FILE OWNS THE STRIP. The board draws it under the verdict and the floor
+// draws it under the masthead, and a strip written twice is a percentage that
+// can read two ways on two pages, which is the defect the strip exists to fix.
+// src/board/sessions.js and src/board/floor.js keep the names (capFigure,
+// capToken, bindingOf and the rest) and delegate here; nothing in either file
+// draws a token itself.
+//
+// The three board scripts have no module system, so the page hands its own
+// primitives over with use(): el(), the login labels and the time grammar are
+// owned by sessions.js (and carried, character for character, by floor.js), so
+// this file never grows a third copy of them.
+(function () {
+  'use strict'
+
+  // { el, accountLabel, idOf, acctState, worstWindow, until, clockAt, spoken }
+  let H = null
+  function use(helpers) { H = helpers || H; return api }
+
+  // ---- the binding bucket -------------------------------------------------
+  // The bucket that will actually stop the work: the one the endpoint marked
+  // active, else the highest percentage it reported, else the legacy hottest of
+  // the two windows, which is all an older record or a guest payload carries.
+  // Mirrors binding() in src/usage.mjs; the board cannot import from it.
+  const BUCKET_WORD = { weekly_scoped: 'week', weekly_all: 'week', session: 'session', spend: 'spend', seven_day: '7d', five_hour: '5h' }
+  function bindingOf(a) {
+    const buckets = Array.isArray(a && a.buckets) ? a.buckets.filter((b) => b && Number.isFinite(b.percent)) : []
+    const top = (l) => (l.length ? [...l].sort((x, y) => y.percent - x.percent)[0] : null)
+    const b = top(buckets.filter((x) => x.is_active)) || top(buckets)
+    if (b) return { kind: b.kind, model: b.model || null, percent: b.percent, resets_at: Number.isFinite(b.resets_at) ? b.resets_at : null, scope: b.model ? 'model' : 'account' }
+    const w = H.worstWindow(a)
+    if (!w || !Number.isFinite(w.pct)) return null
+    return { kind: a && a.seven_day === w ? 'seven_day' : 'five_hour', model: null, percent: w.pct, resets_at: Number.isFinite(w.resets_at) ? w.resets_at : null, scope: 'account' }
+  }
+  // the token's two words: `fable week`, `week`, `session`, `5h`
+  function bucketWord(b) { const word = BUCKET_WORD[b.kind] || b.kind; return b.model ? `${b.model} ${word}` : word }
+  // the same bucket inside a sentence: "63% of its week"
+  function windowPhrase(b) { return b.kind === 'session' ? 'its session' : b.kind === 'five_hour' ? 'its 5 hours' : 'its week' }
+  // every model this login has published anything about. A model named by
+  // neither a bucket nor a wall is one Leg has never seen, and it is never
+  // guessed at.
+  function knownModels(a) {
+    const out = []
+    for (const b of (a && a.buckets) || []) if (b && b.model && !out.includes(b.model)) out.push(b.model)
+    for (const m of Object.keys((a && a.walls) || {})) if (!out.includes(m)) out.push(m)
+    return out
+  }
+  function wallFor(a, model) {
+    const w = a && a.walls ? a.walls[model] : null
+    return w && Number.isFinite(w.limited_until) && w.limited_until * 1000 > Date.now() ? w : null
+  }
+  function walledModels(a) { return knownModels(a).filter((m) => wallFor(a, m)) }
+
+  // ---- one token ----------------------------------------------------------
+  function capFigure(a, b) {
+    // the same two refusals the gauge prints, in the strip's shorter grammar
+    if (a.shared === false) return 'not shared'
+    if (a.loading) return 'reading'
+    if (H.acctState(a) === 'walled') return Number.isFinite(a.limited_until) ? `back ${H.until(a.limited_until)}` : 'back when it resets'
+    // agy publishes no percentage, ever; a login that has one and has not
+    // reported it yet is a different fact and says so.
+    if (!b) return a.agent === 'agy' ? 'no figure' : 'no reading'
+    const observed = Date.parse(a.observed_at || a.updated_at || '')
+    // a reading older than the window it describes prints the clock it was
+    // taken at instead of a bucket word: it is a measurement, not a reading now
+    if (a.stale && a.agent !== 'agy' && Number.isFinite(observed)) return `${Math.round(b.percent)}% ${H.clockAt(observed)}`
+    return `${Math.round(b.percent)}% ${bucketWord(b)}`
+  }
+  // the spoken sentence carries what the visible token cannot: the reset, the
+  // source, the wall and the age of the reading, exactly as the gauges do.
+  function capValueText(a, b) {
+    const parts = []
+    if (a.shared === false) parts.push(`Usage for ${H.accountLabel(a)} is not shared with guests.`)
+    else if (!b) {
+      parts.push(a.agent === 'agy'
+        ? 'agy publishes no usage percentage, ever. Leg sees the wall when agy hits it.'
+        : `No reading has come back from ${H.accountLabel(a)} yet.`)
+    } else {
+      parts.push(`${Math.round(b.percent)} percent of ${b.model ? `the ${b.model} ${BUCKET_WORD[b.kind] || b.kind}` : windowPhrase(b)} used.`)
+      if (Number.isFinite(b.resets_at)) parts.push(`Resets at ${H.until(b.resets_at)}, in ${H.spoken(b.resets_at * 1000 - Date.now())}.`)
+    }
+    if (H.acctState(a) === 'walled') parts.push(`${H.accountLabel(a)} is at its wall until ${H.until(a.limited_until)}, in ${H.spoken(a.limited_until * 1000 - Date.now())}.`)
+    for (const m of walledModels(a)) parts.push(`${m} is out until ${H.until(wallFor(a, m).limited_until)}.`)
+    if (a.source) parts.push(`Source: ${a.source}.`)
+    const observed = Date.parse(a.observed_at || a.updated_at || '')
+    if (a.stale && a.agent !== 'agy' && Number.isFinite(observed)) parts.push(`Read at ${H.clockAt(observed)}, ${H.spoken(Date.now() - observed)} ago, stale.`)
+    return parts.join(' ')
+  }
+  function capToken(a) {
+    const el = H.el
+    const id = H.idOf(a.agent)
+    const b = bindingOf(a)
+    const walled = H.acctState(a) === 'walled'
+    const pct = b ? Math.max(0, Math.min(100, Math.round(b.percent))) : null
+    const token = el('span', { class: 'cap-token' }, [
+      el('span', { class: `dot id-${id}`, 'aria-hidden': 'true' }),
+      el('span', { class: `cap-name id-${id}` }, [H.accountLabel(a)]),
+    ])
+    // no number, no instrument. A track with nothing in it is a reading of zero
+    // to anyone glancing at it, which is exactly what agy does not have.
+    if (pct !== null || walled) {
+      const stop = pct !== null && pct > 85 ? `${((85 / pct) * 100).toFixed(2)}%` : null
+      const fill = el('span', {
+        class: 'cap-fill',
+        style: walled ? 'width:100%;background:var(--danger)'
+          : stop ? `width:${pct}%;background:linear-gradient(to right,var(--id-${id}) 0 ${stop},var(--danger) ${stop} 100%)`
+            : `width:${pct}%;background:var(--id-${id})`,
+      })
+      // a walled login with no percentage is not a meter: 100 would be a number
+      // nobody measured. It keeps the track and carries the sentence instead.
+      const semantics = pct === null
+        ? { role: 'img', 'aria-label': `${H.accountLabel(a)} capacity. ${capValueText(a, b)}` }
+        : { role: 'meter', 'aria-valuemin': '0', 'aria-valuemax': '100', 'aria-valuenow': String(pct), 'aria-label': `${H.accountLabel(a)} capacity`, 'aria-valuetext': capValueText(a, b) }
+      token.appendChild(el('span', { class: 'cap-track', ...semantics }, [fill]))
+    }
+    // with no track the figure carries the whole sentence itself, the way the
+    // gauge's readout does when a window has never been read
+    const quiet = pct === null && !walled ? { role: 'img', 'aria-label': `${H.accountLabel(a)} capacity. ${capValueText(a, b)}` } : {}
+    token.appendChild(el('span', { class: `cap-figure${walled ? ' is-out' : ''}${pct === null && !walled ? ' cap-figure--none' : ''}`, ...quiet }, [capFigure(a, b)]))
+    return token
+  }
+  function capacityStrip(list) {
+    const box = document.getElementById('capacity-tokens')
+    if (!box) return
+    box.textContent = ''
+    for (const a of list || []) box.appendChild(capToken(a))
+  }
+
+  // ---- the disclosure the login panels live behind ------------------------
+  // Whether it is open is the reader's decision, kept across reloads and shared
+  // by both pages: opening it on the board and finding it shut on the floor is
+  // the same fact answering two ways. localStorage throws in a private window
+  // and on a page opened from a file, so it is never load bearing.
+  const CAP_KEY = 'legCapacityOpen'
+  let capacityOpen = (() => { try { return localStorage.getItem(CAP_KEY) === '1' } catch { return false } })()
+  function renderCapacityToggle() {
+    const btn = document.getElementById('capacity-toggle')
+    const drawer = document.getElementById('capacity-drawer')
+    if (btn) {
+      btn.setAttribute('aria-expanded', capacityOpen ? 'true' : 'false')
+      btn.textContent = capacityOpen ? 'Hide capacity and models' : 'Capacity and models >'
+    }
+    if (drawer) drawer.hidden = !capacityOpen
+  }
+  function toggleCapacity() {
+    capacityOpen = !capacityOpen
+    try { localStorage.setItem(CAP_KEY, capacityOpen ? '1' : '0') } catch { /* private window: the drawer still opens, it just does not remember */ }
+    renderCapacityToggle()
+  }
+
+  const api = {
+    use, BUCKET_WORD, bindingOf, bucketWord, windowPhrase, knownModels, wallFor, walledModels,
+    capFigure, capValueText, capToken, capacityStrip, renderCapacityToggle, toggleCapacity,
+    isCapacityOpen: () => capacityOpen,
+  }
+
+  if (typeof window !== 'undefined') window.legStrip = api
+  // test seam: node:test runs this file with a stub document, the way the other
+  // board scripts are run; in a browser there is no `module`
+  if (typeof module !== 'undefined') module.exports = api
+})()

package/src/buckets.mjs

@@ -0,0 +1,101 @@
+// buckets — the one place per-model knowledge lives: the wording a CLI uses
+// when it walls a single model, the model names Leg is willing to say out
+// loud, and the flag each CLI spells its model with.
+// Why one file: the same three facts were about to be needed by the usage
+// record (which wall goes where), the taps (what a StopFailure message meant)
+// and argv building (`--model` vs `-m`). Split across those, a reworded wall
+// or a new alias would have to be fixed in three places and would be found by
+// whichever one was missed. Nothing here reads or writes state.
+//
+// Sources for the wording table: docs/en/costs ("You've hit your Opus limit",
+// session and weekly limits shared across models), the live StopFailure in
+// fixtures/live/claude/limit-rate_limit.json ("You've reached your Fable
+// limit."), and docs/cli-contracts.md:464 for codex ("usage limit for {name}",
+// docs-only: no live codex per-model wall has been captured).
+// Flags: verified in the adapters — src/adapters/claude.mjs:29 and agy.mjs:34
+// push `--model`, codex.mjs:42 and grok.mjs:45 push `-m`.
+
+// Model names per agent, lowercase, in ladder order (strongest first).
+// Only claude publishes per-model buckets today; the others take a model on
+// the command line but expose no per-model limit, so their lists stay empty
+// rather than carrying a guess.
+export const MODEL_ALIASES = {
+  claude: ['fable', 'opus', 'sonnet', 'haiku'],
+  codex: [],
+  agy: [],
+  grok: [],
+}
+
+const MODEL_FLAGS = { claude: '--model', agy: '--model', fake: '--model', codex: '-m', grok: '-m' }
+
+// The flag this agent's CLI spells a model with, or null when Leg does not
+// know it. A null answer means "do not pass a model", never "guess --model".
+export function modelFlagFor(agent) {
+  return MODEL_FLAGS[agent] ?? null
+}
+
+// Where a model sits on its agent's own list: 0 is the strongest. -1 means Leg
+// does not know the name, and an unknown name is never called stronger or
+// weaker than anything.
+export function modelRank(agent, model) {
+  if (!model) return -1
+  return (MODEL_ALIASES[agent] ?? []).indexOf(String(model).toLowerCase())
+}
+
+// A downshift is a move to a weaker model of the SAME login. It is the only
+// move `claude --resume <id> --model <alias>` is used for: the probe in
+// fixtures/live/claude/resume-model-probe.json shows the conversation survives
+// and only the new model answers, but the context is re-read at the new model's
+// rate (cache read 0 on the first resumed turn), so an upshift back to fable
+// would pay that re-read at fable's price and takes the bundle instead.
+export function isDownshift(from, to) {
+  if (!from || !to) return false
+  if (from.agent !== to.agent || (from.account ?? 'default') !== (to.account ?? 'default')) return false
+  const a = modelRank(from.agent, from.model)
+  const b = modelRank(to.agent, to.model)
+  return a >= 0 && b >= 0 && b > a
+}
+
+const SESSION_OR_WEEKLY = /(session|weekly) limit/i
+const SPEND_WALL = /spend limit/i
+const CODEX_MODEL_WALL = /usage limit for ([\w .-]+)/i
+
+// "You've hit your Fable limit" / "You've reached your Opus limit". Built from
+// the agent's own alias list, so codex's "You've hit your usage limit" can
+// never be read as a model called "usage": a name Leg does not know falls
+// through to rule 5 and walls the login.
+function modelWallRe(agent) {
+  const names = MODEL_ALIASES[agent] ?? []
+  if (!names.length) return null
+  return new RegExp(`You.ve (?:hit|reached) your (${names.join('|')}) limit`, 'i')
+}
+
+// What a wall message walled. Ordered; the first rule that matches wins.
+//   { scope: 'account' }                      the whole login is out
+//   { scope: 'account', bucket: 'spend' }     the spend cap, not a window
+//   { scope: 'model', model: 'fable' }        one model family only
+// Unrecognised wording is 'account' on purpose: walling the whole login is the
+// direction that fails safe when the wording is reworded again, which it
+// already was once ("hit" became "reached").
+export function bucketFromWall(agent, text) {
+  const s = String(text ?? '')
+  // 1. session and weekly limits are shared across every model (docs/en/costs),
+  //    so switching model buys nothing: the account is out.
+  if (SESSION_OR_WEEKLY.test(s)) return { scope: 'account' }
+  // 2. "You've hit/reached your <Model> limit" — one family.
+  const re = modelWallRe(agent)
+  const m = re ? re.exec(s) : null
+  if (m) return { scope: 'model', model: m[1].toLowerCase() }
+  // 3. the spend cap is an account fact, and it is not a window.
+  if (SPEND_WALL.test(s)) return { scope: 'account', bucket: 'spend' }
+  // 4. codex names the limit it hit (docs-only wording). The name runs to the
+  //    end of the sentence, so cut at the first period that ends one: a model
+  //    name's own dots (gpt-5.6-sol) are never followed by a space.
+  const c = CODEX_MODEL_WALL.exec(s)
+  if (c) {
+    const model = c[1].split(/\.(?=\s|$)/)[0].trim().toLowerCase()
+    if (model) return { scope: 'model', model }
+  }
+  // 5. anything else: the whole login.
+  return { scope: 'account' }
+}

package/src/cards.mjs

@@ -38,7 +38,12 @@ function kv(raw) {
   return m
 }
 
-export async function createCard(input, actor = { type: 'human', id: 'local' }) {
+// `allowPipelineFile` is false for anything that arrives over HTTP. A pipeline
+// that is a filesystem path is a CLI convenience (`--pipeline ./my.json`);
+// taken from a request body it is an arbitrary read of this machine, and the
+// JSON parser's own message quotes the first bytes of whatever it opened, so a
+// 400 would hand a non-owner the contents of a file they may not see.
+export async function createCard(input, actor = { type: 'human', id: 'local' }, { allowPipelineFile = true } = {}) {
   if (!input.repo) throw new CardInputError('missing repo')
   // stored as given (resolved); every comparison below is canonical, and the
   // worktree path is derived from the real long form in src/worktree.mjs
@@ -93,6 +98,9 @@ export async function createCard(input, actor = { type: 'human', id: 'local' })
     if (Array.isArray(pipelineArg)) pipeline = buildPipeline({ stations: pipelineArg, chain })
     else if (typeof pipelineArg === 'string' && pipelineArg.trim().startsWith('[')) pipeline = buildPipeline({ stations: JSON.parse(pipelineArg), chain })
     else if (PRESET_NAMES.includes(pipelineArg)) pipeline = buildPipeline({ preset: pipelineArg, chain })
+    // the refusal names the presets and never the value it was handed: a
+    // message that quoted the path back would still answer "does this exist"
+    else if (!allowPipelineFile) throw new Error(`pipeline must be one of the presets (${PRESET_NAMES.join(', ')}) or a list of stations`)
     else pipeline = buildPipeline({ file: pipelineArg, chain })
     validatePipeline(pipeline, await loadAdapterModes())
   } catch (err) {

package/src/chain.mjs

@@ -31,6 +31,7 @@ export const TRANSITIONS = [
   ['running', 'land:bounced', 'queued', 'land red/conflict → bounce to build with the failure attached (phase 7)'],
   ['running', 'land:failed', 'failed', 'land attempts exhausted (phase 7)'],
   ['running', 'pause', 'paused', 'human: kill the child, write a bundle'],
+  ['*non-terminal*', 'take_over', 'paused', 'human: sits down in the card\'s worktree themselves; the child is killed and the card leaves the runnable set'],
   ['paused', 'resume', 'queued', 'human: same station and leg; prompt = bundle load + contract'],
   ['*non-terminal*', 'kill', 'killed', 'human'],
   ['*non-terminal*', 'reassign', 'queued', 'human: rewrite the current station\'s chain from the current leg'],
@@ -196,6 +197,18 @@ export function transition(card, action, payload = {}) {
       events.push(ev('paused', 'paused by human'))
       return { card: { ...card, status: 'paused' }, events }
     }
+    // Take over: a human opens an interactive terminal in this card's worktree.
+    // `pause` is legal from `running` alone, so a queued or handing_off card
+    // stayed in the set the scheduler starts from and a leg was launched into
+    // the checkout the human had just been handed. Legal from every
+    // non-terminal status, and it always lands on `paused`, which is the one
+    // state that is both out of the scheduler's reach and honest about what
+    // the card is doing: nothing, because a person has it.
+    case 'take_over': {
+      assertStatus(card, action, NON_TERMINAL)
+      events.push(ev('taken_over', `taken over by a human at ${card.station} leg ${card.leg} (was ${card.status})`))
+      return { card: { ...card, status: 'paused' }, events }
+    }
     case 'resume': {
       assertStatus(card, action, ['paused'])
       events.push(ev('resumed', `resumed at ${card.station} leg ${card.leg}`))

package/src/hook.mjs

@@ -9,7 +9,7 @@
 // (2.1.268 does not; see src/taps/claude-usage.mjs) and prints one Leg line.
 import { appendFileSync } from 'node:fs'
 import { join } from 'node:path'
-import { handleHook, handleStatusline } from './taps/claude.mjs'
+import { handleHook, handleStatusline, terminalSequenceFor } from './taps/claude.mjs'
 import { sessionDir } from './sessions.mjs'
 import { captureLive } from './live-capture.mjs'
 
@@ -40,6 +40,12 @@ try {
     if (payload.hook_event_name === 'StopFailure' && payload.error) {
       try { captureLive('claude', String(payload.error), payload, { sessionId }) } catch {}
     }
+    // Notification hooks cannot block or modify anything and their
+    // systemMessage is discarded, but Claude Code still emits terminalSequence
+    // for them (hooks doc 1490, 622). That is the toast, and it is the only
+    // thing this process prints on stdout for a hook.
+    const seq = terminalSequenceFor(payload)
+    if (seq) process.stdout.write(JSON.stringify({ terminalSequence: seq }) + '\n')
   } else if (kind === 'claude-statusline') {
     const { text } = handleStatusline(sessionId, payload)
     try { appendFileSync(join(sessionDir(sessionId), 'hook.log'), `${new Date().toISOString()} statusline rate_limits=${JSON.stringify(payload.rate_limits ?? null)}\n`) } catch {}

package/src/ledger.mjs

@@ -16,14 +16,22 @@ import { dashclawConfig, record } from './sync/dashclaw.mjs'
 export const EVENT_TYPES = ['card_created', 'leg_started', 'leg_progress', 'leg_exited',
   'limit_detected', 'handoff_written', 'leg_resumed', 'station_done', 'bounced', 'landed',
   'land_warning', 'land_retry', 'blocked_by', 'scheduler_started', 'scheduler_stopped',
-  'approval_needed', 'approved', 'reassigned', 'paused', 'resumed', 'killed', 'done',
+  'approval_needed', 'approved', 'reassigned', 'paused', 'resumed', 'taken_over', 'killed', 'done',
   'failed', 'error', 'status', 'harness', 'harness_blocked']
 export const STATUSES = ['backlog', 'queued', 'running', 'handing_off', 'waiting_human',
   'needs_approval', 'paused', 'done', 'failed', 'killed']
 const CLOSED = ['done', 'failed', 'killed']
 // card.json keys `update --patch` may set (everything else goes through a named flag)
 export const PATCHABLE = ['pipeline', 'leases', 'land_attempts', 'land_mode', 'test_command', 'title', 'trunk',
-  'bounce_reason', 'kill_requested', 'worktree', 'next_leg', 'handoff_outcome', 'resume_from_bundle', 'failure', 'last_bundle', 'pr_url', 'harness']
+  'bounce_reason', 'kill_requested', 'worktree', 'next_leg', 'handoff_outcome', 'resume_from_bundle', 'failure', 'last_bundle', 'pr_url', 'harness',
+  // where this card came from ({ from: <terminal id> } after "End, and keep
+  // going as a card"), and whether its worktree was adopted from that terminal
+  // rather than cut for the card: the orchestrator must not cut a second one
+  // over the top of it (redesign G4)
+  // the branch that checkout is actually on: `leg/<card-id>` for one the card
+  // cut, the TERMINAL's branch for one it adopted, which is not a name the
+  // board can derive from the card id (redesign C.3's register)
+  'lineage', 'worktree_adopted', 'worktree_branch']
 const NAME_RE = /^[a-z0-9][a-z0-9._-]{0,39}$/i
 
 export const ROOT = process.env.LEG_HOME || process.env.BATON_HOME || (existsSync(join(homedir(), '.leg')) ? join(homedir(), '.leg') : existsSync(join(homedir(), '.baton')) ? join(homedir(), '.baton') : join(homedir(), '.leg'))

package/src/models.mjs

@@ -0,0 +1,265 @@
+// models: the model catalog each CLI already publishes, read from where that
+// CLI keeps it rather than from a list Leg maintains by hand.
+//
+// Why not a table in this file: three of the four catalogs move under Leg's
+// feet. codex rewrites ~/.codex/models_cache.json whenever it refreshes from
+// the service, agy and grok print theirs from their own accounts, and a name
+// hard-coded here would be a wrong answer the week after it was written. Only
+// claude's list is static, and it is static because those four words are
+// aliases Claude Code itself resolves (src/buckets.mjs MODEL_ALIASES), not
+// service-side model ids.
+//
+// Sources, each verified on this machine on 2026-09-18:
+//   claude  MODEL_ALIASES.claude, labelled; no default (Claude Code picks one)
+//   codex   <CODEX_HOME>/models_cache.json models[] where visibility == "list",
+//           default from `model = "..."` at the top of <CODEX_HOME>/config.toml
+//   agy     `agy models`, tab-separated `id<TAB>label` after a "Fetching" line
+//   grok    `grok models`, "Default model: X" then "  * id (default)" / "  - id"
+//
+// agy and grok cost a process each, so their answers are cached under
+// <LEG_HOME>/models/<agent>.json for an hour and a request is never made to
+// wait on one: a stale or missing cache is served as-is and the refresh runs
+// behind the answer.
+import { execFile } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { home } from './store.mjs'
+import { writeJsonAtomic } from './fsx.mjs'
+import { MODEL_ALIASES } from './buckets.mjs'
+import { LAYOUT } from './accounts.mjs'
+import agyAdapter from './adapters/agy.mjs'
+import grokAdapter from './adapters/grok.mjs'
+
+export const MODEL_AGENTS = ['claude', 'codex', 'agy', 'grok']
+
+// A model id is pushed onto an agent's argv (`-m <id>`), so the shape is the
+// boundary: letters, digits and the four separators the four catalogs actually
+// use. Anything else (a space, a quote, a leading dash, a path separator) is
+// a flag or a path in disguise and is dropped by the parser rather than
+// corrected, because a corrected id is a model nobody published.
+//
+// Lower case only, and that is a constraint on the catalogs rather than a
+// preference: `normalizeRung` in src/preferences.mjs lower-cases a rung's model
+// before it validates it, so an id with a capital in it would be offered in a
+// select here and then handed to the CLI in a spelling the CLI never published.
+// All 23 ids the four catalogs publish on this machine today are lower case
+// (codex slugs, agy ids, grok bullets, claude's aliases), so nothing is lost;
+// if one ever is not, it is missing from the select, which is visible, rather
+// than silently mangled on a command line, which is not.
+const MODEL_ID_RE = /^[a-z0-9][a-z0-9._:-]{0,63}$/
+
+export function validModelId(id) {
+  return MODEL_ID_RE.test(String(id ?? ''))
+}
+
+const CACHE_MS = 60 * 60 * 1000
+const PROBE_TIMEOUT_MS = 20_000
+
+// ---- parsers: pure, one fixture each under fixtures/models/ ----------------
+
+// "fable" -> "Claude Fable". The alias is what the CLI takes; the label is
+// what a human reads in a select.
+function claudeLabel(alias) {
+  return `Claude ${alias.charAt(0).toUpperCase()}${alias.slice(1)}`
+}
+
+// claude's list never leaves this process: the aliases are Claude Code's own.
+// No default: `claude` with no `--model` picks for itself, and naming one here
+// would be Leg inventing a choice the human did not make.
+export function claudeModels() {
+  return MODEL_ALIASES.claude.filter(validModelId).map((id) => ({ id, label: claudeLabel(id), default: false }))
+}
+
+// models_cache.json plus config.toml. `visibility` is codex's own word for
+// which models it offers a human: "hide" covers gpt-reserve and the internal
+// codex-auto-review, neither of which is a model to start a leg on.
+export function parseCodexModels(cacheText, configText = '') {
+  let parsed = null
+  try { parsed = JSON.parse(String(cacheText ?? '')) } catch { return [] }
+  const rows = Array.isArray(parsed?.models) ? parsed.models : []
+  const preferred = parseCodexDefault(configText)
+  const out = []
+  for (const m of rows) {
+    if (m?.visibility !== 'list') continue
+    const id = String(m?.slug ?? '')
+    if (!validModelId(id)) continue
+    out.push({ id, label: String(m?.display_name || id), default: id === preferred })
+  }
+  return out
+}
+
+// `model = "gpt-6-astra"` at the top level of config.toml. A `model` key inside
+// a `[profiles.x]` table is that profile's, not the one a bare `codex` uses, so
+// the scan stops at the first table header.
+//
+// A trailing `# ...` is ordinary TOML and common in that file, so it is allowed
+// after the closing quote: anchoring at end of line made `model = "gpt-5-codex"
+// # the fast one` read as no default at all, and the board then offered a
+// generic "provider default" for a codex that has one.
+export function parseCodexDefault(configText) {
+  for (const raw of String(configText ?? '').split(/\r?\n/)) {
+    const line = raw.trim()
+    if (line.startsWith('#') || !line) continue
+    if (line.startsWith('[')) break
+    const m = /^model\s*=\s*["']([^"']+)["']\s*(?:#.*)?$/.exec(line)
+    if (m && validModelId(m[1])) return m[1]
+  }
+  return null
+}
+
+// `agy models` prints a progress line first and then one `id<TAB>label` per
+// model. A line with no tab is progress, not a model.
+export function parseAgyModels(stdout) {
+  const out = []
+  for (const raw of String(stdout ?? '').split(/\r?\n/)) {
+    const tab = raw.indexOf('\t')
+    if (tab <= 0) continue
+    const id = raw.slice(0, tab).trim()
+    if (!validModelId(id)) continue
+    out.push({ id, label: raw.slice(tab + 1).trim() || id, default: false })
+  }
+  return out
+}
+
+// `grok models` prints "Default model: X", then a bullet per model with the
+// default marked. grok publishes no display name, so the id is the label.
+export function parseGrokModels(stdout) {
+  const text = String(stdout ?? '')
+  const declared = /^\s*Default model:\s*(\S+)\s*$/m.exec(text)
+  const preferred = declared && validModelId(declared[1]) ? declared[1] : null
+  const out = []
+  for (const raw of text.split(/\r?\n/)) {
+    const m = /^\s*[*-]\s+(\S+)\s*(\(default\))?\s*$/.exec(raw)
+    if (!m || !validModelId(m[1])) continue
+    out.push({ id: m[1], label: m[1], default: m[1] === preferred || Boolean(m[2]) })
+  }
+  return out
+}
+
+// ---- codex: files, read every time (they are two small local reads) --------
+
+function codexHome() {
+  return process.env.CODEX_HOME || LAYOUT.codex.home()
+}
+
+function readIfPresent(file) {
+  try { return existsSync(file) ? readFileSync(file, 'utf8') : '' } catch { return '' }
+}
+
+export function codexModels() {
+  const dir = codexHome()
+  return parseCodexModels(readIfPresent(join(dir, 'models_cache.json')), readIfPresent(join(dir, 'config.toml')))
+}
+
+// ---- agy and grok: a process, cached ---------------------------------------
+
+export function modelsCacheFile(agent) {
+  return join(home(), 'models', `${agent}.json`)
+}
+
+function readCache(agent) {
+  try {
+    const value = JSON.parse(readFileSync(modelsCacheFile(agent), 'utf8'))
+    if (!Array.isArray(value?.models)) return null
+    return { models: value.models.filter((m) => validModelId(m?.id)).map((m) => ({ id: String(m.id), label: String(m.label ?? m.id), default: m.default === true })), observed_at: value.observed_at ?? null, attempted_at: value.attempted_at ?? null }
+  } catch { return null }
+}
+
+// `observed_at` is when a list was last SEEN, `attempted_at` when the probe was
+// last RUN. They part company on a fruitless probe: an agent that is not
+// installed prints nothing, and without the attempt stamp that answer left no
+// cache entry at all, so every board page load, every New card dialog and every
+// floor load spawned a fresh `agy models` and `grok models` for the same
+// nothing. The attempt is cached; the last list Leg really saw is kept.
+function writeCache(agent, models, { observedAt = new Date().toISOString(), attemptedAt = new Date().toISOString() } = {}) {
+  try {
+    mkdirSync(join(home(), 'models'), { recursive: true })
+    writeJsonAtomic(modelsCacheFile(agent), { models, observed_at: observedAt, attempted_at: attemptedAt })
+  } catch { /* a catalog that cannot be cached is still a catalog */ }
+}
+
+// The binary each adapter already resolves, so a probe runs the same agy or
+// grok a leg would, including the LEG_AGY_BIN / LEG_GROK_BIN test seams. No
+// shell: the argv is fixed, and a shell here would be one more thing between
+// Leg and a list of names.
+const PROBES = {
+  agy: { adapter: agyAdapter, args: ['models'], parse: parseAgyModels },
+  grok: { adapter: grokAdapter, args: ['models'], parse: parseGrokModels },
+}
+
+function probeArgv(probe) {
+  const { bin, viaNode } = probe.adapter.resolve()
+  return viaNode ? { bin: process.execPath, args: [bin, ...probe.args] } : { bin, args: [...probe.args] }
+}
+
+// One refresh per agent in flight at a time. Two board tabs opening at once
+// used to be two `agy models` processes for the same answer.
+const inFlight = new Map()
+
+function stale(entry) {
+  if (!entry) return true
+  const ms = (v) => { const n = Date.parse(v ?? ''); return Number.isFinite(n) ? n : -Infinity }
+  // the newer of the two stamps: a probe that answered nothing an hour ago is
+  // due again, and one that answered nothing a second ago is not
+  const at = Math.max(ms(entry.observed_at), ms(entry.attempted_at))
+  return !Number.isFinite(at) || Date.now() - at >= CACHE_MS
+}
+
+// Runs the probe and caches what it prints. Never throws: an agent that is not
+// installed, is not logged in, or hangs leaves the cache exactly as it was.
+export function refreshModels(agent) {
+  const probe = PROBES[agent]
+  if (!probe) return Promise.resolve(readCache(agent)?.models ?? [])
+  if (inFlight.has(agent)) return inFlight.get(agent)
+  const run = new Promise((resolve) => {
+    let spec
+    try { spec = probeArgv(probe) } catch { resolve(readCache(agent)?.models ?? []); return }
+    execFile(spec.bin, spec.args, { timeout: PROBE_TIMEOUT_MS, windowsHide: true, encoding: 'utf8', maxBuffer: 1 << 20 }, (_err, stdout) => {
+      // a non-zero exit still prints the list when the CLI is only
+      // unauthenticated (grok says so and lists anyway), so stdout is parsed
+      // before the exit code is believed
+      const models = probe.parse(stdout ?? '')
+      const prev = readCache(agent)
+      // a fruitless probe is still an answer about this machine: it is stamped
+      // so the next request is served from here instead of spawning again, and
+      // the last list Leg did see is kept until a probe supersedes it
+      if (models.length) writeCache(agent, models)
+      else writeCache(agent, prev?.models ?? [], { observedAt: prev?.observed_at ?? null })
+      resolve(models.length ? models : (prev?.models ?? []))
+    })
+  }).finally(() => inFlight.delete(agent))
+  inFlight.set(agent, run)
+  return run
+}
+
+// The cached answer, with a refresh kicked off behind it when it is stale.
+// Synchronous on purpose: no board request waits on a child process.
+function cachedModels(agent) {
+  const entry = readCache(agent)
+  if (stale(entry)) refreshModels(agent).catch(() => {})
+  return entry?.models ?? []
+}
+
+// ---- the catalog ------------------------------------------------------------
+
+// Every model this machine can start `agent` on, strongest or default first as
+// that agent's own source orders them. An empty list is an honest answer: it
+// means Leg could not read a catalog, and the caller offers "provider default".
+export function modelsFor(agent) {
+  if (agent === 'claude') return claudeModels()
+  if (agent === 'codex') return codexModels()
+  if (agent === 'agy' || agent === 'grok') return cachedModels(agent)
+  return []
+}
+
+export function listModels() {
+  const models = {}
+  for (const agent of MODEL_AGENTS) models[agent] = modelsFor(agent)
+  return { models, observed_at: new Date().toISOString() }
+}
+
+// The model a bare `leg <agent>` would run, or null when the agent picks for
+// itself. Used to label the first option of a model select.
+export function defaultModelFor(agent) {
+  return modelsFor(agent).find((m) => m.default)?.id ?? null
+}