sloptimize 0.3.0

package/bin/sloptimize.mjs

@@ -0,0 +1,346 @@
+#!/usr/bin/env node
+// ============================================================
+// sloptimize CLI — report | check | census | history | fix | doctor  (SPEC §8.1)
+// ============================================================
+// Files-first: every verb reads `.sloptimize/` in the cwd (or --dir) and
+// says what it cannot know instead of guessing. Exit codes are API:
+//   check: 0 all budgets pass · 1 breach · 4 no measurement / no budgets file
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+if (cmd === '--version' || cmd === '-v') {
+  const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'));
+  console.log(pkg.version);
+  process.exit(0);
+}
+const json = args.includes('--json');
+const dirFlag = args.indexOf('--dir');
+const DIR = dirFlag >= 0 ? args[dirFlag + 1] : '.sloptimize';
+
+function readJson(name) {
+  const p = join(DIR, name);
+  if (!existsSync(p)) return null;
+  try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; }
+}
+function readJsonl(name, limit = 50) {
+  const p = join(DIR, name);
+  if (!existsSync(p)) return [];
+  const lines = readFileSync(p, 'utf8').trim().split('\n').filter(Boolean);
+  return lines.slice(-limit).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+}
+function out(obj, human) { console.log(json ? JSON.stringify(obj, null, 2) : human); }
+
+if (cmd === 'report') {
+  const profile = readJson('profile.json');
+  // 80 lines, not 20: heartbeats (1/min while a session is armed) share the
+  // ledger and must not crowd the actual incidents out of the report window.
+  const hitches = readJsonl('perf.jsonl', 80);
+  const marks = hitches.filter((h) => h.type === 'usermark');
+  const auto = hitches.filter((h) => h.type === 'hitch');
+  const jitters = hitches.filter((h) => h.type === 'jitter');
+  const census = readJson('census.json');
+  if (json) { out({ profile, hitches: auto, usermarks: marks, jitters, census }); process.exit(0); }
+  if (!profile) { console.log('no profile.json — is the game running with the sloptimize runtime?'); process.exit(4); }
+  console.log(`profile @ ${profile.at}  regime=${profile.regime ?? 'unknown'}`);
+  const beats = hitches.filter((h) => h.type === 'heartbeat');
+  const lastBeat = beats[beats.length - 1];
+  if (lastBeat) console.log(`  feed: last heartbeat @ ${lastBeat.at}  build=${lastBeat.build ?? '?'}  phase=${lastBeat.phase ?? '?'}  median ${lastBeat.medianFrameMs}ms p95 ${lastBeat.p95Ms}ms`);
+  if (profile.frame?.medianMs !== undefined) {
+    console.log(`  frame median ${profile.frame.medianMs}ms  p95 ${profile.frame.p95Ms}ms  (~${profile.frame.fps}fps)  inside-render ${profile.frame.insideRenderMs}ms`);
+  }
+  if (profile.render) console.log(`  calls ${profile.render.calls}  triangles ${profile.render.triangles}  programs ${profile.memory?.programs}`);
+  console.log(`  hitches recorded: ${auto.length} (showing last ${Math.min(auto.length, 20)})  usermarks: ${marks.length}`);
+  for (const h of auto.slice(-5)) {
+    console.log(`  · ${h.at} ${h.frameMs}ms (median ${h.medianMs}) → ${h.classification?.[0]?.guess}: ${h.classification?.[0]?.evidence}`);
+  }
+  for (const m of marks.slice(-3)) {
+    const w = m.worstFrames?.[0];
+    console.log(`  ★ usermark ${m.at} ${m.note ?? ''} — window ${m.window?.frames}f median ${m.window?.medianMs}ms; worst ${w?.frameMs}ms → ${w?.classification?.[0]?.guess}`);
+  }
+  if (jitters.length) {
+    // Coordinate jumps (SPEC §3.6): the unit or the camera landed off its own
+    // trajectory. Listed apart from hitches — a snap at 60fps is not a slow frame.
+    console.log(`  jitters recorded: ${jitters.length} (showing last ${Math.min(jitters.length, 5)})`);
+    for (const j of jitters.slice(-5)) {
+      const shape = j.kind === 'oscillation' ? `oscillation ×${j.frames} amp ${j.amplitude}` : `snap ${j.units} [${(j.jump ?? []).join(', ')}]`;
+      console.log(`  ↯ ${j.at} ${j.track} ${shape} in a ${j.dtMs}ms frame → ${j.classification?.[0]?.guess}: ${j.classification?.[0]?.evidence}`);
+    }
+  }
+  // The catalogue's head: which causes recur most (SPEC §3.7). The whole
+  // ledger, not the 80-line window — recurrence is the point.
+  const { buildIssues, agoText } = await import('../src/history.js');
+  const issues = buildIssues(readJsonl('perf.jsonl', Infinity), { fixes: readJsonl('fixes.jsonl', Infinity) });
+  if (issues.length) {
+    console.log(`  issues (${issues.length} footprints; top 5 by occurrences — \`sloptimize issues\` for all):`);
+    for (const i of issues.slice(0, 5)) console.log(`  ${i.glyph} fp=${i.id} ×${i.count}  ${i.label} [${i.phase}]  last ${agoText(i.lastAgoMs)}${i.fixes.length ? `  fixes: ${i.fixes.length}` : ''}`);
+  }
+  if (census?.hints?.length) {
+    console.log(`  census hints (${census.hints.length}):`);
+    for (const h of census.hints.slice(0, 8)) console.log(`  · [${h.kind}] ${h.entity ?? ''} ${h.detail}`);
+  }
+  process.exit(0);
+}
+
+if (cmd === 'issues') {
+  // The issue catalogue (SPEC §3.7): every incident type grouped by
+  // footprint, with occurrences, first/last, builds, worst, and the fixes
+  // applied to it. `--from/--to` scope the count; `--all` includes robots.
+  const { buildIssues, agoText } = await import('../src/history.js');
+  const get = (flag) => { const i = args.indexOf(flag); return i >= 0 ? args[i + 1] : undefined; };
+  const issues = buildIssues(readJsonl('perf.jsonl', Infinity), {
+    fixes: readJsonl('fixes.jsonl', Infinity), from: get('--from'), to: get('--to'), includeAutomated: args.includes('--all'),
+  });
+  if (json) { out(issues); process.exit(0); }
+  if (issues.length === 0) { console.log('no incidents on the ledger yet'); process.exit(4); }
+  const only = get('--fp');
+  for (const i of issues) {
+    if (only && i.id !== only) continue;
+    console.log(`${i.glyph} fp=${i.id} ×${String(i.count).padEnd(5)} ${i.label.padEnd(44)} [${i.phase}]  last ${agoText(i.lastAgoMs).padEnd(8)} first ${i.first.slice(0, 16)}  builds ${i.builds.length}${i.worst ? `  worst ${+i.worst.value.toFixed(1)}${i.worst.unit}` : ''}`);
+    if (only || issues.length <= 8) {
+      console.log(`      key ${i.key}`);
+      if (i.sample) console.log(`      last verdict: ${i.sample.guess} — ${i.sample.evidence}`);
+      for (const f of i.fixes) console.log(`      ✔ ${f.at.slice(0, 10)} ${f.status ?? 'recorded'} ${f.title}${f.commit ? ` (${f.commit})` : ''}${f.pr?.url ? ` ${f.pr.url}` : ''}`);
+      if (i.fixes.length === 0) console.log(`      no fix recorded — sloptimize fix propose --footprints ${i.id} --title "…"`);
+    }
+  }
+  process.exit(0);
+}
+
+if (cmd === 'check') {
+  const profile = readJson('profile.json');
+  const budgets = readJson('budgets.json');   // { "perf.budget.draw_calls": 300, ... }
+  if (!profile) { out({ error: 'no measurement' }, 'no profile.json to check against'); process.exit(4); }
+  if (!budgets || Object.keys(budgets).length === 0) {
+    out({ warning: 'no budgets declared', breached: [] }, 'no budgets declared (create .sloptimize/budgets.json) — passing with a warning');
+    process.exit(0);
+  }
+  const countersOnly = args.includes('--counters-only') || profile.regime === 'software';
+  const results = [];
+  const read = {
+    'perf.budget.draw_calls': profile.render?.calls,
+    'perf.budget.triangles': profile.render?.triangles,
+    'perf.budget.frame_ms_p95': countersOnly ? undefined : profile.frame?.p95Ms,
+    'perf.budget.programs': profile.memory?.programs,
+  };
+  let breached = 0;
+  for (const [k, budget] of Object.entries(budgets)) {
+    const v = read[k];
+    if (v === undefined) { results.push({ budget: k, value: null, limit: budget, verdict: countersOnly && k.includes('ms') ? 'skipped (counters-only)' : 'unmeasured' }); continue; }
+    const over = v > budget;
+    if (over) breached++;
+    results.push({ budget: k, value: v, limit: budget, verdict: over ? `over by ${(v / budget).toFixed(1)}x` : 'inside' });
+  }
+  out({ checked: results.length, breached, results },
+    results.map((r) => `  ${r.budget.padEnd(28)} ${String(r.value).padStart(10)} / ${r.limit}   ${r.verdict}`).join('\n')
+    + `\nbudgets: ${results.length} checked, ${breached} breached`);
+  process.exit(breached > 0 ? 1 : 0);
+}
+
+if (cmd === 'census') {
+  const census = readJson('census.json');
+  if (!census) { console.log('no census.json — trigger a walk from the running game (__sloptimize.census())'); process.exit(4); }
+  if (json) { console.log(JSON.stringify(census, null, 2)); process.exit(0); }
+  console.log(`census @ ${census.at}: ${census.totals.meshes} meshes, ${census.totals.triangles} tris, ${census.totals.uniqueMaterials} materials, ${census.totals.uniqueGeometries} geometries`);
+  const rows = [...census.entities].sort((a, b) => b.triangles - a.triangles).slice(0, 15);
+  for (const e of rows) {
+    console.log(`  ${String(e.id).padEnd(28)} meshes ${String(e.meshes).padStart(5)}  tris ${String(e.triangles).padStart(9)}  mats ${String(e.uniqueMaterials).padStart(3)}  shadow-casters ${e.castShadow}`);
+  }
+  for (const h of census.hints ?? []) console.log(`  hint [${h.kind}] ${h.entity ?? ''}: ${h.detail}`);
+  process.exit(0);
+}
+
+if (cmd === 'doctor') {
+  const profile = readJson('profile.json');
+  console.log('sloptimize doctor');
+  console.log(`  data dir: ${DIR} ${existsSync(DIR) ? '(present)' : '(MISSING — runtime not wired or game not run)'}`);
+  console.log(`  profile.json: ${profile ? `fresh as of ${profile.at}` : 'absent'}`);
+  console.log(`  regime: ${profile?.regime ?? 'unknown'} — timing numbers from a software regime are flagged and never compared`);
+  console.log('  stated limits: no per-draw GPU timing; bisection ranks, never sums; workload repro not trajectory repro;');
+  console.log('  gpu:* instruments fire only under a real WebGPU backend — a WebGL2-fallback session reads them as zeros, honestly;');
+  console.log('  bench/gate (M3) not built yet in this install — verify fixes with counters (exact grade) + real-hardware sessions.');
+  process.exit(0);
+}
+
+if (cmd === 'hook-status') {
+  // ≤5 lines for a UserPromptSubmit hook, and SILENT (exit 0, no output)
+  // when nothing is new — ambient perf the way selection is ambient, and
+  // only when it matters (SPEC §8.1). Multi-dir: a game served from the main
+  // checkout and a worktree under active surgery both count.
+  const dirs = [];
+  for (let i = 0; i < args.length; i++) if (args[i] === '--dir' && args[i + 1]) dirs.push(args[i + 1]);
+  if (dirs.length === 0) dirs.push('.sloptimize');
+  const stateP = join(dirs[0], '.hook-state.json');
+  let state = {};
+  try { state = JSON.parse(readFileSync(stateP, 'utf8')); } catch { /* first run */ }
+  const lines = [];
+  for (const dir of dirs) {
+    const read = (n) => { try { return JSON.parse(readFileSync(join(dir, n), 'utf8')); } catch { return null; } };
+    const readL = (n) => { try { return readFileSync(join(dir, n), 'utf8').trim().split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean); } catch { return []; } };
+    const profile = read('profile.json');
+    const recs = readL('perf.jsonl');
+    const marks = recs.filter((r) => r.type === 'usermark');
+    const lastMark = marks[marks.length - 1];
+    const seenKey = `mark:${dir}`;
+    if (lastMark && state[seenKey] !== lastMark.at) {
+      state[seenKey] = lastMark.at;
+      const w = lastMark.worstFrames && lastMark.worstFrames[0];
+      lines.push(`sloptimize ★ NEW perf keyframe (${lastMark.note ?? 'Ctrl+F11'}) @ ${lastMark.at}: window ${lastMark.window?.frames}f median ${lastMark.window?.medianMs}ms; worst ${w?.frameMs}ms → ${w?.classification?.[0]?.guess} (${w?.classification?.[0]?.evidence}) [${dir}/perf.jsonl]`);
+    }
+    const budgets = read('budgets.json');
+    if (profile && budgets) {
+      const countersOnly = profile.regime !== 'hardware';
+      const readV = { 'perf.budget.draw_calls': profile.render?.calls, 'perf.budget.triangles': profile.render?.triangles, 'perf.budget.frame_ms_p95': countersOnly ? undefined : profile.frame?.p95Ms, 'perf.budget.programs': profile.memory?.programs };
+      const over = Object.entries(budgets).filter(([k, b]) => readV[k] !== undefined && readV[k] > b);
+      const overKey = `over:${dir}`;
+      const sig = over.map(([k]) => k).join(',');
+      if (over.length && state[overKey] !== sig) {
+        state[overKey] = sig;
+        lines.push(`sloptimize ⚠ budget breach (${profile.regime}): ` + over.map(([k, b]) => `${k} ${readV[k]}/${b}`).join('  '));
+      } else if (!over.length) state[overKey] = '';
+    }
+    // Liveness: heartbeats keep perf.jsonl fresh while a session is armed, so
+    // a stale ledger MEANS the feed is dark or the session is over — not
+    // merely idle. Said once per distinct last-record (state-deduped): the
+    // instrument going silently dark cost an hour of debugging blind
+    // (2026-08-24 — a runner restart dropped the ingest and nobody was told).
+    const lastRec = recs[recs.length - 1];
+    if (lastRec && lastRec.at) {
+      const ageMin = (Date.now() - Date.parse(lastRec.at)) / 60000;
+      const staleKey = `stale:${dir}`;
+      if (ageMin > 45) {
+        if (state[staleKey] !== lastRec.at) {
+          state[staleKey] = lastRec.at;
+          lines.push(`sloptimize ◌ feed quiet ${Math.round(ageMin)}min (last: ${lastRec.type} @ ${lastRec.at}) [${dir}] — session over, or the feed went dark (ingest disarmed?)`);
+        }
+      } else state[staleKey] = '';
+    }
+  }
+  try { const { writeFileSync, mkdirSync } = await import('node:fs'); mkdirSync(dirs[0], { recursive: true }); writeFileSync(stateP, JSON.stringify(state)); } catch { /* stateless is only chattier */ }
+  if (lines.length) console.log(lines.slice(0, 5).join('\n'));
+  process.exit(0);
+}
+
+// ── The fix loop, git only (src/proposals.mjs) ──────────────────────────────
+//   fix propose --title … [--issue … --solution … --files a,b --footprints id,id --branch … --no-push]
+//   fix merge <id> · fix reject <id> · fixes [--json] · policy · settings --automation propose|merge
+const sub = args[1];
+if ((cmd === 'fix' && ['propose', 'merge', 'reject', 'list'].includes(sub)) || cmd === 'fixes' || cmd === 'policy' || cmd === 'settings') {
+  const P = await import('../src/proposals.mjs');
+  const get = (flag) => { const i = args.indexOf(flag); return i >= 0 ? args[i + 1] : undefined; };
+  const REPO = get('--repo') ?? process.cwd();
+  const fail = (e) => { console.error(`sloptimize ${cmd}${sub ? ` ${sub}` : ''}: ${e.message}`); process.exit(e.message === P.NOT_A_REPO ? 3 : 1); };
+  try {
+    if (cmd === 'policy') {
+      const s = P.readSettings(DIR);
+      out({ ...s, repo: P.isGitRepo(REPO) }, `automation: ${s.automation}${P.isGitRepo(REPO) ? '' : `\n${P.NOT_A_REPO}`}`);
+      process.exit(0);
+    }
+    if (cmd === 'settings') {
+      const level = get('--automation');
+      const s = level ? P.writeSettings(DIR, { automation: level }) : P.readSettings(DIR);
+      out(s, `automation: ${s.automation}`);
+      process.exit(0);
+    }
+    if (cmd === 'fixes' || sub === 'list') {
+      const l = P.listFixes(REPO, DIR);
+      if (json) { out(l); process.exit(0); }
+      if (!l.repo) { console.log(l.error); process.exit(3); }
+      if (l.fixes.length === 0) { console.log('no proposals yet — `sloptimize fix propose --title "…"` records one'); process.exit(0); }
+      for (const f of l.fixes) console.log(`  ${f.status.padEnd(9)} ${f.at.slice(0, 16)}  ${f.title}${f.branch ? `  [${f.branch} @ ${f.commit}${f.upToDate === false ? ', behind main' : ''}]` : ''}  id=${f.id}`);
+      process.exit(0);
+    }
+    if (sub === 'propose') {
+      if (!get('--title')) { console.error('sloptimize fix propose: --title is required'); process.exit(2); }
+      const { buildFix } = await import('../src/history.js');
+      const records = readJsonl('perf.jsonl', Infinity);
+      const fix = P.proposeFix(REPO, DIR, {
+        title: get('--title'), issue: get('--issue'), solution: get('--solution'), branch: get('--branch'),
+        files: get('--files')?.split(','), push: !args.includes('--no-push'),
+        footprints: get('--footprints')?.split(',').filter(Boolean),
+        measure: () => { const f = buildFix(records, { title: get('--title'), before: get('--before'), after: get('--after') }); return { before: f.before, after: f.after }; },
+      });
+      out(fix, `proposed: ${fix.title}\n  branch ${fix.branch} @ ${fix.commit}${fix.pushed ? ' (pushed)' : ''}\n  id ${fix.id}${fix.before ? '' : '\n  (no measured before/after yet — the numbers land when it is played)'}`);
+      process.exit(0);
+    }
+    const id = args[2];
+    if (!id) { console.error(`sloptimize fix ${sub}: <id> is required (see \`sloptimize fixes\`)`); process.exit(2); }
+    const r = sub === 'merge' ? P.mergeFix(REPO, DIR, id) : P.rejectFix(REPO, DIR, id);
+    out(r, `${r.status}: ${id}${r.mergeCommit ? ` → ${r.mergeCommit}` : ''}${r.pushed ? ' (pushed)' : ''}`);
+    process.exit(0);
+  } catch (e) { fail(e); }
+}
+
+if (cmd === 'history' || cmd === 'fix') {
+  // The timeline and the fix ledger (SPEC §8.5). `history` folds perf.jsonl
+  // into buckets + per-build windows; `fix` appends one report to
+  // fixes.jsonl whose before/after are MEASURED windows of that ledger —
+  // the agent names the issue, the solution and the commit; the numbers
+  // come from the recorder, never from the agent.
+  const { buildHistory, buildFix } = await import('../src/history.js');
+  const records = readJsonl('perf.jsonl', Infinity);
+  const fixes = readJsonl('fixes.jsonl', Infinity);
+  const get = (flag) => { const i = args.indexOf(flag); return i >= 0 ? args[i + 1] : undefined; };
+  const fmt = (v, unit = '') => (v === undefined ? '—' : `${v}${unit}`);
+  const line = (s) => `p95 ${fmt(s.p95Ms, 'ms')}  calls ${fmt(s.calls)}  hitches ${s.hitches} (${fmt(s.hitchesPerHour)}/h, worst ${fmt(s.worstMs, 'ms')}${s.worstGuess ? ` ${s.worstGuess}` : ''})`;
+  if (cmd === 'fix') {
+    let commit = get('--commit');
+    if (!commit) {
+      try { const { execSync } = await import('node:child_process'); commit = execSync('git rev-parse --short HEAD', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim(); } catch { /* not a repo */ }
+    }
+    if (!get('--title')) { console.error('sloptimize fix: --title is required'); process.exit(2); }
+    let fix;
+    try {
+      fix = buildFix(records, { title: get('--title'), issue: get('--issue'), solution: get('--solution'), commit,
+        files: get('--files')?.split(','), before: get('--before'), after: get('--after'),
+        footprints: get('--footprints')?.split(',').filter(Boolean) });
+    } catch (e) { console.error(`sloptimize fix: ${e.message}`); process.exit(4); }
+    const { appendFileSync, mkdirSync } = await import('node:fs');
+    mkdirSync(DIR, { recursive: true });
+    appendFileSync(join(DIR, 'fixes.jsonl'), JSON.stringify(fix) + '\n');
+    out(fix, `fix recorded: ${fix.title}${fix.commit ? ` (${fix.commit})` : ''}\n  before ${fix.before.build ?? fix.before.from}: ${line(fix.before)}\n  after  ${fix.after.build ?? fix.after.from}: ${line(fix.after)}`);
+    process.exit(0);
+  }
+  const h = buildHistory(records, { fixes, buckets: Number(get('--buckets')) || 24 });
+  if (json) { out(h); process.exit(0); }
+  if (!h.span) { console.log('no measured records in perf.jsonl yet'); process.exit(4); }
+  console.log(`history ${h.span.from} → ${h.span.to}  (${h.builds.length} builds, ${h.fixes.length} fixes)`);
+  for (const b of h.builds) console.log(`  build ${b.build.padEnd(16)} ${b.from.slice(0, 16)}  ${line(b)}`);
+  console.log('  buckets:');
+  for (const b of h.buckets) console.log(`  ${b.from.slice(5, 16)}  p95 ${String(fmt(b.p95Ms)).padStart(7)}  calls ${String(fmt(b.calls)).padStart(5)}  hitches ${String(b.hitches).padStart(3)}  ${b.worstMs ? `worst ${b.worstMs}ms ${b.worstGuess ?? ''}` : ''}`);
+  for (const f of h.fixes) console.log(`  ✔ ${f.at.slice(0, 10)} ${f.title}${f.commit ? ` (${f.commit})` : ''}: p95 ${fmt(f.before.p95Ms, 'ms')} → ${fmt(f.after.p95Ms, 'ms')}, hitches/h ${fmt(f.before.hitchesPerHour)} → ${fmt(f.after.hitchesPerHour)}`);
+  process.exit(0);
+}
+
+if (cmd === 'watch') {
+  // The push channel (SPEC §8.1.1): tail every --dir's perf.jsonl and print
+  // one line per record an agent should wake for. Never exits — arm it as a
+  // Claude Code Monitor (INTEGRATION.md §5) and just play.
+  const { runWatch } = await import('../src/watch.mjs');
+  const dirs = [];
+  for (let i = 0; i < args.length; i++) if (args[i] === '--dir' && args[i + 1]) dirs.push(args[i + 1]);
+  if (dirs.length === 0) dirs.push('.sloptimize');
+  const get = (flag) => { const i = args.indexOf(flag); return i >= 0 ? Number(args[i + 1]) : undefined; };
+  await runWatch(dirs, { intervalMs: get('--interval') ? get('--interval') * 1000 : undefined, minHitchMs: get('--min-hitch-ms') });
+}
+
+if (cmd === 'attach') {
+  // Tier 0 (SPEC-attach): zero-integration attach. --launch <url> spawns a
+  // browser; bare attach uses an existing --remote-debugging-port session.
+  const { attach } = await import('../src/attach.mjs');
+  const get = (flag) => { const i = args.indexOf(flag); return i >= 0 ? args[i + 1] : undefined; };
+  const session = await attach({
+    launch: get('--launch'),
+    port: get('--port') ? Number(get('--port')) : undefined,
+    dir: get('--dir') ?? '.sloptimize',
+    headless: args.includes('--headless'),
+  });
+  console.log('[attach] recording — Ctrl+C to stop');
+  process.on('SIGINT', async () => { await session.close(); process.exit(0); });
+  await new Promise(() => {});
+}
+
+console.log('usage: sloptimize <report|issues|check|census|history|fix|doctor|hook-status|watch|attach> [--json] [--dir <path>]... [--counters-only] [--interval <s>] [--min-hitch-ms N] [--launch <url>] [--port N] [--headless]\n       sloptimize fix --title "…" [--issue "…"] [--solution "…"] [--commit sha] [--files a,b] [--footprints id,id] [--before <build|ISO..ISO>] [--after <build|ISO..ISO>]\n       sloptimize issues [--json] [--from ISO] [--to ISO] [--fp <id>] [--all]');
+process.exit(2);

package/docs/DESIGN-mecharoyale-v0.md

@@ -0,0 +1,32 @@
+# v0 field deployment: mecharoyale (decision record)
+
+The first real integration target diverges from the spec's assumed platform
+in three ways, and v0 is shaped by meeting the game where it is:
+
+1. **No vite.** The game builds with esbuild and serves itself. The vite
+   plugin (§1) is therefore not the v0 transport: the in-page runtime posts
+   payloads to a dev-gated endpoint on the game's own server
+   (`POST /api/sloptimize/ingest`, active only under `ALLOW_DEBUG_SPAWN=1`),
+   which lands them in `.sloptimize/` exactly as the plugin would. Same
+   files, same schemas, different pipe. The vite plugin remains the plan for
+   vite hosts.
+2. **WebGPURenderer.** `renderer.info` exists with the same counters
+   (`render.drawCalls` not `render.calls`, `render.triangles`,
+   `memory.geometries/textures`; programs via the pipeline cache). The
+   integration maps names at the sampling site; the recorder is
+   renderer-agnostic numbers-in.
+3. **`@slopjs/inspector` is present but constrained** (`?debug&inspect`, own
+   bundle, pause refused for live multiplayer — the game's own integration
+   notes). v0 therefore ships M0+M1 (+§3.5 usermarks): recorder, census,
+   hints, CLI report/check/census/doctor. The bench/gate tier (M3) and
+   paused-world bisection (M4) wait until the pause story for a
+   client-authoritative multiplayer game is resolved; `doctor` says so.
+
+Budgets: v0 reads `.sloptimize/budgets.json` (the game has no vite tunables
+panel wired for `tune()`); moving to `tune('perf.budget.*')` when the
+inspector's tunables surface is adopted by the host remains the spec path.
+
+The host feeds frames from its ONE render loop (both of the game's frame
+loops call a single `sloptimizeFrame()` after their render call), the census
+walks the live match scene with the game's own entity groupings, and
+Ctrl+F11 is wired per §3.5.

package/docs/INTEGRATION.md

@@ -0,0 +1,230 @@
+# Integrating sloptimize into a game (and its Claude Code session)
+
+What the mecharoyale deployment wired, generalized. Five pieces; each is
+small, and the first three are enough to be useful. This doc is the ONE-TIME
+wiring; for how to use the result day to day (the operator's verbs, how new
+and concurrent Claude Code sessions pick up the feed), see USAGE.md. The
+jitter detector and the footprint/issue catalogue have their own step-by-step
+cookbook with the traps spelled out: JITTER-AND-FOOTPRINTS.md — read it
+after §1 here.
+
+## 1. The in-page runtime (the game feeds the recorder)
+
+```js
+import { createRecorder, buildCensus } from 'sloptimize';
+const rec = createRecorder({ budgetFrameMs: 16.7 });
+```
+
+Once per frame, from wherever your loop already reads `renderer.info`,
+hand the recorder numbers you already have (≤0.2ms, zero allocations):
+
+```js
+rec.frame({
+  frameMs,                    // rAF-to-rAF delta (must bound insideRenderMs)
+  insideRenderMs,             // wall time inside renderer.render
+  calls, triangles,           // renderer.info.render.*  (WebGPU: drawCalls)
+  programs,                   // program/pipeline count (WebGPU: pipeline cache size)
+  geometries, textures,       // renderer.info.memory.*
+  spawned,                    // entities added this frame (0 if unknown)
+  paused: false,
+});
+```
+
+Hitches are detected, classified with evidence, and rate-limited
+automatically.
+
+Coordinate jitter (SPEC §3.6) is the second detector — the unit or the
+camera landing off its own trajectory. Feed it once per RENDERED frame,
+after the render (so a transient camera shake the host restores is not
+sampled), with the same clock every frame:
+
+```js
+import { createMotionMonitor } from 'sloptimize';
+const motion = createMotionMonitor({
+  unit: 'm',
+  longFrameMs: 50,     // YOUR sim's dt clamp: a frame past it cannot have its motion judged
+  tracks: {
+    unit:   { floor: 0.1 },                                   // the view pivot: rotation-invariant
+    camera: { floor: 0.1, reach: 'boom', follows: 'unit' },   // the eye; reach = distance to the pivot
+  },
+});
+// per frame:
+motion.sample('unit',   pivot.x,  pivot.y,  pivot.z,  performance.now(), { held: paused || !continuityExpected, phase });
+motion.sample('camera', camera.x, camera.y, camera.z, performance.now(), { held: lookInputThisFrame || paused, reach, phase });
+// on a camera-mode flip, a spectate-target change, a respawn, a session boundary:
+motion.cut();
+// drain beside the recorder's records — same pipe, same ledger:
+post('records', [...rec.drainRecords(), ...motion.drainRecords()]);
+```
+
+Every record's FOOTPRINT (SPEC §3.7) — the identity of its cause — is
+stamped by the writer at post time, and the game's SITUATION rides in it.
+Declare the facets that make two incidents two issues in your game
+(categories only, never positions), refresh the canonical string once a
+second, and hand it along:
+
+```js
+import { canonicalContext, footprintOf } from 'sloptimize';
+let ctx = '';
+setInterval(() => { ctx = canonicalContext({ stance: 'helm', hull: 'elong-x', squad: 'duo', combat: 'no' }); }, 1000);
+rec.frame({ …, ctx });                       // stamped on hitches at mint
+rec.usermark({ …, ctx });
+motion.sample('unit', x, y, z, t, { held, phase, ctx });
+// at post, for every record (host-built ones take the current ctx):
+for (const r of records) { if (r.ctx === undefined && ctx) r.ctx = ctx; const fp = footprintOf(r); if (fp) r.footprint = fp; }
+```
+
+`held` frames are not judged and re-seed the track (a mouse flick swings a
+boom metres in one frame — intended; the reference runtime marks a frame
+held when a mousemove/wheel/touchmove landed since the previous sample).
+`cut()` is for the discontinuities the host MEANT; the reference runtime
+derives them from a view-configuration key (pivot publisher · third-person
+flag · spectated subject) and cuts whenever it changes, so no call site has
+to remember. Bind a chord for the manual channel — capture FIRST, then
+optionally ask the human for one line (see mecharoyale's
+`dev/sloptimize-runtime.ts` for a complete reference including the note
+overlay, held-input tracking, WebGPU regime detection, and the
+GPU-process wrappers):
+
+```js
+if (ctrlF11) { const mark = rec.usermark({ windowMs: 5000, note, world }); }
+```
+
+The debugger itself ships in the package — `createPanel` (Session ·
+Timeline · Fixes + the note box), dependency-free, inline-styled. Capture
+first, then open it; it swallows every key at capture phase while open and
+calls `onNote` exactly once on close:
+
+```js
+import { createPanel } from 'sloptimize';
+const panel = createPanel({
+  incidents: () => sessionIncidents,               // rows the recorder drained this tab
+  feed: () => ({ state: 'ok' }),                   // or { state: 'dark', reason, buffered }
+  history: () => fetch('/api/sloptimize/ledger').then((r) => r.json())
+    .then(({ perf, fixes }) => ({ records: parseJsonl(perf), fixes: parseJsonl(fixes) })),
+  onNote: (note) => { if (note) { mark.note = `f12: ${note}`; post('records', [mark]); } },
+});
+panel.open();
+```
+
+## 2. The sink (files on disk)
+
+- **Vite host**: the plugin (planned surface) lands payloads in `.sloptimize/`.
+- **Any other host** (esbuild, custom server): add one dev-only endpoint —
+  `POST /api/sloptimize/ingest` `{kind: 'profile'|'records'|'census', payload}`
+  → writes `.sloptimize/profile.json`, appends `perf.jsonl`, writes
+  `census.json`. Gate it to your dev flag and 404 identically to unknown
+  routes otherwise (mecharoyale: `server/admin/sloptimize-ingest.ts`, ~100
+  lines + tests).
+- **Activation**: don't gate the client on `location.hostname` — a dev
+  preview proxy looks like production. Probe the ingest endpoint at boot;
+  a 204 arms everything, anything else stays dark — and RETRY the probe on
+  a backoff (5s/30s/2min, then every 5min): an ingest that comes back
+  mid-session must re-light the instrument without a hard refresh.
+- **Transport state, never silent**: once armed, a refused or failed post
+  flips the feed DARK — buffer outgoing posts (bounded, count drops), retry
+  on the same backoff, and SHOW the state (the reference runtime renders it
+  on its PERF chip and in the debugger header, with the reason). The first
+  deployment's "first 404 disables posting for the session" contract lost an
+  hour of real freezes to a server restart that dropped the ingest.
+- **Self-sufficient records**: stamp `build` (the tab's bundle identity) and
+  `phase` (menu/boot/launch/match…) on every ledger line. The recorder
+  accepts `phase` per `frame()` sample and stamps hitches at mint time;
+  backfill the rest at post time. A record read in isolation weeks later
+  should not depend on the arm-probe that happened to precede it.
+- **Heartbeat**: post a tiny `{type:'heartbeat', medianFrameMs, p95Ms,
+  calls, triangles, programs}` ledger line once a minute while armed
+  (directly — never through the recorder, so it costs none of the incident
+  budget). It makes a quiet file MEAN dark-or-closed instead of idle;
+  `sloptimize hook-status` warns once when the ledger goes stale (>45min).
+  The counters ride the beat because `profile.json` is overwritten every
+  2s — without them the ledger has no draw-call HISTORY, and the debugger's
+  Timeline cannot draw "calls over time".
+- **Ledger read-back** (for the debugger's Timeline/Fixes tabs): one
+  dev-gated `GET /api/sloptimize/ledger` → `{ perf, fixes }` — the last
+  ~2MB of `perf.jsonl` (first partial line dropped) and all of
+  `fixes.jsonl`, as raw JSONL strings. Same gate as the ingest, 404
+  otherwise. The page folds it with sloptimize's own `history.js`; the
+  server stays a file reader (mecharoyale: `readSloptimizeLedger`, ~20
+  lines + tests).
+- **GPU-settle verdicts**: if your boot holds its reveal on
+  `queue.onSubmittedWorkDone()` (it should — pipeline compiles bill the
+  first submit that uses them, invisibly to every CPU-side recorder), post
+  `{type:'gpu-settle', tag, ms, settled}` when the wait was real (>50ms or
+  capped). That record is the on-hardware proof the freeze moved behind the
+  cover.
+- **createStacks** (optional, on hitch records): capture `new Error().stack`
+  in your createRenderPipeline/createComputePipeline/createShaderModule
+  wrappers into a small ring (creates are rare — never do this per draw or
+  per write), and attach the top ~3 deduped tails to any hitch whose frame
+  window overlaps them, byte-capped (~2KB). Ship an UNREFERENCED external
+  sourcemap from the same build so the minified positions decode to source
+  file:line on the dev side without ever serving the map to players.
+
+Flush cadence: post `profile` every ~2s, drain records with it.
+Gitignore `.sloptimize/*` except `budgets.json`.
+
+## 3. The CLI (the agent's shell surface)
+
+`sloptimize report|check|census|doctor --dir <game>/.sloptimize` — no
+setup beyond the files existing. Declare budgets in
+`.sloptimize/budgets.json`:
+
+```json
+{ "perf.budget.draw_calls": 400, "perf.budget.frame_ms_p95": 16.7 }
+```
+
+`check` exits 0/1/4 — the termination condition for an agent loop.
+
+## 4. The Claude Code session (pull: ambient on every prompt)
+
+`.claude/settings.json` in the game repo:
+
+```json
+{ "hooks": { "UserPromptSubmit": [ { "hooks": [ {
+  "type": "command",
+  "command": "node <path-to>/sloptimize/bin/sloptimize.mjs hook-status --dir .sloptimize 2>/dev/null || true",
+  "timeout": 10 } ] } ] } }
+```
+
+Silent unless a NEW keyframe or a budget-breach edge exists; at most 5
+lines. Copy the doctrine skill into `.claude/skills/sloptimize/` so any
+future session inherits the playbook (report → classify → census → ONE
+change → verify with counters; never claim a fix without a before/after).
+
+## 5. The push channel (auto mode: the agent is woken, nobody types)
+
+`sloptimize watch` is the watcher (SPEC §8.1.1): a byte cursor over each
+`--dir`'s `perf.jsonl`, polled every 20s, printing ONE line per record an
+agent should act on — every usermark, every auto hitch ≥100ms
+(`--min-hitch-ms`), a gpu-settle that hit its cap, any gpu-stall, every
+coordinate jitter that is its own incident (`↯` — not a long-frame
+catch-up, not a passenger of another track), and the feed going quiet /
+coming back. Every line ends with the record's footprint and how many
+times this ledger has seen that cause (`fp=a3f92c1d ×7`, SPEC §3.7):
+`sloptimize issues --fp a3f92c1d` is its history and the fixes applied. Heartbeats, arm-probes and small hitches
+stay silent. It starts at EOF (history is `report`'s job) and never exits.
+
+Arm it as a Claude Code Monitor — stdout lines become wake events:
+
+```
+Monitor({ command: 'node <path-to>/sloptimize/bin/sloptimize.mjs watch --dir .sloptimize',
+          description: 'sloptimize perf incidents', persistent: true })
+```
+
+To make every session arm it WITHOUT anyone asking, add a `SessionStart`
+hook that prints the instruction into the agent's context (mecharoyale's
+`.claude/settings.json` is the reference; it skips ticket-runner jobs so a
+session working an unrelated task is not pulled off it, unless
+`SLOPTIMIZE_WATCH=1` says otherwise). The operator then just plays:
+auto-detected hitches and Ctrl+F12 notes wake the agent with the
+classification attached, and it starts the §8.2 playbook unprompted.
+
+## Porting cost, measured once
+
+mecharoyale (149k-line client, esbuild, WebGPU, no vite): runtime file
+~250 lines, server endpoint ~100 + tests, build-resolution plugin ~15,
+one `rec.frame(...)` call at the existing stats site, settings + skill
+copies. One session end to end, including the mistakes this doc exists
+to save you from (hostname gating, arming inside an on-demand function,
+frameMs not bounding insideRenderMs).