@ucsandman/legcli 0.8.0 → 0.10.0

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)}`) }

package/src/harness/cli.mjs

@@ -0,0 +1,281 @@
+// `leg harness <verb>` — the human surface of the portable harness. Every
+// verb prints for a person by default and JSON with --json; every write is
+// explicit (enable, sync, capture, source, policy), and check/status/inspect/
+// explain/diff/doctor write nothing. Exit codes follow the rest of the CLI:
+// 0 fine, 1 stale or attention (check, sync), 2 usage, 3 not enabled / no
+// bundle / declined.
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { createInterface } from 'node:readline'
+import {
+  COMPONENTS, CLIENT_IDS, NO_ADAPTER, STATES, POLICIES,
+  applyHarness, captureHarness, detectSources, explainHarnessDrops, getHarnessStatus, harnessConfig, harnessDir, harnessHome,
+  inspectHarness, readHistory, registry, resolveSource, setHarnessConfig, bundleDir, captureFile,
+} from './index.mjs'
+import { HARNESS_POLICIES, HARNESS_SOURCES } from '../preferences.mjs'
+import { check as checkVendor } from '../../scripts/sync-harness-engine.mjs'
+
+const VERBS = ['status', 'inspect', 'enable', 'disable', 'capture', 'sync', 'check', 'explain', 'diff', 'source', 'policy', 'doctor', 'history']
+const GLYPH = { synced: '✓', partial: '◐', stale: '✗', attention: '!', unsupported: '-', error: 'E', source: '=', blocked: '✗', off: '·' }
+const ABBR = { rules: 'rules', identity: 'ident', hooks: 'hooks', skills: 'skills', agents: 'agents', commands: 'cmds', mcp: 'mcp', permissions: 'perms' }
+
+export const HELP = `leg harness: carry the source agent's working environment to the agents a hand-off lands on
+  status [--json]                 what is enabled, the source, when it was captured, each client's state
+  inspect [--json]                what the captured harness holds: rules, hooks, skills, agents, commands, MCP servers, permissions
+  enable [--source claude|codex] [--policy warn|sync|strict] [--to a,b] [--yes]
+                                  first run: detect clients, capture, show what each client receives and drops, apply after confirmation
+  disable                         stop carrying the harness; nothing already written is removed
+  capture [claude|codex] [--force] re-read the source client (fingerprinted: a no-op when nothing changed)
+  sync [--to a,b] [--force] [--dry-run] [--json]
+                                  capture, then write every managed file that is out of date; --force replaces hand-edited files (backed up)
+  check [--to a,b] [--json]       report only, write nothing; exit 1 when a client is stale or needs attention
+  explain [--to a,b] [--json]     every item a client could not receive, and why
+  diff <client>                   what a sync would write to that client, file by file, without writing it
+  source claude|codex             which client's harness is the one carried
+  policy warn|sync|strict         what an unattended hand-off may do (warn: report; sync: write when safe; strict: refuse an unsafe destination)
+  doctor [--json]                 the engine, the source, the bundle, the state and every client, each with a verdict
+  history [--json] [--limit n]    the evidence trail: every capture, sync and hand-off decision`
+
+function table(targets, { source }) {
+  const ids = Object.keys(targets)
+  const w = Math.max(6, ...ids.map((id) => targets[id].name.length))
+  const head = ['client'.padEnd(w), 'state'.padEnd(11), ...COMPONENTS.map((c) => ABBR[c].padEnd(6)), 'dropped'].join(' ')
+  const lines = [head, '-'.repeat(head.length)]
+  for (const id of ids) {
+    const t = targets[id]
+    const cells = COMPONENTS.map((c) => {
+      const comp = t.components[c]
+      if (t.state === 'source') return '='.padEnd(6)
+      const g = GLYPH[comp?.state] ?? '?'
+      const n = comp?.total !== null && comp?.total !== undefined ? `${g}${comp.carried}/${comp.total}` : g
+      return n.padEnd(6)
+    })
+    const note = t.state === 'source' ? 'source of truth; never written' : !t.installed ? 'not installed' : t.attention.length ? `${t.attention.length} need attention` : ''
+    lines.push(`${t.name.padEnd(w)} ${t.state.padEnd(11)} ${cells.join(' ')} ${String(t.dropped.length).padStart(7)}  ${note}`)
+  }
+  lines.push(`legend: ✓ synced  ◐ partial (some items dropped)  ✗ stale  ! attention (hand-edited or error)  - unsupported  = source${source ? ` (${source})` : ''}`)
+  return lines.join('\n')
+}
+
+function dropLines(targets) {
+  const out = []
+  for (const t of Object.values(targets)) {
+    if (!t.dropped.length && !t.attention.length) continue
+    out.push(`  ${t.name}`)
+    for (const d of t.dropped) out.push(`    ${d.component}: ${d.item}${d.excluded ? ' (excluded by policy)' : ''}: ${d.reason}`)
+    for (const a of t.attention) out.push(`    ${a.component}: ${a.file ?? ''}${a.file ? ': ' : ''}${a.reason}`)
+  }
+  return out
+}
+
+async function confirm(question) {
+  if (!process.stdin.isTTY) return false
+  const rl = createInterface({ input: process.stdin, output: process.stderr })
+  const answer = await new Promise((r) => rl.question(`${question} [y/N] `, r))
+  rl.close()
+  return /^y(es)?$/i.test(answer.trim())
+}
+
+const list = (v) => (typeof v === 'string' ? v.split(',').map((s) => s.trim()).filter(Boolean) : null)
+
+export async function harnessCommand(cmd, args, { out, die, env = process.env }) {
+  const json = Boolean(args.json)
+  if (!cmd || cmd === 'help' || cmd === '--help') { out(HELP); return 0 }
+  if (!VERBS.includes(cmd)) return die(2, `unknown harness command "${cmd}" (${VERBS.join('|')})`)
+  const cfg = harnessConfig()
+
+  if (cmd === 'status') {
+    const s = getHarnessStatus({ env })
+    if (json) { out(JSON.stringify(s, null, 2)); return 0 }
+    out(`portable harness: ${s.enabled ? `on (policy ${s.policy})` : 'off'}${s.enabled ? '' : '  · leg harness enable'}`)
+    out(`source: ${s.source ?? 'none detected'}${s.sources_detected.length ? ` (on this machine: ${s.sources_detected.join(', ')})` : ''}`)
+    if (s.captured) out(`captured: ${s.captured_at} · fingerprint ${String(s.fingerprint).slice(0, 12)} · ${Object.entries(s.components ?? {}).map(([k, v]) => `${k} ${v}`).join(', ')}${s.source_changed ? ' · SOURCE CHANGED since (leg harness sync)' : ''}`)
+    else out('captured: never')
+    if (s.corrupt) out(`bundle: unreadable (${s.corrupt}); leg harness capture --force`)
+    for (const w of s.warnings) out(`  ! ${w}`)
+    if (Object.keys(s.targets).length) out(table(s.targets, { source: s.source }))
+    for (const [agent, why] of Object.entries(s.unsupported)) out(`${agent}: unsupported. ${why}`)
+    return 0
+  }
+
+  if (cmd === 'inspect') {
+    const i = inspectHarness()
+    if (json) { out(JSON.stringify(i, null, 2)); return i.captured ? 0 : 3 }
+    if (!i.captured) { out('no harness captured yet: leg harness capture'); return 3 }
+    if (i.corrupt) { out(`the captured harness is unreadable: ${i.corrupt}`); return 3 }
+    out(`source ${i.source}, captured ${i.captured_at}, fingerprint ${i.fingerprint.slice(0, 12)}`)
+    out(`rules: ${i.rules_bytes} bytes${i.identity ? ', identity present' : ', no identity file'}`)
+    out(`hooks: ${Object.entries(i.hooks).map(([e, n]) => `${e} ${n}`).join(', ') || '(none)'}`)
+    out(`skills (${i.skills.length}): ${i.skills.join(', ') || '(none)'}`)
+    out(`agents (${i.agents.length}): ${i.agents.map((a) => `${a.name} [${a.model}${a.readonly ? ', read-only' : ''}]`).join(', ') || '(none)'}`)
+    out(`commands (${i.commands.length}): ${i.commands.join(', ') || '(none)'}`)
+    out(`mcp (${i.mcp.length}): ${i.mcp.map((m) => `${m.name} (${m.transport}${m.env_refs ? `, ${m.env_refs} env ref` : ''})`).join(', ') || '(none)'}`)
+    out(`permissions: allow ${i.permissions.allow.length}, deny ${i.permissions.deny.length}, ask ${i.permissions.ask.length}`)
+    for (const w of i.warnings) out(`  ! ${w}`)
+    return 0
+  }
+
+  if (cmd === 'enable') {
+    const found = detectSources({ env })
+    const source = typeof args.source === 'string' ? args.source : cfg.source ?? found[0]?.id ?? null
+    if (!source) return die(3, `no source client found: neither ~/.claude/CLAUDE.md nor ~/.codex/AGENTS.md exists under ${harnessHome(env)}`)
+    if (!HARNESS_SOURCES.includes(source)) return die(2, `--source must be one of ${HARNESS_SOURCES.join(', ')}`)
+    const policy = typeof args.policy === 'string' ? args.policy : 'sync'
+    if (!HARNESS_POLICIES.includes(policy)) return die(2, `--policy must be one of ${HARNESS_POLICIES.join(', ')}`)
+    const to = list(args.to)
+    if (to) for (const id of to) if (!CLIENT_IDS.includes(id)) return die(2, `--to: unknown client "${id}" (${CLIENT_IDS.join(', ')})`)
+    out(`source: ${source}${found.length > 1 ? ` (also on this machine: ${found.filter((s) => s.id !== source).map((s) => s.id).join(', ')}; --source to choose)` : ''}`)
+    let cap
+    try { cap = captureHarness({ source, force: true, env }) } catch (err) { return die(3, `capture failed: ${err.message}`) }
+    const c = cap.bundle.manifest.components
+    out(`captured ${source}: ${Object.entries(c).map(([k, v]) => `${k} ${v}`).join(', ')}`)
+    for (const w of cap.warnings) out(`  ! ${w}`)
+    const plan = applyHarness({ to, dryRun: true, env, bundle: cap.bundle })
+    const rows = Object.values(plan.targets)
+    out('')
+    out(table(plan.targets, { source }))
+    const drops = dropLines(plan.targets)
+    if (drops.length) { out(''); out('not carried:'); for (const l of drops) out(l) }
+    const writable = rows.filter((t) => t.installed && t.state !== 'source')
+    out('')
+    out(`policy ${policy}: ${policy === 'warn' ? 'hand-offs report drift and never write' : policy === 'sync' ? 'hand-offs write managed files when that is safe' : 'a hand-off refuses a destination that cannot be made safe'}`)
+    const go = args.yes ? true : await confirm(`write the managed files above into ${writable.map((t) => t.name).join(', ') || 'nothing (no client installed)'} and turn portable harness on?`)
+    if (!go) { out('nothing written. Re-run with --yes to enable without a prompt.'); return 3 }
+    const applied = writable.length ? applyHarness({ to, env, bundle: cap.bundle }) : { targets: {} }
+    setHarnessConfig({ enabled: true, policy, source })
+    out(`portable harness on: source ${source}, policy ${policy}${writable.length ? `; wrote ${Object.values(applied.targets).reduce((n, t) => n + t.files_written, 0)} file(s), ${Object.values(applied.targets).reduce((n, t) => n + t.backups.length, 0)} backup(s) under ${join(harnessDir(), 'backups')}` : ''}`)
+    const attention = Object.values(applied.targets).flatMap((t) => t.attention)
+    for (const a of attention) out(`  ! ${a.component}: ${a.file ?? ''} ${a.reason}`)
+    return attention.length ? 1 : 0
+  }
+
+  if (cmd === 'disable') {
+    setHarnessConfig({ enabled: false })
+    out('portable harness off: hand-offs carry task context only. Files Leg wrote stay where they are (each carries "GENERATED by Leg harness"); leg harness enable turns it back on.')
+    return 0
+  }
+
+  if (cmd === 'capture') {
+    const source = args._[0] ?? cfg.source ?? resolveSource({ env, cfg })
+    if (!source) return die(3, 'no source client found: leg harness source <claude|codex>')
+    if (!HARNESS_SOURCES.includes(source)) return die(2, `source must be one of ${HARNESS_SOURCES.join(', ')}`)
+    try {
+      const cap = captureHarness({ source, force: Boolean(args.force), env })
+      if (json) { out(JSON.stringify({ source, cached: cap.cached, fingerprint: cap.bundle.manifest.fingerprint, captured_at: cap.bundle.manifest.capturedAt, components: cap.bundle.manifest.components, warnings: cap.warnings, elapsed_ms: cap.elapsed_ms }, null, 2)); return 0 }
+      out(`${cap.cached ? 'unchanged' : 'captured'} ${source} (${cap.elapsed_ms} ms): ${Object.entries(cap.bundle.manifest.components).map(([k, v]) => `${k} ${v}`).join(', ')} · fingerprint ${cap.bundle.manifest.fingerprint.slice(0, 12)}`)
+      for (const w of cap.warnings) out(`  ! ${w}`)
+      return 0
+    } catch (err) { return die(3, `capture failed: ${err.message}`) }
+  }
+
+  if (cmd === 'sync' || cmd === 'check' || cmd === 'diff') {
+    const to = cmd === 'diff' ? (args._[0] ? [args._[0]] : null) : list(args.to)
+    if (cmd === 'diff' && !to) return die(2, 'usage: leg harness diff <client>')
+    if (to) for (const id of to) if (!CLIENT_IDS.includes(id)) return die(2, `unknown client "${id}" (${CLIENT_IDS.join(', ')}${NO_ADAPTER[id] ? `; ${NO_ADAPTER[id]}` : ''})`)
+    const source = cfg.source ?? resolveSource({ env, cfg })
+    if (!source) return die(3, 'no source client found: leg harness source <claude|codex>')
+    const dryRun = cmd !== 'sync' || Boolean(args['dry-run'])
+    // the one consent is `enable`, which shows the plan first; a sync on an
+    // install that never gave it writes nothing
+    if (!dryRun && !cfg.enabled) return die(3, 'portable harness is off: leg harness enable shows what a sync would write and asks first (leg harness check reports without writing)')
+    let cap
+    try { cap = captureHarness({ source, env }) } catch (err) { return die(3, `capture failed: ${err.message}`) }
+    let r
+    try { r = applyHarness({ to, force: Boolean(args.force), dryRun, env, bundle: cap.bundle }) } catch (err) { return die(3, err.message) }
+    const rows = Object.values(r.targets)
+    const stale = rows.some((t) => t.state === 'stale' || t.state === 'attention' || t.state === 'error')
+    if (json) { out(JSON.stringify({ ...r, cached_capture: cap.cached, warnings: cap.warnings }, null, 2)); return stale ? 1 : 0 }
+    if (cmd === 'diff') {
+      const raw = JSON.parse(readFileSync(join(harnessDir(), 'harness-report.json'), 'utf8'))
+      const t = raw.targets[to[0]]
+      out(`${source} → ${to[0]} (${t.installed ? 'installed' : 'not installed'}): what a sync would do`)
+      for (const [c, res] of Object.entries(t.components ?? {})) {
+        for (const f of res.files ?? []) if (f.action !== 'unchanged' && f.action !== 'inspected') out(`  ${c.padEnd(11)} ${f.action.padEnd(20)} ${f.path}`)
+      }
+      const same = Object.values(t.components ?? {}).every((res) => (res.files ?? []).every((f) => f.action === 'unchanged' || f.action === 'inspected' || f.action === 'skipped-real-directory'))
+      if (same) out('  (nothing to write: already in sync)')
+      for (const l of dropLines({ [to[0]]: r.targets[to[0]] })) out(l)
+      return 0
+    }
+    out(`${cap.cached ? 'harness unchanged' : `captured ${source}`} · ${dryRun ? 'check only, nothing written' : `synced ${rows.filter((t) => t.state !== 'source').map((t) => t.id).join(', ')}`}`)
+    for (const w of cap.warnings) out(`  ! ${w}`)
+    out(table(r.targets, { source }))
+    const drops = dropLines(r.targets)
+    if (drops.length) { out('not carried:'); for (const l of drops) out(l) }
+    if (!dryRun) {
+      const written = rows.reduce((n, t) => n + t.files_written, 0)
+      const backups = rows.reduce((n, t) => n + t.backups.length, 0)
+      out(`${written} file(s) written, ${backups} backup(s)${backups ? ` under ${join(harnessDir(), 'backups')}` : ''}`)
+    }
+    return stale ? 1 : 0
+  }
+
+  if (cmd === 'explain') {
+    const to = list(args.to)
+    const e = explainHarnessDrops({ to, env })
+    if (json) { out(JSON.stringify(e, null, 2)); return 0 }
+    if (!e.source) { out('no harness captured yet: leg harness capture'); return 3 }
+    out(`from the ${e.source} harness, ${e.dropped.length} item(s) not carried:`)
+    for (const d of e.dropped) out(`  ${d.target.padEnd(7)} ${d.component.padEnd(11)} ${d.item}${d.excluded ? ' (excluded by policy)' : ''}: ${d.reason}`)
+    for (const [agent, why] of Object.entries(e.unsupported)) out(`  ${agent.padEnd(7)} everything    ${why}`)
+    return 0
+  }
+
+  if (cmd === 'source') {
+    const source = args._[0]
+    if (!source || !HARNESS_SOURCES.includes(source)) return die(2, `usage: leg harness source <${HARNESS_SOURCES.join('|')}>`)
+    const found = detectSources({ env }).map((s) => s.id)
+    if (!found.includes(source)) out(`note: no ${source} rules file under ${harnessHome(env)} right now; the setting is saved anyway`)
+    setHarnessConfig({ source })
+    out(`harness source: ${source}. Run leg harness sync to carry it.`)
+    return 0
+  }
+
+  if (cmd === 'policy') {
+    const policy = args._[0]
+    if (!policy || !HARNESS_POLICIES.includes(policy)) return die(2, `usage: leg harness policy <${HARNESS_POLICIES.join('|')}>`)
+    setHarnessConfig({ policy })
+    out(`harness policy: ${policy}${cfg.enabled ? '' : ' (portable harness is off; leg harness enable turns it on)'}`)
+    return 0
+  }
+
+  if (cmd === 'history') {
+    const rows = readHistory(args.limit ? parseInt(args.limit, 10) : 30)
+    if (json) { out(JSON.stringify(rows, null, 2)); return 0 }
+    if (!rows.length) { out('(no harness activity yet)'); return 0 }
+    for (const r of rows) out(`${r.ts}  ${String(r.op).padEnd(8)} ${r.op === 'capture' ? `${r.source} fp ${String(r.fingerprint).slice(0, 12)} ${JSON.stringify(r.components)}` : r.op === 'apply' ? `${r.source} → ${r.target}: ${r.state}, ${r.written ?? 0} written, ${r.backups?.length ?? 0} backup(s)${r.force ? ' (forced)' : ''}` : `${r.from ?? '?'} → ${r.to}: ${r.state}${r.proceed === false ? ' BLOCKED' : ''} (${r.policy}${r.reason ? `; ${r.reason}` : ''})`}${r.session_id ? `  [${r.session_id}]` : ''}  ${r.elapsed_ms ?? ''}ms`)
+    return 0
+  }
+
+  if (cmd === 'doctor') {
+    const rows = []
+    const push = (name, ok, detail) => rows.push({ name, status: ok === true ? 'ok' : ok === false ? 'FAIL' : 'note', detail })
+    try { const v = checkVendor(); push('engine', v.problems.length === 0, `vendored Agnostic AI engine at ${String(v.commit).slice(0, 12)}: ${v.checked} file(s) checked${v.problems.length ? `; ${v.problems.join('; ')}` : ''}`) } catch (err) { push('engine', false, err.message) }
+    const homeDir = harnessHome(env)
+    push('home', existsSync(homeDir), `client configs are read under ${homeDir}${env.LEG_HARNESS_HOME || env.BATON_HARNESS_HOME ? ' (LEG_HARNESS_HOME)' : ''}`)
+    push('enabled', cfg.enabled ? true : null, cfg.enabled ? `on, policy ${cfg.policy}` : 'off (leg harness enable)')
+    const found = detectSources({ env })
+    const source = cfg.source ?? found[0]?.id ?? null
+    push('source', Boolean(source), source ? `${source}${cfg.source ? ' (configured)' : ' (detected)'}` : 'none of ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md found')
+    const cap = existsSync(captureFile()) ? JSON.parse(readFileSync(captureFile(), 'utf8')) : null
+    push('bundle', cap ? (existsSync(join(bundleDir(), 'manifest.json')) ? true : false) : null, cap ? `captured ${cap.captured_at} from ${cap.source}; ${existsSync(join(bundleDir(), 'manifest.json')) ? 'manifest present' : 'manifest missing (leg harness capture --force)'}` : 'never captured')
+    if (cap) {
+      try { const i = inspectHarness(); push('bundle valid', !i.corrupt, i.corrupt ?? `fingerprint ${String(i.fingerprint).slice(0, 12)}`) } catch (err) { push('bundle valid', false, err.message) }
+    }
+    const stateFile = join(harnessDir(), 'harness-state.json')
+    let state = null
+    if (existsSync(stateFile)) { try { state = JSON.parse(readFileSync(stateFile, 'utf8')); push('state', true, `${Object.keys(state.targets ?? {}).length} client(s) with ownership records`) } catch (err) { push('state', false, `harness-state.json unreadable: ${err.message}`) } } else push('state', null, 'no ownership records yet (nothing written)')
+    push('policy file', null, existsSync(join(harnessDir(), 'policy.json')) ? `${join(harnessDir(), 'policy.json')} merged over the defaults` : 'defaults (nothing excluded)')
+    for (const t of registry({ env, home: homeDir })) push(`client ${t.id}`, t.installed ? true : null, t.installed ? `installed at ${t.home}` : `not installed (${t.home} absent)`)
+    for (const [agent, why] of Object.entries(NO_ADAPTER)) push(`client ${agent}`, null, why)
+    if (cap && source) {
+      try { const s = getHarnessStatus({ env }); for (const t of Object.values(s.targets)) if (t.state !== 'source') push(`sync ${t.id}`, t.state === 'synced' || t.state === 'partial' ? true : t.state === 'unsupported' ? null : false, `${t.state}${t.attention.length ? `: ${t.attention.map((a) => a.reason).join('; ')}` : ''}`) } catch (err) { push('sync', false, err.message) }
+    }
+    if (json) { out(JSON.stringify({ rows, states: STATES, policies: POLICIES }, null, 2)); return rows.some((r) => r.status === 'FAIL') ? 1 : 0 }
+    const w = Math.max(...rows.map((r) => r.name.length))
+    for (const r of rows) out(`${r.name.padEnd(w)}  ${r.status.padEnd(4)}  ${r.detail}`)
+    out(`doctor: ${rows.filter((r) => r.status === 'FAIL').length} failure(s) across ${rows.length} check(s)`)
+    return rows.some((r) => r.status === 'FAIL') ? 1 : 0
+  }
+  return die(2, `unknown harness command "${cmd}"`)
+}

package/src/harness/fingerprint.mjs

@@ -0,0 +1,68 @@
+// fingerprint — "did the source client's harness change since the last
+// capture", answered from file metadata alone. A hand-off must not re-read a
+// whole client home to find out that nothing moved: this stats the handful of
+// surfaces a capture reads (rules and their imports, settings, MCP, agents,
+// commands, skills) and hashes their paths, sizes and mtimes. A miss costs one
+// capture; a hit costs a few dozen stat calls.
+import { createHash } from 'node:crypto'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+
+function stat(p) {
+  try { const s = statSync(p); return `${s.size}:${Math.round(s.mtimeMs)}` } catch { return 'absent' }
+}
+
+function dirEntries(dir, inner = null) {
+  let names
+  try { names = readdirSync(dir).filter((n) => !n.startsWith('.')).sort() } catch { return [`${dir}=absent`] }
+  return names.map((n) => `${dir}/${n}=${stat(inner ? join(dir, n, inner) : join(dir, n))}`)
+}
+
+// The files a Claude Code rules file pulls in (`@path` lines), one level deep,
+// the same way the capture inlines them.
+function claudeImports(rulesFile, home) {
+  const out = []
+  let text
+  try { text = readFileSync(rulesFile, 'utf8') } catch { return out }
+  for (const line of text.split(/\r?\n/)) {
+    const m = line.match(/^@(\S+)[ \t]*$/)
+    if (!m) continue
+    const spec = m[1]
+    const p = spec === '~' ? home : spec.startsWith('~/') || spec.startsWith('~\\') ? join(home, spec.slice(2)) : isAbsolute(spec) ? resolve(spec) : resolve(dirname(rulesFile), spec)
+    out.push(p)
+  }
+  return out
+}
+
+// Every path a capture of `source` reads, with its metadata.
+export function sourceSurfaces(source, target, home) {
+  const lines = []
+  if (source === 'claude') {
+    const rules = join(target.home, 'CLAUDE.md')
+    lines.push(`${rules}=${stat(rules)}`)
+    for (const imp of claudeImports(rules, home)) lines.push(`${imp}=${stat(imp)}`)
+    for (const f of [target.hooksConfigFile, target.traitsFile, target.mcpConfigFile, join(target.home, '.mcp.json')]) if (f) lines.push(`${f}=${stat(f)}`)
+    lines.push(...dirEntries(target.agentsDir))
+    lines.push(...dirEntries(target.commandsDir))
+    lines.push(...dirEntries(target.skillsDir, 'SKILL.md'))
+  } else if (source === 'codex') {
+    for (const f of [target.rulesFile, target.hooksConfigFile]) if (f) lines.push(`${f}=${stat(f)}`)
+    lines.push(...dirEntries(target.agentsDir))
+    lines.push(...dirEntries(target.commandsDir))
+    lines.push(...dirEntries(target.skillsDir, 'SKILL.md'))
+    if (target.permissionsFile) lines.push(...dirEntries(dirname(target.permissionsFile)))
+  } else {
+    throw new Error(`no capture adapter for source "${source}"`)
+  }
+  return lines
+}
+
+export function sourceFingerprint(source, target, home) {
+  const lines = sourceSurfaces(source, target, home)
+  return { hash: createHash('sha256').update(lines.join('\n')).digest('hex').slice(0, 24), surfaces: lines.length }
+}
+
+export function sourcePresent(source, target) {
+  const rules = source === 'claude' ? join(target.home, 'CLAUDE.md') : target.rulesFile
+  return existsSync(rules)
+}