@ucsandman/legcli 0.12.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/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
+}

package/src/preferences.mjs

@@ -73,6 +73,29 @@ export function validRungAccount(agent, account) {
   return null
 }
 
+// A rung's model reaches the agent's argv as `--model <id>` or `-m <id>`, so
+// the first question is shape, not membership: a value with a space, a quote,
+// a leading dash or a path separator in it is a flag or a path in disguise.
+//
+// Membership is asked of claude alone. MODEL_ALIASES.claude is a CLOSED list:
+// four words Claude Code resolves itself, not service-side ids, so a fifth
+// word there is a typo and saying so is help. The other three catalogs are
+// live (src/models.mjs reads codex's cache file and asks agy and grok), they
+// gain and lose names between Leg releases, and a list frozen in this file
+// would refuse tomorrow's model with "Leg knows no model names for it" while
+// the CLI next to it ran it happily. Their ids are checked for shape and then
+// believed: the CLI itself is the authority on its own catalog, and it answers
+// an id it does not have in one line on the leg's own log.
+const RUNG_MODEL_RE = /^[a-z0-9][a-z0-9._:-]{0,63}$/
+
+export function validRungModel(agent, model) {
+  const id = String(model ?? '')
+  if (!RUNG_MODEL_RE.test(id)) return `rung "model" must be a model id of letters, digits, . _ : and - (got "${model}")`
+  const closed = MODEL_ALIASES[agent] ?? []
+  if (closed.length && !closed.includes(id)) return `${agent} has no model "${id}" (${closed.join(', ')})`
+  return null
+}
+
 export function normalizeRung(value) {
   const agent = String(value?.agent ?? '')
   const model = value?.model === undefined || value?.model === null || value?.model === '' ? null : String(value.model).toLowerCase()
@@ -119,10 +142,8 @@ export function requireHandoffLadder(value) {
     const rung = normalizeRung(raw)
     const badAccount = validRungAccount(rung.agent, rung.account)
     if (badAccount) throw new TypeError(badAccount)
-    if (rung.model && !(MODEL_ALIASES[rung.agent] ?? []).includes(rung.model)) {
-      const known = (MODEL_ALIASES[rung.agent] ?? []).join(', ')
-      throw new TypeError(`${rung.agent} has no model "${rung.model}"${known ? ` (${known})` : ': Leg knows no model names for it'}`)
-    }
+    const badModel = rung.model ? validRungModel(rung.agent, rung.model) : null
+    if (badModel) throw new TypeError(badModel)
     if (raw.when !== undefined && !(typeof raw.when === 'string' && WHEN_RE.test(raw.when))) throw new TypeError(`rung "when" must be always, below:N or walled-only (got "${raw.when}")`)
     if (raw.cost !== undefined && !RUNG_COSTS.includes(raw.cost)) throw new TypeError(`rung "cost" must be one of ${RUNG_COSTS.join(', ')}`)
     const key = rungKey(rung)
@@ -144,11 +165,38 @@ export function orderFromLadder(ladder) {
   return out.filter((a) => wanted.includes(a))
 }
 
+// One bad rung is one bad rung. `requireHandoffLadder` throws on the first
+// problem it meets, and catching that threw the whole ladder away: a user who
+// mistyped one claude alias in a file docs/configuration.md invites them to
+// hand-edit lost their three good rungs with it, silently, and their terminals
+// then handed off somewhere they never asked for. The same swallow fired for a
+// rung naming an account that has since been removed, which is a live check.
+//
+// → { ladder, dropped }, where a dropped rung keeps the reason it was refused.
+export function salvageHandoffLadder(value) {
+  const ladder = []
+  const dropped = []
+  const seen = new Set()
+  for (const raw of Array.isArray(value) ? value : []) {
+    let rung = null
+    try { [rung] = requireHandoffLadder([raw]) } catch (err) { dropped.push({ rung: raw, why: err.message }); continue }
+    const k = rungKey(rung)
+    if (seen.has(k)) { dropped.push({ rung: raw, why: `handoff_ladder names ${rung.agent}/${rung.account}${rung.model ? '/' + rung.model : ''} twice` }); continue }
+    seen.add(k)
+    ladder.push(rung)
+  }
+  return { ladder, dropped }
+}
+
 // The ladder a preferences object means: its own, else the long-hand form of
 // its `handoff_order`, else the default ladder.
 export function normalizeHandoffLadder(prefs) {
   const value = Array.isArray(prefs) ? prefs : prefs?.handoff_ladder
-  if (Array.isArray(value) && value.length) { try { return requireHandoffLadder(value) } catch { /* fall through to the order */ } }
+  if (Array.isArray(value) && value.length) {
+    const { ladder } = salvageHandoffLadder(value)
+    if (ladder.length) return ladder
+    /* nothing readable left: fall through to the order */
+  }
   if (!Array.isArray(prefs) && validHandoffOrder(prefs?.handoff_order)) return ladderFromOrder(prefs.handoff_order)
   if (Array.isArray(prefs)) return defaultLadder()
   return defaultLadder()
@@ -258,6 +306,12 @@ const defaults = () => {
   return { handoff_order: orderFromLadder(ladder), handoff_ladder: ladder, climb_back: 'next-handoff', may_spend: false, reserve: {}, auto_approve: true, notify_terminal: true, notify_board: false, harness: { ...HARNESS_DEFAULTS } }
 }
 
+// The file verbatim, or null when there is not one Leg can parse. Used by
+// writePreferences to leave alone what it could not read.
+function rawPreferences() {
+  try { return JSON.parse(readFileSync(preferencesFile(), 'utf8')) } catch { return null }
+}
+
 export function readPreferences() {
   const file = preferencesFile()
   if (!existsSync(file)) return defaults()
@@ -295,6 +349,16 @@ export function writePreferences(patch) {
   return withFileLock(preferencesFile() + '.lock', () => {
     const current = readPreferences()
     const next = { ...current }
+    // A ladder Leg could only read part of stays on disk exactly as the human
+    // wrote it. readPreferences drops the rung it cannot parse so the machine
+    // keeps walking the rest, but that reading is not a decision to delete
+    // anything: a save about may_spend must never be what removes a rung
+    // somebody typed into a file the docs call hand-editable.
+    const raw = ladder === undefined && order === undefined ? rawPreferences() : null
+    if (Array.isArray(raw?.handoff_ladder) && raw.handoff_ladder.length && !validHandoffLadder(raw.handoff_ladder)) {
+      next.handoff_ladder = raw.handoff_ladder
+      if (validHandoffOrder(raw.handoff_order)) next.handoff_order = [...raw.handoff_order]
+    }
     if (ladder !== undefined) { next.handoff_ladder = ladder; next.handoff_order = orderFromLadder(ladder) }
     if (order !== undefined) { next.handoff_order = order; if (ladder === undefined) next.handoff_ladder = ladderFromOrder(order) }
     if (climbBack !== undefined) next.climb_back = climbBack