@ucsandman/legcli 0.10.0 → 0.12.0

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/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,180 @@ 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
+}
+
+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)
+    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'}`)
+    }
+    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))
+}
+
+// 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(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 +247,62 @@ 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 } }
+}
+
 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
+    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