@ucsandman/legcli 0.7.0 → 0.9.0

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.
@@ -22,7 +22,7 @@
     handing_off: ['handing off', 'warn'], waiting: ['waiting for reset', 'warn'], handed_off: ['handed off', 'idle'], ended: ['ended', 'idle'], lost: ['lost', 'danger'],
   }
   const WIN_WORDS = { '5h': '5 hour', '7d': '7 day' }
-  const IDS = ['claude', 'codex', 'agy', 'fake']
+  const IDS = ['claude', 'codex', 'agy', 'grok', 'fake']
 
   let view = null
   const NO_BRANCH_BLOCKER = 'this terminal works in the checkout itself: there is no branch of its own to land'
@@ -643,15 +643,15 @@
   // A result that belongs to a terminal is written into that terminal's sentence
   // slot, where the reader is already looking. Only a result that belongs to no
   // object on this page goes to the one system message.
-  async function act(id, action, btn) {
+  async function act(id, action, btn, body = null) {
     btn.disabled = true
     actionNotes.delete(id)
     try {
       if (action.startsWith('requests/')) {
-        await api(`/api/sessions/${encodeURIComponent(id)}/${action}`, { method: 'POST' })
+        await api(`/api/sessions/${encodeURIComponent(id)}/${action}`, { method: 'POST', body })
         actionNotes.set(id, { at: Date.now(), tone: 'ok', text: action.endsWith('approve') ? 'approved; this terminal hands off in a few seconds' : 'the request was dismissed' })
       } else if (action === 'request-handoff') {
-        await api(`/api/sessions/${encodeURIComponent(id)}/request-handoff`, { method: 'POST' })
+        await api(`/api/sessions/${encodeURIComponent(id)}/request-handoff`, { method: 'POST', body })
         sysMessage('asked; the owner of that terminal decides', 'ok')
       } else if (action === 'remove') {
         const r = await api(`/api/sessions/${encodeURIComponent(id)}`, { method: 'DELETE' })
@@ -660,9 +660,10 @@
         await api(`/api/sessions/${encodeURIComponent(id)}?force=1&keep_worktree=1`, { method: 'DELETE' })
         sysMessage('removed the Leg record; the worktree and the branch are kept', 'ok')
       } else {
-        await api(`/api/sessions/${encodeURIComponent(id)}/${action}`, { method: 'POST' })
+        await api(`/api/sessions/${encodeURIComponent(id)}/${action}`, { method: 'POST', body })
         if (action === 'handoff') actionNotes.set(id, { at: Date.now(), tone: 'warn', text: 'hand-off requested; this terminal switches agents in a few seconds' })
         else if (action === 'end') actionNotes.set(id, { at: Date.now(), tone: 'warn', text: 'end requested; the agent stops after its current turn' })
+        else if (action === 'land/fix') actionNotes.set(id, { at: Date.now(), tone: 'ok', text: 'applied fix' })
       }
       refresh()
     } catch (err) {
@@ -774,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']))
@@ -849,25 +855,63 @@
     // G10: the order is Land, Hand off now, Details, End, and it never reflows
     // by availability. A button that does not apply is omitted, never moved.
     const landing = Boolean(s.land && s.land.state === 'landing')
-    const blocker = s.worktree ? s.land_blocker : NO_BRANCH_BLOCKER
-    // G10 is disabled-with-its-reason, so the reason is attached to the control
-    // as well as printed: the title used to be on the inverse condition, giving
-    // the tooltip to the button that explains itself and none to the one that
-    // needs it, and nothing connected the sentence below to the button above.
+    const cl = s.can_land || (s.worktree ? (s.land_blocker ? { ok: false, blockers: [{ code: 'legacy', message: s.land_blocker }] } : { ok: true, blockers: [] }) : { ok: false, blockers: [{ code: 'no_worktree', message: NO_BRANCH_BLOCKER }] })
+    const isOnTarget = cl.blockers && cl.blockers.some((b) => b.code === 'on_target_branch')
+    const targetLocked = cl.blockers && cl.blockers.find((b) => b.code === 'target_locked')
+    const blocker = !cl.ok ? (cl.blockers[0]?.message || NO_BRANCH_BLOCKER) : null
     const blockerId = blocker ? `land-blocker-${s.session_id}` : null
-    // Land is the primary action only when it can actually run. A disabled
-    // button painted in the one accent colour spends the loudest thing in the
-    // design on something the reader cannot do.
-    const land = el('button', {
-      type: 'button',
-      class: `btn ${blocker ? 'btn-secondary' : 'btn-primary'}${landing ? ' is-loading' : ''}`,
-      disabled: blocker || landing ? '' : null,
-      'data-focus-key': `land:${s.session_id}`,
-      'aria-describedby': blockerId,
-      title: blocker || `commit this terminal's work on ${s.worktree.branch}, rebase it onto ${s.worktree.base}, run the tests, fast-forward ${s.worktree.base}; a bounce says why`,
-    }, [landing ? 'Landing…' : 'Land'])
-    land.addEventListener('click', () => act(s.session_id, 'land', land))
-    actions.appendChild(land)
+
+    if (isOnTarget) {
+      const commitDirect = el('button', {
+        type: 'button',
+        class: 'btn btn-secondary',
+        'data-focus-key': `commit-direct:${s.session_id}`,
+        title: `Commit directly on ${s.branch || s.worktree?.base || 'main'}`,
+      }, ['Commit directly'])
+      commitDirect.addEventListener('click', () => act(s.session_id, 'land/fix', commitDirect, { action: 'commit_directly' }))
+      actions.appendChild(commitDirect)
+    } else {
+      const landLabel = landing ? 'Landing…' : targetLocked ? targetLocked.message : 'Land'
+      const landDisabled = !cl.ok || landing
+      const land = el('button', {
+        type: 'button',
+        class: `btn ${landDisabled ? 'btn-secondary' : 'btn-primary'}${landing ? ' is-loading' : ''}`,
+        disabled: landDisabled ? '' : null,
+        'data-focus-key': `land:${s.session_id}`,
+        'aria-describedby': blockerId,
+        title: blocker || (s.worktree ? `commit work on ${s.worktree.branch}, rebase onto ${s.worktree.base}, test, and fast-forward ${s.worktree.base}` : 'Land'),
+      }, [landLabel])
+      if (!landDisabled) {
+        land.addEventListener('click', async () => {
+          land.disabled = true
+          land.classList.add('is-loading')
+          land.textContent = 'Preparing…'
+          try {
+            const res = await api(`/api/sessions/${encodeURIComponent(s.session_id)}/land/prepare`, { method: 'POST' })
+            land.classList.remove('is-loading')
+            if (!res.ok) {
+              actionNotes.set(s.session_id, { at: Date.now(), tone: 'danger', text: res.error || 'Prepare failed' })
+              refresh()
+              return
+            }
+            const statText = res.diff_stat || `${res.files?.length || 0} files changed`
+            const question = `Prepared: ${statText} · tests green. Land onto ${s.worktree?.base || 'main'} and ship to GitHub?`
+            pendingConfirm = {
+              id: s.session_id,
+              question,
+              verb: 'Land',
+              action: 'land',
+            }
+            renderSessions(view)
+          } catch (err) {
+            land.classList.remove('is-loading')
+            actionNotes.set(s.session_id, { at: Date.now(), tone: 'danger', text: err.message })
+            refresh()
+          }
+        })
+      }
+      actions.appendChild(land)
+    }
     if (s.active) {
       const h = el('button', { type: 'button', class: `btn ${blocker ? 'btn-primary' : 'btn-secondary'}`, title: 'save the bundle, stop this agent, start the next option in the same terminal', 'data-focus-key': `handoff:${s.session_id}` }, ['Hand off now'])
       h.addEventListener('click', () => act(s.session_id, 'handoff', h))
@@ -901,8 +945,33 @@
     }
     row.appendChild(actions)
     term.appendChild(row)
-    // the reason a disabled control is disabled is printed, never left in a title
-    if (blocker) term.appendChild(el('p', { class: 'blocker', id: blockerId }, [blocker]))
+
+    // Why can't I land expander or fallback blocker message
+    if (!cl.ok && !isOnTarget && s.worktree) {
+      const list = el('ul', { class: 'blocker-list' })
+      for (const b of cl.blockers) {
+        const item = el('li', { class: 'blocker-item' })
+        item.appendChild(el('span', { class: 'blocker-msg' }, [b.message]))
+        const fixes = b.fixes || (b.fix ? [b.fix] : [])
+        if (fixes.length) {
+          const grp = el('span', { class: 'blocker-fixes' })
+          for (const f of fixes) {
+            const fBtn = el('button', { type: 'button', class: 'btn btn-sm btn-secondary', title: f.label }, [f.label])
+            fBtn.addEventListener('click', () => act(s.session_id, 'land/fix', fBtn, { action: f.action, target_session: f.target_session }))
+            grp.appendChild(fBtn)
+          }
+          item.appendChild(grp)
+        }
+        list.appendChild(item)
+      }
+      const expander = el('details', { class: 'why-cant-land', id: blockerId }, [
+        el('summary', { class: 'why-cant-land-summary' }, ["Why can't I land?"]),
+        list,
+      ])
+      term.appendChild(expander)
+    } else if (blocker) {
+      term.appendChild(el('p', { class: 'blocker', id: blockerId }, [blocker]))
+    }
     return term
   }
 
@@ -1014,9 +1083,12 @@
   }
 
   function messageRow(m, key) {
-    return el('div', { class: 'turn drawer-msg' }, [
-      el('span', { class: 'turn-role drawer-msg-role' }, [m.role === 'user' ? 'human' : 'agent']),
-      m.ts ? el('span', { class: 'turn-when drawer-msg-when' }, [whenAgo(m.ts)]) : null,
+    const isUser = m.role === 'user'
+    return el('div', { class: `turn drawer-msg ${isUser ? 'is-human' : 'is-agent'}` }, [
+      el('div', { class: 'drawer-msg-head' }, [
+        el('span', { class: `turn-role drawer-msg-role ${isUser ? '' : 'chip-state-ok'}` }, [isUser ? 'human' : 'agent']),
+        m.ts ? el('span', { class: 'turn-when drawer-msg-when' }, [whenAgo(m.ts)]) : null,
+      ]),
       // every box that can scroll carries a key, so where the reader had
       // scrolled to survives the rebuild three seconds later
       el('p', { 'data-scroll-key': `msg:${key}` }, [m.text]),
@@ -1024,7 +1096,7 @@
   }
 
   function fileRow(f) {
-    const wrap = el('div', {})
+    const wrap = el('div', { class: 'drawer-file-item' })
     const pre = el('pre', { class: 'drawer-diff', hidden: '', 'data-scroll-key': `diff:${f.path}` })
     const row = el('button', { type: 'button', class: 'btn btn-text file-row', 'aria-expanded': 'false', 'data-focus-key': `file:${f.path}` }, [
       el('span', { class: 'mono', title: f.path }, [f.path]),
@@ -1080,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]),
@@ -1115,16 +1252,18 @@
       return
     }
     const [label] = STATUS[s.status] || [s.status]
-    const controls = el('div', { class: 'cap-line' }, [
+    const left = el('div', { class: 'detail-brand' }, [
+      el('span', { class: `dot id-${idOf(s.agent)}` }),
       el('span', { class: `acct-name chip-id-${idOf(s.agent)}` }, [s.agent]),
-      el('span', { class: 'chip' }, [tail(s.session_id)]),
+      el('span', { class: 'chip mono' }, [tail(s.session_id)]),
+      el('span', { class: s.active ? 'chip chip-state-ok' : 'chip is-stale' }, [s.active ? (label || 'running') : (label || s.status)]),
     ])
     const pause = el('button', { type: 'button', class: 'btn btn-secondary', id: 'session-drawer-pause', 'data-focus-key': 'drawer-pause' }, [drawer.paused ? 'Resume updates' : 'Pause updates'])
     pause.addEventListener('click', () => { drawer.paused = !drawer.paused; if (!drawer.paused) loadDrawer(); else renderDrawer() })
     const close = el('button', { type: 'button', class: 'btn btn-secondary', id: 'session-drawer-close', 'data-focus-key': 'drawer-close' }, ['Close'])
     close.addEventListener('click', closeSessionDrawer)
-    controls.append(pause, close)
-    box.appendChild(controls)
+    const header = el('div', { class: 'detail-masthead' }, [left, el('div', { class: 'detail-ctrls' }, [pause, close])])
+    box.appendChild(header)
     if (drawer.error) box.appendChild(el('p', { class: 'sentence tone-danger' }, [drawer.error]))
 
     const last = d && d.messages ? [...d.messages].reverse().find((m) => m.role === 'assistant') : null
@@ -1171,10 +1310,10 @@
       // header on the same panel printing the same instant as 11:04 PM. The
       // summary is a block, as board.js:754 builds the same row, or the kind
       // word and the sentence render glued: `lostrunner pid 999002 is gone`.
-      timeline.appendChild(el('div', { class: 'turn' }, [
+      timeline.appendChild(el('div', { class: 'turn timeline-item' }, [
         el('span', { class: 'mono turn-when' }, [clockAt(Date.parse(e.ts))]),
         el('span', { class: 'turn-role' }, [e.type]),
-        el('p', {}, [e.summary || '']),
+        el('p', { class: 'timeline-summary' }, [e.summary || '']),
       ]))
     }
     if (!events.length) timeline.appendChild(el('p', { class: 'sentence tone-muted' }, [d ? 'nothing recorded yet' : 'reading the timeline']))
@@ -1187,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)
   }
@@ -1433,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)}`) }