@ucsandman/legcli 0.7.0

package/src/env.mjs

@@ -0,0 +1,19 @@
+// Child-process variable sanitization shared by every adapter. Lives in its
+// own module (re-exported by src/runner.mjs) so adapters can import it without
+// a top-level-await import cycle through the runner.
+//
+// Subscription auth only: every provider API key and base-URL override goes
+// (Anthropic, OpenAI, and the Google/Gemini set agy honours), and so do the session markers
+// a Claude Code parent would leak into the child (a leaked session key
+// overrides the machine login and kills the run with "Invalid API key"). The
+// print ceiling must be 0 for a detached claude -p.
+export function sanitizeEnv(env, { interactive = false } = {}) {
+  const out = { ...env }
+  for (const key of Object.keys(out)) {
+    if (/^(ANTHROPIC_API_KEY|ANTHROPIC_AUTH_TOKEN|ANTHROPIC_BASE_URL|ANTHROPIC_CUSTOM_HEADERS|OPENAI_API_KEY|OPENAI_BASE_URL|OPENAI_API_BASE|GEMINI_API_KEY|GOOGLE_API_KEY|GOOGLE_GEMINI_BASE_URL|GOOGLE_GENAI_USE_VERTEXAI|GOOGLE_GENAI_USE_ENTERPRISE|GOOGLE_CLOUD_PROJECT|GOOGLE_CLOUD_LOCATION|GOOGLE_APPLICATION_CREDENTIALS|CLAUDECODE|CLAUDE_CODE_\w+|CLAUDE_EFFORT|CLAUDE_PLUGIN_DATA)$/.test(key)) {
+      delete out[key]
+    }
+  }
+  if (!interactive) out.CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS = '0'
+  return out
+}

package/src/fsx.mjs

@@ -0,0 +1,72 @@
+// fsx — atomic JSON writes that survive Windows. Readers (board, orchestrator,
+// tests) poll card.json and run.json; write-then-rename keeps them from seeing
+// a torn file, but on Windows a rename over a file another process has open
+// fails with EPERM/EBUSY for a moment. Retry briefly, then fall back to a
+// direct write rather than lose the record (the supervisor's final run.json
+// once went missing this way and the orchestrator read a stale 'running').
+import { writeFileSync, renameSync, unlinkSync, existsSync, realpathSync, openSync, closeSync, statSync } from 'node:fs'
+import { resolve, dirname, basename, join } from 'node:path'
+
+// Canonical form for comparing paths: symlinks resolved and, on Windows, 8.3
+// short names expanded (a GitHub runner's temp dir is C:\Users\RUNNER~1\...
+// while git reports C:\Users\runneradmin\...). A path that does not exist
+// yet is canonicalised through its deepest existing ancestor.
+export function canonPath(p) {
+  const out = realPath(p)
+  return process.platform === 'win32' ? out.toLowerCase() : out
+}
+
+// The real, long-form path (case preserved): what Baton stores and hands to
+// git, so a short or symlinked input never leaks into card.json or worktrees.
+export function realPath(p) {
+  let base = resolve(p)
+  const rest = []
+  while (!existsSync(base)) {
+    const parent = dirname(base)
+    if (parent === base) break
+    rest.unshift(basename(base))
+    base = parent
+  }
+  let out = base
+  try { out = realpathSync.native(base) } catch {}
+  return rest.length ? join(out, ...rest) : out
+}
+
+const sleepSync = (ms) => { const t = Date.now() + ms; while (Date.now() < t) { /* spin */ } }
+
+// Cross-process advisory lock around a read-modify-write of a shared JSON file.
+// `openSync(..., 'wx')` is atomic-create, so only one process (a hook, a tap, a
+// poller) holds it at a time. A lock older than staleMs (a crashed holder) is
+// stolen. If it cannot be acquired within the budget, fn runs anyway rather
+// than hang the caller (a Claude Code hook must never block the user's turn).
+export function withFileLock(lockPath, fn, { retries = 60, waitMs = 20, staleMs = 5000 } = {}) {
+  let fd = null
+  for (let i = 0; i < retries; i++) {
+    try { fd = openSync(lockPath, 'wx'); break } catch (err) {
+      // EEXIST: held. EPERM/EACCES/EBUSY: Windows, the holder's unlink is
+      // still pending and the path is briefly untouchable; that is "held" too,
+      // not a reason to run unlocked.
+      if (!['EEXIST', 'EPERM', 'EACCES', 'EBUSY'].includes(err.code)) break
+      try { if (Date.now() - statSync(lockPath).mtimeMs > staleMs) { unlinkSync(lockPath); continue } } catch {}
+      sleepSync(waitMs)
+    }
+  }
+  try { return fn() } finally { if (fd !== null) { try { closeSync(fd) } catch {} try { unlinkSync(lockPath) } catch {} } }
+}
+
+export function writeJsonAtomic(file, obj) {
+  const text = JSON.stringify(obj, null, 2) + '\n'
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`
+  writeFileSync(tmp, text)
+  for (let i = 0; i < 20; i++) {
+    try {
+      renameSync(tmp, file)
+      return
+    } catch (err) {
+      if (!['EPERM', 'EBUSY', 'EACCES', 'EEXIST'].includes(err.code)) { try { unlinkSync(tmp) } catch {} throw err }
+      sleepSync(25)
+    }
+  }
+  try { unlinkSync(tmp) } catch {}
+  writeFileSync(file, text)
+}

package/src/git-snapshot.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+// Ported 2026-09-10 from private ucsandman team tooling; see NOTICE and docs/REUSE.md.
+// git-snapshot — read-only git state snapshot. Prints ONE compact JSON object to stdout. Never mutates the repo.
+// See PROTOCOL.md § Git workflow (coding tasks).
+import { execFileSync } from 'node:child_process'
+import { existsSync, statSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+function die(code, msg) {
+  process.stderr.write(msg + '\n')
+  process.exit(code)
+}
+
+function parseArgs(argv) {
+  const args = {}
+  for (let i = 0; i < argv.length; i += 2) {
+    if (!argv[i].startsWith('--') || argv[i + 1] === undefined) {
+      die(2, `bad argument pair near "${argv[i]}"`)
+    }
+    args[argv[i].slice(2)] = argv[i + 1]
+  }
+  return args
+}
+
+const args = parseArgs(process.argv.slice(2))
+
+const repoArg = args['repo']
+if (!repoArg) die(2, 'missing --repo <path>')
+const repo = resolve(repoArg)
+if (!existsSync(repo) || !statSync(repo).isDirectory()) {
+  die(2, `not a directory: ${repo}`)
+}
+
+let maxFiles = 20
+if (args['max-files'] !== undefined) {
+  maxFiles = parseInt(args['max-files'], 10)
+  if (!Number.isInteger(maxFiles) || maxFiles < 1) {
+    die(2, `invalid --max-files "${args['max-files']}"`)
+  }
+}
+
+function git(gitArgs) {
+  // MSYS_NO_PATHCONV: Git Bash would rewrite a leading-slash argument into a
+  // Windows path (LESSONS 07-09); harmless elsewhere.
+  return execFileSync('git', gitArgs, { cwd: repo, windowsHide: true, encoding: 'utf8', env: { ...process.env, MSYS_NO_PATHCONV: '1' } })
+}
+
+try {
+  git(['rev-parse', '--is-inside-work-tree'])
+} catch {
+  die(2, `not a git repo: ${repo}`)
+}
+
+let branch
+try {
+  branch = git(['symbolic-ref', '--short', '-q', 'HEAD']).trim()
+} catch {
+  branch = 'DETACHED'
+}
+
+let head, head_subject
+try {
+  head = git(['rev-parse', '--short', 'HEAD']).trim()
+  head_subject = git(['log', '-1', '--format=%s']).trim()
+} catch {
+  die(2, `repo has no commits: ${repo}`)
+}
+
+const statusLines = git(['status', '--porcelain']).split(/\r?\n/).filter(Boolean)
+let staged = 0
+let modified = 0
+let untracked = 0
+for (const line of statusLines) {
+  if (line.startsWith('??')) {
+    untracked++
+    continue
+  }
+  if (line[0] !== ' ') staged++
+  if (line[1] !== ' ') modified++
+}
+const dirty = {
+  staged,
+  modified,
+  untracked,
+  files: statusLines.slice(0, maxFiles),
+  truncated: statusLines.length > maxFiles,
+}
+
+let submodules_dirty = []
+try {
+  const subLines = git(['submodule', 'status']).split(/\r?\n/).filter(Boolean)
+  submodules_dirty = subLines
+    .filter((l) => l[0] === '+' || l[0] === 'U')
+    .map((l) => l.slice(1).trim().split(/\s+/)[1])
+    .filter(Boolean)
+} catch {
+  submodules_dirty = []
+}
+
+let recommendation
+if (dirty.staged === 0 && dirty.modified === 0 && dirty.untracked === 0) {
+  recommendation = 'branch'
+} else {
+  recommendation = 'worktree'
+}
+
+const snapshot = {
+  ts: new Date().toISOString(),
+  repo,
+  branch,
+  head,
+  head_subject,
+  dirty,
+  submodules_dirty,
+  recommendation,
+}
+
+if (args['diff-since']) {
+  const since = args['diff-since']
+  let logLines
+  let numstatLines
+  try {
+    logLines = git(['log', '--oneline', `${since}..HEAD`]).split(/\r?\n/).filter(Boolean)
+    numstatLines = git(['diff', '--numstat', `${since}..HEAD`]).split(/\r?\n/).filter(Boolean)
+  } catch (err) {
+    die(2, `invalid --diff-since ref "${since}": ${err.message}`)
+  }
+  const commits = logLines.map((l) => {
+    const sp = l.indexOf(' ')
+    return sp === -1 ? { hash: l, subject: '' } : { hash: l.slice(0, sp), subject: l.slice(sp + 1) }
+  })
+  let insertions = 0
+  let deletions = 0
+  const files = []
+  for (const line of numstatLines) {
+    const [ins, del, path] = line.split('\t')
+    if (ins !== '-') insertions += parseInt(ins, 10)
+    if (del !== '-') deletions += parseInt(del, 10)
+    files.push(path)
+  }
+  snapshot.diff = {
+    since,
+    commits,
+    changed_files: numstatLines.length,
+    insertions,
+    deletions,
+    files: files.slice(0, maxFiles),
+    truncated: files.length > maxFiles,
+  }
+}
+
+process.stdout.write(JSON.stringify(snapshot) + '\n')

package/src/handoff.mjs

@@ -0,0 +1,171 @@
+// handoff — the context-handoff-bundle seam. Baton never re-implements the
+// bundle format: it writes a structured notes file, calls the CLI as an argv
+// subprocess (`save --repo-local` inside the worktree so the next agent finds
+// the bundle in its cwd), validates the bundle, and later `load`s the resume.
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { scrub } from './runner.mjs'
+
+const MIN_VERSION = [0, 4, 0]
+
+let resolved = null
+
+// `context-handoff-bundle` on PATH (a real exe from pip's Scripts dir on
+// Windows, a script elsewhere), else `python -m context_handoff_bundle`.
+export function resolveChb() {
+  if (resolved) return resolved
+  const chbEnv = process.env.LEG_CHB_BIN || process.env.BATON_CHB_BIN;
+  if (chbEnv) {
+    resolved = { bin: chbEnv, prefix: [] }
+    return resolved
+  }
+  const direct = spawnSync('context-handoff-bundle', ['--help'], { windowsHide: true, encoding: 'utf8', timeout: 20000 })
+  if (!direct.error && direct.status === 0) {
+    resolved = { bin: 'context-handoff-bundle', prefix: [] }
+    return resolved
+  }
+  for (const py of ['python', 'python3', 'py']) {
+    const r = spawnSync(py, ['-m', 'context_handoff_bundle', '--help'], { windowsHide: true, encoding: 'utf8', timeout: 20000 })
+    if (!r.error && r.status === 0) {
+      resolved = { bin: py, prefix: ['-m', 'context_handoff_bundle'] }
+      return resolved
+    }
+  }
+  throw new Error('context-handoff-bundle not found: pip install -U context-handoff-bundle')
+}
+
+export function chb(args, { cwd, timeout = 120000 } = {}) {
+  const { bin, prefix } = resolveChb()
+  const r = spawnSync(bin, [...prefix, ...args], { cwd, windowsHide: true, encoding: 'utf8', timeout, env: process.env })
+  if (r.error) throw new Error(`context-handoff-bundle ${args[0]} failed to start: ${r.error.message}`)
+  return { status: r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? '' }
+}
+
+// Version from package metadata (works on releases without --version).
+export function chbVersion() {
+  const v = chb(['--version'])
+  let text = v.status === 0 ? v.stdout.trim().split(/\s+/).pop() : null
+  if (!text) {
+    const r = spawnSync('python', ['-c', "from importlib.metadata import version; print(version('context-handoff-bundle'))"], { windowsHide: true, encoding: 'utf8', timeout: 20000 })
+    text = r.status === 0 ? r.stdout.trim() : null
+  }
+  return text
+}
+
+export function versionOk(v = chbVersion()) {
+  if (!v) return false
+  const parts = v.split('.').map((x) => parseInt(x, 10))
+  for (let i = 0; i < 3; i++) {
+    if ((parts[i] ?? 0) > MIN_VERSION[i]) return true
+    if ((parts[i] ?? 0) < MIN_VERSION[i]) return false
+  }
+  return true
+}
+
+function bullets(items) {
+  return items.filter(Boolean).map((x) => `- ${String(x).replace(/\r?\n/g, ' ').trim()}`)
+}
+
+// Notes in the CLI's own section vocabulary (Scope / Findings / Opportunities /
+// Open questions / Evidence anchors) carrying Baton's four parts: Task, Done so
+// far, Diff, Open findings. Anything not under a known heading is dropped by
+// the parser, so every Baton line lives under one of those five.
+export function buildNotes({ card, station, leg, entry, run, progress = '', lastMessage = null, diff = null, diffStat = '', changedFiles = [], extra = [] }) {
+  const outcome = run?.outcome ?? 'handoff'
+  const signal = run?.signal && run.signal !== 'none' ? ` (${run.signal})` : ''
+  const progressLines = progress.split(/\r?\n/).map((l) => l.trim()).filter(Boolean).slice(-40)
+  const diffLine = diff
+    ? `Diff since leg start: ${diff.files ?? 0} file(s) changed${diff.head_at_start && diff.head && diff.head !== diff.head_at_start ? `, HEAD moved ${diff.head_at_start.slice(0, 7)} → ${diff.head.slice(0, 7)}` : ''}${diffStat ? `; ${diffStat.trim().split(/\r?\n/).pop()}` : ''}`
+    : 'Diff since leg start: (no git evidence)'
+  const lines = [
+    '## Scope',
+    '',
+    `Task: ${card.task}`,
+    `Card ${card.card_id}, station ${station.name}, leg ${leg} (${entry?.adapter ?? run?.adapter ?? 'agent'}) stopped with outcome ${outcome}${signal}. The next agent resumes in the same worktree.`,
+    '',
+    '## Projects mentioned',
+    '',
+    `- ${card.card_id}`,
+    '',
+    '## Findings',
+    '',
+    ...bullets(progressLines.length ? progressLines.map((l, i) => `Done so far ${i + 1}: ${l}`) : ['Done so far: (no PROGRESS.md entries from the previous agent)']),
+    ...bullets([lastMessage ? `Last message from the previous agent: ${scrub(String(lastMessage)).slice(0, 600)}` : null]),
+    ...bullets([diffLine]),
+    ...bullets(changedFiles.slice(0, 50).map((f) => `Diff touches ${f}`)),
+    '',
+    '## Opportunities',
+    '',
+    ...bullets([
+      'Next agent: read .leg/PROGRESS.md and .leg/CONTRACT.md, continue from the last done step, then write .leg/DONE.',
+      progressLines.length ? null : 'Next agent: the previous run left no progress notes; check the diff first.',
+    ]),
+    '',
+    '## Open questions',
+    '',
+    ...bullets([
+      `Open findings: previous leg ended ${outcome}${signal}: ${run?.reason ?? 'no reason recorded'}`,
+      run?.exit_code !== undefined && run?.exit_code !== null ? `Open findings: exit code ${run.exit_code}` : null,
+      ...extra.map((e) => `Open findings: ${e}`),
+    ]),
+    '',
+    '## Evidence anchors',
+    '',
+    ...bullets(changedFiles.slice(0, 50)),
+    ...bullets(['.leg/PROGRESS.md', '.leg/CONTRACT.md']),
+    '',
+  ]
+  return scrub(lines.join('\n'))
+}
+
+function tailFile(path, lines = 15) {
+  if (!existsSync(path)) return ''
+  return readFileSync(path, 'utf8').trim().split('\n').slice(-lines).join(' | ')
+}
+
+export function ensureExcluded(repo, pattern) {
+  const f = join(repo, '.git', 'info', 'exclude')
+  try {
+    const cur = existsSync(f) ? readFileSync(f, 'utf8') : ''
+    if (!cur.split(/\r?\n/).includes(pattern)) appendFileSync(f, `${cur.endsWith('\n') || !cur ? '' : '\n'}${pattern}\n`)
+  } catch {}
+}
+
+// Writes the notes, saves the bundle repo-local in the worktree, validates it.
+// Returns { bundle_id, path, notes_path, quality, score } (throws on failure).
+export function writeHandoff({ card, station, leg, entry, run, worktree, runDir, extra = [], changedFiles = [], diffStat = '' }) {
+  const pPath = existsSync(join(worktree, '.leg', 'PROGRESS.md')) ? join(worktree, '.leg', 'PROGRESS.md') : join(worktree, '.baton', 'PROGRESS.md');
+  const progress = existsSync(pPath) ? readFileSync(pPath, 'utf8') : '';
+  let lastMessage = null
+  if (runDir && existsSync(join(runDir, 'last.md'))) lastMessage = readFileSync(join(runDir, 'last.md'), 'utf8')
+  if (!lastMessage && run?.last_message) lastMessage = run.last_message
+  const stderrTail = runDir ? tailFile(join(runDir, 'err.log')) : ''
+  const notes = buildNotes({
+    card, station, leg, entry, run, progress, lastMessage, diff: run?.diff ?? null, diffStat, changedFiles,
+    extra: [...extra, stderrTail && run?.exit_code !== 0 ? `stderr tail: ${scrub(stderrTail).slice(0, 800)}` : null].filter(Boolean),
+  })
+  const legDir = join(worktree, '.leg')
+  mkdirSync(legDir, { recursive: true })
+  const notesPath = join(legDir, `handoff-${station.name}-leg${leg}.md`)
+  writeFileSync(notesPath, notes)
+  if (card.repo) ensureExcluded(card.repo, '.context-handoffs/')
+  const slug = `baton-${card.card_id}-${station.name}-leg${leg}`.toLowerCase().replace(/[^a-z0-9-]+/g, '-').slice(0, 80)
+  const title = `baton ${card.card_id} ${station.name} leg ${leg} ${entry?.adapter ?? run?.adapter ?? 'agent'}`
+  const save = chb(['save', '--repo-local', '--title', title, '--slug', slug, '--notes', notesPath, '--tag', 'baton'], { cwd: worktree })
+  if (save.status !== 0) throw new Error(`context-handoff-bundle save failed (exit ${save.status}): ${scrub(save.stderr || save.stdout).slice(0, 500)}`)
+  let out
+  try { out = JSON.parse(save.stdout) } catch { throw new Error(`context-handoff-bundle save printed no JSON: ${scrub(save.stdout).slice(0, 300)}`) }
+  const bundleId = out.bundle_id
+  const bundlePath = join(worktree, '.context-handoffs', bundleId)
+  const validate = chb(['validate', bundlePath], { cwd: worktree })
+  if (validate.status !== 0) throw new Error(`context-handoff-bundle validate failed: ${scrub(validate.stderr || validate.stdout).slice(0, 500)}`)
+  return { bundle_id: bundleId, path: bundlePath, notes_path: notesPath, quality: out.quality ?? null, score: out.score ?? null }
+}
+
+// The resume text the next leg's prompt starts with.
+export function loadResume(worktree, query = 'latest') {
+  const r = chb(['load', query], { cwd: worktree })
+  if (r.status !== 0) throw new Error(`context-handoff-bundle load failed (exit ${r.status}): ${scrub(r.stderr || r.stdout).slice(0, 500)}`)
+  return r.stdout
+}

package/src/hook.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// hook — the process Claude Code runs for a Baton session's hooks and status
+// line (wired by src/taps/claude.mjs through `--settings`). Reads the JSON
+// payload on stdin, updates the session record, exits 0 always: a broken hook
+// must never stall the user's session.
+//   node hook.mjs claude-hook --session <id>
+//   node hook.mjs claude-statusline --session <id>
+// The status line entry records rate_limits when a Claude Code build runs it
+// (2.1.268 does not; see src/taps/claude-usage.mjs) and prints one Baton line.
+import { appendFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { handleHook, handleStatusline } from './taps/claude.mjs'
+import { sessionDir } from './sessions.mjs'
+import { captureLive } from './live-capture.mjs'
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let d = ''
+    const t = setTimeout(() => resolve(d), 4000)
+    process.stdin.setEncoding('utf8')
+    process.stdin.on('data', (c) => { d += c })
+    process.stdin.on('end', () => { clearTimeout(t); resolve(d) })
+    process.stdin.on('error', () => { clearTimeout(t); resolve(d) })
+  })
+}
+
+const [kind, ...rest] = process.argv.slice(2)
+const i = rest.indexOf('--session')
+const sessionId = i !== -1 ? rest[i + 1] : null
+
+try {
+  const raw = await readStdin()
+  let payload = {}
+  try { payload = JSON.parse(raw) } catch {}
+  if (!sessionId) process.exit(0)
+  if (kind === 'claude-hook') {
+    const line = handleHook(sessionId, payload)
+    try { appendFileSync(join(sessionDir(sessionId), 'hook.log'), `${new Date().toISOString()} ${payload.hook_event_name ?? '?'} ${line}\n`) } catch {}
+    // the first real StopFailure per error kind is kept as evidence (never a simulated one)
+    if (payload.hook_event_name === 'StopFailure' && payload.error) {
+      try { captureLive('claude', String(payload.error), payload, { sessionId }) } catch {}
+    }
+  } 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 {}
+    process.stdout.write(text + '\n')
+  }
+} catch {}
+process.exit(0)

package/src/land.mjs

@@ -0,0 +1,106 @@
+// land — the land station handler the orchestrator calls, and the Land button
+// on a terminal card. `ff` mode runs the merge queue (src/mergequeue.mjs); `pr`
+// mode opens a pull request through the gh stub (src/stations/pr.mjs) and
+// parks the card for a human. A terminal session in its own worktree lands its
+// branch (baton/<session-id>) through the same queue.
+import { join } from 'node:path'
+import { existsSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { land } from './mergequeue.mjs'
+import { openPr } from './stations/pr.mjs'
+import { cardDir, ledgerAppend } from './store.mjs'
+import { remove as removeWorktree, ensureExcludeEntries } from './worktree.mjs'
+import { appendEvent, writeLand, appendLanding } from './sessions.mjs'
+import { scrub } from './redact.mjs'
+
+export async function landCard(card, worktree) {
+  const warn = (msg) => ledgerAppend(card.card_id, { type: 'land_warning', station: card.station, leg: 0, summary: msg })
+  if (card.land_mode === 'pr') {
+    const r = openPr({ card: { ...card, worktree }, runDir: join(cardDir(card.card_id), 'land') })
+    if (!r.ok) return { landed: false, bounced: false, pr: false, reason: `pr mode: ${r.error}` }
+    return { landed: false, pr: true, url: r.url, summary: `pull request opened: ${r.url ?? '(no url)'}`, argv: r.argv }
+  }
+  return land(card, worktree, { onWarning: warn })
+}
+
+// ---- terminals ----
+const inFlight = new Set()
+export function landingNow(id) { return inFlight.has(id) }
+
+function git(cwd, args) {
+  const r = spawnSync('git', args, { cwd, windowsHide: true, encoding: 'utf8', env: { ...process.env, MSYS_NO_PATHCONV: '1' } })
+  return { ok: r.status === 0, out: (r.stdout ?? '').trim() }
+}
+
+// Why this session cannot land right now, or null.
+export function landBlocker(s) {
+  if (!s.worktree) return 'this terminal works in the checkout itself: there is no branch of its own to land'
+  if (!s.worktree.base) return `${s.worktree.branch} was cut from a detached HEAD: there is no branch to land it onto`
+  if (!existsSync(s.worktree.path)) return `the worktree ${s.worktree.path} is gone`
+  if (inFlight.has(s.session_id)) return 'already landing'
+  return null
+}
+
+// The Land button: commit what the agent left in the worktree, rebase the
+// branch onto its base, run the tests, fast-forward the base (never a merge
+// commit); a bounce carries the reason. land.json holds the card's state,
+// landings.jsonl who landed what. Resolves with the queue's result.
+export async function landSession(session, { by = 'local' } = {}) {
+  const id = session.session_id
+  const { path, branch, base } = session.worktree
+  inFlight.add(id)
+  writeLand(id, { state: 'landing', at: new Date().toISOString(), by, branch, base })
+  appendEvent(id, { type: 'land_requested', by, summary: `land requested by ${by}: ${branch} onto ${base}` })
+  let r
+  try {
+    await new Promise((res) => setImmediate(res)) // the caller answers the request first
+    ensureExcludeEntries(session.repo) // the commit step adds everything else the agent left
+    const task = String(session.task ?? 'terminal session').split('\n')[0].slice(0, 60)
+    r = await land({ card_id: id, repo: session.repo, trunk: base, title: `${session.agent} ${id.split('-').pop()}: ${task}`, test_command: null }, path, {
+      allowDirtyRoot: true,
+      onWarning: (msg) => appendEvent(id, { type: 'land_warning', by, summary: msg }),
+    })
+  } catch (err) {
+    r = { landed: false, bounced: true, reason: 'error', detail: String(err.message) }
+  } finally {
+    inFlight.delete(id)
+  }
+  const at = new Date().toISOString()
+  if (r.landed && r.sha === r.sha_before) {
+    writeLand(id, { state: 'noop', at, by, branch, base })
+    appendEvent(id, { type: 'land_noop', by, summary: `nothing to land: ${branch} has no changes beyond ${base}` })
+  } else if (r.landed) {
+    const commits = git(session.repo, ['rev-list', '--reverse', `${r.sha_before}..${r.sha}`]).out.split('\n').filter(Boolean)
+    const tested = Boolean(r.tests)
+    appendLanding({ repo: session.repo, trunk: base, session_id: id, agent: session.agent, account: session.account, by, sha: r.sha, sha_before: r.sha_before, commits, files: r.files, insertions: r.insertions, deletions: r.deletions, tested })
+    writeLand(id, { state: 'landed', at, by, branch, base, sha: r.sha, files: r.files, insertions: r.insertions, deletions: r.deletions, tested, summary: r.summary })
+    appendEvent(id, { type: 'landed', by, summary: `${r.summary} · Land pressed by ${by}` })
+  } else {
+    const detail = scrub(String(r.detail ?? '')).slice(0, 4000)
+    writeLand(id, { state: 'bounced', at, by, branch, base, reason: r.reason, detail, files: r.files ?? [] })
+    appendEvent(id, { type: 'bounced', by, summary: `land bounced (${r.reason}): ${detail.split('\n')[0].slice(0, 200)}`, body: detail })
+  }
+  return r
+}
+
+// Removing a finished session takes its worktree and branch with it only when
+// nothing is lost: a clean worktree whose branch is already in its base.
+export function pruneSessionWorktree(s) {
+  const wt = s.worktree
+  if (!wt || !existsSync(wt.path)) return { removed: false, reason: 'no worktree on disk' }
+  const status = git(wt.path, ['status', '--porcelain'])
+  // a status check that fails must not read as clean
+  if (!status.ok) return { removed: false, reason: `cannot verify ${wt.path}: git status failed` }
+  if (status.out) return { removed: false, reason: `uncommitted changes in ${wt.path}` }
+  // "already landed" is true not just for a fast-forward ancestor but also for a
+  // squash- or rebase-merge and a cherry-pick: git cherry marks a commit whose
+  // patch is already upstream with '-', so no '+' line means the work is in base
+  const cherry = wt.base ? git(s.repo, ['cherry', wt.base, wt.branch]) : { ok: false, out: '' }
+  const ancestor = wt.base && git(s.repo, ['merge-base', '--is-ancestor', wt.branch, wt.base]).ok
+  const merges = wt.base ? git(s.repo, ['rev-list', '--merges', `${wt.base}..${wt.branch}`]) : { ok: false, out: '' }
+  const patchEquivalent = cherry.ok && merges.ok && !merges.out && !cherry.out.split('\n').some((l) => l.startsWith('+'))
+  const merged = wt.base && (ancestor || patchEquivalent)
+  if (!merged) return { removed: false, reason: `${wt.branch} has commits that are not on ${wt.base ?? 'any branch'}` }
+  const removed = removeWorktree(s.repo, s.session_id, { deleteBranch: true })
+  return { removed: removed.removed, branchDeleted: removed.branchDeleted, branch: wt.branch }
+}