@ucsandman/legcli 0.7.0

package/src/usage.mjs

@@ -0,0 +1,179 @@
+// usage — per (agent, account) limit state and the handoff chooser.
+// $BATON_HOME/usage/<agent>--<account>.json:
+//   { agent, account, five_hour: {pct, resets_at}|null, seven_day: {...}|null,
+//     limited_until: epoch-seconds|null, limited_reason, limited_at,
+//     source, observed_at, available_at, updated_at }
+// Sources: claude statusline JSON (rate_limits.*) and StopFailure rate_limit;
+// codex app-server/rollout rate limits (identified by window duration) and
+// the usage-limit error; agy only the wall itself (no percent exposed).
+import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { home } from './store.mjs'
+import { writeJsonAtomic, withFileLock } from './fsx.mjs'
+import { AGENTS } from './sessions.mjs'
+
+export const WARN_PCT = Number((process.env.LEG_WARN_PCT || process.env.BATON_WARN_PCT) || 85)
+// A limit hit with no reset time from the agent: assume the 5-hour window.
+const DEFAULT_LIMIT_S = 5 * 3600
+
+export function usageDir() { return join(home(), 'usage') }
+export function usageFile(agent, account = 'default') { return join(usageDir(), `${agent}--${account}.json`) }
+
+export function readUsage(agent, account = 'default') {
+  const f = usageFile(agent, account)
+  if (!existsSync(f)) return emptyUsage(agent, account)
+  try { return { ...emptyUsage(agent, account), ...JSON.parse(readFileSync(f, 'utf8')) } } catch { return emptyUsage(agent, account) }
+}
+
+function emptyUsage(agent, account) {
+  return { agent, account, five_hour: null, seven_day: null, limited_until: null, limited_reason: null, limited_at: null, source: null, observed_at: null, available_at: null, updated_at: null }
+}
+
+export function listUsage() {
+  const dir = usageDir()
+  if (!existsSync(dir)) return []
+  return readdirSync(dir).filter((n) => n.endsWith('.json')).sort().map((n) => { try { return JSON.parse(readFileSync(join(dir, n), 'utf8')) } catch { return null } }).filter(Boolean)
+}
+
+function write(u) {
+  mkdirSync(usageDir(), { recursive: true })
+  writeJsonAtomic(usageFile(u.agent, u.account), { ...u, updated_at: new Date().toISOString() })
+}
+
+// read → mutate → write under one cross-process lock, so a percentage write
+// from the poller/status-line never erases a wall a hook set in the same moment
+// (that race handed the baton straight back to a walled login).
+function mutate(agent, account, fn) {
+  mkdirSync(usageDir(), { recursive: true })
+  return withFileLock(usageFile(agent, account) + '.lock', () => {
+    const u = readUsage(agent, account)
+    const out = fn(u)
+    if (out === false) return u
+    const next = out ?? u
+    write(next)
+    return next
+  })
+}
+
+// windows: { five_hour: {pct, resets_at}|null, seven_day: ... }
+// `available` must be an explicit backend answer. Percentages cannot clear a
+// wall: Codex's rate-limit schema says null availability is unknown, even when
+// a window is below 100%.
+export function recordUsage(agent, account, windows, source, { observed_at = new Date().toISOString(), available = null } = {}) {
+  let applied = false
+  const value = mutate(agent, account, (u) => {
+    const seenMs = Date.parse(observed_at)
+    const currentMs = Date.parse(u.observed_at ?? u.updated_at ?? 0)
+    if (Number.isFinite(seenMs) && Number.isFinite(currentMs) && seenMs < currentMs) return false
+    if (windows.five_hour !== undefined) u.five_hour = windows.five_hour
+    if (windows.seven_day !== undefined) u.seven_day = windows.seven_day
+    u.source = source
+    u.observed_at = Number.isFinite(seenMs) ? new Date(seenMs).toISOString() : new Date().toISOString()
+    applied = true
+    if (available === true) u.available_at = u.observed_at
+    // A window that has reset clears an old wall.
+    const nowS = Math.floor(Date.now() / 1000)
+    if (u.limited_until && u.limited_until <= nowS) { u.limited_until = null; u.limited_reason = null; u.limited_at = null }
+    const wallMs = Date.parse(u.limited_at ?? u.updated_at ?? 0)
+    if (u.limited_until && available === true && (!Number.isFinite(wallMs) || !Number.isFinite(seenMs) || seenMs >= wallMs)) {
+      u.limited_until = null
+      u.limited_reason = null
+      u.limited_at = null
+    } else if (available === false) {
+      const windows = [u.five_hour, u.seven_day].filter((w) => w && Number.isFinite(w.resets_at) && w.resets_at > nowS)
+      windows.sort((a, b) => (b.pct ?? 0) - (a.pct ?? 0))
+      u.limited_until = windows.length ? windows[0].resets_at : nowS + DEFAULT_LIMIT_S
+      u.limited_reason = 'usage_limit_exceeded'
+      u.limited_at = u.observed_at
+    }
+    return u
+  })
+  return { ...value, usage_applied: applied }
+}
+
+export function markLimited(agent, account, { resets_at = null, reason = 'limit', source, observed_at = new Date().toISOString() } = {}) {
+  let applied = false
+  const value = mutate(agent, account, (u) => {
+    const seenMs = Date.parse(observed_at)
+    const currentMs = Math.max(Date.parse(u.limited_at ?? 0) || 0, Date.parse(u.available_at ?? 0) || 0)
+    if (Number.isFinite(seenMs) && Number.isFinite(currentMs) && seenMs < currentMs) return false
+    const nowS = Math.floor(Date.now() / 1000)
+    let until = Number.isFinite(resets_at) && resets_at > nowS ? resets_at : null
+    if (!until) {
+      // Prefer the window that actually walled (highest used %) over the soonest
+      // reset: a weekly wall (100% / days away) must not be recorded as the
+      // 5-hour window's near reset, or the account is handed back and re-walls.
+      const windows = [u.five_hour, u.seven_day].filter((w) => w && Number.isFinite(w.resets_at) && w.resets_at > nowS)
+      windows.sort((a, b) => (b.pct ?? 0) - (a.pct ?? 0))
+      until = windows.length ? windows[0].resets_at : nowS + DEFAULT_LIMIT_S
+    }
+    u.limited_until = until
+    u.limited_reason = reason
+    u.limited_at = Number.isFinite(seenMs) ? new Date(seenMs).toISOString() : new Date().toISOString()
+    u.observed_at = u.limited_at
+    if (source) u.source = source
+    applied = true
+    return u
+  })
+  return { ...value, wall_applied: applied }
+}
+
+export function clearLimited(agent, account) {
+  return mutate(agent, account, (u) => { u.limited_until = null; u.limited_reason = null; u.limited_at = null; return u })
+}
+
+export function usageIsStale(u, nowMs = Date.now(), maxAgeMs = 5 * 60 * 1000) {
+  const observedMs = Date.parse(u?.observed_at ?? u?.updated_at ?? 0)
+  return !Number.isFinite(observedMs) || nowMs - observedMs > maxAgeMs
+}
+
+export function isAvailable(u, nowS = Math.floor(Date.now() / 1000)) {
+  return !(u.limited_until && u.limited_until > nowS)
+}
+
+// Highest used percentage across the windows we know (for warnings).
+export function pressure(u) {
+  const p = [u.five_hour?.pct, u.seven_day?.pct].filter((x) => Number.isFinite(x))
+  return p.length ? Math.max(...p) : null
+}
+
+// Which window is closest to the wall, for the warning text.
+export function hottest(u) {
+  const w = [['5h', u.five_hour], ['7d', u.seven_day]].filter(([, x]) => x && Number.isFinite(x.pct))
+  w.sort((a, b) => b[1].pct - a[1].pct)
+  return w.length ? { window: w[0][0], ...w[0][1] } : null
+}
+
+// The chain after (agent, account): other accounts of the same agent first,
+// then every other agent in the saved order. The order is an absolute priority
+// list, not a rotation anchored on the current agent: an agent parked last
+// stays last whichever agent the terminal started on (codex → claude → agy
+// hands claude to codex, never to agy first).
+// accounts: { claude: ['default', 'work'], codex: ['default'], agy: ['default'] }
+export function candidates({ agent, account = 'default', accounts, order = AGENTS }) {
+  const out = []
+  for (const a of accounts[agent] ?? ['default']) if (a !== account) out.push({ agent, account: a })
+  for (const ag of order) if (ag !== agent) for (const a of accounts[ag] ?? ['default']) out.push({ agent: ag, account: a })
+  return out
+}
+
+// → { next: {agent, account} | null, out: [{agent, account, resets_at}] sorted by reset }
+export function chooseNext({ agent, account, accounts, installed, order = AGENTS, nowS = Math.floor(Date.now() / 1000) }) {
+  const out = []
+  for (const c of candidates({ agent, account, accounts, order })) {
+    if (installed && installed[c.agent] === false) continue
+    const u = readUsage(c.agent, c.account)
+    if (isAvailable(u, nowS)) return { next: c, out }
+    out.push({ ...c, resets_at: u.limited_until, reason: u.limited_reason })
+  }
+  out.sort((a, b) => (a.resets_at ?? Infinity) - (b.resets_at ?? Infinity))
+  return { next: null, out }
+}
+
+export function fmtReset(epochS) {
+  if (!Number.isFinite(epochS)) return 'unknown'
+  const d = new Date(epochS * 1000)
+  const mins = Math.round((epochS * 1000 - Date.now()) / 60000)
+  const rel = mins < 60 ? `${Math.max(0, mins)}m` : mins < 48 * 60 ? `${Math.floor(mins / 60)}h${mins % 60}m` : `${Math.floor(mins / 1440)}d`
+  return `${d.toLocaleString()} (in ${rel})`
+}

package/src/wait.mjs

@@ -0,0 +1,30 @@
+// wait — when every option is walled, the terminal stays open and counts down
+// to the first reset instead of exiting. Pure timing here; src/attach.mjs
+// wires the countdown line, the session record and the restart from the
+// bundle around it.
+export function fmtCountdown(secs) {
+  const s = Math.max(0, Math.floor(secs))
+  const h = Math.floor(s / 3600); const m = Math.floor((s % 3600) / 60); const r = s % 60
+  return h ? `${h}h${String(m).padStart(2, '0')}m${String(r).padStart(2, '0')}s` : m ? `${m}m${String(r).padStart(2, '0')}s` : `${r}s`
+}
+
+// Resolve 'ready' once resetsAt (epoch seconds) has passed, 'cancelled' when
+// the signal aborts or isCancelled() says so. onTick(remainingSecs) runs every
+// tickMs and once at the start. A null resetsAt resolves 'ready' at once.
+export function waitForReset({ resetsAt, tickMs = 1000, signal = null, isCancelled = () => false, onTick = () => {} } = {}) {
+  return new Promise((resolvePromise) => {
+    let timer = null
+    const finish = (r) => { if (timer) clearInterval(timer); signal?.removeEventListener?.('abort', onAbort); resolvePromise(r) }
+    const onAbort = () => finish('cancelled')
+    const check = () => {
+      if (signal?.aborted || isCancelled()) return finish('cancelled')
+      const remaining = Number.isFinite(resetsAt) ? resetsAt - Date.now() / 1000 : 0
+      if (remaining <= 0) return finish('ready')
+      onTick(remaining)
+    }
+    signal?.addEventListener?.('abort', onAbort, { once: true })
+    check()
+    // the interval is what keeps the process alive while it waits: never unref it
+    timer = setInterval(check, tickMs)
+  })
+}

package/src/worktree.mjs

@@ -0,0 +1,207 @@
+// worktree — one git worktree per card under <repo>/.baton-worktrees/<cardId>,
+// on branch baton/<cardId>. Every git call runs with MSYS_NO_PATHCONV=1 (see
+// git-snapshot.mjs) so Git Bash on Windows never rewrites an absolute path
+// argument. Never pushes; never deletes outside <repo>/.baton-worktrees/.
+import { execFileSync } from 'node:child_process'
+import { existsSync, statSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { join, resolve, sep, isAbsolute } from 'node:path'
+import { homedir } from 'node:os'
+import { canonPath, realPath } from './fsx.mjs'
+
+function git(cwd, argv) {
+  return execFileSync('git', argv, { cwd, windowsHide: true, encoding: 'utf8', env: { ...process.env, MSYS_NO_PATHCONV: '1' } })
+}
+
+// git reports long, real paths; callers may hand us short or symlinked ones
+function samePath(a, b) {
+  return canonPath(a) === canonPath(b)
+}
+
+function isUnder(child, parent) {
+  const c = canonPath(child)
+  const p = canonPath(parent)
+  return c === p || c.startsWith(p + sep)
+}
+
+function isNestedWorktreePath(resolved) {
+  const segments = resolved.split(sep)
+  return segments.some((s) => { const l = process.platform === 'win32' ? s.toLowerCase() : s; return l === '.leg-worktrees' || l === '.baton-worktrees'; })
+}
+
+export function worktreePath(repo, cardId) {
+  // long real path: git reports worktrees that way, and the short 8.3 form a
+  // caller may pass must never become the stored worktree path
+  const root = realPath(repo); const oldPath = join(root, '.baton-worktrees', cardId); if (existsSync(oldPath)) return oldPath; return join(root, '.leg-worktrees', cardId);
+}
+
+export function branchName(cardId) {
+  return `leg/${cardId}`
+}
+
+export function validateRepo(repo) {
+  const resolved = realPath(repo)
+  const legHome = resolve(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')))
+  if (samePath(resolved, legHome)) {
+    throw new Error(`refusing to use LEG_HOME as a repo: ${resolved}`)
+  }
+  if (isNestedWorktreePath(resolved)) {
+    throw new Error('refusing a nested worktree path as a repo')
+  }
+  if (!existsSync(resolved) || !statSync(resolved).isDirectory()) {
+    throw new Error(`not a directory: ${resolved}`)
+  }
+  try {
+    git(resolved, ['rev-parse', '--show-toplevel'])
+  } catch {
+    throw new Error(`not a git repo: ${resolved}`)
+  }
+  try {
+    git(resolved, ['rev-parse', 'HEAD'])
+  } catch {
+    throw new Error(`repo has no commits: ${resolved}`)
+  }
+  return resolved
+}
+
+function parseWorktreeList(output) {
+  const entries = []
+  let current = null
+  for (const line of output.split(/\r?\n/)) {
+    if (line.startsWith('worktree ')) {
+      current = { path: resolve(line.slice('worktree '.length)), head: null, branch: null }
+      entries.push(current)
+    } else if (line.startsWith('HEAD ') && current) {
+      current.head = line.slice('HEAD '.length)
+    } else if (line.startsWith('branch ') && current) {
+      current.branch = line.slice('branch '.length).replace(/^refs\/heads\//, '')
+    }
+  }
+  return entries
+}
+
+export function list(repo) {
+  const resolved = resolve(repo)
+  const out = git(resolved, ['worktree', 'list', '--porcelain'])
+  return parseWorktreeList(out)
+}
+
+// Never committed by a landing: Baton's own directories, and the local state a
+// DashClaw hook writes into every directory an agent runs in.
+export function ensureExcludeEntries(repo) {
+  // a linked worktree or submodule has `.git` as a FILE, so the shared info dir
+  // must come from git, not from assuming <repo>/.git is a directory
+  let gitDir
+  try { gitDir = git(repo, ['rev-parse', '--git-common-dir']).trim() } catch { gitDir = join(repo, '.git') }
+  const infoDir = isAbsolute(gitDir) ? join(gitDir, 'info') : join(repo, gitDir, 'info')
+  mkdirSync(infoDir, { recursive: true })
+  const excludePath = join(infoDir, 'exclude')
+  // .env / .env.* so a Land never commits a secret the agent left in the
+  // worktree; the placeholder files are re-included, since `.env.*` otherwise
+  // swallows the .env.example an agent was asked to update (an exclude entry
+  // has no effect on a file the repo already tracks)
+  const needed = ['.leg-worktrees/', '.leg/', '.baton-worktrees/', '.baton/', '.context-handoffs/', '.dashclaw-local/', '.env', '.env.*', '!.env.example', '!.env.sample']
+  const content = existsSync(excludePath) ? readFileSync(excludePath, 'utf8') : ''
+  const lines = content.split(/\r?\n/)
+  const missing = needed.filter((n) => !lines.includes(n))
+  if (missing.length === 0) return
+  const joiner = content.length && !content.endsWith('\n') ? '\n' : ''
+  writeFileSync(excludePath, content + joiner + missing.join('\n') + '\n')
+}
+
+// The branch this repo actually calls its trunk: origin's default if there is
+// one, else whatever the root checkout is on.
+function defaultBranch(repo) {
+  for (const argv of [['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], ['symbolic-ref', '--short', 'HEAD']]) {
+    try { return git(repo, argv).trim().replace(/^origin\//, '') } catch {}
+  }
+  return null
+}
+
+export function ensure(repo, cardId, { trunk = 'main' } = {}) {
+  const resolvedRepo = validateRepo(repo)
+  const wtPath = worktreePath(resolvedRepo, cardId)
+  const branch = branchName(cardId)
+
+  const already = list(resolvedRepo).find((w) => samePath(w.path, wtPath))
+  if (already && existsSync(wtPath)) {
+    ensureExcludeEntries(resolvedRepo)
+    return { path: wtPath, branch, created: false }
+  }
+  // git still lists a worktree whose directory was deleted by hand; prune the
+  // stale admin entry so `worktree add` below does not refuse the path
+  if (already) git(resolvedRepo, ['worktree', 'prune'])
+
+  let branchExists = true
+  try {
+    git(resolvedRepo, ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`])
+  } catch {
+    branchExists = false
+  }
+
+  const result = { path: wtPath, branch, created: true }
+  if (branchExists) {
+    git(resolvedRepo, ['worktree', 'add', wtPath, branch])
+  } else {
+    // A card cut from HEAD because its trunk does not exist runs its whole
+    // agent chain and then bounces every land attempt until it fails: refuse
+    // here, while it has cost nothing, and name the branch this repo uses.
+    try {
+      git(resolvedRepo, ['rev-parse', '--verify', '--quiet', trunk])
+    } catch {
+      const actual = defaultBranch(resolvedRepo)
+      throw new Error(`trunk ${trunk} does not exist in ${resolvedRepo}${actual ? `; this repo's default branch is ${actual} (add the card with --trunk ${actual})` : ''}`)
+    }
+    git(resolvedRepo, ['worktree', 'add', '-b', branch, wtPath, trunk])
+  }
+
+  ensureExcludeEntries(resolvedRepo)
+  return result
+}
+
+export function remove(repo, cardId, { deleteBranch = false, force = false } = {}) {
+  const resolvedRepo = resolve(repo)
+  const wtPath = worktreePath(resolvedRepo, cardId)
+  const legWt = join(resolvedRepo, '.leg-worktrees'); const batonWt = join(resolvedRepo, '.baton-worktrees'); if (!isUnder(wtPath, legWt) && !isUnder(wtPath, batonWt)) { throw new Error(`refusing to remove a path outside .leg-worktrees: ${wtPath}`); }
+
+  const branch = branchName(cardId)
+  const already = list(resolvedRepo).find((w) => samePath(w.path, wtPath))
+  let removed = false
+  if (already) {
+    git(resolvedRepo, ['worktree', 'remove', ...(force ? ['--force'] : []), wtPath])
+    git(resolvedRepo, ['worktree', 'prune'])
+    removed = true
+  }
+
+  // `git branch -d` refuses an unmerged branch; only escalate to `-D` (which
+  // discards commits) when the caller explicitly forces it. branchUnmerged
+  // tells the caller work would be lost.
+  let branchDeleted = false
+  let branchUnmerged = false
+  if (deleteBranch) {
+    try {
+      git(resolvedRepo, ['branch', '-d', branch])
+      branchDeleted = true
+    } catch {
+      branchUnmerged = true
+      if (force) { try { git(resolvedRepo, ['branch', '-D', branch]); branchDeleted = true } catch { branchDeleted = false } }
+    }
+  }
+
+  return { removed, branchDeleted, branchUnmerged }
+}
+
+// Uncommitted files in a card's worktree (empty when the worktree is clean or
+// absent). Used by the board's Remove to refuse discarding agent work silently.
+// A git that cannot answer throws: "status failed" must never reach that guard
+// as "clean", which is the reading that force-deletes the directory.
+export function worktreeDirty(repo, cardId) {
+  const wtPath = worktreePath(realPath(repo), cardId)
+  if (!existsSync(wtPath)) return []
+  return git(wtPath, ['status', '--porcelain']).split(/\r?\n/).filter(Boolean)
+}
+
+export function isWorktreeOf(repo, cardId) {
+  const resolvedRepo = resolve(repo)
+  const wtPath = worktreePath(resolvedRepo, cardId)
+  return list(resolvedRepo).some((w) => samePath(w.path, wtPath))
+}