@ucsandman/legcli 0.7.0

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@ucsandman/legcli",
+  "version": "0.7.0",
+  "description": "Claude Code and Codex usage limit monitor with an automatic handoff. Type leg claude|codex|agy and get the same interactive agent with a board alongside, usage tracking per agent and account, a live context handoff bundle, and at the limit the next agent continuing in the same terminal. $79 once, 30-day money-back guarantee.",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://legcli.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ucsandman/legcli.git"
+  },
+  "bugs": {
+    "url": "https://legcli.com/support",
+    "email": "legcli@practicalsystems.io"
+  },
+  "keywords": [
+    "claude-usage-limit",
+    "claude-code-usage-limit",
+    "codex-usage-limit",
+    "usage-monitor",
+    "usage-limits",
+    "claude-code",
+    "codex",
+    "coding-agents",
+    "agent-harness",
+    "handoff",
+    "kanban",
+    "worktree",
+    "local-first"
+  ],
+  "author": "Wes Sander",
+  "bin": {
+    "leg": "bin/leg.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "scripts",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "CHANGELOG.md",
+    "docs",
+    "fixtures/limits",
+    "fixtures/live",
+    "fixtures/verified.json"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "start": "node --env-file-if-exists=.env bin/leg.mjs up",
+    "test": "node --test --test-concurrency=1 && node scripts/privacy-check.mjs && node scripts/check-claims.mjs",
+    "lint": "eslint .",
+    "privacy": "node scripts/privacy-check.mjs",
+    "claims": "node scripts/check-claims.mjs",
+    "claims:drift": "node scripts/check-claims.mjs --strict",
+    "docs": "node scripts/build-docs-site.mjs",
+    "dev": "node --env-file-if-exists=.env bin/leg.mjs up --no-open",
+    "stop": "node bin/leg.mjs down"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9",
+    "eslint": "^9",
+    "globals": "^16",
+    "marked": "^18.0.13"
+  }
+}

package/scripts/board-shots.mjs

@@ -0,0 +1,69 @@
+// Screenshots and measures the board at both widths, reporting the numbers that
+// caught real defects in the v4 redesign: full-page height, per-row height,
+// horizontal overflow, the computed font-size floor, console errors, and a
+// scroll-hold probe. Point it at a board seeded by scripts/seed-wes-board.mjs.
+//
+//   node scripts/board-shots.mjs <port> <tag>
+//
+// networkidle never fires on this board because it polls, so it waits for real
+// content instead.
+import { chromium } from 'playwright'
+import { mkdirSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const port = process.argv[2] || '4861'
+const tag = process.argv[3] || 'run'
+const out = fileURLToPath(new URL('./shots/', import.meta.url))
+mkdirSync(out, { recursive: true })
+
+const browser = await chromium.launch()
+const report = {}
+
+for (const w of [1280, 400]) {
+  const page = await browser.newPage({ viewport: { width: w, height: 900 } })
+  const errors = []
+  page.on('console', (m) => { if (m.type() === 'error') errors.push(m.text()) })
+  page.on('pageerror', (e) => errors.push(String(e)))
+  // networkidle never fires: the board polls. Wait for real content instead.
+  await page.goto(`http://127.0.0.1:${port}/`, { waitUntil: 'domcontentloaded' })
+  await page.waitForFunction(() => document.querySelectorAll('[class*="term"], .session-list > *, .panel').length > 0, { timeout: 15000 }).catch(() => {})
+  await page.waitForTimeout(1500)
+
+  const m = await page.evaluate(() => {
+    const rows = [...document.querySelectorAll('.term, .session-list > *')]
+    const px = (n) => Math.round(n)
+    const small = [...document.querySelectorAll('body *')]
+      .filter((e) => e.textContent.trim() && !e.children.length)
+      .map((e) => ({ t: e.textContent.trim().slice(0, 28), s: parseFloat(getComputedStyle(e).fontSize) }))
+      .filter((x) => x.s < 14)
+    return {
+      pageHeight: px(document.documentElement.scrollHeight),
+      docWidth: px(document.documentElement.scrollWidth),
+      viewport: window.innerWidth,
+      overflowX: document.documentElement.scrollWidth > window.innerWidth + 1,
+      rowCount: rows.length,
+      rowHeights: rows.map((r) => px(r.getBoundingClientRect().height)),
+      belowFontFloor: small.slice(0, 6),
+    }
+  })
+
+  // the fold is shot before anything scrolls the page, or it is a mid-page crop
+  await page.screenshot({ path: `${out}${tag}-${w}-fold.png` })
+
+  // scroll-hold: park the viewport, wait through every timer the page owns,
+  // assert it did not move.
+  await page.evaluate(() => window.scrollTo(0, 600))
+  const before = await page.evaluate(() => window.scrollY)
+  await page.waitForTimeout(6000)
+  const after = await page.evaluate(() => window.scrollY)
+  m.scrollHeld = before === after
+  m.scrollDrift = after - before
+  m.consoleErrors = errors
+
+  await page.screenshot({ path: `${out}${tag}-${w}.png`, fullPage: true })
+  report[w] = m
+  await page.close()
+}
+
+await browser.close()
+console.log(JSON.stringify(report, null, 2))

package/scripts/build-docs-site.mjs

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+// Renders the public docs to static HTML under site/docs, so a stranger can
+// read them without the repository. The repository is private and stays that
+// way, which means these pages are the only place the claims on the landing
+// page can be checked.
+//
+//   node scripts/build-docs-site.mjs
+//
+// Regenerate after editing anything in docs/ and commit the output; Vercel
+// serves site/ as static files and runs no build step.
+
+import { readFileSync, writeFileSync, mkdirSync, copyFileSync, readdirSync, rmSync, existsSync } from 'node:fs'
+import { join, dirname, basename } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { marked } from 'marked'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+
+// The one place the domain lives. Friday's custom domain is a single edit here
+// plus the same constant in site/index.html's canonical and og:url.
+const ORIGIN = process.env.LEG_SITE_ORIGIN || process.env.BATON_SITE_ORIGIN || 'https://legcli.com'
+
+// Public docs only. DECISIONS, DEVIATIONS, ERRORS, REUSE, ROADMAP-v2, DEMO and
+// the dated review notes are working files: they name unshipped plans and
+// internal postmortems, and they are not part of what a buyer is promised.
+const PAGES = [
+  {
+    slug: 'index',
+    source: null,
+    title: 'Leg docs: usage limits, the board and the handoff',
+    description: 'Every Leg document: install, the concepts, the board, configuration, the CLI contract, the agent adapters and the FAQ.',
+  },
+  {
+    slug: 'getting-started',
+    nav: 'Install',
+    source: 'docs/getting-started.md',
+    title: 'Install Leg and monitor your Claude Code usage limit',
+    description: 'Install Leg, run your first agent under it, and see the board, the usage reading and the handoff. Node 22+, one npm command.',
+  },
+  {
+    slug: 'concepts',
+    nav: 'How it works',
+    source: 'docs/concepts.md',
+    title: 'How Leg works: sessions, bundles and the wall',
+    description: 'The pieces Leg is built from: a session, the usage reading, the handoff bundle, the wall, worktrees and landing work on trunk.',
+  },
+  {
+    slug: 'board-guide',
+    nav: 'The board',
+    source: 'docs/board-guide.md',
+    title: 'The Leg board, panel by panel',
+    description: 'Every card, gauge, button and drawer on the Leg board, what each number means, and where the reading behind it came from.',
+  },
+  {
+    slug: 'configuration',
+    nav: 'Configuration',
+    source: 'docs/configuration.md',
+    title: 'Leg configuration and environment variables',
+    description: 'Every Leg environment variable, the config file, network exposure, the token seam and the folder-trust switch.',
+  },
+  {
+    slug: 'cli-contracts',
+    nav: 'What it reads',
+    source: 'docs/cli-contracts.md',
+    title: 'What Leg reads from Claude Code, Codex and agy',
+    description: 'The exact usage endpoints, hooks, log lines and limit strings Baton reads from Claude Code, Codex and agy, each cited to its source.',
+  },
+  {
+    slug: 'adapters',
+    nav: 'Adapters',
+    source: 'docs/adapters.md',
+    title: 'Leg agent adapters for Claude Code, Codex and agy',
+    description: 'How each agent adapter spawns its CLI, what it strips from the environment, and how to tell whether a tap is live or docs-only.',
+  },
+  {
+    slug: 'faq',
+    nav: 'FAQ',
+    source: 'docs/faq.md',
+    title: 'Leg FAQ: what it edits, what it sends, how the license works',
+    description: 'What Leg edits and never edits, whether it sends anything anywhere, what happens to your license, and what it does not do.',
+  },
+  {
+    slug: 'real-run',
+    nav: 'A real run',
+    source: 'docs/real-run.md',
+    title: 'A real run: Claude Code hits its usage limit, Codex continues',
+    description: 'One recorded session: Claude Code working, the limit landing, the bundle saved, and Codex picking the work up in the same terminal.',
+  },
+  {
+    slug: 'vocabulary',
+    nav: 'Vocabulary',
+    source: 'docs/VOCABULARY.md',
+    title: 'Leg vocabulary',
+    description: 'The words Leg uses on the board and in the CLI, each with the one meaning it carries everywhere.',
+  },
+  {
+    slug: 'readme',
+    nav: 'README',
+    source: 'README.md',
+    title: 'Leg README',
+    description: 'The complete Leg README as shipped in the npm package: what it does, what it reads, what it never touches, and the license.',
+  },
+  {
+    slug: 'changelog',
+    nav: 'Changelog',
+    source: 'CHANGELOG.md',
+    title: 'Leg changelog',
+    description: 'Every released version of Leg and what changed in it.',
+  },
+]
+
+const escapeHtml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+
+// Where a markdown link inside docs/ should point once the docs are pages.
+const slugForSource = new Map(PAGES.filter((p) => p.source).map((p) => [p.source.toLowerCase(), p.slug]))
+
+function rewriteHref (href) {
+  if (/^(https?:|mailto:|#)/i.test(href)) return href
+  const [path, hash = ''] = href.split('#')
+  if (!path) return href
+  const normalised = path.replace(/^\.\//, '').replace(/^\.\.\//, '').toLowerCase()
+  const withDocs = normalised.startsWith('docs/') ? normalised : `docs/${normalised}`
+  const slug = slugForSource.get(normalised) || slugForSource.get(withDocs)
+  if (slug) return `/docs/${slug}${hash ? '#' + hash : ''}`
+  // An image or asset that travels with the docs.
+  if (/\.(png|jpe?g|gif|svg|webp|mp4)$/i.test(path)) return `/img/docs/${basename(path)}`
+  // Files with a public home of their own.
+  const elsewhere = {
+    license: '/license',
+    'security.md': '/support#security',
+    'code_of_conduct.md': '/support',
+    'contributing.md': '/support',
+  }
+  if (elsewhere[normalised]) return elsewhere[normalised] + (hash ? '#' + hash : '')
+  // Everything left is a working file that ships inside the package but has no
+  // public page: DEMO, REUSE, ROADMAP-v2, DEVIATIONS, NOTICE, the site source.
+  // The package is where a reader can actually open it, so point there rather
+  // than dangling a 404 at a stranger.
+  return 'https://www.npmjs.com/package/@ucsandman/legcli'
+}
+
+const slugify = (text) => text.toLowerCase().replace(/<[^>]+>/g, '').replace(/[^\w\s-]/g, '').trim().replace(/\s+/g, '-')
+
+marked.use({
+  gfm: true,
+  breaks: false,
+  // Rewriting hrefs on the token, before rendering, keeps the default link and
+  // image renderers (and their escaping) exactly as marked ships them.
+  walkTokens (token) {
+    if (token.type === 'link' || token.type === 'image') token.href = rewriteHref(token.href)
+  },
+  renderer: {
+    // Headings get an id so the on-this-page nav and cross-doc anchors resolve.
+    heading ({ tokens, depth }) {
+      const text = this.parser.parseInline(tokens)
+      const id = slugify(tokens.map((t) => t.raw).join(''))
+      return `<h${depth} id="${id}"><a class="anchor" href="#${id}">${text}</a></h${depth}>\n`
+    },
+  },
+})
+
+function page ({ slug, title, description, body, headings }) {
+  const url = slug === 'index' ? `${ORIGIN}/docs` : `${ORIGIN}/docs/${slug}`
+  // Short labels here, not the SEO titles: the sidebar is for finding a page,
+  // and at phone width these become a single swipeable row of pills.
+  const nav = [
+    `<li><a href="/docs"${slug === 'index' ? ' aria-current="page"' : ''}>All docs</a></li>`,
+    ...PAGES.filter((p) => p.slug !== 'index')
+      .map((p) => `<li><a href="/docs/${p.slug}"${p.slug === slug ? ' aria-current="page"' : ''}>${escapeHtml(p.nav || p.title)}</a></li>`),
+  ].join('\n')
+  const onThisPage = headings.length
+    ? `<nav class="toc" aria-label="On this page"><p class="toc-title">On this page</p><ul>${headings.map((h) => `<li><a href="#${h.id}">${escapeHtml(h.text)}</a></li>`).join('')}</ul></nav>`
+    : ''
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(/legcli/i.test(title) ? title : `${title} | LegCli`)}</title>
+<meta name="description" content="${escapeHtml(description)}">
+<link rel="canonical" href="${url}">
+<meta name="theme-color" content="#0E1012">
+<link rel="icon" href="/favicon.svg" type="image/svg+xml">
+<meta property="og:type" content="article">
+<meta property="og:url" content="${url}">
+<meta property="og:site_name" content="LegCli">
+<meta property="og:title" content="${escapeHtml(title)}">
+<meta property="og:description" content="${escapeHtml(description)}">
+<meta property="og:image" content="${ORIGIN}/og.png?v=2">
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:title" content="${escapeHtml(title)}">
+<meta name="twitter:description" content="${escapeHtml(description)}">
+<meta name="twitter:image" content="${ORIGIN}/og.png?v=2">
+<link rel="preload" href="/fonts/atkinson-hyperlegible-next-var.woff2" as="font" type="font/woff2" crossorigin>
+<link rel="preload" href="/fonts/azeret-mono-var.woff2" as="font" type="font/woff2" crossorigin>
+<link rel="stylesheet" href="/style.css">
+<link rel="stylesheet" href="/docs.css">
+<script defer src="/_vercel/insights/script.js"></script>
+</head>
+<body class="docs">
+<a class="skip" href="#doc">Skip to the document</a>
+<header class="docs-top">
+  <div class="docs-top-wrap">
+    <a class="docs-home" href="/">LegCli</a>
+    <nav aria-label="Site"><a href="/docs">Docs</a> <a href="/#pricing">Pricing</a> <a href="/license">License</a></nav>
+  </div>
+</header>
+<div class="docs-shell">
+  <nav class="docs-nav" aria-label="Documentation">
+    <p class="docs-nav-title">Documentation</p>
+    <ul>
+${nav}
+    </ul>
+  </nav>
+  <main id="doc" class="docs-body">
+${onThisPage}
+${body}
+    <hr class="docs-end">
+    <p class="docs-foot">Leg is commercial, source-available software by Wes Sander. The source you run ships in the npm package. Questions or a refund: <a href="mailto:legcli@practicalsystems.io">legcli@practicalsystems.io</a>.</p>
+  </main>
+</div>
+</body>
+</html>
+`
+}
+
+function headingsOf (markdown) {
+  const out = []
+  let inFence = false
+  for (const line of markdown.split('\n')) {
+    if (/^\s*```/.test(line)) { inFence = !inFence; continue }
+    if (inFence) continue
+    const m = /^##\s+(.+?)\s*$/.exec(line)
+    if (m) out.push({ text: m[1].replace(/`/g, ''), id: slugify(m[1]) })
+  }
+  return out
+}
+
+const outDir = join(root, 'site', 'docs')
+rmSync(outDir, { recursive: true, force: true })
+mkdirSync(outDir, { recursive: true })
+
+// Screenshots referenced from the markdown travel with the pages.
+const shots = join(root, 'docs', 'screenshots')
+const imgDir = join(root, 'site', 'img', 'docs')
+mkdirSync(imgDir, { recursive: true })
+let copied = 0
+if (existsSync(shots)) {
+  for (const f of readdirSync(shots)) {
+    if (!/\.(png|jpe?g|gif|svg|webp)$/i.test(f)) continue
+    copyFileSync(join(shots, f), join(imgDir, f))
+    copied++
+  }
+}
+
+const written = []
+for (const p of PAGES) {
+  let body, headings
+  if (p.slug === 'index') {
+    const cards = PAGES.filter((x) => x.slug !== 'index')
+      .map((x) => `<li><a href="/docs/${x.slug}"><strong>${escapeHtml(x.title.replace(/ \| .*$/, ''))}</strong><span>${escapeHtml(x.description)}</span></a></li>`)
+      .join('\n')
+    body = `<h1>Leg documentation</h1>
+<p class="lede">Leg is a local wrapper for coding-agent CLIs: type <code>leg claude</code>, <code>leg codex</code> or <code>leg agy</code> and you get the same interactive agent with a board beside it, usage tracking per agent and account, a handoff bundle kept current, and an automatic handoff to the next agent in the same terminal when the usage limit hits.</p>
+<p class="lede">The source repository is private. These pages carry the same text as the documentation shipped inside the npm package, so every claim on the site can be checked before you buy, and the source itself is readable at <code>$(npm root -g)/legcli/src</code> after you install.</p>
+<ul class="doc-cards">
+${cards}
+</ul>`
+    headings = []
+  } else {
+    const md = readFileSync(join(root, p.source), 'utf8')
+    headings = headingsOf(md)
+    body = marked.parse(md)
+  }
+  const file = p.slug === 'index' ? join(outDir, 'index.html') : join(outDir, `${p.slug}.html`)
+  writeFileSync(file, page({ ...p, body, headings }))
+  written.push(p.slug === 'index' ? '/docs' : `/docs/${p.slug}`)
+}
+
+// The sitemap has to list every page that is now indexable, or the new docs
+// are invisible to search and to the AI crawlers that read sitemaps.
+//
+// No `lastmod`. It is optional, and here it cannot be made honest: this file is
+// generated and committed alongside the pages it describes, so a date read from
+// the clock changes on every build, and a date read from git changes the moment
+// the sources are committed — the sitemap would always describe the commit
+// before the one containing it. Search engines discount a lastmod they cannot
+// trust, so an absent one is worth more than a wrong one.
+const urls = [
+  { loc: `${ORIGIN}/`, priority: '1.0', changefreq: 'weekly' },
+  { loc: `${ORIGIN}/docs`, priority: '0.9', changefreq: 'weekly' },
+  ...PAGES.filter((p) => p.slug !== 'index').map((p) => ({
+    loc: `${ORIGIN}/docs/${p.slug}`,
+    priority: '0.7',
+    changefreq: 'weekly',
+  })),
+  { loc: `${ORIGIN}/support`, priority: '0.5', changefreq: 'monthly' },
+  { loc: `${ORIGIN}/license`, priority: '0.3', changefreq: 'yearly' },
+]
+writeFileSync(join(root, 'site', 'sitemap.xml'), `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urls.map((u) => `  <url><loc>${u.loc}</loc><changefreq>${u.changefreq}</changefreq><priority>${u.priority}</priority></url>`).join('\n')}
+</urlset>
+`)
+
+console.log(`docs pages written: ${written.length} (${written.join(', ')})`)
+console.log(`screenshots copied: ${copied} -> site/img/docs`)
+console.log(`sitemap urls: ${urls.length}`)

package/scripts/check-claims.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// Every dated or numbered claim Baton makes in public, checked against one
+// file. Two separate jobs:
+//
+//   node scripts/check-claims.mjs            consistency, offline, runs in CI
+//   node scripts/check-claims.mjs --strict   also asks each CLI what it is now
+//
+// Consistency asks: does every surface state the versions and counts in
+// fixtures/verified.json? A surface that says "463 tests" while another says
+// "406" is a trust liability whichever one is right, so a mismatch fails.
+//
+// Strict asks: is the pin still true? An agent CLI ships most weeks, and
+// "verified against 2.1.268" quietly becomes a claim about a version nobody
+// runs any more. This half is scheduled weekly rather than run on every push,
+// because drift is not a broken build, it is a prompt to go and re-verify.
+//
+// Every verdict prints the number of things it looked at. A check that can
+// pass without touching anything is indistinguishable from a clean week.
+
+import { readFileSync, existsSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { execFileSync } from 'node:child_process'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const strict = process.argv.includes('--strict')
+const testsArg = process.argv.indexOf('--tests')
+const measuredTests = testsArg !== -1 ? Number(process.argv[testsArg + 1]) : null
+
+const pin = JSON.parse(readFileSync(join(root, 'fixtures', 'verified.json'), 'utf8'))
+const problems = []
+let checked = 0
+
+// ---------------------------------------------------------------- consistency
+
+// A version string is only a claim about a CLI when the CLI is named near it,
+// so each surface is searched for the version and then for a contradicting one:
+// any OTHER version of the same shape attached to the same CLI's name.
+const versionsSeen = new Map()
+
+for (const surface of pin.surfaces) {
+  const path = join(root, surface)
+  if (!existsSync(path)) { problems.push(`surface missing: ${surface}`); continue }
+  const text = readFileSync(path, 'utf8')
+
+  for (const [key, cli] of Object.entries(pin.clis)) {
+    // Every version-shaped token that sits next to this CLI's label.
+    const near = new RegExp(`${cli.label.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}[^\\n]{0,24}?(\\d+\\.\\d+\\.\\d+)`, 'g')
+    for (const m of text.matchAll(near)) {
+      checked++
+      const found = m[1]
+      versionsSeen.set(`${key}:${found}`, (versionsSeen.get(`${key}:${found}`) || 0) + 1)
+      if (found !== cli.version) {
+        problems.push(`${surface}: says ${cli.label} ${found}, fixtures/verified.json pins ${cli.version}`)
+      }
+    }
+  }
+
+  // Test counts. "463 tests" and "406 tests" on two pages is the same defect
+  // whichever number is right.
+  for (const m of text.matchAll(/(\d{2,5})\s+tests\b/g)) {
+    checked++
+    if (Number(m[1]) !== pin.tests) {
+      problems.push(`${surface}: says ${m[1]} tests, fixtures/verified.json pins ${pin.tests}`)
+    }
+  }
+
+  // The verification date, in both the forms the surfaces use.
+  for (const m of text.matchAll(/(?:verified|checked)[^\n.]{0,40}?(\d{4}-\d{2}-\d{2}|\d{1,2} [A-Z][a-z]+ \d{4})/gi)) {
+    checked++
+    const found = m[1]
+    if (found !== pin.verifiedOn && found !== pin.verifiedOnLong) {
+      problems.push(`${surface}: says verified ${found}, fixtures/verified.json pins ${pin.verifiedOn} / ${pin.verifiedOnLong}`)
+    }
+  }
+}
+
+if (measuredTests !== null && Number.isFinite(measuredTests)) {
+  checked++
+  if (measuredTests !== pin.tests) {
+    problems.push(`the suite just reported ${measuredTests} tests, fixtures/verified.json pins ${pin.tests}`)
+  }
+}
+
+console.log(`claims: ${checked} version, count and date mentions checked across ${pin.surfaces.length} surfaces`)
+
+// ---------------------------------------------------------------------- drift
+
+if (strict) {
+  let probed = 0
+  const drift = []
+
+  for (const [, cli] of Object.entries(pin.clis)) {
+    let current = null
+    let how = null
+
+    if (cli.npm) {
+      try {
+        const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(cli.npm)}/latest`, { headers: { Accept: 'application/json' } })
+        if (res.ok) { current = (await res.json()).version; how = `npm ${cli.npm}` }
+        else drift.push(`${cli.label}: npm returned ${res.status}, could not check`)
+      } catch (error) {
+        drift.push(`${cli.label}: npm request failed (${error.message}), could not check`)
+      }
+    } else {
+      // No registry to ask, so ask the binary if this machine has it. Spawned
+      // as argv and never through a shell, like every other spawn in this
+      // repo; on Windows that means naming the shim extension ourselves rather
+      // than letting cmd resolve it.
+      const [bin, ...args] = cli.probe.split(' ')
+      const candidates = process.platform === 'win32' ? [`${bin}.cmd`, `${bin}.exe`, bin] : [bin]
+      for (const candidate of candidates) {
+        try {
+          current = execFileSync(candidate, args, { encoding: 'utf8', timeout: 20000, stdio: ['ignore', 'pipe', 'ignore'] }).trim().split('\n')[0].trim()
+          how = cli.probe
+          break
+        } catch { /* try the next spelling */ }
+      }
+      if (!current) {
+        console.log(`  ${cli.label}: no npm package and ${cli.probe} is not available here; not checked`)
+      }
+    }
+
+    if (!current) continue
+    probed++
+    if (current !== cli.version) {
+      drift.push(`${cli.label}: pinned ${cli.version}, current ${current} (${how})`)
+    }
+  }
+
+  console.log(`drift: ${probed} of ${Object.keys(pin.clis).length} CLIs reachable and compared`)
+
+  if (drift.length) {
+    console.error(`\nThe verified-against versions are behind. Re-run the taps on a real machine, then update fixtures/verified.json and every surface in the same commit.\n`)
+    for (const d of drift) console.error(`  - ${d}`)
+    process.exitCode = 1
+  } else if (probed > 0) {
+    console.log(`every reachable CLI still matches the pin of ${pin.verifiedOn}`)
+  }
+}
+
+// --------------------------------------------------------------------- verdict
+
+if (problems.length) {
+  console.error(`\n${problems.length} claim${problems.length === 1 ? '' : 's'} disagree with fixtures/verified.json:\n`)
+  for (const p of problems) console.error(`  - ${p}`)
+  process.exitCode = 1
+} else {
+  console.log('every surface agrees with the pin')
+}

package/scripts/clean-clone-check.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# clean-clone-check — prove baton runs from a fresh clone: clone, install,
+# test, lint, dry launcher. Usage: bash scripts/clean-clone-check.sh [scratch-dir]
+# Prints "CLEAN-CLONE PASS tests=<n>" or "CLEAN-CLONE FAIL step=<step>".
+set -uo pipefail
+SRC="$(cd "$(dirname "$0")/.." && pwd)"
+SCRATCH="${1:-${TMPDIR:-/tmp}}"
+TS="$(date +%s)"
+DEST="$SCRATCH/baton-clean-$TS"
+LOG="$DEST.log"
+fail() { echo "CLEAN-CLONE FAIL step=$1 (log: $LOG)"; tail -20 "$LOG" 2>/dev/null; exit 1; }
+
+mkdir -p "$SCRATCH" || fail mkdir
+echo "clone $SRC -> $DEST"
+git clone -q "file://$SRC" "$DEST" > "$LOG" 2>&1 || fail clone
+cd "$DEST" || fail cd
+
+echo "npm ci"
+if ! npm ci --no-audit --no-fund >> "$LOG" 2>&1; then
+  if grep -q edgesOut "$LOG"; then
+    echo "npm ci hit edgesOut; retrying with npx --yes npm@latest ci"
+    npx --yes npm@latest ci --no-audit --no-fund >> "$LOG" 2>&1 || fail npm-ci
+  else
+    fail npm-ci
+  fi
+fi
+
+echo "npm test"
+npm test >> "$LOG" 2>&1 || fail npm-test
+TESTS="$(grep -E '^ℹ tests [0-9]+' "$LOG" | tail -1 | grep -oE '[0-9]+$')"
+PASS="$(grep -E '^ℹ pass [0-9]+' "$LOG" | tail -1 | grep -oE '[0-9]+$')"
+FAILS="$(grep -E '^ℹ fail [0-9]+' "$LOG" | tail -1 | grep -oE '[0-9]+$')"
+[ "${FAILS:-1}" = "0" ] || fail npm-test-fail
+[ "${TESTS:-0}" = "${PASS:-x}" ] || fail npm-test-count
+
+echo "npm run lint"
+npm run lint >> "$LOG" 2>&1 || fail lint
+
+echo "node bin/baton.mjs up --dry"
+BATON_HOME="$DEST/.baton-home" node bin/baton.mjs up --dry >> "$LOG" 2>&1 || fail up-dry
+
+echo "CLEAN-CLONE PASS tests=$TESTS"

package/scripts/license-sign.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// Sign a Baton license key by hand (the site's /api/key does the same for
+// paid orders). Needs BATON_LICENSE_PRIVATE_KEY in the environment:
+//   node --env-file=.env scripts/license-sign.mjs --plan personal --email you@example.com
+//   node --env-file=.env scripts/license-sign.mjs --plan team --email ops@acme.com --seats 5 --months 1
+// Prints the key on stdout and nothing else.
+import { randomBytes } from 'node:crypto'
+import { signLicense, emailHash } from '../src/license.mjs'
+
+const args = {}
+const argv = process.argv.slice(2)
+for (let i = 0; i < argv.length; i++) if (argv[i].startsWith('--')) { args[argv[i].slice(2)] = argv[i + 1]; i++ }
+const priv = (process.env.LEG_LICENSE_PRIVATE_KEY || process.env.BATON_LICENSE_PRIVATE_KEY)
+if (!priv) { process.stderr.write('BATON_LICENSE_PRIVATE_KEY is not set\n'); process.exit(2) }
+const plan = args.plan === 'team' ? 'team' : 'personal'
+const issued = args.issued || new Date().toISOString().slice(0, 10)
+const months = parseInt(args.months || (plan === 'team' ? '1' : '12'), 10)
+const end = new Date(issued + 'T00:00:00Z'); end.setUTCMonth(end.getUTCMonth() + months)
+const endIso = new Date(end.getTime() + (plan === 'team' ? 3 * 86400000 : 0)).toISOString().slice(0, 10)
+const payload = { v: 1, id: args.id || ('lic_' + randomBytes(8).toString('hex')), plan, seats: parseInt(args.seats || '1', 10), email_hash: emailHash(args.email || ''), issued }
+if (plan === 'personal') payload.updates_until = endIso
+else { payload.expires = endIso; if (args.sub) payload.sub = args.sub }
+process.stdout.write(signLicense(payload, priv) + '\n')