@ucsandman/legcli 0.8.0 → 0.9.0

package/src/resume.mjs

@@ -1,17 +1,18 @@
 // resume — the pointer that cannot describe a picture that is no longer true.
 //
-// `.baton/RESUME.md` is the file humans and other agents open by habit. It used
+// `.leg/RESUME.md` is the file humans and other agents open by habit (legacy
+// `.baton/RESUME.md` is still read). It used
 // to be an unowned convenience copy: written once per hand-off, never touched
 // again, with no stamp and no expiry, so a normally exited terminal left hours
 // old text sitting there looking live.
 //
 // Two rules fix that, and they are the whole module:
-//   1. Every resume file Baton writes carries a stamp of the git state and the
+//   1. Every resume file Leg writes carries a stamp of the git state and the
 //      live terminals it was written against (an HTML comment, invisible in
 //      rendered markdown).
 //   2. Freshness is never remembered — it is recomputed from git at READ time.
 //      A file cannot lie about HEAD to a reader who re-asks git.
-// Baton owns the file: it rewrites it when a session ends and when the board
+// Leg owns the file: it rewrites it when a session ends and when the board
 // starts, so nothing is left describing a terminal that is gone.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { spawnSync } from 'node:child_process'
@@ -24,8 +25,8 @@ export const STAMP_PREFIX = '<!-- leg-resume '
 export const LEGACY_STAMP_PREFIX = '<!-- baton-resume '
 const STAMP_SUFFIX = ' -->'
 const STAMP_VERSION = 1
-// Baton's own directories dirty the tree on every write; a reader must not see
-// Baton's bookkeeping as the human's work moving on.
+// Leg's own directories dirty the tree on every write; a reader must not see
+// Leg's bookkeeping as the human's work moving on.
 const LEG_DIRS = /^(\.leg|\.baton|\.context-handoffs|\.dashclaw-local)[\\/]/
 const MAX_REASONS = 5
 
@@ -81,6 +82,7 @@ export function perSessionFile(cwd, id) {
   if (existsSync(join(cwd, '.baton')) && !existsSync(join(cwd, '.leg'))) return baton
   return leg
 }
+export { synthesisFile } from './synthesis.mjs'
 
 // An agent started deeper in the tree still finds its checkout's pointer.
 export function findResume(startDir) {
@@ -117,7 +119,7 @@ export function readStamp(text) {
   } catch { return null }
 }
 
-// The text without its stamp: what a human reads and what `baton resume` prints.
+// The text without its stamp: what a human reads and what `leg resume` prints.
 export function bodyOf(text) {
   const s = String(text ?? '')
   return readStamp(s) ? s.slice(s.indexOf('\n') + 1).replace(/^\n+/, '') : s
@@ -200,10 +202,10 @@ export function lastHandoffIn(root, sessions = listSessions()) {
 }
 
 function idleBody(last, live) {
-  const lines = ['# Baton: nothing in flight', '']
+  const lines = ['# Leg: nothing in flight', '']
   lines.push(live.length
     ? `No hand-off is waiting to be picked up here. Still live in this checkout: ${live.map((s) => `${s.session_id} (${s.agent})`).join(', ')}.`
-    : 'No Baton terminal is live in this checkout.')
+    : 'No Leg terminal is live in this checkout.')
   lines.push('')
   if (last) {
     const at = last.at ? String(last.at).slice(0, 16).replace('T', ' ') : 'an unrecorded time'
@@ -221,7 +223,7 @@ function idleBody(last, live) {
 }
 
 // The "nothing in flight" pointer. Always writes; the callers that must not
-// create a file in a checkout Baton never handed off in check first.
+// create a file in a checkout Leg never handed off in check first.
 export function writeIdlePointer(root, { sessions = listSessions() } = {}) {
   if (!root) return null
   const dir = existsSync(join(root, '.baton')) && !existsSync(join(root, '.leg')) ? join(root, '.baton') : join(root, '.leg')
@@ -235,7 +237,7 @@ export function writeIdlePointer(root, { sessions = listSessions() } = {}) {
 }
 
 // A session ending must not leave its hand-off sitting there looking live.
-// Only ever rewrites a pointer that already exists: Baton owns RESUME.md where
+// Only ever rewrites a pointer that already exists: Leg owns RESUME.md where
 // it wrote one, and creates none in a checkout it never handed off in.
 export function endSessionPointer(session) {
   const root = workRoot(session)
@@ -243,7 +245,7 @@ export function endSessionPointer(session) {
   return writeIdlePointer(root)
 }
 
-// Board start: every checkout Baton wrote a pointer in gets it recomputed, so a
+// Board start: every checkout Leg wrote a pointer in gets it recomputed, so a
 // terminal that crashed instead of exiting cannot leave a live-looking hand-off
 // behind. A checkout whose terminal really is live keeps its hand-off text.
 // Returns the roots rewritten.
@@ -260,9 +262,9 @@ export function refreshPointers() {
     const v = resumeVerdict(root, { sessions })
     if (v.state === 'fresh') continue
     // The terminal that wrote a hand-off owns it while it is still running: its
-    // text is the live description, and "the repo moved on" is for `baton resume
+    // text is the live description, and "the repo moved on" is for `leg resume
     // --check` to report, not for the board to overwrite. Anything else — a
-    // hand-off from a terminal that is gone, a file no Baton stamped — is
+    // hand-off from a terminal that is gone, a file no Leg stamped — is
     // replaced even when some OTHER terminal happens to be live in the
     // checkout, which is the case that left three day old text sitting there.
     if (v.session?.active) continue
@@ -284,14 +286,14 @@ function describe(list) { return list.map((s) => `${s.id ?? s.session_id} (${s.a
 export function resumeVerdict(cwd, { sessions = listSessions() } = {}) {
   const found = findResume(cwd)
   if (!found) {
-    return { state: 'missing', exit_code: EXIT.missing, root: null, file: null, kind: null, stamp: null, reasons: ['there is no .baton/RESUME.md in this checkout'], summary: 'no resume pointer in this checkout', head: null, dirty: null, live: null, session: null, written_at: null, age_ms: null }
+    return { state: 'missing', exit_code: EXIT.missing, root: null, file: null, kind: null, stamp: null, reasons: ['there is no .leg/RESUME.md in this checkout'], summary: 'no resume pointer in this checkout', head: null, dirty: null, live: null, session: null, written_at: null, age_ms: null }
   }
   const { root, file } = found
   let text = ''
   try { text = readFileSync(file, 'utf8') } catch { /* raced a rewrite */ }
   const stamp = readStamp(text)
   if (!stamp) {
-    return { state: 'unstamped', exit_code: EXIT.unstamped, root, file, kind: null, stamp: null, reasons: ['this file carries no Baton stamp, so its freshness cannot be checked against git'], summary: 'cannot be checked: no Baton stamp', head: null, dirty: null, live: null, session: null, written_at: null, age_ms: null }
+    return { state: 'unstamped', exit_code: EXIT.unstamped, root, file, kind: null, stamp: null, reasons: ['this file carries no Leg stamp, so its freshness cannot be checked against git'], summary: 'cannot be checked: no Leg stamp', head: null, dirty: null, live: null, session: null, written_at: null, age_ms: null }
   }
 
   const now = gitState(root)

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,7 +151,7 @@ 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 }
 }

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,6 +26,7 @@ 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, canLand, prepareLanding, applyLandFix } from './land.mjs'
 import { readUsage, recordUsage, usageIsStale, candidates, isAvailable } from './usage.mjs'
@@ -34,7 +35,17 @@ 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' }
@@ -258,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'}`,
   }
@@ -290,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
@@ -352,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))
 }
@@ -460,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
@@ -599,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) {
@@ -814,12 +842,12 @@ 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.
           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 Baton stamped it`)
+              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) {

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)
@@ -44,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 }
 
@@ -58,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 })

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).