@ucsandman/legcli 0.7.0 → 0.9.0

package/src/runner.mjs

@@ -129,7 +129,7 @@ function errTail(path, lines = 10) {
 
 function killTree(pid, log) {
   if ((process.env.LEG_SKIP_KILL || process.env.BATON_SKIP_KILL) === '1') { // test seam: unkillable agent
-    log('BATON_SKIP_KILL=1: killTree skipped')
+    log('LEG_SKIP_KILL=1: killTree skipped')
     return
   }
   if (process.platform === 'win32') {
@@ -151,14 +151,14 @@ function gitHead(cwd) {
 function gitDiff(cwd, headAtStart) {
   const r = spawnSync('git', ['status', '--porcelain'], { cwd, windowsHide: true, encoding: 'utf8', env: { ...process.env, MSYS_NO_PATHCONV: '1' } })
   if (r.status !== 0) return null
-  const files = r.stdout.split(/\r?\n/).filter(Boolean).filter((l) => !/\.baton[\\/]/.test(l)).length
+  const files = r.stdout.split(/\r?\n/).filter(Boolean).filter((l) => !/\.(baton|leg)[\\/]/.test(l)).length
   const head = gitHead(cwd)
   return { changed: files > 0 || (headAtStart !== null && head !== headAtStart), files, head_at_start: headAtStart, head }
 }
 
 // Fallback when the cwd is not a git repo (tests, ad-hoc dirs): a shallow
 // mtime snapshot, so "wrote a file but no DONE" still reads as incomplete.
-const SNAP_SKIP = new Set(['.git', 'node_modules', '.baton', '.baton-worktrees'])
+const SNAP_SKIP = new Set(['.git', 'node_modules', '.baton', '.baton-worktrees', '.leg', '.leg-worktrees'])
 function fsSnapshot(cwd, depth = 3) {
   const out = new Map()
   const walk = (dir, rel, d) => {

package/src/scheduler.mjs

@@ -46,7 +46,7 @@ export function pickRunnable(cards, { max = MAX_CONCURRENT, landing = new Set()
 
 export function pidfile() { return join(home(), 'scheduler.pid') }
 
-export function createScheduler({ max = MAX_CONCURRENT, intervalMs = 1000, actor = { type: 'baton' } } = {}) {
+export function createScheduler({ max = MAX_CONCURRENT, intervalMs = 1000, actor = { type: 'leg' } } = {}) {
   const state = { blockedKeys: new Map(), inflight: new Map(), stopped: false, ticks: 0 }
 
   async function tick() {

package/src/server.mjs

@@ -2,8 +2,8 @@
 // server — the board's HTTP + SSE backend. Ledger-backed: every handler reads
 // card.json / events-*.jsonl on demand (no module-level card store), so a
 // restart shows the same board and a second process sees the same truth.
-// BATON_BIND (127.0.0.1) + BATON_PORT (4747) + BATON_TOKEN are the
-// multiplayer seams (src/auth.mjs).
+// LEG_BIND (127.0.0.1) + LEG_PORT (4747) + LEG_TOKEN are the
+// multiplayer seams (src/auth.mjs). BATON_* names still work as fallback.
 import http from 'node:http'
 import { spawnSync } from 'node:child_process'
 import { existsSync, readFileSync, statSync, rmSync, watch as fsWatch, mkdirSync, openSync, fstatSync, readSync, closeSync } from 'node:fs'
@@ -26,15 +26,26 @@ import { scrub } from './runner.mjs'
 import { resolveChb } from './handoff.mjs'
 import { listSessions, readSession, readEvents as readSessionEvents, requestControl, removeSession, overlaps, isActive, sessionsRoot, reapLost, readLand, readLandings, readRequests, writeRequests, appendEvent as appendSessionEvent, updateSession, HANDOFF_ORDER_CAPABILITY } from './sessions.mjs'
 import { sessionDetail, sessionDiff, DiffInputError } from './session-detail.mjs'
+import { hasRecentSynthesis } from './synthesis.mjs'
 import { refreshPointers } from './resume.mjs'
-import { landSession, landBlocker, landingNow, pruneSessionWorktree } from './land.mjs'
+import { landSession, landBlocker, landingNow, pruneSessionWorktree, canLand, prepareLanding, applyLandFix } from './land.mjs'
 import { readUsage, recordUsage, usageIsStale, candidates, isAvailable } from './usage.mjs'
 import { readAccounts, envFor, LAYOUT } from './accounts.mjs'
 import { readCodexUsage } from './taps/codex.mjs'
 import { readPreferences, writePreferences, normalizeHandoffOrder, requireHandoffOrder } from './preferences.mjs'
 
 const SELF = fileURLToPath(import.meta.url)
-const BOARD_DIR = join(dirname(SELF), 'board')
+export function resolveBoardDir() {
+  const dir = join(dirname(SELF), 'board')
+  if (existsSync(dir)) return dir
+  const wtMatch = /[\\/]\.(?:leg|baton)-worktrees(?:[\\/].*)?$/.exec(dirname(SELF))
+  if (wtMatch) {
+    const root = dirname(SELF).slice(0, wtMatch.index)
+    const fallback = join(root, 'src', 'board')
+    if (existsSync(fallback)) return fallback
+  }
+  return dir
+}
 const VERSION = JSON.parse(readFileSync(join(dirname(SELF), '..', 'package.json'), 'utf8')).version
 const DEFAULT_ORDER = ['plan', 'build', 'review', 'test', 'land']
 const TYPES = { '.html': 'text/html; charset=utf-8', '.css': 'text/css; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.svg': 'image/svg+xml', '.png': 'image/png', '.ico': 'image/x-icon', '.json': 'application/json; charset=utf-8', '.woff2': 'font/woff2' }
@@ -191,16 +202,17 @@ export async function detectTools({ refresh = false } = {}) {
     return !r.error && r.status === 0
   }
   const agents = {}
-  for (const name of ['claude', 'codex', 'agy']) {
+  for (const name of ['claude', 'codex', 'agy', 'grok']) {
     try {
-      const { bin, viaNode, entry } = (await getAdapter(name)).resolve()
+      const a = name === 'grok' ? (await import('./adapters/grok.mjs')).default : await getAdapter(name)
+      const { bin, viaNode, entry } = a.resolve()
       const target = viaNode ? (entry ?? bin) : bin
       agents[name] = /[\\/]/.test(target) ? existsSync(target) : probe(target)
     } catch { agents[name] = false }
   }
   let chb = false
   try { resolveChb(); chb = true } catch {}
-  toolsCache = { ...agents, grok: probe('grok'), chb, git: probe('git') }
+  toolsCache = { ...agents, chb, git: probe('git') }
   return toolsCache
 }
 
@@ -257,6 +269,8 @@ function redactSession(s) {
     // the branch is already on the worktree chip: naming it again costs nothing
     // and is what the board's land line reads
     land: s.land ? { state: s.land.state, branch: s.land.branch ?? null, base: s.land.base ?? null, sha: s.land.sha ?? null, reason: s.land.reason ?? null } : null,
+    // the chip's word only: paths, dropped items and attention text stay on this machine
+    harness: s.harness ? { state: s.harness.state, target: s.harness.target ?? null } : null,
     task: null, cwd: null, files: [], overlap: [], requests: [], hidden: true,
     land_blocker: `read-only: this terminal belongs to ${s.owner ?? 'someone else'}`,
   }
@@ -279,6 +293,7 @@ export function sessionsView({ viewer = null, share = null } = {}) {
     const preferredNext = chain[0] ?? null
     const availabilityKnown = Boolean(s.installed)
     const eligibleNext = availabilityKnown ? (chain.find((next) => s.installed[next.agent] !== false && isAvailable(readUsage(next.agent, next.account))) ?? null) : null
+    const can = s.worktree ? canLand(s) : { ok: false, blockers: [{ code: 'no_worktree', message: 'this terminal works in the checkout itself: there is no branch of its own to land', fix: null }] }
     return {
       ...s,
       handoff_order: handoffOrder,
@@ -288,6 +303,7 @@ export function sessionsView({ viewer = null, share = null } = {}) {
       handoff_availability_known: availabilityKnown,
       can_edit_handoff_order: s.runtime_capabilities?.includes(HANDOFF_ORDER_CAPABILITY) ?? false,
       active: isActive(s),
+      has_synthesis: hasRecentSynthesis(s),
       overlap: ov.get(s.session_id) ?? [],
       elapsed_ms: Date.now() - Date.parse(s.started_at),
       // Older attached Codex processes can retain one parser mistake where an
@@ -296,7 +312,8 @@ export function sessionsView({ viewer = null, share = null } = {}) {
       files: [...new Set([...(s.files_touched ?? []), ...(s.files_dirty ?? [])])].filter(visibleSessionFile),
       // a 'landing' left behind by a board restart is no longer in flight
       land: land?.state === 'landing' && !landingNow(s.session_id) ? { ...land, state: 'interrupted' } : land,
-      land_blocker: s.worktree ? landBlocker(s) : null,
+      can_land: can,
+      land_blocker: s.worktree ? (can.ok ? null : can.blockers[0]?.message) : null,
     }
   })
   const accounts = []
@@ -349,10 +366,11 @@ function readBody(req) {
 }
 
 function serveStatic(res, urlPath) {
-  const map = { '/': 'index.html', '/floor': 'floor.html' }
+  const map = { '/': 'index.html', '/board': 'index.html', '/board/': 'index.html', '/floor': 'floor.html', '/floor/': 'floor.html' }
   const rel = map[urlPath] ?? urlPath.replace(/^\/+/, '')
-  const file = resolve(BOARD_DIR, rel)
-  if (!file.startsWith(BOARD_DIR + sep) || !existsSync(file) || !statSync(file).isFile()) return send(res, 404, 'not found')
+  const boardDir = resolveBoardDir()
+  const file = resolve(boardDir, rel)
+  if (!file.startsWith(boardDir + sep) || !existsSync(file) || !statSync(file).isFile()) return send(res, 404, 'not found')
   res.writeHead(200, { 'Content-Type': TYPES[extname(file)] ?? 'application/octet-stream', 'Cache-Control': 'no-store' })
   res.end(readFileSync(file))
 }
@@ -457,7 +475,7 @@ function createSse({ healthIntervalMs = 10000, debounceMs = 30, viewFor = () =>
 // ---- the server ----
 export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN || process.env.BATON_TOKEN || '', scheduler = (process.env.LEG_NO_SCHEDULER || process.env.BATON_NO_SCHEDULER) !== '1', share, usagePolling = false, usageReader = readCodexUsage } = {}) {
   // An explicit `share` (tests) is fixed; the real server passes none and reads
-  // share.json from disk, re-reading it per request (mtime-cached) so `baton
+  // share.json from disk, re-reading it per request (mtime-cached) so `leg
   // share add|rotate|rm` takes effect on a live board — a new link works at
   // once and a removed or rotated one stops at once — without a restart.
   const explicitShare = share !== undefined
@@ -563,7 +581,7 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
         const you = { ...viewer, share: { on: shared, people: shared ? share.people.length : 0 } }
         if (guest) return send(res, 200, { ok: true, version: VERSION, you })
         const cards = listCards()
-        return send(res, 200, { ok: true, version: VERSION, bind, port, home: home(), you, scheduler: { ...schedulerStatus(), in_process: Boolean(sched), max_concurrent: MAX_CONCURRENT }, tools: await detectTools(), columns: columnsFor(cards), cards: cards.length })
+        return send(res, 200, { ok: true, pid: process.pid, version: VERSION, bind, port, home: home(), you, scheduler: { ...schedulerStatus(), in_process: Boolean(sched), max_concurrent: MAX_CONCURRENT }, tools: await detectTools(), columns: columnsFor(cards), cards: cards.length })
       }
       if (req.method === 'GET' && path === '/api/adapters') return send(res, 200, { adapters: await adaptersInfo() })
       if (req.method === 'GET' && path === '/api/presets') return send(res, 200, { presets: PRESETS })
@@ -596,7 +614,20 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
         if (req.method === 'POST' || req.method === 'PATCH') {
           const body = await readBody(req)
           try {
-            const preferences = writePreferences({ handoff_order: requireHandoffOrder(body.handoff_order) })
+            const patch = {}
+            if (body.handoff_order !== undefined) patch.handoff_order = requireHandoffOrder(body.handoff_order)
+            if (body.harness !== undefined) {
+              // the board may narrow the policy or turn the feature off; turning
+              // it on is the first-run consent flow, which shows what will be
+              // written before it writes (leg harness enable)
+              if (body.harness?.enabled === true) return send(res, 400, { error: 'turn the portable harness on from a terminal: leg harness enable shows what it will write before it writes it' })
+              const rank = ['warn', 'sync', 'strict']
+              const current = readPreferences().harness
+              if (body.harness?.policy !== undefined && rank.indexOf(body.harness.policy) > rank.indexOf(current.policy)) return send(res, 400, { error: `the board may only narrow the harness policy (now ${current.policy}); widen it from a terminal: leg harness policy ${body.harness.policy}` })
+              patch.harness = { policy: body.harness?.policy, enabled: body.harness?.enabled === false ? false : undefined }
+            }
+            if (!Object.keys(patch).length) return send(res, 400, { error: 'nothing to change: send handoff_order or harness' })
+            const preferences = writePreferences(patch)
             sse.broadcast('sessions', (v) => viewFor(v))
             return send(res, 200, { preferences })
           } catch (err) {
@@ -687,9 +718,25 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
           }
         }
         if (req.method === 'POST' && parts[3] === 'land') {
+          if (parts[4] === 'prepare') {
+            const cl = canLand(sess)
+            if (!cl.ok) return send(res, 409, { ok: false, error: cl.blockers[0].message, blockers: cl.blockers })
+            const prep = await prepareLanding(sess, { by: actor.id })
+            return send(res, prep.ok ? 200 : 409, prep)
+          }
+          if (parts[4] === 'fix') {
+            const body = await readBody(req)
+            try {
+              const r = await applyLandFix(sess.session_id, body?.action, { by: actor.id, message: body?.message })
+              try { sse.broadcast('sessions', (v) => viewFor(v)) } catch {}
+              return send(res, 200, r)
+            } catch (err) {
+              return send(res, 400, { ok: false, error: err.message })
+            }
+          }
           const why = landBlocker(sess)
           if (why) return send(res, 409, { error: why })
-          landSession(sess, { by: actor.id })
+          landSession(sess, { by: actor.id, autoCommit: true })
             .catch((err) => log(`land ${id}: ${err.message}`))
             .finally(() => { trunkCache.clear(); try { sse.broadcast('sessions', (v) => viewFor(v)) } catch {} })
           log(`land requested for ${id} by ${actor.id}`)
@@ -795,12 +842,14 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
           const addr = server.address()
           log(`listening on http://${bind}:${addr.port} (home ${home()}${token ? ', token required' : ', loopback open'})`)
           // A terminal that crashed instead of exiting left its hand-off in
-          // .baton/RESUME.md looking live. The board is the thing that starts
+          // .leg/RESUME.md looking live. The board is the thing that starts
           // after a crash, so it is where that gets corrected.
-          try {
-            const touched = refreshPointers()
-            if (touched.length) log(`rewrote ${touched.length} stale resume pointer${touched.length === 1 ? '' : 's'}: the terminal each described is gone, or no Baton stamped it`)
-          } catch (err) { log(`resume pointers not refreshed: ${err.message}`) }
+          setImmediate(() => {
+            try {
+              const touched = refreshPointers()
+              if (touched.length) log(`rewrote ${touched.length} stale resume pointer${touched.length === 1 ? '' : 's'}: the terminal each described is gone, or no Leg stamped it`)
+            } catch (err) { log(`resume pointers not refreshed: ${err.message}`) }
+          })
           if (scheduler) {
             sched = createScheduler()
             sched.run().catch((err) => log(`scheduler crashed: ${err.message}`))

package/src/session-detail.mjs

@@ -11,6 +11,7 @@ import { scrub } from './redact.mjs'
 import { transcriptTail as claudeTail } from './taps/claude.mjs'
 import { transcriptTail as codexTail } from './taps/codex.mjs'
 import { resumeVerdict, verdictForBoard } from './resume.mjs'
+import { readHistory } from './harness/index.mjs'
 
 export const MESSAGE_LIMIT = 8
 export const DIFF_MAX_LINES = 400
@@ -41,7 +42,7 @@ export function sessionMessages(session, limit = MESSAGE_LIMIT) {
   if (!path) return []
   const tail = session.agent === 'claude' ? claudeTail(path, limit)
     : session.agent === 'codex' ? codexTail(path, limit)
-      : [] // agy keeps no transcript Baton can read
+      : [] // agy keeps no transcript Leg can read
   return tail.map((m) => ({ role: m.role === 'user' ? 'user' : 'assistant', text: scrub(m.text), ts: m.ts ?? null }))
 }
 
@@ -116,6 +117,18 @@ function resumeFor(session) {
   try { return verdictForBoard(resumeVerdict(root)) } catch { return null }
 }
 
+// The harness the leg now running was given: what the session recorded when
+// the leg started, plus every capture, sync and decision the harness trail
+// holds for this session. Paths in the attention list are local; a guest never
+// reaches the drawer.
+function harnessFor(session) {
+  const h = session.harness ?? null
+  let history = []
+  try { history = readHistory(200).filter((r) => r.session_id === session.session_id).slice(-20) } catch { /* the drawer renders without the trail */ }
+  if (!h && !history.length) return null
+  return { ...(h ?? {}), history }
+}
+
 export function sessionDetail(session) {
   return {
     session_id: session.session_id,
@@ -124,6 +137,7 @@ export function sessionDetail(session) {
     events: readEvents(session.session_id).slice(-EVENT_LIMIT),
     bundle: session.bundle ?? null,
     resume: resumeFor(session),
+    harness: harnessFor(session),
     ts: new Date().toISOString(),
   }
 }

package/src/sessions.mjs

@@ -1,4 +1,4 @@
-// sessions — the store behind `baton claude|codex|agy`. One directory per
+// sessions — the store behind `leg claude|codex|agy`. One directory per
 // interactive terminal session under $BATON_HOME/sessions/<id>/:
 //   session.json   the live record the board renders (atomic writes)
 //   events.jsonl   timeline (started, turn, warning, limit, handoff, ended)
@@ -11,9 +11,10 @@ import { randomBytes } from 'node:crypto'
 import { home } from './store.mjs'
 import { writeJsonAtomic, withFileLock } from './fsx.mjs'
 import { scrub } from './redact.mjs'
-import { HANDOFF_AGENTS, normalizeHandoffOrder } from './preferences.mjs'
+import { HANDOFF_AGENTS, ALL_HANDOFF_AGENTS, normalizeHandoffOrder } from './preferences.mjs'
 
 export const AGENTS = HANDOFF_AGENTS
+export const SUPERVISED_AGENTS = ALL_HANDOFF_AGENTS
 export const HANDOFF_ORDER_CAPABILITY = 'handoff_order_v1'
 export const SESSION_STATUSES = ['starting', 'running', 'warning', 'limit', 'handing_off', 'waiting', 'handed_off', 'ended', 'lost']
 const ACTIVE = ['starting', 'running', 'warning', 'limit', 'handing_off', 'waiting']
@@ -43,7 +44,7 @@ export function listSessions() {
 
 export function isActive(s) { return ACTIVE.includes(s?.status) }
 
-// The checkout this session's files live in: its own worktree when Baton gave
+// The checkout this session's files live in: its own worktree when Leg gave
 // it one (repo stays the main checkout, for grouping and landing), else the repo.
 export function workRoot(s) { return s?.worktree?.path ?? s?.repo ?? s?.cwd ?? null }
 
@@ -57,10 +58,13 @@ export function createSession({ id, agent, account = 'default', cwd, repo = null
     task: null, turns: 0,
     files_touched: [], files_dirty: [], head: null, head_at_start: null,
     limits: null, limit: null, warning: null,
-    bundle: null, handoff: null, chain,
+    bundle: null, handoff: null, chain, checkpoints: [],
     handoff_order: normalizeHandoffOrder(handoffOrder), installed,
     runtime_capabilities: [...new Set(runtimeCapabilities)],
     lineage: { from: null, to: null },
+    // the portable-harness outcome for the leg now running (src/harness/index.mjs);
+    // null until the feature is enabled and a leg has been prepared
+    harness: null,
     exit_code: null,
   }
   mkdirSync(sessionDir(id), { recursive: true })
@@ -160,7 +164,7 @@ export function readLandings() {
   return readFileSync(landingsFile(), 'utf8').split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l) } catch { return null } }).filter(Boolean)
 }
 
-function pidAlive(pid) {
+export function pidAlive(pid) {
   if (!pid) return false
   // EPERM means the process exists but is not ours to signal (e.g. an elevated
   // terminal): it is alive. Only ESRCH ("no such process") means gone.

package/src/share.mjs

@@ -1,7 +1,7 @@
-// share — optional multiplayer for the board, off until `baton share on`
+// share — optional multiplayer for the board, off until `leg share on`
 // writes $BATON_HOME/share.json. With it on, the board binds the Tailscale or
 // LAN address, every human has a name and their own token (kept as a sha256
-// hash: a token is printed once and `baton share rotate` issues a new one),
+// hash: a token is printed once and `leg share rotate` issues a new one),
 // and every session belongs to the human whose terminal started it
 // (`BATON_PERSON`, else the owner). With it off nothing changes: loopback is
 // open and `BATON_TOKEN` is the only token.

package/src/stations/agent.mjs

@@ -1,4 +1,4 @@
-// Station kind: agent. One chain leg runs here (or, after `baton down` or a
+// Station kind: agent. One chain leg runs here (or, after `leg down` or a
 // crashed server, the orchestrator re-attaches to the run it left behind),
 // the run is settled, and its verdict is applied to the card. `ops` are the
 // orchestrator's helpers; this module never imports the orchestrator.

package/src/sync/dashclaw.mjs

@@ -1,5 +1,5 @@
 // dashclaw sync — records every ledger event as a DashClaw action over native
-// http/https (LESSONS 07-12: no global fetch). Off unless BATON_SYNC_DASHCLAW=1
+// http/https (LESSONS 07-12: no global fetch). Off unless LEG_SYNC_DASHCLAW=1
 // and DASHCLAW_URL + DASHCLAW_API_KEY are set. Field names come from
 // DashClaw's validator (app/lib/validate.js ACTION_RECORD_SCHEMA): agent_id,
 // action_type and declared_goal are required; status is one of running,
@@ -26,11 +26,11 @@ const STATUS_BY_TYPE = {
 
 // One ledger event → one action record (the request body).
 export function actionForEvent(ev, card = null) {
-  const actor = ev.actor ?? { type: 'baton' }
-  const agent = actor.type === 'agent' ? `baton/${actor.adapter}` : actor.type === 'human' ? `baton/human:${actor.id}` : 'baton'
+  const actor = ev.actor ?? { type: 'leg' }
+  const agent = actor.type === 'agent' ? `leg/${actor.adapter}` : actor.type === 'human' ? `leg/human:${actor.id}` : 'leg'
   const body = {
     agent_id: agent,
-    action_type: `baton_${ev.type}`,
+    action_type: `leg_${ev.type}`,
     declared_goal: String(ev.summary ?? ev.type).slice(0, 2000),
     status: STATUS_BY_TYPE[ev.type] ?? 'completed',
     reversible: true,

package/src/synthesis.mjs

@@ -0,0 +1,165 @@
+// synthesis — the agent-maintained judgment record included in the handoff bundle.
+// Spec: Leg Handoff Synthesis Layer — build spec v1
+// File: .leg/SYNTHESIS-<session-id>.md
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const MAX_SYNTHESIS_BYTES = 4096
+export const TRUNCATED_MARKER = '[synthesis truncated]'
+export const INVALID_HEADER_PREFIX = '[synthesis header invalid, rendering body as-is]'
+export const SYNTHESIS_POINTER_PARAGRAPH = "Read the Synthesis section first if present. Treat 'Ruled out' as settled: do not retry a ruled-out approach unless you have new evidence it was wrong. Start from the top-ranked Next step unless the repo state contradicts it."
+
+export const SYNTHESIS_SECTIONS = [
+  '## Ruled out',
+  '## Decisions',
+  '## Next steps',
+  '## Open questions',
+]
+
+// The synthesis file path for a session in its checkout/worktree root
+export function synthesisFile(cwd, id) {
+  if (!cwd || !id) return null
+  const leg = join(cwd, '.leg', `SYNTHESIS-${id}.md`)
+  const baton = join(cwd, '.baton', `SYNTHESIS-${id}.md`)
+  if (existsSync(leg)) return leg
+  if (existsSync(baton)) return baton
+  if (existsSync(join(cwd, '.baton')) && !existsSync(join(cwd, '.leg'))) return baton
+  return leg
+}
+
+// Safely read the synthesis file; returns null if absent, empty, or unreadable
+export function readSynthesis(cwd, id) {
+  if (!cwd || !id) return null
+  const file = synthesisFile(cwd, id)
+  try {
+    if (!existsSync(file)) return null
+    const text = readFileSync(file, 'utf8')
+    if (!text || !text.trim()) return null
+    return text
+  } catch {
+    return null
+  }
+}
+
+// The standing directive for Leg per-session instructions
+export function synthesisDirective(sessionId = '<session-id>') {
+  return `Maintain .leg/SYNTHESIS-${sessionId}.md using the schema in section 4. Update it whenever you rule out an approach, make a consequential decision, or change direction. Keep each section to 5 bullets max, one line per bullet.`
+}
+
+// Validates the 2-line header per schema v1:
+//   synthesis_version: 1
+//   session: <session-id>  updated: <ISO-8601 UTC>
+export function validateSynthesisHeader(text, { sessionId = null } = {}) {
+  if (typeof text !== 'string') return { valid: false, reason: 'content is not a string' }
+  const lines = text.split(/\r?\n/)
+  if (lines.length < 2) return { valid: false, reason: 'fewer than 2 lines' }
+
+  const l0 = lines[0].trim()
+  if (!/^synthesis_version:\s*1$/.test(l0)) {
+    return { valid: false, reason: 'missing or invalid synthesis_version: 1' }
+  }
+
+  const l1 = lines[1].trim()
+  const m = /^session:\s*(\S+)\s+updated:\s*(\S+)$/.exec(l1)
+  if (!m) {
+    return { valid: false, reason: 'missing or invalid session/updated header line' }
+  }
+
+  const [, sessId, updated] = m
+  if (sessionId && sessId !== sessionId) {
+    return { valid: false, reason: `session mismatch: expected ${sessionId}, got ${sessId}` }
+  }
+
+  const parsed = Date.parse(updated)
+  if (Number.isNaN(parsed) || !/(?:Z|[+-]00:?00)$/i.test(updated)) {
+    return { valid: false, reason: 'updated timestamp is not valid ISO-8601 UTC' }
+  }
+
+  return { valid: true, version: 1, session: sessId, updated }
+}
+
+// Validates the full schema v1: header + optional sections in fixed order with max 5 bullets each
+export function validateSynthesis(text, { sessionId = null } = {}) {
+  const header = validateSynthesisHeader(text, { sessionId })
+  const errors = []
+  if (!header.valid) {
+    errors.push(header.reason)
+  }
+
+  if (typeof text !== 'string') {
+    return { valid: false, headerValid: false, errors: ['content is not a string'] }
+  }
+
+  const lines = text.split(/\r?\n/)
+  let lastSectionIdx = -1
+  let currentSection = null
+  let currentBullets = 0
+
+  for (let i = 2; i < lines.length; i++) {
+    const line = lines[i].trim()
+    if (line.startsWith('## ')) {
+      const idx = SYNTHESIS_SECTIONS.indexOf(line)
+      if (idx === -1) {
+        errors.push(`unknown section: ${line}`)
+      } else if (idx <= lastSectionIdx) {
+        errors.push(`section out of order: ${line}`)
+      } else {
+        lastSectionIdx = idx
+      }
+      currentSection = line
+      currentBullets = 0
+    } else if (line.startsWith('- ')) {
+      currentBullets++
+      if (currentBullets > 5) {
+        errors.push(`section ${currentSection || 'unknown'} exceeds 5 bullets`)
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    headerValid: header.valid,
+    errors,
+    session: header.session ?? null,
+    updated: header.updated ?? null,
+  }
+}
+
+// Inlines synthesis into the ## Synthesis section with size cap (4 KB) and malformed header handling
+export function formatSynthesisSection(rawText, { sessionId = null } = {}) {
+  if (!rawText || !rawText.trim()) return ''
+
+  let content = rawText
+  const buf = Buffer.from(content, 'utf8')
+  if (buf.length > MAX_SYNTHESIS_BYTES) {
+    const sliced = buf.subarray(0, MAX_SYNTHESIS_BYTES).toString('utf8')
+    const sep = sliced.endsWith('\n') ? '' : '\n'
+    content = `${sliced}${sep}${TRUNCATED_MARKER}`
+  }
+
+  const header = validateSynthesisHeader(content, { sessionId })
+  if (!header.valid) {
+    content = `${INVALID_HEADER_PREFIX}\n${content}`
+  }
+
+  return `## Synthesis\n\n${content.trim()}`
+}
+
+// True if .leg/SYNTHESIS-<session-id>.md exists, is non-empty, and was modified within the last 3 checkpoints
+export function hasRecentSynthesis(session) {
+  if (!session) return false
+  const root = session.worktree?.path ?? session.repo ?? session.cwd ?? null
+  if (!root || !session.session_id) return false
+  const file = synthesisFile(root, session.session_id)
+  try {
+    if (!existsSync(file)) return false
+    const st = statSync(file)
+    if (!st.isFile() || st.size === 0) return false
+    const checkpoints = session.checkpoints ?? []
+    if (checkpoints.length < 3) return true
+    const threshold = new Date(checkpoints[checkpoints.length - 3]).getTime()
+    return st.mtimeMs >= threshold
+  } catch {
+    return false
+  }
+}

package/src/taps/agy.mjs

@@ -1,8 +1,8 @@
 // agy tap — Antigravity CLI 1.2.0 is a closed Go binary with no hooks and no
-// usage percentage on any surface Baton can read (its own status line fetches
+// usage percentage on any surface Leg can read (its own status line fetches
 // a quota summary from the backend; the value is not written anywhere). What
 // it does give:
-//   --log-file <path>       one log per Baton session; the wall shows up as
+//   --log-file <path>       one log per Leg session; the wall shows up as
 //                           RESOURCE_EXHAUSTED / "it resets in <d>" / "out of quota"
 //                           (strings present in agy.exe; docs-only until hit live)
 //   ~/.gemini/antigravity-cli/history.jsonl

package/src/taps/claude-usage.mjs

@@ -3,7 +3,7 @@
 // Why not the status line: Claude Code 2.1.268 renders its built-in status
 // line and does not run a custom `statusLine` command passed via --settings
 // or a project settings file (verified 2026-09-11 with an `echo` command at
-// both levels; hooks from the same --settings file do run). So Baton asks the
+// both levels; hooks from the same --settings file do run). So Leg asks the
 // usage endpoint directly with the OAuth token Claude Code stored at login.
 // The token is read by this process only, sent only to api.anthropic.com,
 // and never written anywhere (the ledger scrubs bearer tokens regardless).