@marcomigozzi/trailhead 0.14.0 → 0.16.0

package/plugins/trailhead/hooks/lib/auto-queue.test.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+// Tests for templates/trailhead-auto-queue.js. Run: node auto-queue.test.js
+// No framework: plain asserts, same style as uat-backfill.test.js.
+//
+// Layers covered:
+//   1. buildQueue() / main() against a fake tracker behind an injected `gh`
+//      runner that honours the frontier search filter and the paused-claims read.
+//   2. End-to-end: the script itself with a fake `gh` on PATH.
+const assert = require('assert');
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const scriptPath = path.resolve(__dirname, '..', '..', 'templates', 'trailhead-auto-queue.js');
+const { main, buildQueue, RUN_SEARCH, NEEDS_YOU } = require(scriptPath);
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// --- fake tracker ------------------------------------------------------------
+// issue: { number, title, labels:[names], assignee: 'me'|null, state }
+function makeTracker(init = {}) {
+  const t = { issues: init.issues || [], failOn: init.failOn || null, badJson: init.badJson || null, limit: init.limit || 1000, calls: [] };
+  const res = (stdout, status = 0) => ({ status, stdout, stderr: status ? 'forced failure' : '' });
+  t.gh = (args) => {
+    t.calls.push(args.join(' '));
+    if (args[0] !== 'issue' || args[1] !== 'list') return res('', 1);
+    const want = [];
+    let search = '';
+    let assignee = null;
+    let state = 'open';
+    let limit = 1000;
+    for (let i = 2; i < args.length; i++) {
+      if (args[i] === '--label') want.push(args[++i]);
+      else if (args[i] === '--search') search = args[++i];
+      else if (args[i] === '--assignee') assignee = args[++i];
+      else if (args[i] === '--state') state = args[++i];
+      else if (args[i] === '--limit') limit = Number(args[++i]);
+    }
+    const kind = want.includes('trailhead:map') ? 'maps' : want.includes('trailhead:paused') ? 'paused' : 'frontier';
+    if (t.failOn === kind) return res('', 1);
+    if (t.badJson && t.badJson === kind) return res('not json');
+    const excl = [...search.matchAll(/-label:(\S+)/g)].map((m) => m[1]);
+    const noAssignee = /no:assignee/.test(search);
+    let rows = t.issues.filter((i) => i.state !== 'closed' && state === 'open')
+      .filter((i) => want.every((l) => i.labels.includes(l)))
+      .filter((i) => !excl.some((l) => i.labels.includes(l)))
+      .filter((i) => !noAssignee || !i.assignee)
+      .filter((i) => assignee !== '@me' || i.assignee === 'me');
+    rows = rows.slice(0, t.limit === 1000 ? limit : t.limit);
+    return res(JSON.stringify(rows.map((i) => ({ number: i.number, title: i.title, labels: i.labels.map((name) => ({ name })) }))));
+  };
+  return t;
+}
+
+function run(t, argv) {
+  let out = '';
+  let errOut = '';
+  const code = main(argv, { gh: t.gh, stdout: { write: (s) => { out += s; } }, stderr: { write: (s) => { errOut += s; } } });
+  let json = null;
+  try { json = JSON.parse(out.trim()); } catch { /* not json */ }
+  return { code, out, json, errOut };
+}
+
+const map = (n, extra = {}) => ({ number: n, title: `Map ${n}`, labels: ['trailhead:map'], ...extra });
+const tk = (n, type, labels, extra = {}) => ({ number: n, title: `T${n}`, labels: ['trailhead:ticket', `trailhead:${type}`, ...labels], assignee: null, ...extra });
+const nums = (list) => list.map((x) => x.number);
+
+const base = () => [
+  map(5), map(2), map(9, { state: 'closed' }),
+  tk(30, 'build', ['trailhead:map-5']),
+  tk(21, 'bug', ['trailhead:map-2']),
+  tk(11, 'task', ['trailhead:map-2']),
+  tk(40, 'research', ['trailhead:whiteboard']),
+  tk(31, 'decision', ['trailhead:map-5']),
+  tk(50, 'build', ['trailhead:map-9']), // closed map: ignored
+  tk(51, 'build', []), // no scope label: ignored
+  tk(52, 'build', ['trailhead:map-2', 'trailhead:whiteboard']), // map wins
+  tk(60, 'build', ['trailhead:map-2', 'trailhead:blocked']), // blocked: never queued
+  tk(61, 'build', ['trailhead:map-5', 'trailhead:paused']),
+  tk(62, 'build', ['trailhead:map-5', 'trailhead:unverified']),
+  tk(63, 'build', ['trailhead:map-5'], { assignee: 'someone' }),
+  tk(70, 'build', ['trailhead:map-2', 'trailhead:map-5']), // two open maps: drift
+];
+
+// --- ordering: everything ----------------------------------------------------
+{
+  const t = makeTracker({ issues: base() });
+  const r = run(t, ['queue', '--scope', 'everything', '--repo', 'o/r']);
+  ok('exit 0, one JSON line', r.code === 0 && r.json.status === 'ok' && r.out.trim().split('\n').length === 1);
+  ok('groups: maps ascending, whiteboard last', JSON.stringify(r.json.groups.map((g) => g.map)) === '[2,5,null]' && r.json.groups[2].kind === 'whiteboard');
+  ok('tickets ascending inside a group, map label wins over whiteboard', JSON.stringify(nums(r.json.groups[0].tickets)) === '[11,21,52]');
+  ok('map 5 group', JSON.stringify(nums(r.json.groups[1].tickets)) === '[30,31]');
+  ok('whiteboard group', JSON.stringify(nums(r.json.groups[2].tickets)) === '[40]');
+  ok('each ticket carries its type', r.json.groups[0].tickets[0].type === 'task' && r.json.groups[0].tickets[1].type === 'bug' && r.json.groups[1].tickets[1].type === 'decision');
+  const all = r.json.groups.flatMap((g) => nums(g.tickets));
+  ok('blocked/unverified/paused/assigned never queued', [60, 61, 62, 63].every((n) => !all.includes(n)));
+  ok('closed-map and unlabelled tickets ignored', !all.includes(50) && !all.includes(51));
+  ok('multi-map-label ticket is drift, not queued', JSON.stringify(nums(r.json.drift)) === '[70]' && !all.includes(70));
+  ok('next is the lowest ticket of the first map', r.json.next.number === 11 && r.json.next.map === 2);
+  ok('queue reads: frontier uses the canonical search', t.calls.some((c) => c.includes('--label trailhead:ticket') && c.includes('no:assignee -label:trailhead:blocked -label:trailhead:unverified -label:trailhead:paused') && c.includes('--limit 1000') && c.includes('--json number,title,labels')));
+  ok('queue reads: open maps and caller paused claims', t.calls.some((c) => c.includes('--label trailhead:map --state open') && c.includes('--json number,title')) && t.calls.some((c) => c.includes('--label trailhead:paused') && c.includes('--assignee @me')));
+}
+
+// --- skip / next -------------------------------------------------------------
+{
+  const t = makeTracker({ issues: base() });
+  let r = run(t, ['queue', '--scope', 'everything', '--skip', '11,21']);
+  ok('skipped tickets dropped, next stays in the current map', JSON.stringify(nums(r.json.groups[0].tickets)) === '[52]' && r.json.next.number === 52);
+  r = run(t, ['queue', '--scope', 'everything', '--skip', '11,21,52']);
+  ok('next moves to the next map only when the group is empty after skip', r.json.next.number === 30 && r.json.next.map === 5);
+  r = run(t, ['queue', '--scope', 'everything', '--skip', '11,21,52,30,31']);
+  ok('whiteboard only after every map', r.json.next.number === 40 && r.json.next.map === null);
+  r = run(t, ['queue', '--scope', 'everything', '--skip', '11,21,52,30,31,40']);
+  ok('drained scope has next null', r.code === 0 && r.json.next === null);
+}
+
+// --- single scopes -----------------------------------------------------------
+{
+  const t = makeTracker({ issues: base() });
+  let r = run(t, ['queue', '--scope', 'map:5']);
+  ok('map:<n> yields only that map', r.json.groups.length === 1 && r.json.groups[0].map === 5 && r.json.next.number === 30);
+  ok('map:<n> drift is limited to that map', JSON.stringify(nums(r.json.drift)) === '[70]');
+  r = run(t, ['queue', '--scope', 'whiteboard']);
+  ok('whiteboard scope yields only the whiteboard group', r.json.groups.length === 1 && r.json.groups[0].kind === 'whiteboard' && r.json.next.number === 40 && r.json.drift.length === 0);
+  r = run(t, ['queue', '--scope', 'map:9']);
+  ok('a closed map is an error naming it', r.code === 1 && r.json.status === 'error' && /9/.test(r.json.reason));
+  r = run(t, ['queue', '--scope', 'map:77']);
+  ok('an unknown map is an error naming it', r.code === 1 && r.json.status === 'error' && /77/.test(r.json.reason));
+  ok('a non-map issue is an error', run(makeTracker({ issues: [tk(8, 'build', ['trailhead:map-2'])] }), ['queue', '--scope', 'map:8']).code === 1);
+}
+
+// --- resume ------------------------------------------------------------------
+{
+  const issues = [
+    map(2), map(5),
+    tk(14, 'build', ['trailhead:map-5', 'trailhead:paused'], { assignee: 'me' }),
+    tk(12, 'bug', ['trailhead:map-5', 'trailhead:paused'], { assignee: 'me' }),
+    tk(13, 'build', ['trailhead:map-2', 'trailhead:paused'], { assignee: 'other' }),
+    tk(15, 'task', ['trailhead:whiteboard', 'trailhead:paused'], { assignee: 'me' }),
+    tk(30, 'build', ['trailhead:map-5']),
+  ];
+  const t = makeTracker({ issues });
+  let r = run(t, ['queue', '--scope', 'everything']);
+  ok('resume lists the caller paused tickets per group, ascending', JSON.stringify(nums(r.json.groups[1].resume)) === '[12,14]' && r.json.groups[0].resume.length === 0 && JSON.stringify(nums(r.json.groups[2].resume)) === '[15]');
+  ok('paused tickets are not in the work queue', JSON.stringify(nums(r.json.groups[1].tickets)) === '[30]');
+  r = run(t, ['queue', '--scope', 'map:5']);
+  ok('resume is scoped', r.json.groups.length === 1 && JSON.stringify(nums(r.json.groups[0].resume)) === '[12,14]');
+}
+
+// --- needs-you tickets are skipped by the run ---------------------------------
+{
+  const issues = [
+    map(2),
+    tk(11, 'build', ['trailhead:map-2']),
+    tk(12, 'build', ['trailhead:map-2', 'trailhead:needs-you']),
+    tk(13, 'build', ['trailhead:map-2', 'trailhead:paused', 'trailhead:needs-you'], { assignee: 'me' }),
+    tk(14, 'build', ['trailhead:map-2', 'trailhead:paused'], { assignee: 'me' }),
+  ];
+  const t = makeTracker({ issues });
+  let r = run(t, ['queue', '--scope', 'everything']);
+  ok('needs-you ticket is not queued nor next', JSON.stringify(nums(r.json.groups[0].tickets)) === '[11]' && r.json.next.number === 11);
+  ok('needs-you ticket is never auto-resumed', JSON.stringify(nums(r.json.groups[0].resume)) === '[14]');
+  ok('frontier read sends the needs-you exclusion', t.calls.some((c) => c.includes('--label trailhead:ticket') && c.includes('-label:trailhead:paused -label:trailhead:needs-you')));
+  r = run(t, ['scopes']);
+  ok('scopes does not count a needs-you ticket', r.json.maps[0].frontier === 1);
+  ok('RUN_SEARCH extends the canonical frontier', RUN_SEARCH.endsWith(' -label:trailhead:needs-you') && NEEDS_YOU === 'trailhead:needs-you');
+  // defence against a lagging search index: the pure builder drops it too
+  const q = buildQueue([{ number: 2, title: 'm' }],
+    [{ number: 5, title: 'a', labels: ['trailhead:map-2', 'trailhead:needs-you'] }, { number: 6, title: 'b', labels: ['trailhead:map-2'] }],
+    [{ number: 7, title: 'c', labels: ['trailhead:map-2', 'trailhead:needs-you'] }], 'everything', []);
+  ok('buildQueue drops needs-you from frontier and resume', nums(q.groups[0].tickets).join() === '6' && q.groups[0].resume.length === 0 && q.next.number === 6);
+}
+
+// --- fail closed -------------------------------------------------------------
+{
+  const many = [map(2)];
+  for (let i = 0; i < 1000; i++) many.push(tk(100 + i, 'build', ['trailhead:map-2']));
+  const t = makeTracker({ issues: many });
+  const r = run(t, ['queue', '--scope', 'everything']);
+  ok('a frontier read at the limit fails closed', r.code === 1 && r.json.status === 'error' && /incomplete/.test(r.json.reason) && !r.json.groups);
+  const s = run(t, ['scopes']);
+  ok('scopes fails closed on truncation too', s.code === 1 && s.json.status === 'error' && /incomplete/.test(s.json.reason));
+  const maps = [];
+  for (let i = 1; i <= 1000; i++) maps.push(map(i));
+  ok('a truncated map list fails closed', run(makeTracker({ issues: maps }), ['queue', '--scope', 'everything']).code === 1);
+}
+for (const kind of ['maps', 'frontier', 'paused']) {
+  let r = run(makeTracker({ issues: base(), failOn: kind }), ['queue', '--scope', 'everything']);
+  ok(`gh failure on ${kind} read is an error`, r.code === 1 && r.json.status === 'error');
+  r = run(makeTracker({ issues: base(), badJson: kind }), ['queue', '--scope', 'everything']);
+  ok(`bad JSON on ${kind} read is an error`, r.code === 1 && r.json.status === 'error');
+}
+
+// --- scopes ------------------------------------------------------------------
+{
+  const t = makeTracker({ issues: base() });
+  const r = run(t, ['scopes', '--repo', 'o/r']);
+  ok('scopes: open maps ascending with frontier counts', r.code === 0 && JSON.stringify(r.json.maps) === JSON.stringify([
+    { number: 2, title: 'Map 2', frontier: 3 }, { number: 5, title: 'Map 5', frontier: 2 }]));
+  ok('scopes: whiteboard count', r.json.whiteboard.frontier === 1);
+  ok('scopes: passes -R', t.calls.every((c) => c.includes('-R o/r')));
+}
+
+// --- pure buildQueue ---------------------------------------------------------
+{
+  const q = buildQueue([{ number: 1, title: 'a' }], [{ number: 3, title: 'x', labels: ['trailhead:map-1', 'trailhead:build'] }], [], 'everything', []);
+  ok('buildQueue accepts string labels', q.groups[0].tickets[0].type === 'build' && q.next.number === 3);
+  ok('buildQueue reports a bad scope', buildQueue([], [], [], 'map:4', []).error);
+}
+
+// --- usage -------------------------------------------------------------------
+for (const argv of [[], ['bogus'], ['queue'], ['queue', '--scope', 'nope'], ['queue', '--scope', 'map:x'], ['queue', '--scope', 'everything', '--skip', 'a,b'],
+  ['queue', '--scope'], ['scopes', '--bogus'], ['scopes', '--repo', 'nope']]) {
+  const t = makeTracker();
+  const r = run(t, argv);
+  ok(`usage error exit 2: ${argv.join(' ')}`, r.code === 2 && t.calls.length === 0);
+}
+
+// --- end-to-end with a fake gh on PATH -----------------------------------------
+{
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'auto-queue-'));
+  const binDir = path.join(tmp, 'bin');
+  fs.mkdirSync(binDir);
+  const script = `#!/bin/sh
+case "$*" in
+  *"--label trailhead:map "*) echo '[{"number":2,"title":"M"}]' ;;
+  *"--label trailhead:paused"*) echo '[]' ;;
+  *) echo '[{"number":7,"title":"T","labels":[{"name":"trailhead:map-2"},{"name":"trailhead:build"}]}]' ;;
+esac
+`;
+  fs.writeFileSync(path.join(binDir, 'gh'), script, { mode: 0o755 });
+  const env = { ...process.env, PATH: binDir + path.delimiter + process.env.PATH };
+  const res = spawnSync('node', [scriptPath, 'queue', '--scope', 'map:2'], { encoding: 'utf8', env });
+  const j = JSON.parse(res.stdout.trim());
+  ok('e2e: queue prints one JSON line with next', res.status === 0 && j.status === 'ok' && j.next.number === 7 && j.next.type === 'build');
+  fs.writeFileSync(path.join(binDir, 'gh'), '#!/bin/sh\nexit 1\n', { mode: 0o755 });
+  const bad = spawnSync('node', [scriptPath, 'queue', '--scope', 'everything'], { encoding: 'utf8', env });
+  ok('e2e: gh failing exits 1 with an error line', bad.status === 1 && JSON.parse(bad.stdout.trim()).status === 'error');
+  ok('e2e: usage error exits 2', spawnSync('node', [scriptPath, '--bogus'], { encoding: 'utf8' }).status === 2);
+  fs.rmSync(tmp, { recursive: true, force: true });
+}
+
+console.log(`auto-queue.test.js: ${passed} checks passed`);

package/plugins/trailhead/hooks/lib/auto-run.test.js

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+// Tests for templates/trailhead-auto-run.js. Run: node auto-run.test.js
+// No framework: plain asserts, same style as work-state.test.js.
+//
+// Layers covered:
+//   1. sanitizeRecord() / parseArgs() pure.
+//   2. main() with injected cwd/env/stdout/stderr against mkdtemp folders.
+//   3. Fault injection: an fs whose write, read or unlink throws.
+//   4. End-to-end: spawnSync of the script, including a simulated compaction.
+const assert = require('assert');
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const scriptPath = path.resolve(__dirname, '..', '..', 'templates', 'trailhead-auto-run.js');
+const { main, parseArgs, sanitizeRecord } = require(scriptPath);
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const mktmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-auto-run-test-'));
+const recPath = (dir) => path.join(dir, '.trailhead', 'auto-run.json');
+const readRec = (dir) => JSON.parse(fs.readFileSync(recPath(dir), 'utf8'));
+const trailheadFiles = (dir) => fs.existsSync(path.join(dir, '.trailhead')) ? fs.readdirSync(path.join(dir, '.trailhead')) : [];
+const fixedNow = () => new Date('2026-10-20T10:00:00.000Z');
+
+// Esegue main() catturando stdout e stderr; ritorna { code, lines, err }.
+function run(argv, { cwd = '/', env = {}, fsMod } = {}) {
+  const chunks = [];
+  const errChunks = [];
+  const code = main(argv, {
+    cwd,
+    env,
+    now: fixedNow(),
+    stdout: { write: (s) => chunks.push(s) },
+    stderr: { write: (s) => errChunks.push(String(s)) },
+    ...(fsMod ? { fs: fsMod } : {}),
+  });
+  const lines = chunks.join('').split('\n').filter(Boolean).map((l) => JSON.parse(l));
+  return { code, lines, err: errChunks.join('') };
+}
+
+const START = (dir, extra = []) => ['start', '--repo', dir, '--scope', 'map:12', '--slots', '2', '--review', '2', ...extra];
+
+// --- start -------------------------------------------------------------------
+{
+  const dir = mktmp();
+  const r = run(START(dir), { env: { CLAUDE_CODE_SESSION_ID: 'sess-1' } });
+  const rec = readRec(dir);
+  ok('start: exit 0, one line, status written', r.code === 0 && r.lines.length === 1 && r.lines[0].status === 'written');
+  ok('start: output carries path and record', r.lines[0].path === recPath(dir) && r.lines[0].record.scope === 'map:12');
+  ok('start: exact key set', JSON.stringify(Object.keys(rec)) ===
+    JSON.stringify(['version', 'scope', 'slots', 'review', 'session', 'skip', 'unmerged', 'startedAt', 'updatedAt']));
+  ok('start: values', rec.version === 1 && rec.scope === 'map:12' && rec.slots === 2 && rec.review === '2');
+  ok('start: empty lists', Array.isArray(rec.skip) && rec.skip.length === 0 && Array.isArray(rec.unmerged) && rec.unmerged.length === 0);
+  ok('start: session from env', rec.session === 'sess-1');
+  ok('start: timestamps ISO and equal', rec.startedAt === '2026-10-20T10:00:00.000Z' && rec.updatedAt === rec.startedAt);
+  ok('start: no temp file left', JSON.stringify(trailheadFiles(dir)) === JSON.stringify(['auto-run.json']));
+}
+
+// --- session null (Codex) ----------------------------------------------------
+{
+  const dir = mktmp();
+  run(START(dir), { env: {} });
+  ok('start: session unset -> null', readRec(dir).session === null);
+  const dir2 = mktmp();
+  run(START(dir2), { env: { CLAUDE_CODE_SESSION_ID: '' } });
+  ok('start: session empty -> null', readRec(dir2).session === null);
+}
+
+// --- scope / review tokens ---------------------------------------------------
+for (const scope of ['whiteboard', 'everything', 'map:7']) {
+  const dir = mktmp();
+  const r = run(['start', '--repo', dir, '--scope', scope, '--slots', '1', '--review', 'config']);
+  ok(`start: scope ${scope} accepted`, r.code === 0 && readRec(dir).scope === scope);
+}
+for (const review of ['config', '1', '2', '3', 'until', 'skip']) {
+  const dir = mktmp();
+  const r = run(['start', '--repo', dir, '--scope', 'everything', '--slots', '4', '--review', review]);
+  ok(`start: review ${review} accepted`, r.code === 0 && readRec(dir).review === review);
+}
+
+// --- start on an existing record ---------------------------------------------
+{
+  const dir = mktmp();
+  run(START(dir));
+  run(['skip', '--repo', dir, '--ticket', '5']);
+  const r = run(['start', '--repo', dir, '--scope', 'everything', '--slots', '3', '--review', 'until']);
+  ok('start over existing: exists with the old record', r.code === 0 && r.lines[0].status === 'exists' && r.lines[0].record.scope === 'map:12');
+  ok('start over existing: nothing written', readRec(dir).scope === 'map:12' && readRec(dir).skip[0] === 5);
+  const r2 = run(['start', '--repo', dir, '--scope', 'everything', '--slots', '3', '--review', 'until', '--replace']);
+  const rec = readRec(dir);
+  ok('start --replace: written fresh', r2.lines[0].status === 'written' && rec.scope === 'everything' && rec.slots === 3 && rec.review === 'until' && rec.skip.length === 0);
+}
+{
+  const dir = mktmp();
+  fs.mkdirSync(path.join(dir, '.trailhead'));
+  fs.writeFileSync(recPath(dir), '{not json');
+  const r = run(START(dir));
+  ok('start over corrupt: exists, no record, file untouched', r.lines[0].status === 'exists' && r.lines[0].record === null && fs.readFileSync(recPath(dir), 'utf8') === '{not json');
+  const r2 = run(START(dir, ['--replace']));
+  ok('start --replace over corrupt: written', r2.lines[0].status === 'written' && readRec(dir).scope === 'map:12');
+}
+
+// --- read --------------------------------------------------------------------
+{
+  const dir = mktmp();
+  const r = run(['read', '--repo', dir]);
+  ok('read: absent', r.code === 0 && r.lines[0].status === 'absent' && trailheadFiles(dir).length === 0);
+}
+{
+  const dir = mktmp();
+  run(START(dir), { env: { CLAUDE_CODE_SESSION_ID: 'sess-1' } });
+  const same = run(['read', '--repo', dir], { env: { CLAUDE_CODE_SESSION_ID: 'sess-1' } });
+  ok('read: found with record', same.lines[0].status === 'found' && same.lines[0].record.slots === 2);
+  ok('read: sameSession true', same.lines[0].sameSession === true);
+  const other = run(['read', '--repo', dir], { env: { CLAUDE_CODE_SESSION_ID: 'sess-2' } });
+  ok('read: sameSession false for another session', other.lines[0].sameSession === false);
+  const none = run(['read', '--repo', dir], { env: {} });
+  ok('read: sameSession false when the reader has no session', none.lines[0].sameSession === false);
+}
+{
+  const dir = mktmp();
+  run(START(dir), { env: {} });
+  const r = run(['read', '--repo', dir], { env: { CLAUDE_CODE_SESSION_ID: 'sess-1' } });
+  ok('read: sameSession false when the record has no session', r.lines[0].sameSession === false);
+  const r2 = run(['read', '--repo', dir], { env: {} });
+  ok('read: sameSession false when both sessions are null', r2.lines[0].sameSession === false);
+}
+{
+  const dir = mktmp();
+  fs.mkdirSync(path.join(dir, '.trailhead'));
+  fs.writeFileSync(recPath(dir), '{not json');
+  const r = run(['read', '--repo', dir]);
+  ok('read: unparseable is corrupt', r.code === 0 && r.lines[0].status === 'corrupt');
+  for (const patch of [{ version: 2 }, { scope: 'nope' }, { slots: 9 }, { slots: 0 }, { review: 'x' }, { version: undefined }, { scope: undefined }, { slots: undefined }, { review: undefined }]) {
+    const base = { version: 1, scope: 'whiteboard', slots: 1, review: 'config', session: null, skip: [], unmerged: [], startedAt: 'a', updatedAt: 'b' };
+    fs.writeFileSync(recPath(dir), JSON.stringify({ ...base, ...patch }));
+    const rr = run(['read', '--repo', dir]);
+    ok(`read: invalid required field ${JSON.stringify(patch)} is corrupt`, rr.code === 0 && rr.lines[0].status === 'corrupt');
+  }
+  fs.writeFileSync(recPath(dir), '[1,2]');
+  ok('read: array is corrupt', run(['read', '--repo', dir]).lines[0].status === 'corrupt');
+  fs.writeFileSync(recPath(dir), 'null');
+  ok('read: null is corrupt', run(['read', '--repo', dir]).lines[0].status === 'corrupt');
+}
+{
+  // Voci di lista invalide: scartate, il record resta found.
+  const dir = mktmp();
+  fs.mkdirSync(path.join(dir, '.trailhead'));
+  fs.writeFileSync(recPath(dir), JSON.stringify({
+    version: 1, scope: 'everything', slots: 2, review: 'skip', session: 's', startedAt: 'a', updatedAt: 'b',
+    skip: [9, 3, 'x', -1, 0, 1.5, 3],
+    unmerged: [
+      { ticket: 4, branch: 'trailhead/t4', files: ['a.js', 7, ''], mergeTicket: 11 },
+      { ticket: 'x', branch: 'trailhead/t5', files: [], mergeTicket: null },
+      { ticket: 6, branch: '', files: [], mergeTicket: null },
+      { ticket: 7, branch: 'a\nb', files: [], mergeTicket: null },
+      { ticket: 8, branch: 'trailhead/t8', files: 'nope', mergeTicket: 'z' },
+      'junk',
+    ],
+  }));
+  const r = run(['read', '--repo', dir]);
+  const rec = r.lines[0].record;
+  ok('read: partial list entries -> found', r.lines[0].status === 'found');
+  ok('read: skip sanitized, deduped, sorted', JSON.stringify(rec.skip) === JSON.stringify([3, 9]));
+  ok('read: unmerged invalid entries dropped', rec.unmerged.length === 2 && rec.unmerged[0].ticket === 4 && rec.unmerged[1].ticket === 8);
+  ok('read: unmerged fields normalised', JSON.stringify(rec.unmerged[0].files) === JSON.stringify(['a.js']) && rec.unmerged[0].mergeTicket === 11 &&
+    rec.unmerged[1].files.length === 0 && rec.unmerged[1].mergeTicket === null);
+}
+
+// --- skip --------------------------------------------------------------------
+{
+  const dir = mktmp();
+  const r = run(['skip', '--repo', dir, '--ticket', '3']);
+  ok('skip: absent record, nothing written', r.code === 0 && r.lines[0].status === 'absent' && trailheadFiles(dir).length === 0);
+  run(START(dir));
+  run(['skip', '--repo', dir, '--ticket', '30']);
+  run(['skip', '--repo', dir, '--ticket', '4']);
+  const again = run(['skip', '--repo', dir, '--ticket', '30']);
+  run(['skip', '--repo', dir, '--ticket', '17']);
+  ok('skip: written status and record', again.lines[0].status === 'written' && again.lines[0].record.skip.length === 2);
+  ok('skip: sorted ascending, deduped', JSON.stringify(readRec(dir).skip) === JSON.stringify([4, 17, 30]));
+  ok('skip: other fields kept', readRec(dir).scope === 'map:12' && readRec(dir).startedAt === '2026-10-20T10:00:00.000Z');
+}
+{
+  const dir = mktmp();
+  fs.mkdirSync(path.join(dir, '.trailhead'));
+  fs.writeFileSync(recPath(dir), 'garbage');
+  const r = run(['skip', '--repo', dir, '--ticket', '3']);
+  ok('skip: corrupt record reported, not overwritten', r.code === 0 && r.lines[0].status === 'corrupt' && fs.readFileSync(recPath(dir), 'utf8') === 'garbage');
+}
+
+// --- unmerged ----------------------------------------------------------------
+{
+  const dir = mktmp();
+  const r = run(['unmerged', '--repo', dir, '--ticket', '3', '--branch', 'trailhead/t3']);
+  ok('unmerged: absent record, nothing written', r.code === 0 && r.lines[0].status === 'absent' && trailheadFiles(dir).length === 0);
+  run(START(dir));
+  const a = run(['unmerged', '--repo', dir, '--ticket', '8', '--branch', 'trailhead/t8', '--file', 'a.js', '--file', 'b/c.js']);
+  ok('unmerged: insert', a.lines[0].status === 'written' && JSON.stringify(readRec(dir).unmerged) ===
+    JSON.stringify([{ ticket: 8, branch: 'trailhead/t8', files: ['a.js', 'b/c.js'], mergeTicket: null }]));
+  run(['unmerged', '--repo', dir, '--ticket', '5', '--branch', 'trailhead/t5']);
+  ok('unmerged: no files is an empty list, sorted by ticket', JSON.stringify(readRec(dir).unmerged.map((u) => u.ticket)) === '[5,8]' && readRec(dir).unmerged[0].files.length === 0);
+  run(['unmerged', '--repo', dir, '--ticket', '8', '--branch', 'trailhead/t8', '--file', 'a.js', '--file', 'b/c.js', '--merge-ticket', '99']);
+  const rec = readRec(dir);
+  ok('unmerged: upsert replaces the entry (no duplicate)', rec.unmerged.length === 2 && rec.unmerged.find((u) => u.ticket === 8).mergeTicket === 99);
+}
+
+// --- clear -------------------------------------------------------------------
+{
+  const dir = mktmp();
+  ok('clear: absent', run(['clear', '--repo', dir]).lines[0].status === 'absent');
+  run(START(dir));
+  const r = run(['clear', '--repo', dir]);
+  ok('clear: cleared and file gone', r.code === 0 && r.lines[0].status === 'cleared' && !fs.existsSync(recPath(dir)));
+  ok('clear: read afterwards is absent', run(['read', '--repo', dir]).lines[0].status === 'absent');
+}
+
+// --- --repo default is cwd ---------------------------------------------------
+{
+  const dir = mktmp();
+  run(['start', '--scope', 'whiteboard', '--slots', '1', '--review', 'skip'], { cwd: dir });
+  ok('repo defaults to cwd', readRec(dir).scope === 'whiteboard');
+}
+
+// --- usage errors: exit 2, nothing written -----------------------------------
+for (const argv of [
+  [],
+  ['nope'],
+  ['start', '--scope', 'map:1', '--slots', '2'],
+  ['start', '--scope', 'map:0', '--slots', '2', '--review', 'config'],
+  ['start', '--scope', 'map:x', '--slots', '2', '--review', 'config'],
+  ['start', '--scope', 'maps', '--slots', '2', '--review', 'config'],
+  ['start', '--scope', 'everything', '--slots', '0', '--review', 'config'],
+  ['start', '--scope', 'everything', '--slots', '5', '--review', 'config'],
+  ['start', '--scope', 'everything', '--slots', 'two', '--review', 'config'],
+  ['start', '--scope', 'everything', '--slots', '2', '--review', 'four'],
+  ['start', '--scope', 'everything', '--slots', '2', '--review', 'config', '--bogus', 'x'],
+  ['start', '--scope', 'everything', '--slots'],
+  ['skip', '--ticket', '0'],
+  ['skip', '--ticket', 'abc'],
+  ['skip'],
+  ['unmerged', '--ticket', '3'],
+  ['unmerged', '--branch', 'trailhead/t3'],
+  ['unmerged', '--ticket', '3', '--branch', ''],
+  ['unmerged', '--ticket', '3', '--branch', 'a\nb'],
+  ['unmerged', '--ticket', '3', '--branch', 'b', '--merge-ticket', '0'],
+  ['unmerged', '--ticket', '3', '--branch', 'b', '--merge-ticket', 'q'],
+  ['read', '--ticket', '3'],
+  ['clear', '--replace'],
+  ['skip', '--ticket', '3', '--replace'],
+]) {
+  const dir = mktmp();
+  const withRepo = argv.length ? [argv[0], '--repo', dir, ...argv.slice(1)] : argv;
+  const r = run(withRepo);
+  ok(`usage error exit 2, nothing written: ${JSON.stringify(argv)}`, r.code === 2 && r.lines.length === 0 && r.err.length > 0 && trailheadFiles(dir).length === 0);
+}
+ok('parseArgs: --replace only on start', parseArgs(['clear', '--replace']).error !== undefined && parseArgs(START('/x', ['--replace'])).replace === true);
+ok('parseArgs: --file repeatable', JSON.stringify(parseArgs(['unmerged', '--ticket', '1', '--branch', 'b', '--file', 'x', '--file', 'y']).files) === '["x","y"]');
+
+// --- sanitizeRecord pure -----------------------------------------------------
+ok('sanitizeRecord: non-object is an error', sanitizeRecord(null).error !== undefined && sanitizeRecord('x').error !== undefined);
+
+// --- skipped path: an injected failing fs ------------------------------------
+const boom = () => { throw new Error('disk on fire'); };
+{
+  const dir = mktmp();
+  const r = run(START(dir), { fsMod: { ...fs, writeFileSync: boom } });
+  ok('skipped: start with a failing write', r.code === 0 && r.lines.length === 1 && r.lines[0].status === 'skipped' && /disk on fire/.test(r.lines[0].message));
+  ok('skipped: start leaves no temp file', trailheadFiles(dir).every((f) => !f.endsWith('.tmp')));
+  const r2 = run(START(dir), { fsMod: { ...fs, renameSync: boom } });
+  ok('skipped: start with a failing rename', r2.code === 0 && r2.lines[0].status === 'skipped' && trailheadFiles(dir).every((f) => !f.endsWith('.tmp')));
+}
+{
+  const dir = mktmp();
+  run(START(dir));
+  const fail = { ...fs, writeFileSync: boom };
+  const s = run(['skip', '--repo', dir, '--ticket', '3'], { fsMod: fail });
+  ok('skipped: skip with a failing write', s.code === 0 && s.lines[0].status === 'skipped' && readRec(dir).skip.length === 0);
+  const u = run(['unmerged', '--repo', dir, '--ticket', '3', '--branch', 'b'], { fsMod: fail });
+  ok('skipped: unmerged with a failing write', u.code === 0 && u.lines[0].status === 'skipped' && readRec(dir).unmerged.length === 0);
+  const rd = run(['read', '--repo', dir], { fsMod: { ...fs, readFileSync: boom } });
+  ok('skipped: read with a failing read', rd.code === 0 && rd.lines[0].status === 'skipped');
+  const c = run(['clear', '--repo', dir], { fsMod: { ...fs, unlinkSync: boom } });
+  ok('skipped: clear with a failing unlink', c.code === 0 && c.lines[0].status === 'skipped' && fs.existsSync(recPath(dir)));
+}
+
+// --- end-to-end, simulated compaction ----------------------------------------
+{
+  const dir = mktmp();
+  const cli = (args, env = {}) => {
+    const p = spawnSync(process.execPath, [scriptPath, ...args], { encoding: 'utf8', env: { PATH: process.env.PATH, ...env } });
+    return { code: p.status, line: JSON.parse(p.stdout.trim().split('\n').pop()) };
+  };
+  // Un solo processo: start + skip + unmerged (poi upsert con merge ticket).
+  const writer = (args) => run(args, { env: { CLAUDE_CODE_SESSION_ID: 'sess-A' } });
+  writer(['start', '--repo', dir, '--scope', 'map:42', '--slots', '3', '--review', 'until']);
+  writer(['skip', '--repo', dir, '--ticket', '31']);
+  writer(['skip', '--repo', dir, '--ticket', '12']);
+  writer(['unmerged', '--repo', dir, '--ticket', '12', '--branch', 'trailhead/t12', '--file', 'src/a.ts', '--file', 'src/b.ts']);
+  writer(['unmerged', '--repo', dir, '--ticket', '12', '--branch', 'trailhead/t12', '--file', 'src/a.ts', '--file', 'src/b.ts', '--merge-ticket', '77']);
+  // Dopo la compattazione: un processo fresco rilegge tutto.
+  const fresh = cli(['read', '--repo', dir], { CLAUDE_CODE_SESSION_ID: 'sess-A' });
+  const rec = fresh.line.record;
+  ok('compaction: fresh process finds the record', fresh.code === 0 && fresh.line.status === 'found' && fresh.line.sameSession === true);
+  ok('compaction: scope, slots, review survive', rec.scope === 'map:42' && rec.slots === 3 && rec.review === 'until');
+  ok('compaction: skip list survives', JSON.stringify(rec.skip) === '[12,31]');
+  ok('compaction: unmerged list survives with the merge ticket', JSON.stringify(rec.unmerged) ===
+    JSON.stringify([{ ticket: 12, branch: 'trailhead/t12', files: ['src/a.ts', 'src/b.ts'], mergeTicket: 77 }]));
+  const other = cli(['read', '--repo', dir], { CLAUDE_CODE_SESSION_ID: 'sess-B' });
+  ok('compaction: another session sees sameSession false', other.line.sameSession === false && other.line.record.scope === 'map:42');
+  ok('cli: usage error exits 2', spawnSync(process.execPath, [scriptPath, 'nope'], { encoding: 'utf8' }).status === 2);
+  ok('cli: clear then read is absent', cli(['clear', '--repo', dir]).line.status === 'cleared' && cli(['read', '--repo', dir]).line.status === 'absent');
+}
+
+console.log(`auto-run.test.js: ${passed} checks passed`);