@ucsandman/legcli 0.11.0 → 0.13.0

package/src/orchestrator.mjs

@@ -288,9 +288,18 @@ export async function runCard(id, { actor = BATON_ACTOR } = {}) {
 
 async function driveCard(id, card, actor) {
   if (card.status === 'backlog') card = step(id, 'enqueue', {}, actor)
-  const wt = ensureWorktree(card.repo, card.card_id, { trunk: card.trunk || 'main' })
-  if (card.worktree !== wt.path) {
-    ledgerUpdate(id, { patch: { worktree: wt.path } })
+  // A card born from "End, and keep going as a card" continues in the
+  // terminal's own worktree, exactly where the terminal stopped (redesign G4).
+  // Cutting a second worktree on that branch is the conflict machine the
+  // roadmap already rejects, so an adopted checkout is used as it is.
+  const wt = card.worktree_adopted && card.worktree && existsSync(card.worktree)
+    ? { path: card.worktree, branch: null, created: false }
+    : ensureWorktree(card.repo, card.card_id, { trunk: card.trunk || 'main' })
+  // the branch that checkout is on is recorded with it: the board's row prints
+  // it, and for an adopted checkout it is the TERMINAL's branch, which no
+  // reader can derive from the card id (redesign C.3)
+  if (card.worktree !== wt.path || (wt.branch && card.worktree_branch !== wt.branch)) {
+    ledgerUpdate(id, { patch: { worktree: wt.path, ...(wt.branch ? { worktree_branch: wt.branch } : {}) } })
     card = readCard(id)
   }
   for (;;) {
@@ -349,7 +358,7 @@ export function humanAction(id, action, payload = {}, actor = { type: 'human', i
   if (!card) throw new Error(`card not found: ${id}`)
   const result = transition(card, action, payload)
   const next = apply(id, card, result, actor)
-  if (['kill', 'pause', 'reassign', 'handoff_now'].includes(action) && card.status === 'running') killActiveRun(id)
+  if (['kill', 'pause', 'reassign', 'handoff_now', 'take_over'].includes(action) && card.status === 'running') killActiveRun(id)
   return next
 }
 

package/src/preferences.mjs

@@ -5,6 +5,8 @@ import { existsSync, mkdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { home } from './store.mjs'
 import { writeJsonAtomic, withFileLock } from './fsx.mjs'
+import { MODEL_ALIASES } from './buckets.mjs'
+import { readAccounts, ACCOUNT_NAME_RE } from './accounts.mjs'
 
 export const HANDOFF_AGENTS = ['claude', 'codex', 'agy']
 export const ALL_HANDOFF_AGENTS = ['claude', 'codex', 'agy', 'grok']
@@ -27,6 +29,228 @@ export function requireHandoffOrder(value) {
   return [...value]
 }
 
+// ---- the fallback ladder (docs/redesign-2026-09-17.md B.3) ----
+// A rung is a destination, not an agent: { agent, account, model, when, cost }.
+// `handoff_order` stays on the file and stays derived from the ladder's
+// distinct agent order, so `validHandoffOrder`, `requireHandoffOrder` and every
+// older reader of this file keep working unchanged.
+export const CLIMB_BACK_POLICIES = ['next-handoff', 'never'] // `when-quiet` is deliberately not shipped (B.7)
+export const RUNG_COSTS = ['free', 'plan', 'credits', 'metered']
+const WHEN_RE = /^(?:always|walled-only|below:(100|[0-9]{1,2}))$/
+
+// The word for what a rung spends when nothing about the login is known yet.
+// agy is free, grok bills metered credits through its proxy, a subscription
+// login is `plan`. Deliberately not a function of live state: a word persisted
+// in preferences.json must not be able to go stale (rungCost does the live part).
+export function staticCost(agent) {
+  return agent === 'agy' ? 'free' : agent === 'grok' ? 'metered' : 'plan'
+}
+
+// What this rung spends RIGHT NOW, derived from the agent and the live login.
+// `credits` is the one cost that depends on live state: claude/fable bills
+// usage credits only once the login has them enabled (extra_usage.enabled),
+// and until then it is ordinary plan usage.
+//
+// The word on the rung is never consulted: it is a label that was persisted
+// once and can be any age. An install whose ladder was migrated from a bare
+// handoff_order carries `plan` on every rung, and reading that word let an
+// unattended hand-off take grok and bill metered credits with may_spend false
+// (B.5's gate exists for exactly that rung). Agent plus live login, every time.
+export function rungCost(rung, usage = null) {
+  if (!rung) return 'plan'
+  if (rung.agent === 'claude' && rung.model === 'fable' && usage?.extra_usage?.enabled === true) return 'credits'
+  return staticCost(rung.agent)
+}
+
+// An account name reaches the CLI's config dir (CLAUDE_CONFIG_DIR) and the
+// usage record's file name, so a rung may only name one this machine actually
+// has. Anything else is a path in disguise: `../../../../pwned` pointed the
+// client at an attacker-chosen directory and wrote the record beside it.
+export function validRungAccount(agent, account) {
+  if (!ACCOUNT_NAME_RE.test(String(account ?? ''))) return `rung "account" must be a name of letters, digits, - and _ (got "${account}")`
+  const known = readAccounts()[agent] ?? ['default']
+  if (!known.includes(account)) return `${agent} has no account "${account}" on this machine (${known.join(', ')})`
+  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()
+  return {
+    agent,
+    account: value?.account ? String(value.account) : 'default',
+    model,
+    when: typeof value?.when === 'string' && WHEN_RE.test(value.when) ? value.when : 'always',
+    cost: RUNG_COSTS.includes(value?.cost) ? value.cost : staticCost(agent),
+  }
+}
+
+export const rungKey = (r) => `${r.agent}--${r.account}--${r.model ?? ''}`
+
+// One rung per agent, model null, the cost that agent actually has: what an
+// existing `handoff_order` means, written out long-hand. Behaviour is
+// bit-identical to the order it came from until a human edits a rung. The cost
+// word is read off the agent (`staticCost`) rather than fixed at 'plan',
+// because grok and agy are exactly the two agents the word exists for: a
+// migrated grok rung written as 'plan' walks straight through the spending gate.
+export function ladderFromOrder(order) {
+  return normalizeHandoffOrder(order).map((agent) => ({ agent, account: 'default', model: null, when: 'always', cost: staticCost(agent) }))
+}
+
+// A fresh install: the claude models first (a same-login switch keeps the
+// conversation, B.5), then every other agent of the default order (G2).
+export function defaultLadder() {
+  const rungs = MODEL_ALIASES.claude.slice(0, 3).map((model) => ({ agent: 'claude', account: 'default', model, when: 'always', cost: 'plan' }))
+  for (const agent of HANDOFF_AGENTS) if (agent !== 'claude') rungs.push({ agent, account: 'default', model: null, when: 'always', cost: staticCost(agent) })
+  return rungs
+}
+
+export function validHandoffLadder(value) {
+  try { requireHandoffLadder(value); return true } catch { return false }
+}
+
+export function requireHandoffLadder(value) {
+  if (!Array.isArray(value) || !value.length) throw new TypeError('handoff_ladder must be a non-empty array of rungs')
+  const seen = new Set()
+  const out = []
+  for (const raw of value) {
+    if (!raw || typeof raw !== 'object') throw new TypeError('each rung must be an object: {agent, account, model, when, cost}')
+    if (!ALL_HANDOFF_AGENTS.includes(raw.agent)) throw new TypeError(`unknown agent "${raw.agent}" in handoff_ladder (${ALL_HANDOFF_AGENTS.join(', ')})`)
+    const rung = normalizeRung(raw)
+    const badAccount = validRungAccount(rung.agent, rung.account)
+    if (badAccount) throw new TypeError(badAccount)
+    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)
+    if (seen.has(key)) throw new TypeError(`handoff_ladder names ${rung.agent}/${rung.account}${rung.model ? '/' + rung.model : ''} twice`)
+    seen.add(key)
+    out.push(rung)
+  }
+  return out
+}
+
+// The ladder's distinct agents, in the order the ladder first names them, then
+// whatever the old three- or four-agent contract still needs so that
+// `validHandoffOrder` stays true for every older reader of this file.
+export function orderFromLadder(ladder) {
+  const out = []
+  for (const r of ladder) if (!out.includes(r.agent)) out.push(r.agent)
+  const wanted = out.includes('grok') ? ALL_HANDOFF_AGENTS : HANDOFF_AGENTS
+  for (const a of wanted) if (!out.includes(a)) out.push(a)
+  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) {
+    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()
+}
+
+// The ladder a RECORD means, where the record carries both keys and something
+// that never heard of ladders may have written one of them. `handoff_order` is
+// the older, narrower statement of the same intent: when the two disagree, the
+// order wins and the ladder is rebuilt from it, because the writer that set an
+// order alone is the one that did not know the ladder was there. Leg's own
+// writers always set both, so this only ever fires for an outside edit.
+export function ladderFor(record) {
+  const ladder = normalizeHandoffLadder({ handoff_ladder: record?.handoff_ladder, handoff_order: record?.handoff_order })
+  if (!Array.isArray(record?.handoff_ladder) || !record.handoff_ladder.length) return ladder
+  if (!validHandoffOrder(record?.handoff_order)) return ladder
+  const derived = orderFromLadder(ladder)
+  const same = derived.length === record.handoff_order.length && derived.every((a, i) => a === record.handoff_order[i])
+  return same ? ladder : ladderFromOrder(record.handoff_order)
+}
+
+export function normalizeClimbBack(value) {
+  return CLIMB_BACK_POLICIES.includes(value) ? value : 'next-handoff'
+}
+
+export function requireClimbBack(value) {
+  if (!CLIMB_BACK_POLICIES.includes(value)) throw new TypeError(`climb_back must be one of ${CLIMB_BACK_POLICIES.join(', ')}`)
+  return value
+}
+
+// Per login, the share of a window an automatic hand-off may not eat into, so a
+// background card cannot spend the last of what the human wants for their own
+// terminal. `{}` by default: a floor nobody asked for is a wrong number.
+export function normalizeReserve(value) {
+  const out = {}
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return out
+  for (const [agent, pct] of Object.entries(value)) {
+    if (!ALL_HANDOFF_AGENTS.includes(agent)) continue
+    const n = Number(pct)
+    if (!Number.isFinite(n) || n <= 0 || n > 100) continue
+    out[agent] = Math.round(n)
+  }
+  return out
+}
+
+export function requireReserve(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError('reserve must be an object of {agent: percent}')
+  for (const [agent, pct] of Object.entries(value)) {
+    if (!ALL_HANDOFF_AGENTS.includes(agent)) throw new TypeError(`unknown agent "${agent}" in reserve (${ALL_HANDOFF_AGENTS.join(', ')})`)
+    const n = Number(pct)
+    if (!Number.isFinite(n) || n <= 0 || n > 100) throw new TypeError(`reserve.${agent} must be a percentage between 1 and 100`)
+  }
+  return normalizeReserve(value)
+}
+
 // Portable harness (src/harness/): off for every existing install. `enabled`
 // is the explicit consent `leg harness enable` records; `policy` is what an
 // unattended hand-off may do (warn: report only; sync: write managed state
@@ -71,29 +295,78 @@ export function resolveAutoApprove({ env = process.env, preferences = null, cliF
   return true
 }
 
+// Where a terminal that is waiting on a human says so. `notify_terminal` is on
+// by default: the OSC 9 toast reaches the window the human is already in, with
+// no browser and no permission prompt (docs/redesign-2026-09-17.md E, the
+// notifications table). `notify_board` is off by default because the browser's
+// own Notification permission has to be granted first, and a toggle that asks
+// for a permission nobody wanted is worse than no toggle.
+const defaults = () => {
+  const ladder = defaultLadder()
+  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 { handoff_order: [...HANDOFF_AGENTS], auto_approve: true, harness: { ...HARNESS_DEFAULTS } }
+  if (!existsSync(file)) return defaults()
   try {
     const value = JSON.parse(readFileSync(file, 'utf8'))
+    // The ladder is the richer key, so it decides the order when the file
+    // carries both; a file written by an older Leg carries only the order, and
+    // the ladder it means is that order written out long-hand.
+    const ladder = normalizeHandoffLadder(value)
     return {
-      handoff_order: normalizeHandoffOrder(value?.handoff_order),
+      handoff_order: Array.isArray(value?.handoff_ladder) && value.handoff_ladder.length ? orderFromLadder(ladder) : normalizeHandoffOrder(value?.handoff_order),
+      handoff_ladder: ladder,
+      climb_back: normalizeClimbBack(value?.climb_back),
+      may_spend: value?.may_spend === true,
+      reserve: normalizeReserve(value?.reserve),
       auto_approve: value?.auto_approve !== false,
+      notify_terminal: value?.notify_terminal !== false,
+      notify_board: value?.notify_board === true,
       harness: normalizeHarness(value?.harness),
     }
   } catch {
-    return { handoff_order: [...HANDOFF_AGENTS], auto_approve: true, harness: { ...HARNESS_DEFAULTS } }
+    return defaults()
   }
 }
 
 export function writePreferences(patch) {
-  const order = patch?.handoff_order !== undefined ? requireHandoffOrder(patch?.handoff_order) : undefined
+  // Writing one of the two rewrites the other: the ladder is the shape Leg
+  // walks, `handoff_order` is the shape every older reader knows, and they may
+  // never disagree on disk.
+  const ladder = patch?.handoff_ladder !== undefined ? requireHandoffLadder(patch.handoff_ladder) : undefined
+  const order = patch?.handoff_order !== undefined ? requireHandoffOrder(patch.handoff_order) : undefined
+  const climbBack = patch?.climb_back !== undefined ? requireClimbBack(patch.climb_back) : undefined
+  const reserve = patch?.reserve !== undefined ? requireReserve(patch.reserve) : undefined
   mkdirSync(home(), { recursive: true })
   return withFileLock(preferencesFile() + '.lock', () => {
     const current = readPreferences()
     const next = { ...current }
-    if (order !== undefined) next.handoff_order = order
+    // 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
+    if (reserve !== undefined) next.reserve = reserve
+    if (patch?.may_spend !== undefined) next.may_spend = Boolean(patch.may_spend)
     if (patch?.auto_approve !== undefined) next.auto_approve = Boolean(patch.auto_approve)
+    if (patch?.notify_terminal !== undefined) next.notify_terminal = Boolean(patch.notify_terminal)
+    if (patch?.notify_board !== undefined) next.notify_board = Boolean(patch.notify_board)
     if (patch?.harness !== undefined) next.harness = requireHarness(patch.harness, current.harness)
     writeJsonAtomic(preferencesFile(), next)
     return next

package/src/scheduler.mjs

@@ -9,6 +9,7 @@ import { conflicts } from './leases.mjs'
 import { canonPath } from './fsx.mjs'
 import { runCard, orphanedRun, unsettledRun, driverAlive } from './orchestrator.mjs'
 import { listCards, ledgerAppend, ledgerLog, home, sleep } from './store.mjs'
+import { readSession, isActive } from './sessions.mjs'
 
 export const MAX_CONCURRENT = Math.max(1, parseInt((process.env.LEG_MAX_CONCURRENT || process.env.BATON_MAX_CONCURRENT) || '2', 10) || 2)
 const ACTIVE = ['running', 'handing_off']
@@ -44,6 +45,21 @@ export function pickRunnable(cards, { max = MAX_CONCURRENT, landing = new Set()
   return { start, blocked, running }
 }
 
+// A card born from "End, and keep going as a card" runs in the terminal's own
+// checkout. The board waits for that terminal to stop before it queues the
+// card, but a card queued by hand (Run), by a rerun, or by an older board must
+// not start a headless agent in a working tree an interactive one is still
+// writing to. The record is the same one the board reads to know a terminal
+// ended.
+export function heldByLiveTerminal(card) {
+  const from = card?.lineage?.from
+  if (!from || !card.worktree_adopted) return null
+  try {
+    const s = readSession(from)
+    return s && isActive(s) ? from : null
+  } catch { return null }
+}
+
 export function pidfile() { return join(home(), 'scheduler.pid') }
 
 export function createScheduler({ max = MAX_CONCURRENT, intervalMs = 1000, actor = { type: 'leg' } } = {}) {
@@ -53,7 +69,14 @@ export function createScheduler({ max = MAX_CONCURRENT, intervalMs = 1000, actor
     state.ticks += 1
     const cards = listCards()
     const landing = landingRepos(cards)
-    const { start, blocked } = pickRunnable(cards, { max, landing })
+    const picked = pickRunnable(cards, { max, landing })
+    const start = []
+    const blocked = [...picked.blocked]
+    for (const c of picked.start) {
+      const terminal = heldByLiveTerminal(c)
+      if (terminal) blocked.push({ card: c, conflicts: [], reason: `terminal ${terminal} is still running in this card's checkout` })
+      else start.push(c)
+    }
     for (const b of blocked) {
       const key = b.conflicts.length ? b.conflicts.map((x) => `${x.holder}:${x.lease}`).join(',') : b.reason
       if (state.blockedKeys.get(b.card.card_id) === key) continue