@ucsandman/legcli 0.8.0 → 0.9.0

package/src/attach.mjs

@@ -1,5 +1,5 @@
-// attach — `baton claude|codex|agy [args…]`: the normal interactive agent in
-// this terminal, with Baton alongside it. Baton (1) makes sure the board is
+// attach — `leg claude|codex|agy [args…]`: the normal interactive agent in
+// this terminal, with Leg alongside it. Leg (1) makes sure the board is
 // up and opens it once, (2) registers the session so it shows on the board,
 // (3) taps the agent for usage (claude: hooks + status line via --settings;
 // codex: its rollout file; agy: its log), (4) polls git for the files the
@@ -28,16 +28,26 @@ import { findRollout, createTail, parseLines, readCodexUsage, transcriptTail as
 import { scanLog, promptsSince, logSize } from './taps/agy.mjs'
 import { fetchGrokUsage, scanLog as scanGrokLog, promptsSince as grokPromptsSince } from './taps/grok.mjs'
 import { fetchClaudeUsage } from './taps/claude-usage.mjs'
-import { saveSessionBundle, resumePrompt } from './bundle.mjs'
+import { saveSessionBundle, resumePrompt, sessionCommitDelta } from './bundle.mjs'
 import { endSessionPointer } from './resume.mjs'
 import { openBoard, pidfile } from './launcher.mjs'
 import { LAYOUT } from './accounts.mjs'
 import { captureLive } from './live-capture.mjs'
 import { waitForReset, fmtCountdown } from './wait.mjs'
 import { readPreferences, normalizeHandoffOrder, resolveAutoApprove } from './preferences.mjs'
+import { prepareHarnessForHandoff, harnessLine } from './harness/index.mjs'
 
 const SRC = dirname(fileURLToPath(import.meta.url))
-const SERVER = join(SRC, 'server.mjs')
+function resolveServer() {
+  const wtMatch = /[\\/]\.(?:leg|baton)-worktrees(?:[\\/].*)?$/.exec(SRC)
+  if (wtMatch) {
+    const root = SRC.slice(0, wtMatch.index)
+    const mainServer = join(root, 'src', 'server.mjs')
+    if (existsSync(mainServer)) return mainServer
+  }
+  return join(SRC, 'server.mjs')
+}
+const SERVER = resolveServer()
 const POLL_MS = Number(process.env.LEG_ATTACH_POLL_MS || process.env.BATON_ATTACH_POLL_MS || 2000)
 const GIT_EVERY = 3 // polls
 const USAGE_MS = Number(process.env.LEG_USAGE_POLL_MS || process.env.BATON_USAGE_POLL_MS || 60000)
@@ -81,15 +91,15 @@ export async function ensureBoard({ open = true } = {}) {
   if (await health(port, host)) return { url, started: false }
   mkdirSync(home(), { recursive: true })
   const logFd = (await import('node:fs')).openSync(join(home(), 'board.log'), 'a')
-  const child = spawn(process.execPath, [SERVER], { detached: true, windowsHide: true, stdio: ['ignore', logFd, logFd], env: { ...process.env, BATON_PORT: String(port), BATON_BIND: host, BATON_QUIET: '0' } })
+  const child = spawn(process.execPath, [SERVER], { detached: true, windowsHide: true, stdio: ['ignore', logFd, logFd], env: { ...process.env, LEG_PORT: String(port), LEG_BIND: host, LEG_QUIET: '0', BATON_PORT: String(port), BATON_BIND: host, BATON_QUIET: '0' } })
   child.unref()
   const t0 = Date.now()
   while (Date.now() - t0 < 15000) {
     const h = await health(port, host)
     if (h) {
       // only claim the pidfile for a child we actually started: under a race,
-      // another `baton` won the port and ours died on EADDRINUSE — writing our
-      // dead pid would make `baton down` kill nothing and report "not running"
+      // another `leg` won the port and ours died on EADDRINUSE — writing our
+      // dead pid would make `leg down` kill nothing and report "not running"
       const ours = h.pid ? h.pid === child.pid : (child.exitCode === null && Boolean(child.pid))
       if (ours) writeFileSync(pidfile(), JSON.stringify({ pid: child.pid, port, bind: host, children: [child.pid], detached: true, started_by: 'attach', started_at: new Date().toISOString() }, null, 2) + '\n')
       if (open) openBoard(url)
@@ -195,7 +205,7 @@ export async function spawnSpec(agent, { account, args, sessionId, prompt, cwd,
   const argv = []
   // viaNode: either an npm entry (codex bin/codex.js) or a BATON_<AGENT>_BIN that names a .mjs (tests)
   if (viaNode) argv.push(entry ?? bin)
-  // a leg Baton starts on its own (after a hand-off) takes BATON_<AGENT>_ARGS,
+  // a leg Leg starts on its own (after a hand-off) takes BATON_<AGENT>_ARGS,
   // e.g. BATON_CODEX_ARGS="-m gpt-5-mini" to keep a test chain on cheap models
   if (prompt) args = [...(process.env[`LEG_${agent.toUpperCase()}_ARGS`] ?? process.env[`BATON_${agent.toUpperCase()}_ARGS`] ?? '').split(/\s+/).filter(Boolean), ...args]
   if (agent === 'claude') {
@@ -484,14 +494,14 @@ function messagesFor(agent, s) {
 // an order save is consumed here, or the editor sees handing_off and refuses.
 // No eligible choice leaves the session unclaimed so all-out waiting can keep
 // accepting order edits.
-export function claimHandoffChoice({ sid, agent, account, installed, bundle = null, reason = 'limit', nowS = Math.floor(Date.now() / 1000) }) {
+export function claimHandoffChoice({ sid, agent, account, installed, bundle = null, reason = 'limit', nowS = Math.floor(Date.now() / 1000), exclude = [] }) {
   let choice = { next: null, out: [] }
   let claimed = false
   const session = updateSession(sid, (current) => {
     const accounts = readAccounts()
     const order = normalizeHandoffOrder(current.handoff_order)
-    choice = chooseNext({ agent, account, accounts, installed, order, nowS })
-    if (!choice.next && isAvailable(readUsage(agent, account), nowS)) choice = { next: { agent, account }, out: [] }
+    choice = chooseNext({ agent, account, accounts, installed, order, nowS, exclude })
+    if (!choice.next && isAvailable(readUsage(agent, account), nowS) && !exclude.some((x) => x.agent === agent && x.account === account)) choice = { next: { agent, account }, out: [] }
     if (!choice.next) return {}
     claimed = true
     return {
@@ -510,14 +520,29 @@ export function claimHandoffChoice({ sid, agent, account, installed, bundle = nu
   return { choice, claimed, session }
 }
 
+// The portable harness, decided before a leg starts (src/harness/index.mjs).
+// Off by default: then this records nothing and changes nothing. On, it
+// carries the source agent's working environment to the agent about to run,
+// per the saved policy, and the session keeps the outcome so the board can say
+// what transferred and what did not. Never throws into the session.
+function prepareLegHarness({ sid, from, to }) {
+  let outcome
+  try { outcome = prepareHarnessForHandoff({ from, to, sessionId: sid }) } catch (err) { outcome = { state: 'error', policy: 'unknown', proceed: true, to, target: to, reason: String(err.message).slice(0, 200), summary: `harness error: ${String(err.message).slice(0, 120)}` } }
+  if (outcome.state === 'off') return outcome
+  updateSession(sid, { harness: outcome })
+  const line = harnessLine(outcome)
+  if (line) { say(line); appendEvent(sid, { type: outcome.proceed ? 'harness' : 'harness_blocked', summary: line, body: outcome.dropped?.length || outcome.attention?.length ? [...(outcome.attention ?? []).map((a) => `attention ${a.component}: ${a.reason}`), ...(outcome.dropped ?? []).map((d) => `dropped ${d.component}: ${d.item}: ${d.reason}`)].join('\n') : undefined }) }
+  return outcome
+}
+
 // ---- the command ----
 export async function attach(agent, args = [], { open = true } = {}) {
   if (!SUPERVISED_AGENTS.includes(agent)) throw new Error(`unknown agent "${agent}" (claude|codex|agy|grok)`)
   // the paid gate: a valid key, or no session (exit 4). The bare agent is never
-  // affected; only what Baton adds is licensed.
+  // affected; only what Leg adds is licensed.
   const ent = entitlement()
   if (!allows(ent, 'run')) { say(describeLicense(ent)); return 4 }
-  // --no-worktree is Baton's flag, not the agent's: it never passes through
+  // --no-worktree is Leg's flag, not the agent's: it never passes through
   const shareCheckout = args.includes('--no-worktree')
   args = args.filter((a) => a !== '--no-worktree')
   let autoApproveCli = null
@@ -578,6 +603,9 @@ export async function attach(agent, args = [], { open = true } = {}) {
   let prompt = null
   let legArgs = args
   let exit = 0
+  // the first leg is the agent the human chose: its harness is prepared per
+  // policy and recorded, never refused (strict applies to hand-offs)
+  prepareLegHarness({ sid, from: null, to: agent })
   // unbounded: the 12-leg cap below stops a runaway chain, and the all-out wait
   // bounds a wait; a normal session runs one leg and exits
   for (let leg = 0; ; leg++) {
@@ -593,10 +621,14 @@ export async function attach(agent, args = [], { open = true } = {}) {
     // saveSessionBundle writes the notes file before it shells out to chb, so
     // even when chb is missing and the save throws, the context is on disk
     const notesFile = join(workRoot(cur) ?? cur.cwd, '.leg', `session-${sid}.md`)
-    let claim = claimHandoffChoice({ sid, agent, account, installed, bundle, reason: r.reason })
+    // destinations the strict harness policy refused during this hand-off
+    const excluded = []
+    let claim = claimHandoffChoice({ sid, agent, account, installed, bundle, reason: r.reason, exclude: excluded })
     let choice = claim.choice
     let cancelled = false
+    let blocked = false
     while (!choice.next) {
+      if (excluded.length && !choice.out.length) { blocked = true; break }
       // every option is out: keep the terminal, count down to the SOONEST reset
       // (the current agent's own wall included — it may be the first back), then
       // start that option from the bundle. Ctrl-C (or End) quits with exit 3.
@@ -612,7 +644,7 @@ export async function attach(agent, args = [], { open = true } = {}) {
       updateSession(sid, { status: 'waiting', all_out: all, waiting: first ? { agent: first.agent, account: first.account, resets_at: first.resets_at, since: new Date().toISOString() } : null }, { event: { type: 'all_out', summary: `every option is out; waiting for ${label} at ${first ? fmtReset(first.resets_at) : 'unknown'}` } })
       const r2 = await waitInTerminal({ sid, label, resetsAt: first?.resets_at ?? null })
       if (r2 === 'cancelled') { cancelled = true; break }
-      claim = claimHandoffChoice({ sid, agent, account, installed, bundle, reason: r.reason })
+      claim = claimHandoffChoice({ sid, agent, account, installed, bundle, reason: r.reason, exclude: excluded })
       choice = claim.choice
     }
     if (cancelled) {
@@ -620,6 +652,24 @@ export async function attach(agent, args = [], { open = true } = {}) {
       exit = 3
       break
     }
+    // strict harness policy: a destination whose harness cannot be made safe is
+    // refused and the next option is tried; when none is left the session ends
+    // with exit 5 rather than launching an agent without its environment
+    while (!blocked && choice.next) {
+      const prepared = prepareLegHarness({ sid, from: agent, to: choice.next.agent })
+      if (prepared.proceed) break
+      excluded.push(choice.next)
+      say(`${choice.next.agent} refused by the strict harness policy: ${prepared.reason ?? prepared.state}`)
+      claim = claimHandoffChoice({ sid, agent, account, installed, bundle, reason: r.reason, exclude: excluded })
+      choice = claim.choice
+      if (!choice.next) blocked = true
+    }
+    if (blocked) {
+      say('every remaining option was refused by the strict harness policy; stopping (exit 5). Fix what needs attention (leg harness status) or relax the policy (leg harness policy sync), then run leg again in this directory.')
+      updateSession(sid, { status: 'ended', ended_at: new Date().toISOString(), exit_code: 5, waiting: null }, { event: { type: 'ended', summary: 'strict harness policy refused every destination; stopped (exit 5)' } })
+      exit = 5
+      break
+    }
     const next = choice.next
     // bound the number of hand-offs in one terminal so a chain that limits
     // instantly can never loop forever; stopping is explicit, not a silent exit 0
@@ -630,9 +680,15 @@ export async function attach(agent, args = [], { open = true } = {}) {
       break
     }
     appendEvent(sid, { type: 'handoff', summary: `${agent}${account !== 'default' ? '/' + account : ''} → ${next.agent}${next.account !== 'default' ? '/' + next.account : ''}${bundle ? ` (bundle ${bundle.id})` : ''}` })
-    prompt = bundle
-      ? resumePrompt(cur, bundle, next)
-      : `You are taking over an interactive coding session from ${agent}.${existsSync(notesFile) ? ` Read ${notesFile} in this directory first (the previous agent's notes: task, last messages, dirty files).` : ''} Check git status and git diff, then continue the work. The task: ${cur.task ?? 'see the recent changes'}`
+    if (bundle) {
+      prompt = resumePrompt(cur, bundle, next)
+    } else {
+      const delta = sessionCommitDelta(workRoot(cur) ?? cur.cwd, cur)
+      const fallbackAction = delta.isClean && delta.newCommits.length > 0
+        ? `The previous agent committed changes (${delta.newCommits.length} commit(s)) and left a clean working tree. Check git log and verify whether the task is already complete before doing redundant work; continue only if work remains.`
+        : 'Check git status and git diff, then continue the work.'
+      prompt = `You are taking over an interactive coding session from ${agent}.${existsSync(notesFile) ? ` Read ${notesFile} in this directory first (the previous agent's notes: task, last messages, dirty files).` : ''} ${fallbackAction} The task: ${cur.task ?? 'see the recent changes'}`
+    }
     say(`starting ${next.agent}${next.account !== 'default' ? '/' + next.account : ''} in this terminal from the bundle`)
     agent = next.agent; account = next.account; legArgs = []
     // the chain is what comes after the agent now taking over, not after the
@@ -646,7 +702,7 @@ export async function attach(agent, args = [], { open = true } = {}) {
   if (fin && fin.status !== 'ended') updateSession(sid, { status: 'ended', ended_at: new Date().toISOString(), exit_code: exit }, { event: { type: 'ended', summary: `session ended (exit ${exit})` } })
   // Every way out of the loop arrives here: a clean exit, a cancelled wait, the
   // 12-leg cap, an agent that never started. The terminal is gone, so RESUME.md
-  // must stop describing it as live — Baton owns that file, and leaving the last
+  // must stop describing it as live — Leg owns that file, and leaving the last
   // hand-off sitting there is exactly the lie this rewrite exists to stop.
   try { endSessionPointer(readSession(sid)) } catch (err) { appendEvent(sid, { type: 'error', summary: `resume pointer not rewritten: ${err.message.slice(0, 160)}` }) }
   try { rmSync(join(sessionDir(sid), 'control.json'), { force: true }) } catch {}

package/src/auth.mjs

@@ -1,6 +1,6 @@
 // auth — who is allowed in. Loopback with no token is open; any other bind
 // address refuses to start without a token, and with a token every /api
-// request needs `Authorization: Bearer <token>` (timing-safe). With `baton
+// request needs `Authorization: Bearer <token>` (timing-safe). With `leg
 // share` on, each human has their own token and the board knows their name
 // and role (src/share.mjs); a loopback request is still the owner, so the
 // machine's own browser needs nothing.
@@ -75,7 +75,7 @@ export function authorize({ token, req, url, share = null, bind = null, loopback
     return { ok: false, subject: null, person: null }
   }
   // checkBind's invariant, re-applied per request: share.json stops reading as
-  // on (`baton share off`, a truncated file) while the shared address is still
+  // on (`leg share off`, a truncated file) while the shared address is still
   // bound, and nobody but this machine may be the local owner in that window
   if (!token && loopbackOwner === false) return { ok: false, subject: null, person: null }
   if (!token && bind && !isLoopback(bind) && !isLoopback(remoteAddress(req))) return { ok: false, subject: null, person: null }

package/src/board/board.js

@@ -253,10 +253,10 @@
   }
 
   function formatActor(actor) {
-    if (!actor) return 'baton'
+    if (!actor) return 'leg'
     if (actor.type === 'human') return `human:${actor.id || 'local'}`
     if (actor.type === 'agent') return `agent:${actor.adapter || '?'}`
-    return 'baton'
+    return 'leg'
   }
 
   function baseAdapterName(name) { return String(name || '').replace(/^fake-/, '') }
@@ -1042,7 +1042,7 @@
     for (const a of adapters) adapterSelect.appendChild(el('option', { value: a.name }, [adapterLabel(a)]))
     // Add fallback agent used to default to the first option in the list, which
     // is normally the agent already chosen as First agent: the summary line then
-    // read "Baton tries claude, then agy, then claude", a fallback that cannot
+    // read "Leg tries claude, then agy, then claude", a fallback that cannot
     // fire. rebuildDefaultFallbacks already applies this filter.
     if (!preferred && !first) {
       const used = chosenAdapters(ui)

package/src/board/sessions.js

@@ -1,7 +1,7 @@
 // Terminals lane: the window rail (5h/7d per login), the sessions started with
-// `baton claude|codex|agy`, overlap flags (two live sessions editing the same
+// `leg claude|codex|agy`, overlap flags (two live sessions editing the same
 // file), and what has landed on trunk. Data: /api/sessions, pushed as the SSE
-// `sessions` event (board.js re-dispatches it as `baton:sessions`).
+// `sessions` event (board.js re-dispatches it as `leg:sessions`).
 //
 // The design is .design/BOARD-DESIGN.md sections 6.1 to 6.6; the ids, class
 // names and frozen source shapes are .design/BUILD-CONTRACT.md section 6.1.
@@ -775,6 +775,11 @@
     if (shared() && s.owner) register.appendChild(el('span', { class: 'chip' }, [isMine(s) ? `${s.owner}, you` : s.owner]))
     if (s.lineage && s.lineage.from) register.appendChild(el('span', { class: 'chip' }, [`from ${s.lineage.from}`]))
     if (s.worktree) register.appendChild(el('span', { class: 'chip' }, [`own worktree, from ${s.worktree.base || 'a detached HEAD'}`]))
+    if (s.has_synthesis) register.appendChild(el('span', { class: 'chip', title: 'synthesis record active' }, ['synthesis']))
+    // the portable harness, one word: what this leg's client received from the
+    // source harness (src/harness/index.mjs STATES); nothing when the feature is off
+    const hb = harnessBadge(s.harness)
+    if (hb) register.appendChild(el('span', { class: hb.cls, title: hb.title }, [hb.text]))
     body.appendChild(register)
 
     if (s.hidden) body.appendChild(el('p', { class: 'term-prompt term-prompt--empty' }, ['prompt hidden']))
@@ -1147,6 +1152,71 @@
     return el('p', { class: cls, title: 'freshness is recomputed from git on every poll; leg resume --check' }, [text])
   }
 
+  // ---- the portable harness ----
+  // Every word here comes from the outcome the session recorded when the leg
+  // started (src/harness/index.mjs prepareHarnessForHandoff), never from a guess.
+  const HARNESS_WORD = { synced: 'harness synced', partial: 'harness partial', stale: 'harness stale', attention: 'harness attention', blocked: 'harness refused', error: 'harness error', unsupported: 'harness unsupported', source: 'harness source' }
+  function harnessBadge(h) {
+    if (!h || h.state === 'off' || h.state === 'same-client') return null
+    const text = HARNESS_WORD[h.state] || `harness ${h.state}`
+    const cls = h.state === 'synced' || h.state === 'partial' || h.state === 'source' ? 'chip chip-state-ok' : h.state === 'unsupported' ? 'chip' : 'chip is-stale'
+    return { text, cls, title: h.summary || text }
+  }
+
+  function harnessSection(s, d) {
+    const h = (d && d.harness) || s.harness
+    if (!h || h.state === 'off') return null
+    const box = el('div', { class: 'detail-section' })
+    const src = h.source ? `${h.source}` : 'unknown'
+    const captured = h.captured_at ? `captured ${whenAgo(h.captured_at)}` : 'not captured'
+    const head = h.state === 'same-client'
+      ? `${h.to} to ${h.to}: same client, same harness`
+      : h.state === 'source' ? `${h.target} is the source of the harness; nothing to carry`
+        : `source ${src}, ${captured}${h.synced_at ? `, synced ${whenAgo(h.synced_at)}` : ''}${h.policy ? `, policy ${h.policy}` : ''}`
+    box.appendChild(el('div', { class: 'well' }, [
+      el('div', {}, [head]),
+      h.summary && h.state !== 'same-client' && h.state !== 'source' ? el('p', { class: `sentence ${h.state === 'synced' || h.state === 'partial' ? 'tone-ok' : h.state === 'unsupported' ? 'tone-muted' : 'tone-warn'}` }, [h.summary]) : null,
+      h.reason && (h.state === 'blocked' || h.state === 'error' || h.state === 'unsupported') ? el('p', { class: 'blocker' }, [h.reason]) : null,
+    ]))
+    if (h.components) {
+      const rows = el('div', { class: 'drawer-timeline' })
+      for (const [name, c] of Object.entries(h.components)) {
+        const count = c.total !== null && c.total !== undefined ? `${c.carried} / ${c.total}` : ''
+        rows.appendChild(el('div', { class: 'turn timeline-item' }, [
+          el('span', { class: 'mono turn-when' }, [name]),
+          el('span', { class: 'turn-role' }, [c.state]),
+          el('p', { class: 'timeline-summary' }, [`${count}${c.note ? `${count ? ' · ' : ''}${c.note}` : ''}`]),
+        ]))
+      }
+      box.appendChild(rows)
+    }
+    const dropped = h.dropped || []
+    const attention = h.attention || []
+    if (attention.length) {
+      const list = el('div', {})
+      for (const a of attention) list.appendChild(el('p', { class: 'blocker' }, [`${a.component}: ${a.file ? `${a.file}: ` : ''}${a.reason}`]))
+      box.appendChild(el('div', { class: 'detail-section' }, [el('div', {}, ['Needs you']), list]))
+    }
+    if (dropped.length) {
+      const list = el('div', {})
+      for (const dr of dropped) list.appendChild(el('p', { class: 'sentence tone-muted' }, [`${dr.component}: ${dr.item}${dr.excluded ? ' (excluded by policy)' : ''}. ${dr.reason}`]))
+      box.appendChild(el('div', { class: 'detail-section' }, [el('div', {}, [`Dropped (${dropped.length})`]), list]))
+    }
+    const history = (d && d.harness && d.harness.history) || []
+    if (history.length) {
+      const list = el('div', { class: 'drawer-timeline' })
+      for (const r of history.slice(-8).reverse()) {
+        list.appendChild(el('div', { class: 'turn timeline-item' }, [
+          el('span', { class: 'mono turn-when' }, [clockAt(Date.parse(r.ts))]),
+          el('span', { class: 'turn-role' }, [r.op]),
+          el('p', { class: 'timeline-summary' }, [r.op === 'apply' ? `${r.source} to ${r.target}: ${r.state}, ${r.written || 0} written, ${(r.backups || []).length} backed up` : r.op === 'capture' ? `${r.source} captured` : `${r.from || 'start'} to ${r.to}: ${r.state}${r.proceed === false ? ', refused' : ''}`]),
+        ]))
+      }
+      box.appendChild(list)
+    }
+    return box
+  }
+
   function section(title, note, body) {
     const s = el('section', { class: 'detail-section' }, [
       el('h3', { class: 'detail-heading' }, [title, note ? el('span', { class: 'detail-sub' }, [note]) : null]),
@@ -1256,6 +1326,9 @@
     if (s.bundle) next.appendChild(el('p', { class: 'blocker' }, [`bundle ${s.bundle.id}${s.bundle.at ? `, saved ${whenAgo(s.bundle.at)}` : ''}`]))
     if (d && d.resume) next.appendChild(resumeLine(d.resume))
     box.appendChild(section('What happens next', '', next))
+
+    const harness = harnessSection(s, d)
+    if (harness) box.appendChild(section('Harness', 'the working environment this leg was given', harness))
     putScroll(box, inner)
     putFocus(box, focus)
   }
@@ -1502,7 +1575,8 @@
   }
 
   window.addEventListener('leg:sessions', (e) => render(e.detail));
-  window.addEventListener('baton:sessions', (e) => render(e.detail));
+  window.addEventListener('leg:sessions', (e) => render(e.detail));
+  window.addEventListener('baton:sessions', (e) => render(e.detail)); // legacy alias
   document.addEventListener('keydown', (e) => {
     if (e.key !== 'Escape') return
     if (pendingConfirm) { pendingConfirm = null; if (view) renderSessions(view); return }

package/src/bundle.mjs

@@ -9,6 +9,7 @@ import { chb, ensureExcluded } from './handoff.mjs'
 import { scrub } from './redact.mjs'
 import { updateSession, workRoot } from './sessions.mjs'
 import { perSessionFile, writeHandoffPointer } from './resume.mjs'
+import { readSynthesis, formatSynthesisSection, synthesisDirective, SYNTHESIS_POINTER_PARAGRAPH } from './synthesis.mjs'
 
 const LEG_DIRS = /^(\.leg|\.baton|\.context-handoffs|\.dashclaw-local)[\\/]/
 const bullets = (items) => items.filter(Boolean).map((x) => `- ${String(x).replace(/\r?\n/g, ' ').trim()}`)
@@ -21,12 +22,31 @@ function git(cwd, args) {
 
 export function slugFor(session) { return `leg-${session.session_id}`.toLowerCase().replace(/[^a-z0-9-]+/g, '-').slice(0, 80) }
 
+export function sessionCommitDelta(cwd, session) {
+  if (!cwd) return { isClean: false, dirty: [], newCommits: [] }
+  const dirty = git(cwd, ['status', '--porcelain']).split('\n').filter(Boolean).map((l) => l.slice(3).replace(/^"|"$/g, '')).filter((f) => !LEG_DIRS.test(f)).slice(0, 60)
+  const isClean = dirty.length === 0
+  let newCommits = []
+  if (isClean && session?.head_at_start) {
+    const head = git(cwd, ['rev-parse', 'HEAD']).trim()
+    if (head && head !== session.head_at_start) {
+      const raw = git(cwd, ['log', '--oneline', `${session.head_at_start}..${head}`])
+      if (raw) newCommits = raw.split('\n').filter(Boolean)
+    }
+  }
+  return { isClean, dirty, newCommits }
+}
+
 // Notes in the CLI's section vocabulary; see src/handoff.mjs buildNotes.
 export function sessionNotes(session, { messages = [], why = 'handoff' } = {}) {
   const cwd = workRoot(session)
   const stat = git(cwd, ['diff', '--stat'])
-  const dirty = git(cwd, ['status', '--porcelain']).split('\n').filter(Boolean).map((l) => l.slice(3).replace(/^"|"$/g, '')).filter((f) => !LEG_DIRS.test(f)).slice(0, 60)
+  const delta = sessionCommitDelta(cwd, session)
+  const dirty = delta.dirty
   const recent = git(cwd, ['log', '--oneline', '-5'])
+  const opportunity = delta.isClean && delta.newCommits.length > 0
+    ? `Next agent: read this bundle. The previous agent committed changes (${delta.newCommits.length} commit(s): ${delta.newCommits.slice(0, 3).join(' | ')}) and left a clean working tree. Check git log to verify whether the task is already satisfied before doing redundant work. Do not ask the human to restate the task.`
+    : 'Next agent: read this bundle, inspect `git status` and `git diff`, continue the task from the last agent message, and do not ask the human to restate the task.'
   const lines = [
     '## Scope', '',
     `Task: ${session.task ?? '(no prompt recorded yet; read the transcript)'}`,
@@ -39,7 +59,10 @@ export function sessionNotes(session, { messages = [], why = 'handoff' } = {}) {
     ...bullets((session.files_touched ?? []).slice(0, 50).map((f) => `Edited this session: ${f}`)),
     ...bullets(recent ? [`Recent commits: ${recent.replace(/\n/g, ' | ')}`] : []),
     '', '## Opportunities', '',
-    ...bullets(['Next agent: read this bundle, inspect `git status` and `git diff`, continue the task from the last agent message, and do not ask the human to restate the task.']),
+    ...bullets([
+      opportunity,
+      synthesisDirective(session.session_id),
+    ]),
     '', '## Open questions', '',
     ...bullets([`Why the previous agent stopped: ${why}`, session.limit?.detail ? `Limit text: ${session.limit.detail}` : null]),
     '', '## Evidence anchors', '',
@@ -67,8 +90,18 @@ export function saveSessionBundle(session, { messages = [], why = 'checkpoint' }
   if (r.status !== 0) throw new Error(`context-handoff-bundle save failed (exit ${r.status}): ${scrub(r.stderr || r.stdout).slice(0, 400)}`)
   let out
   try { out = JSON.parse(r.stdout) } catch { throw new Error(`context-handoff-bundle save printed no JSON: ${scrub(r.stdout).slice(0, 200)}`) }
-  const bundle = { id: out.bundle_id, path: join(cwd, '.context-handoffs', out.bundle_id), notes: notesPath, quality: out.quality ?? null, updated_at: new Date().toISOString(), why }
-  updateSession(session.session_id, { bundle })
+  const nowIso = new Date().toISOString()
+  const bundle = { id: out.bundle_id, path: join(cwd, '.context-handoffs', out.bundle_id), notes: notesPath, quality: out.quality ?? null, updated_at: nowIso, why }
+  if (why === 'checkpoint') {
+    const checkpoints = [...(session.checkpoints ?? []), nowIso].slice(-20)
+    session.checkpoints = checkpoints
+    updateSession(session.session_id, (cur) => ({
+      bundle,
+      checkpoints: [...(cur?.checkpoints ?? []), nowIso].slice(-20),
+    }))
+  } else {
+    updateSession(session.session_id, { bundle })
+  }
   return bundle
 }
 
@@ -82,22 +115,35 @@ export function resumePrompt(session, bundle, next) {
     if (r.status === 0) loaded = r.stdout
   } catch {}
   const header = `# Leg handoff\n\nPrevious agent: ${session.agent} (${session.account}). Reason: ${session.limit?.reason ?? session.handoff?.reason ?? 'handoff requested'}${session.limit?.detail ? `, ${session.limit.detail}` : ''}.\nNext agent: ${next.agent} (${next.account}).\nBundle: ${bundle.path}\n\n`
-  const body = header + (loaded || readFileSync(bundle.notes, 'utf8'))
+  const bundleDump = loaded || readFileSync(bundle.notes, 'utf8')
+  let synthesisSection = ''
+  try {
+    const rawSyn = readSynthesis(cwd, session.session_id)
+    if (rawSyn) {
+      synthesisSection = formatSynthesisSection(rawSyn, { sessionId: session.session_id })
+    }
+  } catch {}
+  const body = header + (synthesisSection ? `${synthesisSection}\n\n` : '') + bundleDump
   // src/resume.mjs owns both files: the per-session one so two sessions sharing
   // one checkout (--no-worktree, or two started in the same instant) never
   // overwrite each other's handoff, and RESUME.md, the copy everyone opens.
   // Both are stamped with the git state and the live terminals they describe,
-  // so `baton resume --check` can tell a reader when they stopped being true.
+  // so `leg resume --check` can tell a reader when they stopped being true.
   const why = session.limit?.reason ?? session.handoff?.reason ?? 'handoff requested'
   writeHandoffPointer(session, body, { bundle, why })
   const perSession = perSessionFile(cwd, session.session_id)
   const task = session.task ? `\n\nThe task, as the human first stated it: ${session.task.slice(0, 700)}` : ''
+  const delta = sessionCommitDelta(cwd, session)
+  const actionText = delta.isClean && delta.newCommits.length > 0
+    ? `. The previous agent committed changes (${delta.newCommits.length} commit(s): ${delta.newCommits.slice(0, 2).join(' | ')}) and left a clean working tree. Check git log and verify whether the task is already complete before doing redundant work; continue only if work remains.`
+    : ', check git status and git diff, then continue the work from where it stopped.'
   // the absolute path: the next agent is spawned in the session's cwd, which is
-  // a subdirectory of the work root whenever Baton was started in one
-  return `You are taking over an interactive coding session from ${session.agent}, which hit its usage limit. Read ${perSession} (the context handoff bundle is at ${bundle.path}), check git status and git diff, then continue the work from where it stopped. Do not ask the human to restate the task.${task}`
+  // a subdirectory of the work root whenever Leg was started in one
+  return `You are taking over an interactive coding session from ${session.agent}, which hit its usage limit. Read ${perSession} (the context handoff bundle is at ${bundle.path})${actionText} Do not ask the human to restate the task.${task}\n\n${SYNTHESIS_POINTER_PARAGRAPH}`
 }
 
 // Freshness, never existence: src/resume.mjs recomputes it from git at read
 // time. `resumeFileExists` used to live here and answered "a file is on disk",
 // which every caller then read as "the handoff it describes is still true".
 export { resumeVerdict } from './resume.mjs'
+export { synthesisFile, readSynthesis, validateSynthesis, validateSynthesisHeader, formatSynthesisSection, hasRecentSynthesis, synthesisDirective, SYNTHESIS_POINTER_PARAGRAPH } from './synthesis.mjs'

package/src/chain.mjs

@@ -19,7 +19,7 @@ export const TRANSITIONS = [
   ['running', 'leg:completed', 'waiting_human', 'agent leg completed and a human station is next'],
   ['running', 'leg:handoff', 'handing_off', 'limit | incomplete | no_progress | stalled | failed and the chain has a next leg'],
   ['running', 'leg:handoff', 'failed', 'same outcomes with the chain exhausted'],
-  ['running', 'leg:auth_failed', 'failed', 'Baton/environment fault; no advance; human fixes and clicks Rerun'],
+  ['running', 'leg:auth_failed', 'failed', 'Leg/environment fault; no advance; human fixes and clicks Rerun'],
   ['running', 'leg:launch_failed', 'failed', 'same'],
   ['running', 'leg:killed', 'killed', 'the leg was killed from the board'],
   ['handing_off', 'bundle_written', 'queued', 'next leg (leg+1) queued at the same station'],

package/src/contract.mjs

@@ -1,6 +1,6 @@
 // contract — the per-leg prompt. Every CLI gets the same contract file at
-// .baton/CONTRACT.md in the worktree (CLI-agnostic completion: write
-// .baton/DONE when finished). Leg 1 prompt = the contract; a later leg or a
+// .leg/CONTRACT.md in the worktree (CLI-agnostic completion: write
+// .leg/DONE when finished). Leg 1 prompt = the contract; a later leg or a
 // resume = the handoff bundle's resume text + the contract.
 import { mkdirSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
@@ -44,8 +44,9 @@ export async function renderContract({ card, station, leg, entry, worktree, resu
     '',
     `- Work only inside this directory: ${worktree}. It is a git worktree on its own branch; commit as you go or leave changes uncommitted, both are fine.`,
     '- Keep .leg/PROGRESS.md updated as you go: one line per meaningful step, newest last. It is how the next agent (or a human) picks up if you stop early.',
+    '- Maintain .leg/SYNTHESIS-<session-id>.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.',
     '- Do not push, do not create remotes, do not open pull requests, do not change git config.',
-    '- Do not touch anything under .leg/ except PROGRESS.md and DONE.',
+    '- Do not touch anything under .leg/ except PROGRESS.md, SYNTHESIS-*.md, and DONE.',
     '- No interactive prompt will be answered; if you need a permission you do not have, write what you need to .leg/PROGRESS.md and stop.',
     '',
     '## Finish',

package/src/fsx.mjs

@@ -16,7 +16,7 @@ export function canonPath(p) {
   return process.platform === 'win32' ? out.toLowerCase() : out
 }
 
-// The real, long-form path (case preserved): what Baton stores and hands to
+// The real, long-form path (case preserved): what Leg 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)
@@ -39,7 +39,9 @@ const sleepSync = (ms) => { const t = Date.now() + ms; while (Date.now() < t) {
 // 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 } = {}) {
+// `mustHold`: a caller for whom running unlocked is worse than not running
+// (two harness applies would tear one ownership record) gets a throw instead.
+export function withFileLock(lockPath, fn, { retries = 60, waitMs = 20, staleMs = 5000, mustHold = false } = {}) {
   let fd = null
   for (let i = 0; i < retries; i++) {
     try { fd = openSync(lockPath, 'wx'); break } catch (err) {
@@ -51,6 +53,7 @@ export function withFileLock(lockPath, fn, { retries = 60, waitMs = 20, staleMs
       sleepSync(waitMs)
     }
   }
+  if (fd === null && mustHold) throw new Error(`could not take ${lockPath} within ${Math.round(retries * waitMs / 1000)} s; another Leg process holds it`)
   try { return fn() } finally { if (fd !== null) { try { closeSync(fd) } catch {} try { unlinkSync(lockPath) } catch {} } }
 }
 

package/src/handoff.mjs

@@ -1,4 +1,4 @@
-// handoff — the context-handoff-bundle seam. Baton never re-implements the
+// handoff — the context-handoff-bundle seam. Leg 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.
@@ -68,9 +68,9 @@ function bullets(items) {
 }
 
 // Notes in the CLI's own section vocabulary (Scope / Findings / Opportunities /
-// Open questions / Evidence anchors) carrying Baton's four parts: Task, Done so
+// Open questions / Evidence anchors) carrying Leg'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.
+// the parser, so every Leg 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})` : ''
@@ -150,9 +150,9 @@ export function writeHandoff({ card, station, leg, entry, run, worktree, runDir,
   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 })
+  const slug = `leg-${card.card_id}-${station.name}-leg${leg}`.toLowerCase().replace(/[^a-z0-9-]+/g, '-').slice(0, 80)
+  const title = `leg ${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', 'leg'], { 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)}`) }